釋出部署技能的路徑修正與體檢目錄頁改版至 master，版本 0.2.8 升到 0.3.2 #60
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-cli",
|
||||
"version": "0.2.8",
|
||||
"version": "0.3.2",
|
||||
"description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-cli",
|
||||
"version": "0.2.8",
|
||||
"version": "0.3.2",
|
||||
"description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署",
|
||||
"skills": "./skills",
|
||||
"jsc": {
|
||||
|
||||
@@ -54,11 +54,11 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
### `doctor`
|
||||
|
||||
一次體檢執行環境，只讀不改。四項檢查**同時啟動，各一個 sub agent**：技能版本（`jsc-hooks/hooks/version-guard.sh report`）、Hook 接線（`jsc-hooks/tools/wire-cli.sh status`，唯讀子命令）、設定現況（`tools/scan-config.sh scan all` 比對 `tools/config-spec.tsv`，一次掃完全域與專案兩個範圍）、漏登錄變數（`scan-config.sh orphans`）。唯讀契約下放程式層：呼叫 `wire-cli.sh` 一律帶 `JSC_READONLY=1`，打錯子命令也不會改到機器。每項各出一張表，專案那張一定寫出掃的是哪個目錄；待修項目由 `tools/build-todo.sh` 合併三份輸出並排序。整份結果寫進 wiki `CHECK_{HASH}`，`HASH` 取 `{短主機名}/{登入帳號}`，兩個值都由程式取，主機名一律切掉網域，只保留最新一次。目錄頁 `CHECK_CONTENTS` 住另一個庫（`JSC_WIKI_REPO_CONTENTS`），改由 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 4` 只寫本機那一列。鍵是第 4 欄的裸 `HASH`，不是第 1 欄的連結：網址會隨站台、存取庫與頁名編碼改變，拿網址當鍵就比不中，同一台機器每體檢一次就多附一列。第 1 欄的連結給人點，填絕對網址。修復交給 `/jsc-cli:setup`，體檢本身不動任何設定。
|
||||
一次體檢執行環境，只讀不改。四項檢查**同時啟動，各一個 sub agent**：技能版本（`jsc-hooks/hooks/version-guard.sh report`）、Hook 接線（`jsc-hooks/tools/wire-cli.sh status`，唯讀子命令）、設定現況（`tools/scan-config.sh scan all` 比對 `tools/config-spec.tsv`，一次掃完全域與專案兩個範圍）、漏登錄變數（`scan-config.sh orphans`）。唯讀契約下放程式層：呼叫 `wire-cli.sh` 一律帶 `JSC_READONLY=1`，打錯子命令也不會改到機器。每項各出一張表，專案那張一定寫出掃的是哪個目錄；待修項目由 `tools/build-todo.sh` 合併三份輸出並排序。整份結果寫進 wiki `CHECK_{HASH}`，`HASH` 取 `{短主機名}/{登入帳號}`，兩個值都由程式取，主機名一律切掉網域，只保留最新一次。目錄頁 `CHECK_CONTENTS` 住另一個庫（`JSC_WIKI_REPO_CONTENTS`），版面是 H1 加 `>` 引言，再一台機器一個 H2 區塊，頁上沒有 markdown 表格；改由 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 只寫本機那一個區塊，欄位是 `- {欄位名}：{值}` 的條列。鍵是 H2 標題，也就是體檢頁頁名 `CHECK_{HASH}`，不是任何含網址的值：網址會隨站台、存取庫與頁名編碼改變，頁名只由主機加帳號決定，拿網址當鍵就比不中，同一台機器每體檢一次就多附一個區塊。第二個參數 `1` 是 `<key-col>`，只在頁面還是舊表格、需要自動轉檔時用得到，指舊表格裡持有 `[CHECK_{HASH}](網址)` 的第 1 欄。「體檢頁」那一條的連結給人點，填絕對網址。修復交給 `/jsc-cli:setup`，體檢本身不動任何設定。
|
||||
|
||||
### `setup`
|
||||
|
||||
修復 `/jsc-cli:doctor` 找出的問題，一次一項，逐項確認才動手。待修清單優先讀 wiki `CHECK_{HASH}`，沒有頁面就當場重掃：**三支檢查腳本併行跑**，再用 `tools/build-todo.sh` 合併成同一張表。依修法分流：`auto` 用 `tools/apply-config.sh` 直接寫、`ask` 先用決策樹問到值再寫、`manual` 印出步驟交給操作者。複合修復交回原主：版本落後找 `/jsc-cli:deploy`（連同已確認的模式與版本報告一起傳過去，不讓它重問重查）、hook 未接線找 `/jsc-hooks:hooks-install`、缺 `model-tags.tsv` 找 `/jsc-cli:models`。逐項確認維持循序，**寫完的重驗併行**；環境變數類只驗「rc 段落裡確實有那一行」，環境層面交給下一次 `/jsc-cli:doctor`。最後覆寫體檢頁 `CHECK_{HASH}`，並用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 4` 以裸 `HASH` 當鍵更新目錄頁 `CHECK_CONTENTS` 的本機那一列，兩頁分屬不同存取庫。
|
||||
修復 `/jsc-cli:doctor` 找出的問題，一次一項，逐項確認才動手。待修清單優先讀 wiki `CHECK_{HASH}`，沒有頁面就當場重掃：**三支檢查腳本併行跑**，再用 `tools/build-todo.sh` 合併成同一張表。依修法分流：`auto` 用 `tools/apply-config.sh` 直接寫、`ask` 先用決策樹問到值再寫、`manual` 印出步驟交給操作者。複合修復交回原主：版本落後找 `/jsc-cli:deploy`（連同已確認的模式與版本報告一起傳過去，不讓它重問重查）、hook 未接線找 `/jsc-hooks:hooks-install`、缺 `model-tags.tsv` 找 `/jsc-cli:models`。逐項確認維持循序，**寫完的重驗併行**；環境變數類只驗「rc 段落裡確實有那一行」，環境層面交給下一次 `/jsc-cli:doctor`。最後覆寫體檢頁 `CHECK_{HASH}`，並用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 以 H2 標題（也就是體檢頁頁名）當鍵，更新目錄頁 `CHECK_CONTENTS` 的本機那一個區塊，兩頁分屬不同存取庫。
|
||||
|
||||
<!-- JSC-SKILLS:END -->
|
||||
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-cli",
|
||||
"version": "0.2.8",
|
||||
"version": "0.3.2",
|
||||
"description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署",
|
||||
"skills": "./skills/",
|
||||
"jsc": {
|
||||
|
||||
+20
-20
@@ -7,47 +7,47 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 一件邊界清楚的工作要交給另一支已安裝的 AI agent CLI 執行時用。盤點模型（models）、部署技能組（deploy）、必須留在目前 agent 手上的工作都不用；給不出通過或失敗判準的目標也不用 |
|
||||
| 關鍵步驟 | 寫下一句目標與可判定通過或失敗的驗收條件、同時起跑 detect-clis.sh 與 list-models.sh 取得 CLI 清單與模型清單、先選定目標 CLI 再用 model-tags.sh 的 gate 或 model 驗證模型能力標籤、組出帶目標、驗收條件、目標 CLI、模型代號、最小脈絡、寫入範圍與 TSV 輸出合約的提示、開一個 sub agent 執行、查驗回傳的結束碼與 result、summary、criterion、wrote 各行、把成功、失敗、需要使用者補充分三段回報 |
|
||||
| 外部呼叫 | jsc-cli/tools/detect-clis.sh、jsc-cli/tools/list-models.sh、jsc-cli/tools/model-tags.sh（gate 與 model 兩個子命令）、一個代跑工作的 sub agent |
|
||||
| 完成條件 | 目標 CLI 與模型各只有一個，且模型通過能力要求；sub agent 回傳的每一條驗收條件都有判定；每個 wrote 路徑都落在寫入範圍內；報告分三段列出結果。中途停下時，停下的原因要寫在報告裡 |
|
||||
| 可驗證跡象 | 技能自己不寫檔。可檢查的是 sub agent 依寫入範圍實際改動的檔案，逐條列在回傳的 wrote 行上，照那些路徑去看即可比對；寫入範圍為空的唯讀委派沒有寫入跡象，只有回報內容 |
|
||||
| 關鍵步驟 | 寫下一句目標與可判定通過或失敗的驗收條件、同時起跑 detect-clis.sh 與 list-models.sh 取得 CLI 清單與模型清單、先選定目標 CLI 再用 model-tags.sh 的 gate 或 model 驗證模型能力標籤、組出帶目標、驗收條件、目標 CLI、模型代號、最小脈絡、寫入範圍與 TSV 輸出合約的提示、開一個 sub agent 執行、查驗回傳的結束碼與 result、summary、criterion、wrote 各行、把成功、失敗、需要使用者補充分三段回報，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:delegate 寫下這一輪的結果。收尾那一筆走每一條出口，連停在能力閘門那一條也要寫；status 五選一，sub agent 回 0 且每條驗收條件都 pass、wrote 也都在範圍內是 ok，能力鎖擋下所有候選模型、或一支 CLI 都沒偵測到、整輪沒開 sub agent 是 blocked，sub agent 非零退出、回傳格式不符、有驗收條件 fail、或 wrote 越界是 failed，sub agent 回 needs-input、工作只做一半等使用者補資料是 degraded，目標給不出通過或失敗判準、或請求裡包了兩個以上獨立目標而主動停手是 aborted。detail 只放目標 CLI 與模型代號，不放 sub agent 的輸出。腳本不在這台機器就安靜跳過，回報失敗不得改變這支技能的結果 |
|
||||
| 外部呼叫 | jsc-cli/tools/detect-clis.sh、jsc-cli/tools/list-models.sh、jsc-cli/tools/model-tags.sh（gate 與 model 兩個子命令）、jsc-hooks/tools/report-status.sh skill-end、一個代跑工作的 sub agent |
|
||||
| 完成條件 | 目標 CLI 與模型各只有一個，且模型通過能力要求；sub agent 回傳的每一條驗收條件都有判定；每個 wrote 路徑都落在寫入範圍內；報告分三段列出結果。中途停下時，停下的原因要寫在報告裡。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | 技能自己只寫這一筆事件。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:delegate，status 與 exit 就是這一輪的結果。另一項可檢查的是 sub agent 依寫入範圍實際改動的檔案，逐條列在回傳的 wrote 行上，照那些路徑去看即可比對；寫入範圍為空的唯讀委派沒有其他寫入跡象，只有回報內容與那一筆事件 |
|
||||
|
||||
## deploy
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 整組 jsc 技能要在這台機器的每一支已安裝 CLI 上安裝、更新或解除安裝時用。只處理單一技能不用；只想知道版本落後與否，看 doctor 就夠 |
|
||||
| 關鍵步驟 | 同時取得三項事實（detect-clis.sh 的 CLI 清單、version-guard.sh 的 report 版本表與 recommend 結論、marketplace.json 的 domain 清單）、把版本表原樣秀出並定出建議、依 jsc-ask 決策樹問出模式（呼叫端已帶模式就沿用並標明來源）、每支 CLI 各開一個 sub agent 同時跑 tools/deploy.sh {mode} {cli} {domain}...、安裝或更新後把 CLI 清單交給 jsc-hooks:hooks-install、整台機器跑一次 tools/write-guides.sh、彙整每支 CLI 的結果並要求重新啟動工作階段 |
|
||||
| 外部呼叫 | jsc-cli/tools/detect-clis.sh、jsc-cli/tools/deploy.sh、jsc-cli/tools/write-guides.sh、jsc-cli/tools/check-requires.sh（由 deploy.sh 在每個 domain 更新前轉呼叫）、jsc-hooks/hooks/version-guard.sh 的 report 與 recommend、jsc-hooks/hooks/restart-gate.sh require（由 deploy.sh 收尾轉呼叫）、jsc-gitea/tools/gitea.sh 讀 plugins/meta 的 marketplace.json、jsc-ask:ask、jsc-hooks:hooks-install |
|
||||
| 完成條件 | 每一支偵測到的 CLI 都回報結束碼與 result 行，每個 skip、warn、compat 行都照實列出；安裝或更新還要拿到 hooks-install 對每支 CLI 的總結，兩份指引都印出 wrote，收尾印出重啟指示與兩份指引路徑 |
|
||||
| 可驗證跡象 | 各 CLI 的外掛目錄多出或少掉 jsc-{domain}：claude 與 codex 在各自的 plugin 快取、copilot 在 installed-plugins、antigravity 與 kiro 走 $JSC_LOCAL_PLUGINS 的本地 clone 與 $JSC_KIRO_SKILLS 的複製。$JSC_HOME/restart-required.d/{cli} 出現這次的重啟狀態檔；$JSC_HOME/update-guide.md 與 $JSC_HOME/remove-guide.md 被重寫；各 CLI 的 hook 設定檔由 hooks-install 改寫 |
|
||||
| 關鍵步驟 | 先跑一次 `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，解到那一層就停，不再往下解成帶版本號的快取路徑——那種路徑放不進允許清單，版本號寫成萬用字元也對不上；同一步再跑 `[ -d "{剛印出來的路徑}" ]` 確認目錄存在，`JSC_HOME` 沒設時它印的是 `/current`、結束碼 0，非空又是絕對路徑，只看那兩項擋不下來。整輪只解這一次，之後每一次跨外掛腳本呼叫都填成那個字面絕對路徑，不留 `$JSC_HOME` 也不留波浪號；技能自己那四支 `tools/*.sh` 不在 `current` 底下（那裡只有 `jsc-assist`、`jsc-gitea`、`jsc-hooks`），根目錄取自 CLI 載入這支技能時講明的外掛基底目錄，原樣當字面絕對路徑用，一個指令都不跑，四支一律寫成 `{外掛根目錄}/tools/{腳本}`；那個基底目錄帶版本號，四次呼叫都會跳權限詢問，這一支有人在現場（第三步要問模式）所以按得掉，無人值守的技能不得照抄，叫用文字沒講明基底目錄就回報外掛根目錄不明並停手，不猜前綴——權限層靜態比對路徑，帶未展開變數的呼叫一律要人核准，無人看管的輪次會停在第一支腳本，補權限規則也擋不住，因為規則字面同樣是靜態比對；解不出來就停手回報。接著同時取得三項事實（detect-clis.sh 的 CLI 清單、version-guard.sh 的 report 版本表與 recommend 結論、marketplace.json 的 domain 清單）、把版本表原樣秀出並定出建議、依 jsc-ask 決策樹問出模式（呼叫端已帶模式就沿用並標明來源）、每支 CLI 各開一個 sub agent 同時跑 tools/deploy.sh {mode} {cli} {domain}...、安裝或更新後把 CLI 清單交給 jsc-hooks:hooks-install、整台機器跑一次 tools/write-guides.sh、彙整每支 CLI 的結果並要求重新啟動工作階段，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:deploy 寫下這一輪的結果。收尾那一筆接在彙整回報之後，不取代它；走每一條出口，連停在偵測不到 CLI 那一條也要寫。status 五選一，每支 CLI 都回 0、hooks-install 判定乾淨、兩份指引都寫成是 ok，偵測不到任何 CLI、整輪沒下過任何外掛命令是 blocked，marketplace 讀不到或每支 CLI 都失敗、冒煙結果出現 No such file 是 failed，部分 CLI 成功部分失敗、有 domain 被 skip、或 write-guides.sh 回 4 讓機器沒有最新指引是 degraded，使用者沒選模式或在第一支 CLI 開跑前停手是 aborted。detail 只放模式與各項筆數，cmd 與 exit 行留在回報裡 |
|
||||
| 外部呼叫 | `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，加上同一步的 `[ -d ]` 確認，是整輪唯一容許帶變數的兩個指令；跨外掛腳本一律用它組成的字面絕對路徑呼叫：{current 目錄}/jsc-hooks/hooks/version-guard.sh 的 report 與 recommend、{current 目錄}/jsc-gitea/tools/gitea.sh 讀 plugins/meta 的 marketplace.json、{current 目錄}/jsc-hooks/tools/report-status.sh skill-end。技能自己那四支腳本走外掛根目錄組成的字面絕對路徑：{外掛根目錄}/tools/detect-clis.sh、{外掛根目錄}/tools/deploy.sh、{外掛根目錄}/tools/write-guides.sh、{外掛根目錄}/tools/check-requires.sh（由 deploy.sh 在每個 domain 更新前轉呼叫）。第四步那段內文提到的 `jsc-hooks/hooks/version-guard.sh` 是在講擋人發生在哪一層，不是這支技能要下的呼叫，整輪只有第一步那一次真的跑它。另有 jsc-hooks/hooks/restart-gate.sh require（由 deploy.sh 收尾轉呼叫）、jsc-ask:ask、jsc-hooks:hooks-install |
|
||||
| 完成條件 | `current` 那個目錄在第一步就解出一條存在的絕對路徑（用 `[ -d ]` 查過，而且沒有再往下解成帶版本號的快取路徑），技能自己那四支腳本也有一條字面絕對的外掛根目錄可用，後續每一支腳本都用這兩條之一組成的字面絕對路徑呼叫；每一支偵測到的 CLI 都回報結束碼與 result 行，每個 skip、warn、compat 行都照實列出；安裝或更新還要拿到 hooks-install 對每支 CLI 的總結，兩份指引都印出 wrote，收尾印出重啟指示與兩份指引路徑。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | 各 CLI 的外掛目錄多出或少掉 jsc-{domain}：claude 與 codex 在各自的 plugin 快取、copilot 在 installed-plugins、antigravity 與 kiro 走 $JSC_LOCAL_PLUGINS 的本地 clone 與 $JSC_KIRO_SKILLS 的複製。$JSC_HOME/restart-required.d/{cli} 出現這次的重啟狀態檔；$JSC_HOME/update-guide.md 與 $JSC_HOME/remove-guide.md 被重寫；各 CLI 的 hook 設定檔由 hooks-install 改寫；$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:deploy，status 與 exit 就是這一輪的結果。回報與逐行紀錄裡出現的腳本路徑全是字面絕對路徑，找不到 `$JSC_HOME`、`$` 開頭或波浪號開頭的呼叫，唯一的例外是開頭那一次 `readlink -f "$JSC_HOME/current"` 與同一步的 `[ -d ]` 確認；跨外掛那幾支的路徑中段是 `current`，不是 `cache/jsc/{外掛}/{版本}`，技能自己那四支則一律是外掛根目錄接 `tools/`，沒有一支寫成裸的相對路徑 |
|
||||
|
||||
## doctor
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 裝完或更新完技能組、技能因設定或接線問題失敗、機器要交接前用。要動手修不用這支，那是 jsc-cli:setup |
|
||||
| 關鍵步驟 | 同時開四個 sub agent 收版本、hook 接線、設定與未登錄變數，每個 sub agent 回傳原始輸出行、把四份輸出各存成檔、依 templates/check-page.md 印出五個區塊並寫明掃描的專案目錄、用 tools/build-todo.sh 把三份輸出合成待修項目表、用程式取短主機名與登入帳號（主機名切掉第一個點之後的網域）交給 hash-id 算出 HASH、用 wiki-repo CHECK 解出的存取庫透過 jsc-gitea:wiki 整頁覆寫 CHECK_{HASH}、寫完再用 wiki-url 取該頁絕對網址填進第 1 欄的連結、用 wiki-contents.sh upsert CHECK 4 以第 4 欄的裸 HASH 當鍵把本機那一列寫進 CONTENTS 存取庫的 CHECK_CONTENTS、報出四項計數並視情況建議 /jsc-cli:setup |
|
||||
| 外部呼叫 | jsc-hooks/hooks/version-guard.sh report、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh status（一律帶 JSC_READONLY=1）、jsc-cli/tools/scan-config.sh 的 scan all 與 orphans、jsc-cli/tools/build-todo.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert、jsc-gitea:wiki |
|
||||
| 完成條件 | 四項檢查各有結論，或明寫無法驗證與原因；五個區塊與待修項目表都在畫面上；兩頁各自寫成功，或寫入略過連同結束碼一起回報，wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流，建不建新頁的判斷留在腳本裡，技能不自己建；必要項缺漏、設定錯誤、CLI 未接線、domain 落後四項計數都講出來 |
|
||||
| 可驗證跡象 | wiki 的 CHECK_{HASH} 頁（雜湊來源是 {短主機名}/{登入帳號}）被整頁覆寫成這次的結果；另一個存取庫的 CHECK_CONTENTS 多出本機那一列，或該列的缺漏數與最後體檢時間被更新；第 1 欄是連到體檢頁的絕對網址，第 4 欄是裸 HASH，也就是比對用的鍵，同一台機器重跑幾次都只有這一列，別台機器的列一個位元組都沒變。機器本身的設定、接線與版本都不動：這支技能不寫任何設定 |
|
||||
| 關鍵步驟 | 同時開四個 sub agent 收版本、hook 接線、設定與未登錄變數，每個 sub agent 回傳原始輸出行、把四份輸出各存成檔、依 templates/check-page.md 印出五個區塊並寫明掃描的專案目錄、用 tools/build-todo.sh 把三份輸出合成待修項目表、用程式取短主機名與登入帳號（主機名切掉第一個點之後的網域）交給 hash-id 算出 HASH、用 wiki-repo CHECK 解出的存取庫透過 jsc-gitea:wiki 整頁覆寫 CHECK_{HASH}、寫完再用 wiki-url 取該頁絕對網址、把要寫進兩頁的每個連結交給 jsc-gitea/tools/link-check.sh 驗證且只有結束碼 0 才往下寫、「體檢頁」那一條的連結寫成 `[CHECK_{HASH}]({絕對網址})`、用 wiki-contents.sh upsert CHECK 1 CHECK_{HASH} 以 H2 標題也就是體檢頁頁名當鍵，把本機那一個區塊寫進 CONTENTS 存取庫的 CHECK_CONTENTS，區塊檔是 `## CHECK_{HASH}` 那一行、一個空行，再照 templates/check-contents.md 的欄位順序每欄一條 `- {欄位名}：{值}`、報出四項計數並視情況建議 /jsc-cli:setup，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:doctor 寫下這一輪的結果。這一筆是這支技能唯一的寫入動作，記的是查到什麼，不動設定、不動接線、不動版本，唯讀合約照樣成立；走每一條出口都要寫。status 五選一，四項檢查都有結論、五個區塊與待修項目表都在畫面上、兩頁都寫成是 ok，任何一項報成無法驗證、離線讓 Gitea 相關列變成 skipped、或 wiki-repo 回 3 而略過寫頁是 degraded——唯讀技能讀不到來源就是這一種，金鑰失效回 7 或其他 API 失敗回 8 讓紀錄寫不成是 failed，使用者在寫頁之前喊停是 aborted。blocked 這支用不到：沒 CLI、沒登錄檔、沒 wiki 存放庫的機器一樣查得出四項發現，報成 blocked 會把做完的一輪講成沒做事。detail 只放四項計數 |
|
||||
| 外部呼叫 | jsc-hooks/hooks/version-guard.sh report、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh status（一律帶 JSC_READONLY=1）、jsc-cli/tools/scan-config.sh 的 scan all 與 orphans、jsc-cli/tools/build-todo.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/wiki-contents.sh upsert、jsc-hooks/tools/report-status.sh skill-end、jsc-gitea:wiki |
|
||||
| 完成條件 | 四項檢查各有結論，或明寫無法驗證與原因；五個區塊與待修項目表都在畫面上；每個要寫進頁面的連結都經 link-check.sh 驗過，結束碼 0 才寫，1 就兩頁都不寫並列出 DEAD 那幾筆，3 把 GITEA_HOST 排進待修項目最前面，7 停下來回報金鑰問題而不判成死連結；連結一律寫成文字加絕對網址的形式，H2 標題本身不放連結；兩頁各自寫成功，或寫入略過連同結束碼一起回報，wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流，結束碼 1 是組不出頁面內容或寫入失敗，頁上找不到本機那一個區塊不算錯、腳本改成附加，建不建新頁的判斷留在腳本裡，技能不自己建；必要項缺漏、設定錯誤、CLI 未接線、domain 落後四項計數都講出來。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | wiki 的 CHECK_{HASH} 頁（雜湊來源是 {短主機名}/{登入帳號}）被整頁覆寫成這次的結果；另一個存取庫的 CHECK_CONTENTS 多出本機那一個 H2 區塊，或該區塊的缺漏數與最後體檢時間被更新；區塊標題是 `## CHECK_{HASH}`，也就是比對用的鍵，標題上沒有連結也沒有網址，「體檢頁」那一條是 `[CHECK_{HASH}]({絕對網址})` 這種文字加連結的寫法，點下去連得到體檢頁，頁面上找不到同 wiki 的雙括號連結；欄位一律是 `- {欄位名}：{值}` 的條列，頁上沒有 markdown 表格，同一台機器重跑幾次都只有這一個區塊，別台機器的區塊一個位元組都沒變；連結驗不過的那一輪，兩頁都維持上一輪的內容。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:doctor，status 與 exit 就是這一輪的結果，那也是這支技能唯一寫得出來的檔案痕跡。機器本身的設定、接線與版本都不動：這支技能不寫任何設定 |
|
||||
|
||||
## models
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 要盤點各 CLI 可用模型、確認模型合不合 SDLC 階段的能力要求、或檢視階段閘門設定時用。切換模型不用，改 .jsc/models 與 models.conf 也不用 |
|
||||
| 關鍵步驟 | 同時起跑三個收集器（detect-clis.sh、list-models.sh 以 sub agent 執行、model-config.sh list）、對讀不到設定的 CLI 補上標「預設推定」的預設模型、依 references/model-tags.md 為每個模型掛能力標籤、印出 CLI、模型、標籤、使用中四欄表、跑 tools/model-tags.sh sync 把標籤表寫進 $JSC_HOME/model-tags.tsv、附上 SDLC 階段需求表與階段偏好模型表 |
|
||||
| 外部呼叫 | jsc-cli/tools/detect-clis.sh、jsc-cli/tools/list-models.sh、jsc-cli/tools/model-config.sh list、jsc-cli/tools/model-tags.sh sync、references/model-tags.md；標籤表上查不到的模型改用 jsc-ask:ask 發問 |
|
||||
| 完成條件 | 每支偵測到的 CLI 都有模型清單或一組預設推定；每個模型都掛到標籤，或已排進發問；sync 印出寫入路徑，失敗則連同結束碼回報；兩張階段表都列滿 plan、analyze、implement、maintain 四個階段 |
|
||||
| 可驗證跡象 | $JSC_HOME/model-tags.tsv 被重寫，內容就是這次掛好的標籤表；jsc-hooks/hooks/sdlc-gate.sh 讀的正是這份檔，檔案不在，SDLC 階段閘門就判不出來。各 CLI 的模型設定檔不動 |
|
||||
| 關鍵步驟 | 同時起跑三個收集器（detect-clis.sh、list-models.sh 以 sub agent 執行、model-config.sh list）、對讀不到設定的 CLI 補上標「預設推定」的預設模型、依 references/model-tags.md 為每個模型掛能力標籤、印出 CLI、模型、標籤、使用中四欄表、跑 tools/model-tags.sh sync 把標籤表寫進 $JSC_HOME/model-tags.tsv、附上 SDLC 階段需求表與階段偏好模型表，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:models 寫下這一輪的結果。收尾那一筆走每一條出口，連停在偵測不到 CLI 那一條也要寫；status 五選一，每支 CLI 都有模型清單、每個模型都掛到標籤、sync 回 0 印出路徑、兩張階段表都在是 ok，偵測不到任何 CLI、盤點那半段整個沒開始是 blocked，sync 非零而 model-tags.tsv 沒寫成、SDLC 閘門判不出來是 failed，讀不到某支 CLI 的設定而改用預設推定、有模型查不到標籤只能排進發問、或 model-config.sh 失敗讓偏好表變成未取得是 degraded，使用者在 sync 寫檔之前停手是 aborted。detail 只放 CLI 與模型筆數 |
|
||||
| 外部呼叫 | jsc-cli/tools/detect-clis.sh、jsc-cli/tools/list-models.sh、jsc-cli/tools/model-config.sh list、jsc-cli/tools/model-tags.sh sync、jsc-hooks/tools/report-status.sh skill-end、references/model-tags.md；標籤表上查不到的模型改用 jsc-ask:ask 發問 |
|
||||
| 完成條件 | 每支偵測到的 CLI 都有模型清單或一組預設推定；每個模型都掛到標籤，或已排進發問；sync 印出寫入路徑，失敗則連同結束碼回報；兩張階段表都列滿 plan、analyze、implement、maintain 四個階段。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | $JSC_HOME/model-tags.tsv 被重寫，內容就是這次掛好的標籤表；jsc-hooks/hooks/sdlc-gate.sh 讀的正是這份檔，檔案不在，SDLC 階段閘門就判不出來。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:models，status 與 exit 就是這一輪的結果。各 CLI 的模型設定檔不動 |
|
||||
|
||||
## setup
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | doctor 報出待修項目、要實際動手修這台機器時用。只想做唯讀體檢不用這支，那是 jsc-cli:doctor |
|
||||
| 關鍵步驟 | 用程式取短主機名與登入帳號算出 HASH，從 wiki-repo CHECK 解出的存取庫讀 CHECK_{HASH} 的待修項目表，讀不到就以 sub agent 同時重跑設定、接線、版本三個檢查器再用 build-todo.sh 合併、依 jsc-ask 決策樹逐項循序確認、依 fix 欄分流（auto 與 ask 走 apply-config.sh 的 set 或 mkdir、manual 印出步驟交給操作者、domain 落後轉呼叫 jsc-cli:deploy 並附上手上的版本報告、hook 未接線轉呼叫 jsc-hooks:hooks-install、缺 model-tags.tsv 轉呼叫 jsc-cli:models）、同時重驗每個已套用項目、重寫 CHECK_{HASH}、再用 wiki-url 取它的絕對網址填進第 1 欄的連結並以 wiki-contents.sh upsert CHECK 4 用第 4 欄的裸 HASH 當鍵更新 CONTENTS 存取庫的 CHECK_CONTENTS、報出已修、略過、轉呼叫、未修好四項計數 |
|
||||
| 外部呼叫 | jsc-cli/tools/scan-config.sh、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh status（一律帶 JSC_READONLY=1）、jsc-hooks/hooks/version-guard.sh report、jsc-cli/tools/build-todo.sh、jsc-cli/tools/apply-config.sh 的 set、mkdir 與 show、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert、jsc-ask:ask、jsc-gitea:wiki、jsc-cli:deploy、jsc-hooks:hooks-install、jsc-cli:models |
|
||||
| 完成條件 | 每一項都有已修、略過、轉呼叫或未修好的結果；每個已套用項目都由自己那一列指定的檢查器重驗過；每個寫進去的環境變數都附上 export 那一行；兩頁各自寫好或略過都有回報，wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流，建不建新頁的判斷留在腳本裡，技能不自己建；四項計數都講出來 |
|
||||
| 可驗證跡象 | 各 shell rc 檔的 `# jsc-config` 區塊被改寫，改寫前的備份落在 $JSC_HOME/backup/config/{時間戳}/；auto 路線建立的目錄實際出現在磁碟上；wiki CHECK_{HASH} 被改寫成修完後的狀態，另一個存取庫的 CHECK_CONTENTS 只有本機那一列跟著更新，第 1 欄是絕對網址，第 4 欄是當鍵用的裸 HASH；轉呼叫出去的項目留下各自技能的跡象，也就是 deploy 的重啟狀態檔、hooks-install 改寫的接線設定、models 產生的 model-tags.tsv |
|
||||
| 關鍵步驟 | 用程式取短主機名與登入帳號算出 HASH，從 wiki-repo CHECK 解出的存取庫讀 CHECK_{HASH} 的待修項目表，讀不到就以 sub agent 同時重跑設定、接線、版本三個檢查器再用 build-todo.sh 合併、依 jsc-ask 決策樹逐項循序確認、依 fix 欄分流（auto 與 ask 走 apply-config.sh 的 set 或 mkdir、manual 印出步驟交給操作者、domain 落後轉呼叫 jsc-cli:deploy 並附上手上的版本報告、hook 未接線轉呼叫 jsc-hooks:hooks-install、缺 model-tags.tsv 轉呼叫 jsc-cli:models）、同時重驗每個已套用項目、重寫 CHECK_{HASH}、再用 wiki-url 取它的絕對網址、把要寫進兩頁的每個連結交給 jsc-gitea/tools/link-check.sh 驗證且只有結束碼 0 才往下寫、「體檢頁」那一條的連結寫成 `[CHECK_{HASH}]({絕對網址})`、以 wiki-contents.sh upsert CHECK 1 CHECK_{HASH} 用 H2 標題也就是體檢頁頁名當鍵，更新 CONTENTS 存取庫的 CHECK_CONTENTS 上本機那一個區塊，區塊檔是 `## CHECK_{HASH}` 那一行、一個空行，再照 templates/check-contents.md 的欄位順序每欄一條 `- {欄位名}：{值}`、報出已修、略過、轉呼叫、未修好四項計數，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:setup 寫下這一輪的結果。收尾那一筆走每一條出口，連停在讀不到待修項目那一條也要寫；status 五選一，每一項都修好也重驗過、沒有略過、兩頁都寫成是 ok，環境不允許寫入、apply-config.sh 每一項都回 4 而一個 rc 檔都沒動到是 blocked，已套用的項目重驗仍失敗、apply-config.sh 回 2 是這支技能自己下錯命令、或金鑰失效回 7 與其他 API 失敗回 8 讓紀錄改寫不成是 failed，使用者否決某一項而那一項記成略過、或轉呼叫出去的修正沒收尾是 degraded，使用者在逐項確認到一半喊停、剩下的項目沒問到是 aborted。detail 只放四項計數，不放使用者輸入的值 |
|
||||
| 外部呼叫 | jsc-cli/tools/scan-config.sh、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh status（一律帶 JSC_READONLY=1）、jsc-hooks/hooks/version-guard.sh report、jsc-cli/tools/build-todo.sh、jsc-cli/tools/apply-config.sh 的 set、mkdir 與 show、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/wiki-contents.sh upsert、jsc-hooks/tools/report-status.sh skill-end、jsc-ask:ask、jsc-gitea:wiki、jsc-cli:deploy、jsc-hooks:hooks-install、jsc-cli:models |
|
||||
| 完成條件 | 每一項都有已修、略過、轉呼叫或未修好的結果；每個已套用項目都由自己那一列指定的檢查器重驗過；每個寫進去的環境變數都附上 export 那一行；每個要寫進頁面的連結都經 link-check.sh 驗過，結束碼 0 才寫，1 就兩頁都不寫並列出 DEAD 那幾筆，3 回報 GITEA_HOST 仍未修好，7 停下來回報金鑰問題而不判成死連結；連結一律寫成文字加絕對網址的形式，H2 標題本身不放連結；兩頁各自寫好或略過都有回報，wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流，結束碼 1 是組不出頁面內容或寫入失敗，頁上找不到本機那一個區塊不算錯、腳本改成附加，建不建新頁的判斷留在腳本裡，技能不自己建；四項計數都講出來。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | 各 shell rc 檔的 `# jsc-config` 區塊被改寫，改寫前的備份落在 $JSC_HOME/backup/config/{時間戳}/；auto 路線建立的目錄實際出現在磁碟上；wiki CHECK_{HASH} 被改寫成修完後的狀態，另一個存取庫的 CHECK_CONTENTS 只有本機那一個 H2 區塊跟著更新，區塊標題是當鍵用的 `## CHECK_{HASH}`，標題上沒有連結也沒有網址，「體檢頁」那一條是 `[CHECK_{HASH}]({絕對網址})` 這種文字加連結的寫法、點下去連得到體檢頁，頁面上找不到同 wiki 的雙括號連結，欄位一律是 `- {欄位名}：{值}` 的條列、頁上沒有 markdown 表格；連結驗不過的那一輪，兩頁都維持上一輪的內容；轉呼叫出去的項目留下各自技能的跡象，也就是 deploy 的重啟狀態檔、hooks-install 改寫的接線設定、models 產生的 model-tags.tsv；$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-cli:setup，status 與 exit 就是這一輪的結果 |
|
||||
|
||||
@@ -97,6 +97,22 @@ Detection and tag filtering are decided in code, not in prose: `jsc-cli/tools/de
|
||||
|
||||
Done when the CLI, the model, the requirement and the per-criterion verdicts are all in the report, and every failure recorded in step 6 appears in the failure section.
|
||||
|
||||
8. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 1 or step 3 included. Call
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-cli:delegate {status} {exit code} [detail]`
|
||||
|
||||
`{exit code}` is the exit code of whatever decided the outcome — the subagent's own status, or the `detect-clis.sh` or `model-tags.sh` call that ruled the run — and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters: the target CLI and the model id fit there, the subagent's output does not. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
|
||||
|
||||
| status | When this skill uses it |
|
||||
| --- | --- |
|
||||
| `ok` | The subagent exited 0, its output held one `result` and one `summary` line, every acceptance criterion came back `pass`, and every `wrote` path sat inside the write scope |
|
||||
| `blocked` | The capability gate stopped the delegation before it started, so no subagent ran: every candidate model returned `FAIL` or `UNKNOWN-MODEL` from `model-tags.sh gate`, `detect-clis.sh` exited 0 with no row, the CLI the user named is not on this machine, or the target CLI has no model row and no forced model |
|
||||
| `failed` | The delegation ran and broke: the subagent exited non-zero, its exit status could not be obtained at all, its output was missing the `result` or `summary` line, a criterion came back `fail`, or a `wrote` path landed outside the write scope. `detect-clis.sh` or `list-models.sh` exiting non-zero sits here too |
|
||||
| `degraded` | The subagent returned `result needs-input`: part of the goal is done and the rest waits on the user, so the report has a 需要使用者補充 section that is not empty. The delegation happened, the goal did not close |
|
||||
| `aborted` | The premise did not hold, so the skill stopped on its own: step 1 could give the goal no pass-or-fail acceptance criterion, or the request carried two or more independent goals and has to be split. Also used when the user stops the run before step 5 spawns the subagent |
|
||||
|
||||
Done when exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
|
||||
|
||||
## Do not use this skill
|
||||
|
||||
- Do not use it for model inventory. That is `/jsc-cli:models`.
|
||||
|
||||
+58
-8
@@ -5,6 +5,38 @@ description: Batch install, update, or uninstall the whole jsc skill set on ever
|
||||
|
||||
# deploy — batch install, update, or uninstall the skill set
|
||||
|
||||
## Path rule — every script call is a literal absolute path
|
||||
|
||||
Write every script call in this skill as a literal absolute path. Never hand the shell a path that still holds a variable or a tilde — `$JSC_HOME/...`, `~/.jsc/...`, or anything like them. The permission layer matches paths statically. It never expands a variable or a tilde, so such a path matches no allow rule, and the call falls through to an approval prompt. An unattended round has nobody to approve it. The run then dies at its first script, before it deploys anything.
|
||||
|
||||
Measured on a real machine, not assumed. `$JSC_HOME/current/jsc-assist/tools/patrol.sh` was blocked and never ran. `~/.jsc/current/...` was blocked and never ran. `/root/.jsc/current/...` ran. Adding an allow rule that itself starts with `$JSC_HOME` to `~/.claude/settings.json` changed nothing: the call stayed blocked. A wider allow list is not the fix, because the rule text is matched statically too.
|
||||
|
||||
Portability is no reason to put the variable back. Step 0 resolves the root once, at run time, on whatever machine this runs on — that is where portability comes from. Rewriting `{JSC_ROOT}/jsc-hooks/...` back to `$JSC_HOME/current/jsc-hooks/...` for tidiness re-breaks every unattended round.
|
||||
|
||||
## Step 0 — resolve the two roots, once
|
||||
|
||||
Before step 1, run this one command:
|
||||
|
||||
`readlink -f "$JSC_HOME/current"`
|
||||
|
||||
It prints one absolute directory: the absolute path of the `current` directory itself. Call it `{JSC_ROOT}` for the rest of this document. **Stop at that directory — never resolve one level further.** `current` is an ordinary directory, and the symbolic links are its entries, one per plugin; resolving one of those entries lands on the versioned plugin cache (`/root/.claude/plugins/cache/jsc/jsc-hooks/0.4.2`, say), and a versioned path is exactly the kind no allow rule can hold — a rule with `*` where the version segment goes matches nothing, measured. `{JSC_ROOT}` is the version-free root, and staying at it is the whole point. This is the only place a variable may appear. The shell expands it inside the command itself, so no unexpanded path ever reaches the permission layer.
|
||||
|
||||
Substitute `{JSC_ROOT}` with that directory in every later call, so what runs is a literal absolute path. `{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh` becomes, for example, `/root/.jsc/current/jsc-hooks/hooks/version-guard.sh`.
|
||||
|
||||
Resolve it once, at the start of the run. Do not re-resolve it per call. Do not add a tool that prints it.
|
||||
|
||||
Empty output, a non-zero exit, or a path that is not an existing directory → stop and report that `$JSC_HOME/current` does not resolve. **The third item is the one the first two wave through**, so check it: with `JSC_HOME` unset the command prints `/current` and exits 0 — non-empty, absolute, and nowhere — and every literal path built from it then names a place that is not there. Run `[ -d "{the path just printed}" ]` in the same approved step as the resolve, and treat only an existing directory as a root. Every cross-plugin script this skill calls lives under it.
|
||||
|
||||
### The second root — this skill's own `tools/`
|
||||
|
||||
`jsc-cli` is **not** one of the links under `{JSC_ROOT}`; that directory carries `jsc-assist`, `jsc-gitea` and `jsc-hooks` and nothing else. So `tools/detect-clis.sh`, `tools/deploy.sh`, `tools/check-requires.sh` and `tools/write-guides.sh` cannot be reached through `{JSC_ROOT}`, and none of them may be written as a bare relative path either — the rule above wants a literal absolute path at every call site, and a call site with no way to build one is where a prefix gets guessed.
|
||||
|
||||
They sit at `{plugin root}/tools/`, and the plugin root is the base directory the CLI states when it loads this skill. Take that literal path verbatim, call it `{CLI_ROOT}`, and write all four calls as `{CLI_ROOT}/tools/{script}` — `/root/.claude/plugins/cache/jsc/jsc-cli/0.3.2/tools/deploy.sh`, for example. No command runs for this one, and it is taken once, like `{JSC_ROOT}`.
|
||||
|
||||
That base directory carries a version segment, so no allow rule covers it and each of those four calls raises an approval prompt. **That is acceptable in this skill and in no unattended one**: `deploy` runs with a person in front of it — step 3 asks them for the mode, step 4 rewrites every CLI's plugin set — so there is somebody to approve. Never carry this branch into a skill that runs from a scheduler, and never guess a prefix when the invocation states no base directory: report that this skill's own plugin root is unknown and stop, because a guessed prefix runs some other version's copy of these scripts, or nothing at all.
|
||||
|
||||
Done when `{JSC_ROOT}` holds one existing absolute directory and `{CLI_ROOT}` holds one literal absolute path.
|
||||
|
||||
## Inputs a caller may pass
|
||||
|
||||
`jsc-cli:setup` already confirmed the mode with the user and already holds a fresh version report. Re-asking and re-querying would put a second decision tree in front of someone who just answered it.
|
||||
@@ -20,13 +52,13 @@ Nothing passed in → run every step as written below.
|
||||
|
||||
1. Collect the three facts the rest of the run needs. They are independent, so start all three at once and wait for all three.
|
||||
|
||||
1. **Installed CLIs** — `tools/detect-clis.sh`, printing `{name}<TAB>{path}<TAB>{version}`. Exit 0 with at least one row → take the CLI list from it. Exit 0 with no row → stop, and report that none of claude, codex, copilot, antigravity, kiro is installed. Any non-zero exit → stop and report the exit code and stderr; never guess a CLI list.
|
||||
2. **Version evidence and recommendation** — two subcommands of `jsc-hooks/hooks/version-guard.sh`, both needed, run together: `report` prints the per-plugin rows `{domain}<TAB>{本機}<TAB>{遠端}<TAB>{落後|最新|超前|查詢失敗}` closing with `behind<TAB>{count}`, and `recommend` prints one single line and nothing else — `recommend<TAB>{update|none|unverifiable}`. `recommend` deliberately never reprints the table, so its second column stays readable by `cut`; the version table that steps 2, 3 and 7 show comes from `report`, and the conclusion comes from `recommend`. Skip this collector when the caller passed a version report.
|
||||
1. **Installed CLIs** — `{CLI_ROOT}/tools/detect-clis.sh`, printing `{name}<TAB>{path}<TAB>{version}`. Exit 0 with at least one row → take the CLI list from it. Exit 0 with no row → stop, and report that none of claude, codex, copilot, antigravity, kiro is installed. Any non-zero exit → stop and report the exit code and stderr; never guess a CLI list.
|
||||
2. **Version evidence and recommendation** — two subcommands of `{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh`, both needed, run together: `report` prints the per-plugin rows `{domain}<TAB>{本機}<TAB>{遠端}<TAB>{落後|最新|超前|查詢失敗}` closing with `behind<TAB>{count}`, and `recommend` prints one single line and nothing else — `recommend<TAB>{update|none|unverifiable}`. `recommend` deliberately never reprints the table, so its second column stays readable by `cut`; the version table that steps 2, 3 and 7 show comes from `report`, and the conclusion comes from `recommend`. Skip this collector when the caller passed a version report.
|
||||
3. **Domain list** — read `plugins[].name` from the unified marketplace (**never hardcode it**; this skill then follows automatically when domains are added or removed):
|
||||
`jsc-gitea/tools/gitea.sh api GET /repos/plugins/meta/raw/.claude-plugin/marketplace.json`.
|
||||
`{JSC_ROOT}/jsc-gitea/tools/gitea.sh api GET /repos/plugins/meta/raw/.claude-plugin/marketplace.json`.
|
||||
Exit 0 with at least one `plugins[].name` → use that list. Exit 0 with an empty or unparseable list → stop and report that the marketplace holds no plugin entry. Any non-zero exit → stop and report the exit code and stderr; a partial domain list would install a partial skill set and look successful.
|
||||
|
||||
The marketplace is unified as `jsc`; the install token is `jsc-{domain}@jsc`. Each `plugins[].name` already carries the `jsc-` prefix (e.g. `jsc-ask`) — pass it to `tools/deploy.sh` as-is, prefixed or not; the script normalizes it.
|
||||
The marketplace is unified as `jsc`; the install token is `jsc-{domain}@jsc`. Each `plugins[].name` already carries the `jsc-` prefix (e.g. `jsc-ask`) — pass it to `{CLI_ROOT}/tools/deploy.sh` as-is, prefixed or not; the script normalizes it.
|
||||
|
||||
Done when the CLI list holds at least one CLI, the domain list holds at least one name, and the recommendation is either in hand or explicitly inherited from the caller.
|
||||
|
||||
@@ -50,7 +82,7 @@ Nothing passed in → run every step as written below.
|
||||
|
||||
Done when the user has named exactly one of `install`, `update` or `uninstall`, or the inherited mode is named with its source.
|
||||
|
||||
4. Run `tools/deploy.sh {mode} {cli} {domain}...` once per detected CLI, passing the whole domain list in one call so the marketplace command runs only once. This step **MUST run as a sub agent**, one sub agent per CLI, and **all of them start together** — the CLIs write to separate plugin directories, so serialising them only adds up their install times.
|
||||
4. Run `{CLI_ROOT}/tools/deploy.sh {mode} {cli} {domain}...` once per detected CLI, passing the whole domain list in one call so the marketplace command runs only once. This step **MUST run as a sub agent**, one sub agent per CLI, and **all of them start together** — the CLIs write to separate plugin directories, so serialising them only adds up their install times.
|
||||
|
||||
The script prints `cmd` and `exit` lines for every command, one `requires` line before each domain update, optional `compat` lines for Codex cache links, and one `result` line at the end; `-n` prints the commands without running them.
|
||||
|
||||
@@ -61,17 +93,17 @@ Nothing passed in → run every step as written below.
|
||||
| 2 | Usage error — the mode, the CLI name or the domain list is wrong. Report it as a defect in this skill, and do not retry with a guessed argument |
|
||||
| other | Record that CLI as failed with the exit code and stderr |
|
||||
|
||||
On update, `tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. Exit 0 updates the domain as usual. Exit 1 — a missing or too-old required jsc plugin — prints a `warn` line and the domain **is still updated**: skipping it would leave a behind domain permanently unable to reach the version its dependency needs. The block lives one layer up, at skill invocation time, where `jsc-hooks/hooks/version-guard.sh` stops that domain's skills. Exit 4 — the manifest is unreadable, is not valid JSON, or python3 is missing — prints a `note` line and also still updates the domain: no verdict is not the same fact as behind, so it gets its own line rather than a `warn` that would send the operator hunting for a version problem that is not there. Exit 2 or any other code — a `check-requires.sh` usage error or a broken script — prints a `skip` line and leaves that domain untouched, because a checker that failed outright is not a pass. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.
|
||||
On update, `{CLI_ROOT}/tools/check-requires.sh {cli} {manifest}` checks each domain's `jsc.requires` before that domain is updated. Exit 0 updates the domain as usual. Exit 1 — a missing or too-old required jsc plugin — prints a `warn` line and the domain **is still updated**: skipping it would leave a behind domain permanently unable to reach the version its dependency needs. The block lives one layer up, at skill invocation time, where `jsc-hooks/hooks/version-guard.sh` stops that domain's skills. **That last mention is a description of where the block happens, not a call this skill makes** — nothing here runs `version-guard.sh` except step 1.2, which is written as `{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh`, so do not read it as a call site that was left un-prefixed. Exit 4 — the manifest is unreadable, is not valid JSON, or python3 is missing — prints a `note` line and also still updates the domain: no verdict is not the same fact as behind, so it gets its own line rather than a `warn` that would send the operator hunting for a version problem that is not there. Exit 2 or any other code — a `check-requires.sh` usage error or a broken script — prints a `skip` line and leaves that domain untouched, because a checker that failed outright is not a pass. Codex update preserves old `jsc-cli` and `jsc-hooks` cache version paths as symlinks to the newest installed version, so a still-running Codex deploy can keep using its helper scripts and a still-running Codex session whose hook_run_id points at the old cache can finish without `No such file`. Antigravity cannot install from a Gitea URL, so the script clones each domain into the local plugin directory (`JSC_LOCAL_PLUGINS`, default `$JSC_HOME/plugins`) and installs from that path — keep that clone, because update pulls the same one. That default deliberately avoids a development checkout: when the directory holds uncommitted changes or unpushed commits, the script prints a `skip` line, leaves the tree untouched, and installs the on-disk content.
|
||||
|
||||
Done when every detected CLI has reported an exit code and a `result` line, every skipped domain has a checker-failure reason or a local-tree reason, and every `warn` domain is named with the version it still has to catch up to.
|
||||
|
||||
5. After install or update, call `jsc-hooks:hooks-install` and **hand it the CLI list from step 1.1**, so it does not probe the same five executables a second time. `hooks-install` still detects for itself when it receives no list — that fallback is what keeps it usable on its own.
|
||||
|
||||
Take its aggregate result rather than re-reading each CLI's smoke detail; the installer already judged purge, wiring, smoke and scan per CLI, and refreshes `$JSC_HOME/current/jsc-hooks` on the way — the path `deploy.sh` follows to reach `restart-gate.sh`. Keep exactly one extra judgement here, because it is a deploy-side fact the installer does not rule on: **a smoke result containing `No such file` is a failed update**, since it means a rewritten hook path cannot execute. Report it and do not let the deploy finish as successful.
|
||||
Take its aggregate result rather than re-reading each CLI's smoke detail; the installer already judged purge, wiring, smoke and scan per CLI, and refreshes `{JSC_ROOT}/jsc-hooks` on the way — the path `deploy.sh` follows to reach `restart-gate.sh`. Keep exactly one extra judgement here, because it is a deploy-side fact the installer does not rule on: **a smoke result containing `No such file` is a failed update**, since it means a rewritten hook path cannot execute. Report it and do not let the deploy finish as successful.
|
||||
|
||||
Done when hooks-install has returned an aggregate verdict for every CLI in the list, and every `No such file` in it is reported as an update failure.
|
||||
|
||||
6. After install or update, run `tools/write-guides.sh {mode} {domain}...` **once for the whole machine**, after every CLI in step 4 has finished. It rewrites `$JSC_HOME/update-guide.md` and `$JSC_HOME/remove-guide.md` from the live detection result, so the later update and removal runs have the real commands for this machine. Skip it for `uninstall`: the guides describe an installed skill set.
|
||||
6. After install or update, run `{CLI_ROOT}/tools/write-guides.sh {mode} {domain}...` **once for the whole machine**, after every CLI in step 4 has finished. It rewrites `$JSC_HOME/update-guide.md` and `$JSC_HOME/remove-guide.md` from the live detection result, so the later update and removal runs have the real commands for this machine. Skip it for `uninstall`: the guides describe an installed skill set.
|
||||
|
||||
| Exit | Action |
|
||||
| --- | --- |
|
||||
@@ -87,3 +119,21 @@ Nothing passed in → run every step as written below.
|
||||
For install or update, the same block ends with the restart instruction, in these words: 「請關閉目前的工作階段並重新啟動，新的技能內容才會載入」. `deploy.sh` recorded this round in `$JSC_HOME/restart-required.d/{cli}` — one file per CLI — and prints its path on a `restart` line; `jsc-hooks` reads only that CLI's own file and keeps reminding until that CLI restarts, with `JSC_RESTART_GATE=off` as the escape hatch. Restarting one CLI clears its own file and leaves the others' gates standing. Name the two guide paths from step 6 in that same closing block, so the operator knows where this machine's update and removal commands now live.
|
||||
|
||||
Done when every detected CLI appears in the report with its `result` status, and — for install or update — the restart instruction is printed with both guide paths named, or step 6's failure is repeated in their place.
|
||||
|
||||
8. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 1 included. Call
|
||||
|
||||
`{JSC_ROOT}/jsc-hooks/tools/report-status.sh skill-end jsc-cli:deploy {status} {exit code} [detail]`
|
||||
|
||||
`{exit code}` is the exit code of whatever decided the outcome — the worst `deploy.sh` exit of the run, or the collector that stopped step 1 — and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters: the mode and the per-CLI counts fit there, the `cmd` and `exit` lines do not. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
|
||||
|
||||
Record it after step 7's block, never instead of it. The event stream carries one status; the operator still needs the per-CLI report on screen.
|
||||
|
||||
| status | When this skill uses it |
|
||||
| --- | --- |
|
||||
| `ok` | Every detected CLI's `deploy.sh` exited 0, hooks-install returned a clean verdict for each of them with no `No such file` in any smoke result, and both guides printed their `wrote` line |
|
||||
| `blocked` | Nothing was deployed because there was nothing to deploy to: `detect-clis.sh` exited 0 with no row, so none of claude, codex, copilot, antigravity, kiro is installed and the run stops before any plugin command |
|
||||
| `failed` | The run broke: the marketplace read in step 1.3 exited non-zero or returned no plugin entry, or every detected CLI's `deploy.sh` came back non-zero. Also used when a smoke result carries `No such file`, which this skill judges as a failed update even when hooks-install did not |
|
||||
| `degraded` | The deploy landed on part of the machine only: some CLIs exited 0 while others failed, a domain was left untouched by a `skip` line from `check-requires.sh`, or `write-guides.sh` exited 4 so the plugins are installed but this machine has no up-to-date update and remove guide |
|
||||
| `aborted` | The user chose none of `install`, `update` or `uninstall` at step 3, or stopped the run before step 4 launched the first CLI, so no plugin command ran |
|
||||
|
||||
Done when exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
|
||||
|
||||
+52
-11
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: doctor
|
||||
description: Health-check the execution environment in one pass and record the result, changing nothing. Four checks - plugin versions from jsc-hooks/hooks/version-guard.sh report, hook wiring from jsc-hooks/tools/wire-cli.sh status, settings from tools/scan-config.sh against tools/config-spec.tsv, and orphan variables. Report one findings table per check, build the 待修項目 table with tools/build-todo.sh, then write the whole run to wiki CHECK_{HASH} where HASH comes from {short hostname}/{user}; the page keeps only the latest run, while its CHECK_CONTENTS row is upserted through wiki-contents.sh into the contents repo. Use after installing or updating the skill set, when a skill fails on a settings or wiring problem, or before handing a machine over; not for applying fixes, which is jsc-cli:setup.
|
||||
description: Health-check the execution environment in one pass and record the result, changing nothing. Four checks - plugin versions from jsc-hooks/hooks/version-guard.sh report, hook wiring from jsc-hooks/tools/wire-cli.sh status, settings from tools/scan-config.sh against tools/config-spec.tsv, and orphan variables. Report one findings table per check, build the 待修項目 table with tools/build-todo.sh, then write the whole run to wiki CHECK_{HASH} where HASH comes from {short hostname}/{user}; the page keeps only the latest run, while its CHECK_CONTENTS block is upserted through wiki-contents.sh into the contents repo. Use after installing or updating the skill set, when a skill fails on a settings or wiring problem, or before handing a machine over; not for applying fixes, which is jsc-cli:setup.
|
||||
---
|
||||
|
||||
# doctor — execution environment health check
|
||||
@@ -115,29 +115,49 @@ user=${USER:-$(id -un 2>/dev/null || printf 'unknown')}
|
||||
|
||||
**`CHECK_{HASH}` — content page.** Repo: `jsc-gitea/tools/gitea.sh wiki-repo CHECK`. Write it through `jsc-gitea:wiki` and overwrite the whole page, because this page type keeps only the latest run of this one machine. Whole-page overwrite is correct here and forbidden on the page below.
|
||||
|
||||
**`CHECK_CONTENTS` — contents page, in the contents repo.** Repo: `gitea.sh wiki-repo CONTENTS`. Every contents page lives there now; it never falls back to `JSC_WIKI_REPO_CHECK`. Do not hand-edit it — write the row with
|
||||
**`CHECK_CONTENTS` — contents page, in the contents repo.** Repo: `gitea.sh wiki-repo CONTENTS`. Every contents page lives there now; it never falls back to `JSC_WIKI_REPO_CHECK`. It is an H1, a `>` preamble and one H2 block per machine — no markdown table anywhere on it. Do not hand-edit it — write the block with
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert CHECK 4 "{HASH}" {row file} templates/check-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 "CHECK_{HASH}" {block file} templates/check-contents.md`
|
||||
|
||||
The script reads the page back, replaces this machine's row or appends it, then writes the whole page. That keeps the rule in one place: one row per run, never a whole-page overwrite, never another machine's row — those rows are other people's records, and this run read them from nowhere else.
|
||||
The block file holds the whole H2 block: the `## CHECK_{HASH}` line, a blank line, then one bullet per field in the order `templates/check-contents.md` lists them, written as `- {欄位名}：{值}` with a full-width colon. Every field of the template gets a bullet, `HASH` included — the heading is the key, and a field only in the heading is a field the next reader cannot read.
|
||||
|
||||
**The key is column 4, the bare `HASH`.** `4` is the 1-based index of the `HASH` column in `templates/check-contents.md`, and the key is the exact string `hash-id` printed — 40 uppercase hex characters, not shortened, not prefixed, not wrapped in a link. The script compares the whole cell, so the key and that cell must match character for character.
|
||||
The script reads the page back, replaces this machine's block or appends it, then writes the whole page. That keeps the rule in one place: one block per run, never a whole-page overwrite, never another machine's block — those blocks are other people's records, and this run read them from nowhere else.
|
||||
|
||||
The key is the bare hash and not the link cell for a reason: a cell holding a URL changes whenever `GITEA_HOST` changes, whenever `JSC_WIKI_REPO_CHECK` moves to another repo, or whenever Gitea encodes the page name differently. The comparison then never matches, and every run appends another row for the same machine — silently, because the page still looks right.
|
||||
**The key is the H2 heading, `CHECK_{HASH}`.** It is the name of the content page this block points at: the literal `CHECK_` plus exactly what `hash-id` printed — 40 uppercase hex characters, not shortened, not otherwise prefixed, not wrapped in a link, no date appended. The script compares the whole heading text after trimming, so the key and that heading must match character for character.
|
||||
|
||||
Column 1 stays the human-facing link and is never the key. Build it as an **absolute URL** from `gitea.sh wiki-url {CHECK repo} CHECK_{HASH}`. `[[CHECK_{HASH}]]` resolves only inside its own wiki, and the two pages are no longer in the same one. Fetch the URL after `CHECK_{HASH}` is written: `wiki-url` exits 4 on a page that does not exist yet.
|
||||
The page name is the key because it is the one value that does not move. It is decided by `{host}/{user}` alone, so it survives a changed `GITEA_HOST`, a `JSC_WIKI_REPO_CHECK` moved to another repo, and a different Gitea encoding of the page name — all of which change the URL. Key on anything holding a URL and the comparison never matches, so every run appends a second block for the same machine — silently, because the page still looks right.
|
||||
|
||||
`1` is `<key-col>`, and it only matters while a page is still the old markdown table: it is the 1-based index of the column that held the identity, the `[CHECK_{HASH}]({URL})` cell in column 1, whose text becomes the H2 heading when the script converts that table to blocks. On a page already in block form the script ignores it.
|
||||
|
||||
The `體檢頁` bullet stays the human-facing link and is never the key; the heading itself carries no link and no URL. Write the bullet as `[CHECK_{HASH}]({absolute URL})` — text plus link, the one link form this skill set uses. The URL comes from `gitea.sh wiki-url {CHECK repo} CHECK_{HASH}` and is never composed by hand. Fetch it after `CHECK_{HASH}` is written: `wiki-url` exits 4 on a page that does not exist yet.
|
||||
|
||||
A same-wiki link form resolves only inside its own wiki, and the two pages are no longer in the same one. It fails without an error, reading on screen as plain text or a dead link, so nobody finds it and nobody fixes it.
|
||||
|
||||
**Verify every link before writing it.** Collect every URL heading into `CHECK_{HASH}` or into the `CHECK_CONTENTS` block, then hand the whole list to `jsc-gitea/tools/link-check.sh`. It prints `{OK|DEAD|SKIP}<TAB>{URL}<TAB>{reason}` per line. Only exit 0 may be written.
|
||||
|
||||
| Exit | Meaning | Action |
|
||||
| --- | --- | --- |
|
||||
| 0 | Every link answers | Write the page |
|
||||
| 1 | At least one link is unreachable | Write nothing, on either page. Report the `DEAD` lines to the caller |
|
||||
| 2 | Usage error: no URL was given | Report it as a defect in this skill and pass the URLs |
|
||||
| 3 | The list holds a Gitea URL but `GITEA_HOST` is unset | Skip both writes and put `GITEA_HOST` at the top of 待修項目. Never write without verifying |
|
||||
| 7 | Gitea authentication failed | Stop and report the key problem. This is not a dead link |
|
||||
|
||||
Exit 7 stays apart from exit 1 on purpose: with a dead key, Gitea's answer for a private repo looks the same as "page absent". Merge the two and one expired key marks every live page dead, and the blocks pointing at them get rewritten or dropped.
|
||||
|
||||
The script asks the API and never reads a web status code. A private repo's web URL answers 404 to a request with no credentials, so status codes turn good links into dead ones.
|
||||
|
||||
| Exit | Meaning | Action |
|
||||
| --- | --- | --- |
|
||||
| 0 | `updated` or `added` | Report which one it printed, with the repo and page it named |
|
||||
| 1 | Write failed | Nothing landed. Report it with the stderr, and keep 2.1's tables on screen |
|
||||
| 1 | The page content could not be built, or the write failed | Nothing landed. Report it with the stderr, and keep 2.1's tables on screen. A page with no block to replace is not this case: the script appends instead |
|
||||
| 2 | Usage error | Report it as a defect in this skill. Do not retry with guessed arguments. A `templates/check-contents.md` that is not on disk also lands here — then name the path the script looked for, confirm the plugin install is complete, and rerun |
|
||||
| 3 | No contents repo configured | Skip this write and put `JSC_WIKI_REPO_CONTENTS` at the top of 待修項目 |
|
||||
| 4 | Page absent and no template given | Unreachable the way this skill calls the script — the command above always passes `templates/check-contents.md`. A template that is not on disk comes back as exit 2, not 4. So treat a 4 as a malformed call: report it as a defect in this skill, name the command that produced it, and do not retry with guessed arguments |
|
||||
| 7 | Key invalid or no permission | Nothing was read and nothing written. Name the exit code and create nothing |
|
||||
| 8 | Any other API failure | Same as 7: the old rows are unknown, so name the exit code and create nothing |
|
||||
| 8 | Any other API failure | Same as 7: the old blocks are unknown, so name the exit code and create nothing |
|
||||
|
||||
Exits 7 and 8 never mean the page is missing. Writing a fresh template over a directory whose rows were never read wipes every other machine's row, with no merge and no backup behind it — which is exactly why the script creates a page only when its own read reported that page absent, and why it owns that branch instead of this prose.
|
||||
Exits 7 and 8 never mean the page is missing. Writing a fresh template over a directory whose blocks were never read wipes every other machine's block, with no merge and no backup behind it — which is exactly why the script creates a page only when its own read reported that page absent, and why it owns that branch instead of this prose.
|
||||
|
||||
`wiki-repo` exiting 3 means that page type has no wiki repo configured: `JSC_WIKI_REPO_CHECK` for the content page, `JSC_WIKI_REPO_CONTENTS` for the contents page. Print the tables, skip that one write, and put the unset variable at the top of 待修項目 — it is itself a finding, so a failed write never fails the health check. Any other non-zero exit from `wiki-repo`, `wiki-url`, `hash-id` or the wiki write is reported the same way: tables on screen, write skipped, exit code named.
|
||||
|
||||
@@ -145,4 +165,25 @@ Exits 7 and 8 never mean the page is missing. Writing a fresh template over a di
|
||||
|
||||
State the four counts from 2.2's `summary` line: required items missing, settings invalid, CLIs unwired, domains behind. Recommend `/jsc-cli:setup` when any of those is above zero. Never fix anything here.
|
||||
|
||||
Done when each of the two pages is reported with its URL, or its skipped write is reported together with its reason, **and** the four counts are stated with the recommendation given or explicitly withheld.
|
||||
Done when every link written into either page passed `link-check.sh` first — or the `DEAD` list is on screen and that write was skipped — each of the two pages is reported with its URL, or its skipped write is reported together with its reason, **and** the four counts are stated with the recommendation given or explicitly withheld.
|
||||
|
||||
### 3.3 Record how the run ended
|
||||
|
||||
This is the last thing this skill does, and it runs on every path out of the skill. Call
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-cli:doctor {status} {exit code} [detail]`
|
||||
|
||||
`{exit code}` is the exit code of whatever decided the outcome, and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters: the four counts fit there, the five blocks do not. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
|
||||
|
||||
This one call writes, and it is the only write this skill makes. It records what the run found; it changes no setting, no wiring and no version, so the read-only contract of the opening paragraph still holds.
|
||||
|
||||
| status | When this skill uses it |
|
||||
| --- | --- |
|
||||
| `ok` | All four checks reached a conclusion, the five blocks and the 待修項目 table are on screen, and both pages were written |
|
||||
| `degraded` | The checkup ran but part of it has no conclusion, and this is the common outcome for a read-only skill that cannot reach a source. Any check reported as 無法驗證 lands here — `version-guard.sh report` exiting non-zero, `scan-config.sh` exiting 3 on a missing spec table, `wire-cli.sh status` returning an unexpected code, a Gitea-dependent row coming back `skipped` in offline mode — and so does a `wiki-repo` exit 3 that skipped a page write, which this skill treats as a finding rather than a fault |
|
||||
| `failed` | Reading the machine worked, then recording it broke on an error: `link-check.sh`, `gitea.sh` or `wiki-contents.sh` returned 7 on an invalid key, or 8 on any other API failure. Both are errors, never an absent page, and neither leaves a usable record |
|
||||
| `aborted` | The user stopped the run before the record was written, for example by declining to supply `GITEA_HOST` and asking to end the checkup there |
|
||||
|
||||
`blocked` has no place in this skill. Nothing gates a read-only checkup: a machine with no CLI installed, no plugin registry and no wiki repo still produces four findings, and reporting that as `blocked` would hide a run that did its whole job.
|
||||
|
||||
Done when exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
|
||||
|
||||
@@ -38,3 +38,19 @@ description: 'List every model usable by each installed AI CLI (claude, codex, c
|
||||
2. A 「階段偏好模型」 table right after it, built from collector 1.3's rows, with three columns: stage, chain, source (`project` / `global`). State below the table that the chain does **not** grant passage: it only names the model to suggest switching to when the gate blocks, and expresses preference among models that already satisfy the required tags.
|
||||
|
||||
Done when the requirement table shows all four stages with their required tags, and the 階段偏好模型 table shows the same four stages with `-` for unconfigured ones.
|
||||
|
||||
7. **Record how the run ended.** This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 1 included. Call
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-cli:models {status} {exit code} [detail]`
|
||||
|
||||
`{exit code}` is the exit code of whatever decided the outcome — usually `model-tags.sh sync` — and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters: the CLI and model counts fit there, the four-column table does not. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
|
||||
|
||||
| status | When this skill uses it |
|
||||
| --- | --- |
|
||||
| `ok` | Every detected CLI has a model list, every model carries a tag, `sync` exited 0 and printed the path, and both stage tables are on screen |
|
||||
| `blocked` | Nothing could be inventoried because nothing is installed: `detect-clis.sh` exited 0 with no row, so steps 2 to 4 have no CLI to work on. The tag table and the stage requirements are still printed, so say in `{detail}` that the inventory half of the run never started |
|
||||
| `failed` | `model-tags.sh sync` returned 1, 2 or any other non-zero code, so `$JSC_HOME/model-tags.tsv` was not written and the SDLC gate stays broken until it is. `detect-clis.sh` exiting non-zero sits here too |
|
||||
| `degraded` | The tag table was written but the picture is incomplete: `list-models.sh` stayed silent for a CLI so step 2 fell back to 「預設推定」 defaults, a model is missing from `references/model-tags.md` and was queued as a `jsc-ask:ask` question instead of tagged, or `model-config.sh list` failed so the 階段偏好模型 table shows 未取得 |
|
||||
| `aborted` | The user stopped the run before `sync` wrote the file, so the gate reads whatever the previous run left behind |
|
||||
|
||||
Done when exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
|
||||
|
||||
+48
-10
@@ -99,34 +99,72 @@ The two pages live in **two different wiki repos**. Resolve each one on its own.
|
||||
|
||||
Rewrite `CHECK_{HASH}` through `jsc-gitea:wiki` with the post-fix state, per `templates/check-page.md` — repo from `gitea.sh wiki-repo CHECK`. That page is a **content page** and keeps only the latest run, so this overwrites the pre-fix picture on purpose.
|
||||
|
||||
`CHECK_CONTENTS` is a **contents page**, it lives in the contents repo (`gitea.sh wiki-repo CONTENTS`, never a fallback to `JSC_WIKI_REPO_CHECK`), and it gets the opposite treatment. Write the row with
|
||||
`CHECK_CONTENTS` is a **contents page**, it lives in the contents repo (`gitea.sh wiki-repo CONTENTS`, never a fallback to `JSC_WIKI_REPO_CHECK`), and it gets the opposite treatment. It is an H1, a `>` preamble and one H2 block per machine — no markdown table anywhere on it. Write the block with
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert CHECK 4 "{HASH}" {row file} templates/check-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 "CHECK_{HASH}" {block file} templates/check-contents.md`
|
||||
|
||||
which reads the page back and refreshes this machine's row, or appends it when missing. Never overwrite the whole page, and never touch another machine's row.
|
||||
which reads the page back and refreshes this machine's block, or appends it when missing. Never overwrite the whole page, and never touch another machine's block.
|
||||
|
||||
**The key is column 4, the bare `HASH`.** `4` is the 1-based index of the `HASH` column in `templates/check-contents.md`, and the key is exactly what `hash-id` printed for `{host}/{user}` in step 1 — 40 uppercase hex characters, not shortened, not prefixed, not wrapped in a link. The script compares the whole cell, so the key and that cell must match character for character.
|
||||
The block file holds the whole H2 block: the `## CHECK_{HASH}` line, a blank line, then one bullet per field in the order `templates/check-contents.md` lists them, written as `- {欄位名}：{值}` with a full-width colon. Every field of the template gets a bullet, `HASH` included — the heading is the key, and a field only in the heading is a field the next reader cannot read.
|
||||
|
||||
A cell holding a URL would make a moving key: it changes with `GITEA_HOST`, with a move of `JSC_WIKI_REPO_CHECK` to another repo, and with Gitea's encoding of the page name. The comparison then never matches, and every run appends a second row for the same machine instead of updating it.
|
||||
**The key is the H2 heading, `CHECK_{HASH}`.** It is the name of the content page this block points at: the literal `CHECK_` plus exactly what `hash-id` printed for `{host}/{user}` in step 1 — 40 uppercase hex characters, not shortened, not otherwise prefixed, not wrapped in a link, no date appended. The script compares the whole heading text after trimming, so the key and that heading must match character for character.
|
||||
|
||||
Column 1 stays the human-facing link and is never the key. Build it as an **absolute URL** from `gitea.sh wiki-url {CHECK repo} CHECK_{HASH}`, fetched after `CHECK_{HASH}` is rewritten. `[[CHECK_{HASH}]]` resolves only inside its own wiki, and the two pages are no longer in the same one.
|
||||
A key holding a URL would be a moving key: the URL changes with `GITEA_HOST`, with a move of `JSC_WIKI_REPO_CHECK` to another repo, and with Gitea's encoding of the page name. The page name moves with none of them — `{host}/{user}` alone decides it. Key on the URL and the comparison never matches, so every run appends a second block for the same machine instead of updating it.
|
||||
|
||||
`1` is `<key-col>`, and it only matters while a page is still the old markdown table: it is the 1-based index of the column that held the identity, the `[CHECK_{HASH}]({URL})` cell in column 1, whose text becomes the H2 heading when the script converts that table to blocks. On a page already in block form the script ignores it.
|
||||
|
||||
The `體檢頁` bullet stays the human-facing link and is never the key; the heading itself carries no link and no URL. Write the bullet as `[CHECK_{HASH}]({absolute URL})` — text plus link, the one link form this skill set uses. The URL comes from `gitea.sh wiki-url {CHECK repo} CHECK_{HASH}`, fetched after `CHECK_{HASH}` is rewritten, and is never composed by hand.
|
||||
|
||||
A same-wiki link form resolves only inside its own wiki, and the two pages are no longer in the same one. It fails without an error, reading on screen as plain text or a dead link, so nobody finds it and nobody fixes it.
|
||||
|
||||
**Verify every link before writing it.** Collect every URL heading into `CHECK_{HASH}` or into the `CHECK_CONTENTS` block, then hand the whole list to `jsc-gitea/tools/link-check.sh`. It prints `{OK|DEAD|SKIP}<TAB>{URL}<TAB>{reason}` per line. Only exit 0 may be written.
|
||||
|
||||
| Exit | Meaning | Action |
|
||||
| --- | --- | --- |
|
||||
| 0 | Every link answers | Write the page |
|
||||
| 1 | At least one link is unreachable | Write nothing, on either page. Report the `DEAD` lines and leave both pages as they are |
|
||||
| 2 | Usage error: no URL was given | Report it as a defect in this skill and pass the URLs |
|
||||
| 3 | The list holds a Gitea URL but `GITEA_HOST` is unset | Skip both writes and report `GITEA_HOST` as still unfixed. Never write without verifying |
|
||||
| 7 | Gitea authentication failed | Stop and report the key problem. This is not a dead link |
|
||||
|
||||
Exit 7 stays apart from exit 1 on purpose: with a dead key, Gitea's answer for a private repo looks the same as "page absent". Merge the two and one expired key marks every live page dead, and the blocks pointing at them get rewritten or dropped.
|
||||
|
||||
The script asks the API and never reads a web status code. A private repo's web URL answers 404 to a request with no credentials, so status codes turn good links into dead ones.
|
||||
|
||||
| Exit | Action |
|
||||
| --- | --- |
|
||||
| 0 | Report the `updated` or `added` result with the repo and page it named |
|
||||
| 1 | Write failed and nothing landed. Report it with the stderr |
|
||||
| 1 | The page content could not be built, or the write failed, and nothing landed. Report it with the stderr. A page with no block to replace is not this case: the script appends instead |
|
||||
| 2 | Usage error. Report it as a defect in this skill; do not retry with guessed arguments. A `templates/check-contents.md` that is not on disk also lands here — then name the path the script looked for, confirm the plugin install is complete, and rerun |
|
||||
| 3 | No contents repo configured. Skip this write and report `JSC_WIKI_REPO_CONTENTS` as still unfixed |
|
||||
| 4 | Unreachable the way this skill calls the script — the command above always passes `templates/check-contents.md`, and a template that is not on disk comes back as exit 2. So treat a 4 as a malformed call: report it as a defect in this skill, name the command that produced it, and do not retry with guessed arguments |
|
||||
| 7 | Key invalid or no permission. Nothing was read or written; name the exit code and create nothing |
|
||||
| 8 | Any other API failure. Same as 7 |
|
||||
|
||||
Exits 7 and 8 never mean the page is missing: the whole-page overwrite that is correct for `CHECK_{HASH}` would here destroy every other machine's row, unread and unrecoverable. The script creates a page only when its own read reported that page absent, and it owns that branch.
|
||||
Exits 7 and 8 never mean the page is missing: the whole-page overwrite that is correct for `CHECK_{HASH}` would here destroy every other machine's block, unread and unrecoverable. The script creates a page only when its own read reported that page absent, and it owns that branch.
|
||||
|
||||
`gitea.sh wiki-url` has its own exits, and they are read before the upsert runs. Exit 4 means `CHECK_{HASH}` is not on the wiki yet, so rewrite that page first and fetch the URL again. Any other non-zero exit: name the exit code and stop — never hand-build the URL, because a guessed link goes into the row and points nowhere.
|
||||
`gitea.sh wiki-url` has its own exits, and they are read before the upsert runs. Exit 4 means `CHECK_{HASH}` is not on the wiki yet, so rewrite that page first and fetch the URL again. Any other non-zero exit: name the exit code and stop — never hand-build the URL, because a guessed link goes into the block and points nowhere.
|
||||
|
||||
No wiki repo configured, or any non-zero exit from `wiki-repo`, `hash-id`, `wiki-url` or the wiki write → report the tables on screen, say the record was skipped, and name the exit code.
|
||||
|
||||
Then state the counts: fixed, skipped, delegated, and 未修好. Recommend `/jsc-cli:doctor` for a clean re-check when anything was delegated.
|
||||
|
||||
Done when each of the two pages is written or its skip is reported, and the four counts are stated.
|
||||
Done when every link written into either page passed `link-check.sh` first — or the `DEAD` list is on screen and that write was skipped — each of the two pages is written or its skip is reported, and the four counts are stated.
|
||||
|
||||
## 6. Record how the run ended
|
||||
|
||||
This is the last thing this skill does, and it runs on every path out of the skill, the ones that stop at step 1 included. Call
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-cli:setup {status} {exit code} [detail]`
|
||||
|
||||
`{exit code}` is the exit code of whatever decided the outcome — usually the `apply-config.sh` call that ruled the run — and `0` when nothing failed. `{detail}` is one short line, no more than 200 characters: the four counts fit there, the item table does not, and no value the user typed goes in it. **If the script is not on this machine, skip this step in silence and finish the run as it stood** — missing infrastructure is not a failure, and a reporting call may never change what this skill returns or reports.
|
||||
|
||||
| status | When this skill uses it |
|
||||
| --- | --- |
|
||||
| `ok` | Every item on the list was confirmed and applied, each one re-verified by the checker its own row names, nothing was skipped, and both pages were written |
|
||||
| `blocked` | The environment refused every write, so nothing on the machine changed: `apply-config.sh` returned 4 on each item because the backup or the write failed. A run that could not touch a single rc file did no work, so it is never reported as `failed` half-done |
|
||||
| `failed` | Writes landed but the run broke: an applied item still fails its re-verification in step 4, `apply-config.sh` returned 2 on a malformed call this skill made, or `link-check.sh`, `gitea.sh` or `wiki-contents.sh` returned 7 or 8 and the record could not be rewritten |
|
||||
| `degraded` | The run finished with part of the list untouched. The usual case is the user turning an item down at step 2 — a skip is recorded as skipped and never as fixed — and a delegated repair that its owner skill did not close counts the same way. The machine is better than it was, and the 未修好 and 略過 counts are above zero |
|
||||
| `aborted` | The user stopped the sequential confirmation partway and asked to end the run, so the remaining items were never put to them |
|
||||
|
||||
Done when exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
|
||||
|
||||
@@ -1,17 +1,27 @@
|
||||
# 體檢目錄
|
||||
|
||||
> 由 `jsc-cli:doctor` 維護。每台執行環境一列；`HASH` 取 `{短主機名}/{登入帳號}`，算法與其他頁面共用。主機名取不含網域的短名，FQDN 要先切掉第一個點之後的部分，否則同一台機器會多出第二頁。
|
||||
> 由 `jsc-cli:doctor` 維護。每台執行環境一個區塊；`HASH` 取 `{短主機名}/{登入帳號}`，算法與其他頁面共用。主機名取不含網域的短名，FQDN 要先切掉第一個點之後的部分，否則同一台機器會多出第二頁。
|
||||
>
|
||||
> 本頁落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫，與體檢頁 `CHECK_{HASH}` 不同庫。目錄頁全部住這裡，不退回 `JSC_WIKI_REPO_CHECK`。
|
||||
>
|
||||
> 寫入語意：一列代表一台執行環境，也就是一組主機加帳號。一律用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 4 {HASH} {列檔} {本範本}` 寫，它先讀回整頁，該執行環境已經有列就更新那一列，沒有才在表尾附加一列。禁止整頁覆蓋，也不得改動別人的列。體檢頁 `CHECK_{HASH}` 只留最新一次結果、可以整頁改寫，這份目錄頁不行。
|
||||
> 寫入語意：一個區塊代表一台執行環境，也就是一組主機加帳號。一律用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH} {區塊檔} {本範本}` 寫，它先讀回整頁，該執行環境已經有區塊就整塊換掉，沒有才在頁尾附加一個區塊。禁止整頁覆蓋，也不得改動別人的區塊。體檢頁 `CHECK_{HASH}` 只留最新一次結果、可以整頁改寫，這份目錄頁不行。
|
||||
>
|
||||
> 鍵是第 4 欄的 `HASH`：`jsc-gitea/tools/hash-id` 印出什麼就填什麼，完整 40 碼大寫十六進位，不截短、不加前綴、不包成連結。腳本比對的是整格文字，鍵一定要跟這一格一字不差。
|
||||
> 參數說明：第二個參數 `1` 是 `<key-col>`，只在這一頁還留著舊的 markdown 表格時用得到，指舊表格裡持有身分那一欄的序號，也就是持有 `[CHECK_{HASH}](網址)` 的第 1 欄，自動轉檔時取那一格的文字當 H2 標題；頁面已經是條列格式就完全忽略它。第三個參數 `<key>` 是 H2 標題文字，也就是體檢頁頁名 `CHECK_{HASH}`。第四個參數是區塊檔，不是列檔：內容為 `## CHECK_{HASH}` 那一行、一個空行，再接各條欄位。
|
||||
>
|
||||
> 鍵用裸 `HASH` 才穩。`GITEA_HOST` 換掉、`JSC_WIKI_REPO_CHECK` 換過存取庫、Gitea 對頁名的網址編碼有差，網址就跟著變；拿含網址的儲存格當鍵，比對就永遠比不中，同一台機器每體檢一次就多附一列，畫面上還看不出來。
|
||||
> 鍵是 H2 標題 `CHECK_{HASH}`：`jsc-gitea/tools/hash-id` 印出什麼就接在 `CHECK_` 後面，完整 40 碼大寫十六進位，不截短、不加別的前後綴、不包成連結、不加日期。腳本比對的是去掉頭尾空白後的整段標題文字，鍵一定要跟標題一字不差。
|
||||
>
|
||||
> 第 1 欄的連結只給人點，不當鍵用。連結一律填 `jsc-gitea/tools/gitea.sh wiki-url` 印出的絕對網址。`[[CHECK_{HASH}]]` 只在同一個 wiki 內解析，兩頁已經不同庫，寫成雙括號會連不到。
|
||||
> 鍵用頁名才穩。頁名只由 `{短主機名}/{登入帳號}` 決定；`GITEA_HOST` 換掉、`JSC_WIKI_REPO_CHECK` 換過存取庫、Gitea 對頁名的網址編碼有差，網址就跟著變，頁名一個字都不動。拿含網址的值當鍵，比對就永遠比不中，同一台機器每體檢一次就多附一個區塊，畫面上還看不出來。
|
||||
>
|
||||
> 連結寫法：「體檢頁」那一條的連結只給人點，不當鍵用；H2 標題本身不放連結、不放網址。連結一律寫成 `[{文字}]({連結})`，也就是 `[CHECK_{HASH}]({wiki-url 印出的絕對網址})`，網址取 `jsc-gitea/tools/gitea.sh wiki-url` 印出的那一串，不自己組路徑。同 wiki 的雙括號寫法一概不用：兩頁分屬不同存取庫，連不過去，畫面上還看不出壞掉。
|
||||
>
|
||||
> 連結驗證：這個區塊要寫進去的每一個連結，先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫。有任何一筆 DEAD 就整個區塊都不寫，把連不到的清單回報給呼叫端。結束碼 3 代表 `GITEA_HOST` 沒設定，先設好再寫，不得跳過驗證；結束碼 7 代表金鑰失效，停下來回報金鑰問題，不要當成死連結。驗證一律走 API，不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把好連結判成壞的，整批砍掉還在的頁。
|
||||
|
||||
| 體檢頁 | 主機 | 帳號 | HASH | 必要項缺漏 | 設定錯誤 | 最後體檢 |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| [CHECK_{HASH}]({體檢頁絕對網址}) | {短主機名} | {使用者帳號} | {HASH} | {n} | {n} | {yyyy-MM-dd HH:mm} |
|
||||
## CHECK_{HASH}
|
||||
|
||||
- 體檢頁：[CHECK_{HASH}]({wiki-url 印出的絕對網址})
|
||||
- 主機：{短主機名}
|
||||
- 帳號：{使用者帳號}
|
||||
- HASH：{HASH}
|
||||
- 必要項缺漏：{n}
|
||||
- 設定錯誤：{n}
|
||||
- 最後體檢：{yyyy-MM-dd HH:mm}
|
||||
|
||||
Reference in New Issue
Block a user