From 5b0eb784b4ea62155edf0a539fa308af1b84632f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 3 Sep 2026 13:07:07 +0800 Subject: [PATCH 1/2] =?UTF-8?q?fix(doctor,setup):=20=E5=85=A9=E6=94=AF?= =?UTF-8?q?=E6=8A=80=E8=83=BD=E8=A3=9C=E4=B8=8A=E8=B7=AF=E5=BE=91=E5=AE=88?= =?UTF-8?q?=E5=89=87=EF=BC=8C=E5=91=BC=E5=8F=AB=E4=B8=80=E5=BE=8B=E5=AD=97?= =?UTF-8?q?=E9=9D=A2=E7=B5=95=E5=B0=8D=E8=B7=AF=E5=BE=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 這兩支技能的腳本呼叫原本全是裸相對路徑，整份文件沒有任何路徑守則。相對路徑會對著操作者當下的工作目錄解，而那裡從來不是外掛根目錄，所以每一個呼叫點都是模型就地猜前綴的地方。部署技能原本三處相對路徑被補成帶變數路徑，就是同一個機制。 實際掃到的處數比預估多：體檢 18 處、修復 20 處。多出來的是兩類原本沒想到的——裸檔名的 Gitea 呼叫，以及被當成參數傳的資料檔。後者同樣會解錯地方，而且解錯了不會報錯。 兩支各補路徑守則與前置步驟，解出兩條根目錄：跨外掛走 current 那一層（解到那一層就停，再往下解會落到帶版本號的快取路徑，那種路徑進不了允許清單），技能自己的腳本與範本走 CLI 載入技能時講明的外掛基底目錄。 兩支都不靠 current 底下那條 jsc-cli 連結，但理由各自不同，不是照抄部署那一支的。體檢不能靠，因為它正是機器可疑時才跑的技能——觸發時機本身就是連結可能出錯的那幾個時刻，而連結指著舊版時拿到的是舊的掃描腳本與舊的規格表，掃出來的每一列都像真的發現，不會有任何錯誤訊息。修復更不能靠，因為它寫檔，而且它要修的其中一列正是那個決定連結位置的變數：那種機器上根目錄根本解不出來，而修它要用的腳本掛在外掛基底目錄底下、不依賴那個變數，所以解不出來既不停這一輪也不擋那一項修復。何況拿舊的寫入腳本改設定檔，再用同一份舊腳本重驗，兩邊當然對得上，整輪會報成已修。 失敗分支也與部署不同。部署解不出根目錄就停手；這兩支都不停——體檢把它記成一項發現然後跑完不需要跨外掛的檢查，因為唯讀體檢中途停掉操作者什麼都拿不到；修復把它當成待修的那一項，修好再重解一次。 兩份範本與說明文件一併改。範本是這兩支技能在同一輪一起讀的，而且指示寫入，留著裸路徑等於留一個繞過新規則的入口。範本裡另外補掉兩個路徑洞：指向範本自己的佔位符原本沒有路徑，以及一個連目錄都沒有的裸檔名。 行為契約四列跟著改，並補上可稽核的跡象：回報裡的腳本路徑全是字面絕對路徑，跨外掛的路徑中間是 current 那一層而不是帶版本號的快取路徑。 --- README.md | 6 +-- references/behaviors.md | 16 ++++---- skills/doctor/SKILL.md | 70 ++++++++++++++++++++++++++--------- skills/setup/SKILL.md | 74 +++++++++++++++++++++++++++---------- templates/check-contents.md | 10 +++-- templates/check-page.md | 5 ++- 6 files changed, 127 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 3344d21..ee13775 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | `tools/scan-config.sh` | 依規格表盤點設定現況（`scan {global\|project\|all}` 印 TSV 與 summary、`spec` 印規格表、`orphans` 找出漏登錄的變數）；`-o` 為離線模式，需要連 Gitea 的檢查一律標 skipped。唯讀，不寫任何設定；帶 TOKEN 的項目只印 set 或 unset | | `tools/apply-config.sh` | 把設定寫進 shell rc 檔（`set {KEY} {VALUE}`、`unset {KEY}`）或建立目錄（`mkdir {PATH}`）；`show` 印出目前設定，`rcfiles` 印出會寫入的檔案。內容一律收在 `# jsc-config` 標記段落之間，整段重寫不疊加，段落外不動。動檔案前先備份到 `$JSC_HOME/backup/config/{yyyyMMdd_HHmmss}/`，備份失敗就不寫；寫完重讀驗證。fish 自動改用 `set -gx` 語法 | | `tools/model-tags.sh` | 解析 `references/model-tags.md` 的能力標籤與 SDLC 階段必要標籤（`dump`、`sync`、`stage {階段}`、`model {模型 id}`、`gate {階段} {模型 id}`）；`sync` 寫出 `$JSC_HOME/model-tags.tsv` 供 `jsc-hooks` 的 sdlc-gate 讀取。`gate` 的結束碼 0 為 PASS、1 為缺標籤、2 為模型或階段不在表上，`/jsc-cli:delegate` 依這三碼決定收下或退回 | -| `tools/build-todo.sh` | 把三支檢查腳本的輸出合併成一張「待修項目」表（`--config` 收 `scan-config.sh scan`、`--wiring {cli}=` 收 `wire-cli.sh status`、`--version` 收 `version-guard.sh report`）；類別固定排成 missing、invalid、unwired、落後，一項都沒有時仍印一列「無」。`/jsc-cli:doctor` 與 `/jsc-cli:setup` 共用這一份合併規則，兩邊各寫一次就會各自漂移 | +| `tools/build-todo.sh` | 把三支檢查腳本的輸出合併成一張「待修項目」表（`--config` 收 `scan-config.sh scan`、`--wiring {cli}=` 收 `wire-cli.sh status`、`--version` 收 `version-guard.sh report`）；類別固定排成 missing、invalid、unwired、落後，一項都沒有時仍印一列「無」。`/jsc-cli:doctor` 與 `/jsc-cli:setup` 共用這一份合併規則，兩邊各寫一次就會各自漂移。兩支都以 `{CLI_ROOT}/tools/build-todo.sh` 這種字面絕對路徑呼叫它，`{CLI_ROOT}` 是 CLI 載入技能時講明的 jsc-cli 外掛基底目錄；不留 `$JSC_HOME`、波浪號或裸的相對路徑，帶變數的路徑進不了允許清單，相對路徑則會對著操作者當下的工作目錄解 | ## Skills 目錄 @@ -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`），版面是 H1 加 `>` 引言，再一台機器一個 H2 區塊，頁上沒有 markdown 表格；改由 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 只寫本機那一個區塊，欄位是 `- {欄位名}：{值}` 的條列。鍵是 H2 標題，也就是體檢頁頁名 `CHECK_{HASH}`，不是任何含網址的值：網址會隨站台、存取庫與頁名編碼改變，頁名只由主機加帳號決定，拿網址當鍵就比不中，同一台機器每體檢一次就多附一個區塊。第二個參數 `1` 是 ``，只在頁面還是舊表格、需要自動轉檔時用得到，指舊表格裡持有 `[CHECK_{HASH}](網址)` 的第 1 欄。「體檢頁」那一條的連結給人點，填絕對網址。修復交給 `/jsc-cli:setup`，體檢本身不動任何設定。 +一次體檢執行環境，只讀不改。開跑先解出兩條根目錄，整輪的腳本呼叫一律填成字面絕對路徑：`{JSC_ROOT}` 取 `readlink -f "$JSC_HOME/current"`（解到那一層就停，不再往下解成帶版本號的快取路徑），`{CLI_ROOT}` 取 CLI 載入技能時講明的外掛基底目錄。這一支解不出 `{JSC_ROOT}` 不停手，直接把 `JSC_HOME` 記成一項發現：唯讀體檢中途停掉，操作者什麼都拿不到。技能自己的 `tools/` 與 `templates/` 一律走 `{CLI_ROOT}`，不走 `current` 底下那條 `jsc-cli` 連結——體檢正是機器可疑時才跑的，連結指著舊版時拿到的是舊的 scan-config.sh 與舊的 config-spec.tsv，掃出來的每一列都像真的發現，而且不會有任何錯誤訊息。四項檢查**同時啟動，各一個 sub agent**：技能版本（`{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh report`）、Hook 接線（`{JSC_ROOT}/jsc-hooks/tools/wire-cli.sh status`，唯讀子命令）、設定現況（`{CLI_ROOT}/tools/scan-config.sh scan all` 比對 `{CLI_ROOT}/tools/config-spec.tsv`，一次掃完全域與專案兩個範圍）、漏登錄變數（`{CLI_ROOT}/tools/scan-config.sh orphans`）。唯讀契約下放程式層：呼叫 `wire-cli.sh` 一律帶 `JSC_READONLY=1`，打錯子命令也不會改到機器。每項各出一張表，專案那張一定寫出掃的是哪個目錄；待修項目由 `{CLI_ROOT}/tools/build-todo.sh` 合併三份輸出並排序。整份結果寫進 wiki `CHECK_{HASH}`，`HASH` 取 `{短主機名}/{登入帳號}`，兩個值都由程式取，主機名一律切掉網域，只保留最新一次。目錄頁 `CHECK_CONTENTS` 住另一個庫（`JSC_WIKI_REPO_CONTENTS`），版面是 H1 加 `>` 引言，再一台機器一個 H2 區塊，頁上沒有 markdown 表格；改由 `{JSC_ROOT}/jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 只寫本機那一個區塊，欄位是 `- {欄位名}：{值}` 的條列。鍵是 H2 標題，也就是體檢頁頁名 `CHECK_{HASH}`，不是任何含網址的值：網址會隨站台、存取庫與頁名編碼改變，頁名只由主機加帳號決定，拿網址當鍵就比不中，同一台機器每體檢一次就多附一個區塊。第二個參數 `1` 是 ``，只在頁面還是舊表格、需要自動轉檔時用得到，指舊表格裡持有 `[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 1 CHECK_{HASH}` 以 H2 標題（也就是體檢頁頁名）當鍵，更新目錄頁 `CHECK_CONTENTS` 的本機那一個區塊，兩頁分屬不同存取庫。 +修復 `/jsc-cli:doctor` 找出的問題，一次一項，逐項確認才動手。路徑寫法與 doctor 相同：`{JSC_ROOT}` 與 `{CLI_ROOT}` 各解一次，之後每一支腳本都用字面絕對路徑呼叫。這一支寫檔，所以更不能走 `current` 底下那條 `jsc-cli` 連結——`JSC_HOME` 本身就是它要修的一列，那種機器上 `{JSC_ROOT}` 根本解不出來，而修它要用的 apply-config.sh 掛在 `{CLI_ROOT}` 底下，不靠 `JSC_HOME`，所以解不出來既不停這一輪也不擋那一項修復；何況拿舊的 apply-config.sh 寫 rc 檔，再用同一份舊的 `show` 重驗，兩邊當然對得上，整輪會報成已修。待修清單優先讀 wiki `CHECK_{HASH}`，沒有頁面就當場重掃：**三支檢查腳本併行跑**，再用 `{CLI_ROOT}/tools/build-todo.sh` 合併成同一張表。依修法分流：`auto` 用 `{CLI_ROOT}/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_ROOT}/jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 以 H2 標題（也就是體檢頁頁名）當鍵，更新目錄頁 `CHECK_CONTENTS` 的本機那一個區塊，兩頁分屬不同存取庫。 diff --git a/references/behaviors.md b/references/behaviors.md index 3a55c12..702d2be 100644 --- a/references/behaviors.md +++ b/references/behaviors.md @@ -27,10 +27,10 @@ | 項目 | 內容 | | --- | --- | | 觸發時機 | 裝完或更新完技能組、技能因設定或接線問題失敗、機器要交接前用。要動手修不用這支，那是 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 取該頁絕對網址、把要寫進兩頁的每個連結交給 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 就是這一輪的結果，那也是這支技能唯一寫得出來的檔案痕跡。機器本身的設定、接線與版本都不動：這支技能不寫任何設定 | +| 關鍵步驟 | 先跑一次 `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，解到那一層就停，不再往下解成帶版本號的快取路徑——那種路徑放不進允許清單，版本號寫成萬用字元也對不上；同一步再跑 `[ -d "{剛印出來的路徑}" ]` 確認目錄存在，`JSC_HOME` 是有預設值的選擇性項目，沒設時它印的是 `/current`、結束碼 0，非空又是絕對路徑，只看那兩項擋不下來。這一支跟 deploy 不同，解不出來不停手：`JSC_HOME` 直接記成全域設定與待修項目上的一項發現，用得到跨外掛腳本的檢查記成無法驗證，其餘照跑到完——唯讀體檢中途停掉，操作者什麼都拿不到，而路徑解不開的機器正是最需要體檢的那一台。整輪只解這一次，之後每一次跨外掛腳本呼叫都填成那個字面絕對路徑，不留 `$JSC_HOME` 也不留波浪號，也不留裸的相對路徑——相對路徑會對著操作者的專案目錄解，那裡從來不是外掛根目錄，每個這種呼叫點都是前綴被猜出來的地方。技能自己的 `tools/` 與 `templates/` 一律不走 `current`，即使那裡擺著 `jsc-cli` 那一條也一樣：這一支正是機器可疑時才跑的技能，它的觸發時機自己就寫著裝完或更新完、技能因設定或接線失敗、機器要交接，而 deploy 判 degraded 那一輪留下的正是回 fail 或被 skip、還指著舊版的連結；從那條連結拿到的 scan-config.sh 與 config-spec.tsv 是這台機器沒在跑的版本，掃出來的每一列都像真的發現，舊掃描器跑得完，一句錯誤訊息都不會有。改走外掛根目錄就沒有這個問題，連結壞掉、過期或從來沒建起來的機器上，那三支腳本照樣跑得動，`JSC_HOME` 本身也才掃得到、報得出來。根目錄取自 CLI 載入這支技能時講明的外掛基底目錄，原樣當字面絕對路徑用，一個指令都不跑，寫成 `{外掛根目錄}/tools/{腳本}` 與 `{外掛根目錄}/templates/{檔案}`；那個基底目錄帶版本號，這幾次呼叫都會跳權限詢問，這一支有操作者在現場讀五個區塊與待修項目表所以按得掉，無人值守的技能不得照抄，叫用文字沒講明基底目錄就回報外掛根目錄不明並停手，不猜前綴。接著同時開四個 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 只放四項計數 | +| 外部呼叫 | `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，加上同一步的 `[ -d ]` 確認，是整輪唯一容許帶變數的兩個指令；跨外掛腳本一律用它組成的字面絕對路徑呼叫：{current 目錄}/jsc-hooks/hooks/version-guard.sh report、{current 目錄}/jsc-hooks/tools/wire-cli.sh status（一律帶 JSC_READONLY=1）、{current 目錄}/jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、{current 目錄}/jsc-gitea/tools/link-check.sh、{current 目錄}/jsc-gitea/tools/wiki-contents.sh upsert、{current 目錄}/jsc-hooks/tools/report-status.sh skill-end。技能自己的檔案走外掛根目錄組成的字面絕對路徑：{外掛根目錄}/tools/detect-clis.sh、{外掛根目錄}/tools/scan-config.sh 的 scan all 與 orphans、{外掛根目錄}/tools/build-todo.sh，比對用的 {外掛根目錄}/tools/config-spec.tsv 與兩份版型 {外掛根目錄}/templates/check-page.md、{外掛根目錄}/templates/check-contents.md 也一樣。另有 jsc-gitea:wiki | +| 完成條件 | `current` 那個目錄在第一步就解出一條存在的絕對路徑（用 `[ -d ]` 查過，而且沒有再往下解成帶版本號的快取路徑），解不出來就記成 `JSC_HOME` 那一項發現而不是停手；技能自己的 `tools/` 與 `templates/` 也有一條字面絕對的外掛根目錄可用，後續每一支腳本、每一份版型都用這兩條之一組成的字面絕對路徑呼叫。四項檢查各有結論，或明寫無法驗證與原因；五個區塊與待修項目表都在畫面上；每個要寫進頁面的連結都經 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 就是這一輪的結果，那也是這支技能唯一寫得出來的檔案痕跡。機器本身的設定、接線與版本都不動：這支技能不寫任何設定。回報與逐行紀錄裡出現的腳本路徑全是字面絕對路徑，找不到 `$JSC_HOME`、`$` 開頭或波浪號開頭的呼叫，也沒有一支寫成裸的相對路徑，唯一的例外是開頭那一次 `readlink -f "$JSC_HOME/current"` 與同一步的 `[ -d ]` 確認；跨外掛那幾支的路徑中段是 `current`，不是 `cache/jsc/{外掛}/{版本}`，技能自己那三支腳本與兩份版型則一律是外掛根目錄接 `tools/` 或 `templates/` | ## models @@ -47,7 +47,7 @@ | 項目 | 內容 | | --- | --- | | 觸發時機 | 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 取它的絕對網址、把要寫進兩頁的每個連結交給 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 就是這一輪的結果 | +| 關鍵步驟 | 先跑一次 `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，解到那一層就停，不再往下解成帶版本號的快取路徑——那種路徑放不進允許清單，版本號寫成萬用字元也對不上；同一步再跑 `[ -d "{剛印出來的路徑}" ]` 確認目錄存在。全技能組裡最常碰到 `JSC_HOME` 沒設的就是這一支：它是有預設值的選擇性項目，在待修項目表上是一列 auto，而把它寫進去正是這支技能要做的修復，所以那種機器本來就是叫用這支技能的常態理由；沒設時那道指令印的是 `/current`、結束碼 0，非空又是絕對路徑，兩項都擋不下來。解不出來既不停這一輪，也不擋那一項修復：寫 `JSC_HOME` 要用的 apply-config.sh、scan-config.sh、build-todo.sh 全掛在外掛根目錄底下，根本不靠 `JSC_HOME`，先把那一項修好、再重解一次 `current` 就能往下走，仍然構不到的（第五步的 wiki 紀錄、轉呼叫出去的修復）記成未修好並寫明原因，不用猜的。整輪只解這一次，之後每一次跨外掛腳本呼叫都填成那個字面絕對路徑，不留 `$JSC_HOME` 也不留波浪號，也不留裸的相對路徑——相對路徑會對著操作者的專案目錄解，那裡從來不是外掛根目錄。技能自己的 `tools/` 與 `templates/` 一律不走 `current`，即使那裡擺著 `jsc-cli` 那一條也一樣，理由有兩條：一是上面那條，要修的機器往往正是 `JSC_HOME` 壞掉的機器，修復工具走連結農場，就會被它們存在的理由本身擋住；二是這一支會拿舊腳本去寫檔，第三步把每個落後的 domain 交給 jsc-cli:deploy，正因為這台機器的版本可能落後，而連結農場受同一份落後管轄，從那裡拿 apply-config.sh，等於拿這台機器剛被判定已經跟不上的工具去修它，而且結果是寫進 rc 檔，不只是印在畫面上——舊腳本會照它那一版的鍵集重寫每個 rc 檔的 `# jsc-config` 區塊，把舊的當成正確版本備份起來，第四步再用同一份舊的 show 重驗，當然對得上，於是整輪報成已修。根目錄取自 CLI 載入這支技能時講明的外掛基底目錄，原樣當字面絕對路徑用，一個指令都不跑，寫成 `{外掛根目錄}/tools/{腳本}` 與 `{外掛根目錄}/templates/{檔案}`；那個基底目錄帶版本號，這幾次呼叫都會跳權限詢問，這一支有操作者在現場（第二步逐項問到答案才寫）所以按得掉，無人值守的技能不得照抄，叫用文字沒講明基底目錄就在寫任何東西之前回報外掛根目錄不明並停手，不猜前綴。接著用程式取短主機名與登入帳號算出 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 只放四項計數，不放使用者輸入的值 | +| 外部呼叫 | `readlink -f "$JSC_HOME/current"` 解出 `current` 這個目錄的絕對路徑，加上同一步的 `[ -d ]` 確認，是整輪唯一容許帶變數的兩個指令；跨外掛腳本一律用它組成的字面絕對路徑呼叫：{current 目錄}/jsc-hooks/tools/wire-cli.sh status（一律帶 JSC_READONLY=1）、{current 目錄}/jsc-hooks/hooks/version-guard.sh report、{current 目錄}/jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、{current 目錄}/jsc-gitea/tools/link-check.sh、{current 目錄}/jsc-gitea/tools/wiki-contents.sh upsert、{current 目錄}/jsc-hooks/tools/report-status.sh skill-end。技能自己的檔案走外掛根目錄組成的字面絕對路徑：{外掛根目錄}/tools/scan-config.sh、{外掛根目錄}/tools/detect-clis.sh、{外掛根目錄}/tools/build-todo.sh、{外掛根目錄}/tools/apply-config.sh 的 set、mkdir 與 show，比對用的 {外掛根目錄}/tools/config-spec.tsv 與兩份版型 {外掛根目錄}/templates/check-page.md、{外掛根目錄}/templates/check-contents.md 也一樣。另有 jsc-ask:ask、jsc-gitea:wiki、jsc-cli:deploy、jsc-hooks:hooks-install、jsc-cli:models | +| 完成條件 | `current` 那個目錄在第一步就解出一條存在的絕對路徑（用 `[ -d ]` 查過，而且沒有再往下解成帶版本號的快取路徑），解不出來就把它記成 `JSC_HOME` 那一項待修並照修，不停手也不擋住其他項；技能自己的 `tools/` 與 `templates/` 也有一條字面絕對的外掛根目錄可用，後續每一支腳本、每一份版型都用這兩條之一組成的字面絕對路徑呼叫。每一項都有已修、略過、轉呼叫或未修好的結果；每個已套用項目都由自己那一列指定的檢查器重驗過；每個寫進去的環境變數都附上 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 就是這一輪的結果。回報與逐行紀錄裡出現的腳本路徑全是字面絕對路徑，找不到 `$JSC_HOME`、`$` 開頭或波浪號開頭的呼叫，也沒有一支寫成裸的相對路徑，唯一的例外是開頭那一次 `readlink -f "$JSC_HOME/current"` 與同一步的 `[ -d ]` 確認；跨外掛那幾支的路徑中段是 `current`，不是 `cache/jsc/{外掛}/{版本}`，技能自己那四支腳本與兩份版型則一律是外掛根目錄接 `tools/` 或 `templates/`；備份目錄 $JSC_HOME/backup/config/{時間戳}/ 底下那幾份 rc 檔，是由外掛根目錄那一份 apply-config.sh 寫出來的，跟這台機器目前跑的 jsc-cli 版本同一份 | diff --git a/skills/doctor/SKILL.md b/skills/doctor/SKILL.md index 53bf2f1..4723f5d 100644 --- a/skills/doctor/SKILL.md +++ b/skills/doctor/SKILL.md @@ -7,7 +7,41 @@ description: Health-check the execution environment in one pass and record the r Read-only. Every command below either reads a file or asks Gitea; none of them writes a setting. That is the contract with `jsc-cli:setup`: doctor states the facts, setup changes things. -The read-only contract is enforced in code, not by prose: every `jsc-hooks/tools/wire-cli.sh` call in this skill runs with `JSC_READONLY=1` in its environment. A mistyped subcommand then refuses to write instead of rewiring the machine that was only supposed to be measured. +The read-only contract is enforced in code, not by prose: every `{JSC_ROOT}/jsc-hooks/tools/wire-cli.sh` call in this skill runs with `JSC_READONLY=1` in its environment. A mistyped subcommand then refuses to write instead of rewiring the machine that was only supposed to be measured. + +## 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 — and never a bare relative one either. The permission layer matches paths statically: it expands no variable and no tilde, so such a path matches no allow rule and the call falls through to an approval prompt. A bare relative path is the worse form, because it resolves against whatever directory the CLI happens to be in — and this skill deliberately runs from the operator's project directory, which is never a plugin root — so every bare call site is a place where a prefix gets guessed. + +A guessed prefix is the specific danger here, and it is quiet. This skill measures a machine and writes what it found onto a page other people act on, so a call that reaches the wrong copy of a script does not fail — it reports. An old `tools/scan-config.sh` reached through some other version's directory grades this machine against that version's `tools/config-spec.tsv`, and every row it prints looks exactly like a real finding. A checkup that cannot say which script produced its rows is worth less than no checkup, because nobody doubts it. + +Portability is no reason to put the variable back. Step 0 resolves the roots once, at run time, on whatever machine this runs on — that is where portability comes from. + +## 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 `current` directory itself, a farm of version-free symbolic links with one entry per plugin. Call it `{JSC_ROOT}` for the rest of this document. **Stop at that directory — never resolve one level further.** 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. + +Confirm the directory exists, in the same approved step: `[ -d "{the path just printed}" ]`. **That is the check the other two wave through.** `JSC_HOME` is an optional variable with a default, so an unset one is an ordinary machine state rather than an exotic one — it has its own row in `{CLI_ROOT}/tools/config-spec.tsv`, and finding it unset is a normal outcome of this very checkup. With it 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. + +**Unlike `jsc-cli:deploy`, an unresolvable `{JSC_ROOT}` never stops this run.** It is a finding, and findings are what this skill produces: report `JSC_HOME` in the 全域設定 block and at the top of the 待修項目 table. Mark every check that needed a cross-plugin script as 無法驗證 with that as its reason, and let the checks that do not need one finish. A read-only checkup that aborts tells the operator nothing, and the machine most in need of a checkup is the machine whose paths do not resolve. + +Substitute `{JSC_ROOT}` in every cross-plugin 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, and do not add a tool that prints it. + +### The second root — this skill's own `tools/` and `templates/` + +**Do not reach this skill's own files through `{JSC_ROOT}`, even though a `jsc-cli` link is normally sitting there.** `jsc-cli:deploy` refreshes the whole farm at the end of every round, so on a machine that has deployed, that link exists. This skill still may not lean on it, for a reason of its own: **doctor is the skill that gets run when the machine is suspect.** Its own triggers say so — after an install or update, after a skill failed on a settings or wiring problem, before a handover. A deploy that ended `degraded` is one whose `link` lines came back `fail`, or `skip` on a path holding something that is not a symbolic link at all, leaving a plugin's documented path on an old version — and doctor is what runs next. Reached through that link, `tools/scan-config.sh` and its `tools/config-spec.tsv` come from a version this machine is not running, and the findings table then describes a machine that does not exist. Nothing errors: an old scanner runs perfectly well. + +The second root is free of that. `tools/scan-config.sh`, `tools/detect-clis.sh` and `tools/build-todo.sh` reached through it keep working on a machine whose farm is stale, broken, or never built — which is precisely the machine being measured — so `JSC_HOME` itself still gets scanned and still gets reported. + +They sit at `{plugin root}/tools/` and `{plugin root}/templates/`, 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 every own-plugin path as `{CLI_ROOT}/tools/{script}` or `{CLI_ROOT}/templates/{file}` — `/root/.claude/plugins/cache/jsc/jsc-cli/0.3.3/tools/scan-config.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 calls raises an approval prompt. **That is acceptable in this skill and in no unattended one**: doctor runs with the operator in front of it — the five blocks and the 待修項目 table are printed for a person to read and act on — 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 reports some other version's idea of this machine as if it were this machine. + +Done when `{JSC_ROOT}` holds one existing absolute directory or its failure is recorded as a `JSC_HOME` finding, and `{CLI_ROOT}` holds one literal absolute path. ## 1. Collect, four checks in parallel @@ -17,7 +51,7 @@ Done when all four sub agents have returned, and each has either its raw lines o ### 1.1 Skill versions -Run `jsc-hooks/hooks/version-guard.sh report`. It prints `{domain}{本機}{遠端}{落後|最新|超前|查詢失敗}` per plugin, then `behind{count}`. +Run `{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh report`. It prints `{domain}{本機}{遠端}{落後|最新|超前|查詢失敗}` per plugin, then `behind{count}`. A report with no `{domain}` row, or one carrying `noregistry{path}`, means this CLI has no local plugin registry. Report it as 無法驗證 — never as 最新. `behind0` proves nothing when no domain row precedes it. @@ -27,9 +61,9 @@ Done when every installed domain has a status literal, or the check is reported ### 1.2 Hook wiring -First run `jsc-cli/tools/detect-clis.sh`. Exit 0 with at least one row → those are the CLIs to check. Exit 0 with no row → report the wiring table as empty and say no AI agent CLI was detected; that is a finding, not a pass. Any non-zero exit → report the wiring check as 無法驗證 with the exit code and stderr. +First run `{CLI_ROOT}/tools/detect-clis.sh`. Exit 0 with at least one row → those are the CLIs to check. Exit 0 with no row → report the wiring table as empty and say no AI agent CLI was detected; that is a finding, not a pass. Any non-zero exit → report the wiring check as 無法驗證 with the exit code and stderr. -Then run `JSC_READONLY=1 jsc-hooks/tools/wire-cli.sh status {cli}` for every detected CLI. Use `status` and nothing else: `wire-cli.sh` without a subcommand rewires, `purge` deletes, and `smoke` executes hooks — all three break the read-only contract. +Then run `JSC_READONLY=1 {JSC_ROOT}/jsc-hooks/tools/wire-cli.sh status {cli}` for every detected CLI. Use `status` and nothing else: `wire-cli.sh` without a subcommand rewires, `purge` deletes, and `smoke` executes hooks — all three break the read-only contract. | Exit | Meaning | Action | | --- | --- | --- | @@ -46,7 +80,7 @@ Done when every detected CLI carries one of those verdicts and its missing items ### 1.3 Settings, global and project in one scan -Run `jsc-cli/tools/scan-config.sh scan all` from the current working directory. One call covers both scopes: the spec table is read once and the `scope` column separates the rows. It prints `{項目}{範圍}{必要}{現況}{說明}{修法}{判定}`, closing with `summary{missing}{invalid}{unset}{skipped}`. +Run `{CLI_ROOT}/tools/scan-config.sh scan all` from the current working directory. One call covers both scopes: the spec table is read once and the `scope` column separates the rows. It prints `{項目}{範圍}{必要}{現況}{說明}{修法}{判定}`, closing with `summary{missing}{invalid}{unset}{skipped}`. | Exit | Action | | --- | --- | @@ -63,7 +97,7 @@ Done when the summary line is read, the rows are split into the two scopes, and ### 1.4 Orphan variables -Run `jsc-cli/tools/scan-config.sh orphans` — variables used in the source but absent from the spec table. Same exit codes as 1.3; exit 3 here also covers a missing plugins root, so name `JSC_PLUGINS_ROOT` in that case. +Run `{CLI_ROOT}/tools/scan-config.sh orphans` — variables used in the source but absent from the spec table. Same exit codes as 1.3; exit 3 here also covers a missing plugins root, so name `JSC_PLUGINS_ROOT` in that case. They are a maintenance note for the skill set, not a fault on this machine, so they never enter the 待修項目 table. @@ -73,7 +107,7 @@ Done when the orphan list is returned or the check is reported as skipped with i ### 2.1 The five blocks -Report all five blocks per `templates/check-page.md`: 技能版本 from 1.1, Hook 接線 from 1.2, 全域設定 and 自我設定 from 1.3's two scopes, and 未登錄變數 from 1.4. Step 1.4 is the only place the orphan list is collected, so leaving it out here drops it from the run entirely — it never enters the 待修項目 table of 2.2, which is exactly why it needs its own block. +Report all five blocks per `{CLI_ROOT}/templates/check-page.md`: 技能版本 from 1.1, Hook 接線 from 1.2, 全域設定 and 自我設定 from 1.3's two scopes, and 未登錄變數 from 1.4. Step 1.4 is the only place the orphan list is collected, so leaving it out here drops it from the run entirely — it never enters the 待修項目 table of 2.2, which is exactly why it needs its own block. The project rows carry the working directory in their heading. A project-scope result is meaningless without it, because the answer changes with every `cd` — so name the directory that step 1.3 scanned, even when the project table is empty. @@ -83,7 +117,7 @@ When `.env` or `.envrc` exists in that directory, name the spec-table variables Save each collector's raw lines to a file, then run -`jsc-cli/tools/build-todo.sh --config {scan-all 輸出} --wiring {cli}={status 輸出} --version {report 輸出}` +`{CLI_ROOT}/tools/build-todo.sh --config {scan-all 輸出} --wiring {cli}={status 輸出} --version {report 輸出}` one `--wiring` per detected CLI. The script merges the three sources and orders them `missing` → `invalid` → `unwired` → `落後`. Nothing wrong → it prints one row whose class reads 無. @@ -111,15 +145,15 @@ host=$(hostname 2>/dev/null || uname -n 2>/dev/null || printf 'unknown'); host=$ user=${USER:-$(id -un 2>/dev/null || printf 'unknown')} ``` -`${host%%.*}` is the point of the snippet: `hostname` prints the FQDN on some machines and the short name on others, so a hand-written value gives one machine two pages that never merge again. Pass `"{host}/{user}"` to `gitea.sh hash-id` and use exactly what it prints. It is the host and the login account, not `{owner}/{repo}` — doctor checks a machine, and it has to work in directories that are not repositories at all. +`${host%%.*}` is the point of the snippet: `hostname` prints the FQDN on some machines and the short name on others, so a hand-written value gives one machine two pages that never merge again. Pass `"{host}/{user}"` to `{JSC_ROOT}/jsc-gitea/tools/gitea.sh hash-id` and use exactly what it prints. It is the host and the login account, not `{owner}/{repo}` — doctor checks a machine, and it has to work in directories that are not repositories at all. -**`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_{HASH}` — content page.** Repo: `{JSC_ROOT}/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`. 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 +**`CHECK_CONTENTS` — contents page, in the contents repo.** Repo: `{JSC_ROOT}/jsc-gitea/tools/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 1 "CHECK_{HASH}" {block file} templates/check-contents.md` +`{JSC_ROOT}/jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 "CHECK_{HASH}" {block file} {CLI_ROOT}/templates/check-contents.md` -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 block file holds the whole H2 block: the `## CHECK_{HASH}` line, a blank line, then one bullet per field in the order `{CLI_ROOT}/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 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. @@ -129,11 +163,11 @@ The page name is the key because it is the one value that does not move. It is d `1` is ``, 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. +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 `{JSC_ROOT}/jsc-gitea/tools/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}{URL}{reason}` per line. Only exit 0 may be written. +**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_ROOT}/jsc-gitea/tools/link-check.sh`. It prints `{OK|DEAD|SKIP}{URL}{reason}` per line. Only exit 0 may be written. | Exit | Meaning | Action | | --- | --- | --- | @@ -151,9 +185,9 @@ The script asks the API and never reads a web status code. A private repo's web | --- | --- | --- | | 0 | `updated` or `added` | Report which one it printed, with the repo and page it named | | 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 | +| 2 | Usage error | Report it as a defect in this skill. Do not retry with guessed arguments. A `{CLI_ROOT}/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 | +| 4 | Page absent and no template given | Unreachable the way this skill calls the script — the command above always passes `{CLI_ROOT}/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 blocks are unknown, so name the exit code and create nothing | @@ -171,7 +205,7 @@ Done when every link written into either page passed `link-check.sh` first — o 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]` +`{JSC_ROOT}/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. diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md index 00ec66e..be42ebe 100644 --- a/skills/setup/SKILL.md +++ b/skills/setup/SKILL.md @@ -7,9 +7,45 @@ description: Fix what jsc-cli:doctor found, one confirmed item at a time. Read t This skill writes. Every write is confirmed first, backed up, and verified afterwards. +## 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 — and never a bare relative one either. The permission layer matches paths statically: it expands no variable and no tilde, so such a path matches no allow rule and the call falls through to an approval prompt. A bare relative path is the worse form, because it resolves against whatever directory the CLI happens to be in — the operator's project directory, which is never a plugin root — so every bare call site is a place where a prefix gets guessed. + +**This skill writes, and that is what turns a guessed prefix from an annoyance into a wrong machine.** An old `tools/apply-config.sh` reached through some other version's directory rewrites the `# jsc-config` block of every rc file here to that version's idea of the key set, backs the old block up as though that were correct, and then step 4 re-verifies it with `show` from the same wrong copy — which agrees, because it is the same copy. The run reports that item as 已修 and the operator believes it, and nothing in this document catches it. Only the path does. + +Portability is no reason to put the variable back. Step 0 resolves the roots once, at run time, on whatever machine this runs on — that is where portability comes from. + +## 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 `current` directory itself, a farm of version-free symbolic links with one entry per plugin. Call it `{JSC_ROOT}` for the rest of this document. **Stop at that directory — never resolve one level further.** Resolving one of those entries lands on the versioned plugin cache (`/root/.claude/plugins/cache/jsc/jsc-gitea/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. + +Confirm the directory exists, in the same approved step: `[ -d "{the path just printed}" ]`. **No skill meets an unset `JSC_HOME` as often as this one.** It is an optional variable with a default, it has an `auto` row in `{CLI_ROOT}/tools/config-spec.tsv`, and writing it is one of the repairs this skill performs — so a machine whose `JSC_HOME` is unset or wrong is the ordinary reason this skill was called. With it unset the command prints `/current` and exits 0: non-empty, absolute, and nowhere. The emptiness check and the exit code both wave that through, and every literal path built from it names a place that is not there. + +**An unresolvable `{JSC_ROOT}` stops neither this run nor the repair.** Everything needed to write `JSC_HOME` — `{CLI_ROOT}/tools/apply-config.sh`, `{CLI_ROOT}/tools/scan-config.sh`, `{CLI_ROOT}/tools/build-todo.sh` — hangs off the second root below, which does not depend on `JSC_HOME` at all. Fix that item first, re-resolve `{JSC_ROOT}` once afterwards, and carry on; whatever is still unreachable — the wiki record of step 5, a delegated repair — is recorded as 未修好 with that as its reason, never guessed at. + +Substitute `{JSC_ROOT}` in every cross-plugin call, so what runs is a literal absolute path. `{JSC_ROOT}/jsc-gitea/tools/gitea.sh` becomes, for example, `/root/.jsc/current/jsc-gitea/tools/gitea.sh`. Resolve it once. Do not re-resolve it per call, and do not add a tool that prints it. + +### The second root — this skill's own `tools/` and `templates/` + +**Do not reach this skill's own files through `{JSC_ROOT}`, even though a `jsc-cli` link is normally sitting there.** `jsc-cli:deploy` refreshes the whole farm at the end of every round, so on a machine that has deployed, that link exists. This skill still may not lean on it, for two reasons of its own. + +The first is the paragraph above: the machine this skill is called to repair is often the machine whose `JSC_HOME` is unset or wrong, and on it the farm cannot be reached while the repair itself must still run. Route the repair tools through the farm and the one fault they exist to fix becomes the fault that stops them. + +The second is what this skill does with a stale script. Step 3 hands every 落後 domain to `jsc-cli:deploy` precisely because the versions on this machine may be behind — and the farm is governed by that same staleness. Reaching `apply-config.sh` through it would repair the machine with the very tools that machine has just been judged to have outgrown, and the result is written into rc files rather than merely printed. + +They sit at `{plugin root}/tools/` and `{plugin root}/templates/`, 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 every own-plugin path as `{CLI_ROOT}/tools/{script}` or `{CLI_ROOT}/templates/{file}` — `/root/.claude/plugins/cache/jsc/jsc-cli/0.3.3/tools/apply-config.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 calls raises an approval prompt. **That is acceptable in this skill and in no unattended one**: setup runs with the operator in front of it — step 2 puts every item to them one at a time, and nothing is written before they answer — 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 **before writing anything**, because a guessed prefix writes this machine with some other version's script. + +Done when `{JSC_ROOT}` holds one existing absolute directory or its failure is recorded as the `JSC_HOME` item, and `{CLI_ROOT}` holds one literal absolute path. + ## 1. Get the work list -Read the 待修項目 table from wiki `CHECK_{HASH}` — repo from `jsc-gitea/tools/gitea.sh wiki-repo CHECK`, page name from `gitea.sh hash-id "{host}/{user}"`, where `host` is the **short hostname** and `user` the login account, both taken from the machine: +Read the 待修項目 table from wiki `CHECK_{HASH}` — repo from `{JSC_ROOT}/jsc-gitea/tools/gitea.sh wiki-repo CHECK`, page name from `{JSC_ROOT}/jsc-gitea/tools/gitea.sh hash-id "{host}/{user}"`, where `host` is the **short hostname** and `user` the login account, both taken from the machine: ```sh host=$(hostname 2>/dev/null || uname -n 2>/dev/null || printf 'unknown'); host=${host%%.*} @@ -22,11 +58,11 @@ No page, or `wiki-repo` exits 3, or any other non-zero exit from `wiki-repo`, `h | Checker | Command | Exit branching | | --- | --- | --- | -| Settings | `tools/scan-config.sh scan all` | 0 → use the rows; 2 → usage error, report it as a defect in this skill; 3 → spec table missing, name the path and `JSC_CONFIG_SPEC`; other → report settings as 無法驗證 | -| Wiring | `tools/detect-clis.sh`, then `JSC_READONLY=1 jsc-hooks/tools/wire-cli.sh status {cli}` per detected CLI — this step only takes stock, and `wire-cli.sh` without a subcommand rewires, so the read-only contract is carried in the environment rather than trusted to a correctly typed subcommand | detect-clis exit 0 with no row → no CLI to wire, say so and skip; detect-clis non-zero → report wiring as 無法驗證 with the exit code. Per CLI: 0 wired and 1 degraded → nothing to fix; 2 → usage error, defect in this skill; 3 → CLI not installed, drop it; 5 → collect its `missing` items; 6 → readonly refused the call, which means the subcommand was mistyped into a writing one — nothing on the machine changed; fix the command and rerun that CLI; other → report that CLI as 無法驗證 | -| Versions | `jsc-hooks/hooks/version-guard.sh report` | 0 → use the rows, and treat a report with no `{domain}` row or a `noregistry` line as 無法驗證 — other exits → report versions as 無法驗證 with the exit code | +| Settings | `{CLI_ROOT}/tools/scan-config.sh scan all` | 0 → use the rows; 2 → usage error, report it as a defect in this skill; 3 → spec table missing, name the path and `JSC_CONFIG_SPEC`; other → report settings as 無法驗證 | +| Wiring | `{CLI_ROOT}/tools/detect-clis.sh`, then `JSC_READONLY=1 {JSC_ROOT}/jsc-hooks/tools/wire-cli.sh status {cli}` per detected CLI — this step only takes stock, and `wire-cli.sh` without a subcommand rewires, so the read-only contract is carried in the environment rather than trusted to a correctly typed subcommand | detect-clis exit 0 with no row → no CLI to wire, say so and skip; detect-clis non-zero → report wiring as 無法驗證 with the exit code. Per CLI: 0 wired and 1 degraded → nothing to fix; 2 → usage error, defect in this skill; 3 → CLI not installed, drop it; 5 → collect its `missing` items; 6 → readonly refused the call, which means the subcommand was mistyped into a writing one — nothing on the machine changed; fix the command and rerun that CLI; other → report that CLI as 無法驗證 | +| Versions | `{JSC_ROOT}/jsc-hooks/hooks/version-guard.sh report` | 0 → use the rows, and treat a report with no `{domain}` row or a `noregistry` line as 無法驗證 — other exits → report versions as 無法驗證 with the exit code | -Merge the three with `tools/build-todo.sh --config {設定輸出} --wiring {cli}={接線輸出} --version {版本輸出}` so the ordering rule lives in one place. Exit 0 → the `todo` rows are the work list; exit 2 → usage error, report it as a defect in this skill; exit 3 → name the unreadable input and rerun that one checker; any other exit → stop and report, because a half-merged list would silently drop a whole class of items. +Merge the three with `{CLI_ROOT}/tools/build-todo.sh --config {設定輸出} --wiring {cli}={接線輸出} --version {版本輸出}` so the ordering rule lives in one place. Exit 0 → the `todo` rows are the work list; exit 2 → usage error, report it as a defect in this skill; exit 3 → name the unreadable input and rerun that one checker; any other exit → stop and report, because a half-merged list would silently drop a whole class of items. Keep the version report from that run. Step 3 hands it to `jsc-cli:deploy` instead of making it query again. @@ -50,8 +86,8 @@ Done when every item is either confirmed with a value or recorded as skipped. | Route | Action | | --- | --- | -| `auto` on a variable | `tools/apply-config.sh set {KEY} {VALUE}` | -| `auto` on a directory | `tools/apply-config.sh mkdir {PATH}` | +| `auto` on a variable | `{CLI_ROOT}/tools/apply-config.sh set {KEY} {VALUE}` | +| `auto` on a directory | `{CLI_ROOT}/tools/apply-config.sh mkdir {PATH}` | | `ask` | same two commands, with the value the user just gave | | `manual` | print the exact steps and the file to edit; the operator does it | | domain 落後 | call `jsc-cli:deploy` with mode `update` **and the version report from step 1**, so it neither re-asks the mode nor re-queries the versions | @@ -81,8 +117,8 @@ Pick the check by what was actually written, because the two kinds of write beco | What was written | Re-verify with | Why this check | | --- | --- | --- | -| An environment variable in a shell rc file | `tools/apply-config.sh show`, confirming the `KEYVALUE` line is in the `# jsc-config` block | The block is a fact that is already true. The variable reaching the environment is not — a rc file does not touch the running shell | -| A directory | `tools/scan-config.sh scan {scope}`, confirming the row is no longer `missing` or `invalid` | The directory exists the moment it is created | +| An environment variable in a shell rc file | `{CLI_ROOT}/tools/apply-config.sh show`, confirming the `KEYVALUE` line is in the `# jsc-config` block | The block is a fact that is already true. The variable reaching the environment is not — a rc file does not touch the running shell | +| A directory | `{CLI_ROOT}/tools/scan-config.sh scan {scope}`, confirming the row is no longer `missing` or `invalid` | The directory exists the moment it is created | | Wiring, versions, model tags (delegated) | The owner skill's own returned result | The owner already ran its own verification | The same exit branching as step 1 applies to `scan-config.sh` and to `apply-config.sh`. @@ -97,15 +133,15 @@ Done when every applied item has a fresh verdict from the checker its own row na 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. +Rewrite `CHECK_{HASH}` through `jsc-gitea:wiki` with the post-fix state, per `{CLI_ROOT}/templates/check-page.md` — repo from `{JSC_ROOT}/jsc-gitea/tools/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. It is an H1, a `>` preamble and one H2 block per machine — no markdown table anywhere on it. Write the block with +`CHECK_CONTENTS` is a **contents page**, it lives in the contents repo (`{JSC_ROOT}/jsc-gitea/tools/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 1 "CHECK_{HASH}" {block file} templates/check-contents.md` +`{JSC_ROOT}/jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 "CHECK_{HASH}" {block file} {CLI_ROOT}/templates/check-contents.md` 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 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 block file holds the whole H2 block: the `## CHECK_{HASH}` line, a blank line, then one bullet per field in the order `{CLI_ROOT}/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 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. @@ -113,11 +149,11 @@ A key holding a URL would be a moving key: the URL changes with `GITEA_HOST`, wi `1` is ``, 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. +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 `{JSC_ROOT}/jsc-gitea/tools/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}{URL}{reason}` per line. Only exit 0 may be written. +**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_ROOT}/jsc-gitea/tools/link-check.sh`. It prints `{OK|DEAD|SKIP}{URL}{reason}` per line. Only exit 0 may be written. | Exit | Meaning | Action | | --- | --- | --- | @@ -135,15 +171,15 @@ The script asks the API and never reads a web status code. A private repo's web | --- | --- | | 0 | Report the `updated` or `added` result with the repo and page it named | | 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 | +| 2 | Usage error. Report it as a defect in this skill; do not retry with guessed arguments. A `{CLI_ROOT}/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 | +| 4 | Unreachable the way this skill calls the script — the command above always passes `{CLI_ROOT}/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 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 block and points nowhere. +`{JSC_ROOT}/jsc-gitea/tools/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. @@ -155,7 +191,7 @@ Done when every link written into either page passed `link-check.sh` first — o 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]` +`{JSC_ROOT}/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. diff --git a/templates/check-contents.md b/templates/check-contents.md index 86f2d03..d295078 100644 --- a/templates/check-contents.md +++ b/templates/check-contents.md @@ -4,17 +4,19 @@ > > 本頁落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫，與體檢頁 `CHECK_{HASH}` 不同庫。目錄頁全部住這裡，不退回 `JSC_WIKI_REPO_CHECK`。 > -> 寫入語意：一個區塊代表一台執行環境，也就是一組主機加帳號。一律用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH} {區塊檔} {本範本}` 寫，它先讀回整頁，該執行環境已經有區塊就整塊換掉，沒有才在頁尾附加一個區塊。禁止整頁覆蓋，也不得改動別人的區塊。體檢頁 `CHECK_{HASH}` 只留最新一次結果、可以整頁改寫，這份目錄頁不行。 +> 路徑寫法：底下每一支腳本都以字面絕對路徑呼叫，不留 `$JSC_HOME`、不留波浪號，也不留裸的相對路徑——權限層靜態比對路徑，帶變數的比不中任何規則，相對路徑則會對著操作者當下的工作目錄解，而那裡從來不是外掛根目錄。`{JSC_ROOT}` 是 `readlink -f "$JSC_HOME/current"` 解出的那個目錄，解到那一層就停，不再往下解成帶版本號的快取路徑；`{CLI_ROOT}` 是 CLI 載入技能時講明的 jsc-cli 外掛基底目錄。兩者都在技能開跑時各解一次，之後逐字代入。 +> +> 寫入語意：一個區塊代表一台執行環境，也就是一組主機加帳號。一律用 `{JSC_ROOT}/jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH} {區塊檔} {CLI_ROOT}/templates/check-contents.md` 寫，它先讀回整頁，該執行環境已經有區塊就整塊換掉，沒有才在頁尾附加一個區塊。禁止整頁覆蓋，也不得改動別人的區塊。體檢頁 `CHECK_{HASH}` 只留最新一次結果、可以整頁改寫，這份目錄頁不行。 > > 參數說明：第二個參數 `1` 是 ``，只在這一頁還留著舊的 markdown 表格時用得到，指舊表格裡持有身分那一欄的序號，也就是持有 `[CHECK_{HASH}](網址)` 的第 1 欄，自動轉檔時取那一格的文字當 H2 標題；頁面已經是條列格式就完全忽略它。第三個參數 `` 是 H2 標題文字，也就是體檢頁頁名 `CHECK_{HASH}`。第四個參數是區塊檔，不是列檔：內容為 `## CHECK_{HASH}` 那一行、一個空行，再接各條欄位。 > -> 鍵是 H2 標題 `CHECK_{HASH}`：`jsc-gitea/tools/hash-id` 印出什麼就接在 `CHECK_` 後面，完整 40 碼大寫十六進位，不截短、不加別的前後綴、不包成連結、不加日期。腳本比對的是去掉頭尾空白後的整段標題文字，鍵一定要跟標題一字不差。 +> 鍵是 H2 標題 `CHECK_{HASH}`：`{JSC_ROOT}/jsc-gitea/tools/hash-id` 印出什麼就接在 `CHECK_` 後面，完整 40 碼大寫十六進位，不截短、不加別的前後綴、不包成連結、不加日期。腳本比對的是去掉頭尾空白後的整段標題文字，鍵一定要跟標題一字不差。 > > 鍵用頁名才穩。頁名只由 `{短主機名}/{登入帳號}` 決定；`GITEA_HOST` 換掉、`JSC_WIKI_REPO_CHECK` 換過存取庫、Gitea 對頁名的網址編碼有差，網址就跟著變，頁名一個字都不動。拿含網址的值當鍵，比對就永遠比不中，同一台機器每體檢一次就多附一個區塊，畫面上還看不出來。 > -> 連結寫法：「體檢頁」那一條的連結只給人點，不當鍵用；H2 標題本身不放連結、不放網址。連結一律寫成 `[{文字}]({連結})`，也就是 `[CHECK_{HASH}]({wiki-url 印出的絕對網址})`，網址取 `jsc-gitea/tools/gitea.sh wiki-url` 印出的那一串，不自己組路徑。同 wiki 的雙括號寫法一概不用：兩頁分屬不同存取庫，連不過去，畫面上還看不出壞掉。 +> 連結寫法：「體檢頁」那一條的連結只給人點，不當鍵用；H2 標題本身不放連結、不放網址。連結一律寫成 `[{文字}]({連結})`，也就是 `[CHECK_{HASH}]({wiki-url 印出的絕對網址})`，網址取 `{JSC_ROOT}/jsc-gitea/tools/gitea.sh wiki-url` 印出的那一串，不自己組路徑。同 wiki 的雙括號寫法一概不用：兩頁分屬不同存取庫，連不過去，畫面上還看不出壞掉。 > -> 連結驗證：這個區塊要寫進去的每一個連結，先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫。有任何一筆 DEAD 就整個區塊都不寫，把連不到的清單回報給呼叫端。結束碼 3 代表 `GITEA_HOST` 沒設定，先設好再寫，不得跳過驗證；結束碼 7 代表金鑰失效，停下來回報金鑰問題，不要當成死連結。驗證一律走 API，不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把好連結判成壞的，整批砍掉還在的頁。 +> 連結驗證：這個區塊要寫進去的每一個連結，先交給 `{JSC_ROOT}/jsc-gitea/tools/link-check.sh`，結束碼 0 才寫。有任何一筆 DEAD 就整個區塊都不寫，把連不到的清單回報給呼叫端。結束碼 3 代表 `GITEA_HOST` 沒設定，先設好再寫，不得跳過驗證；結束碼 7 代表金鑰失效，停下來回報金鑰問題，不要當成死連結。驗證一律走 API，不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把好連結判成壞的，整批砍掉還在的頁。 ## CHECK_{HASH} diff --git a/templates/check-page.md b/templates/check-page.md index f4413fa..5db2d3e 100644 --- a/templates/check-page.md +++ b/templates/check-page.md @@ -2,6 +2,7 @@ > 由 `jsc-cli:doctor` 維護。這是體檢頁 `CHECK_{HASH}`，只保留最新一次結果，重跑就整頁覆寫。 > 修復請執行 `/jsc-cli:setup`，它讀這頁的「待修項目」逐項處理。 +> 底下提到的腳本都以字面絕對路徑呼叫，不留 `$JSC_HOME`、不留波浪號，也不留裸的相對路徑；`{CLI_ROOT}` 是 CLI 載入技能時講明的 jsc-cli 外掛基底目錄，技能開跑時取一次，之後逐字代入。 - 體檢時間：{yyyy-MM-dd HH:mm} - 工作目錄：{絕對路徑} @@ -44,7 +45,7 @@ ## 待修項目 -> 前六欄直接來自 `jsc-cli/tools/build-todo.sh` 的 `todo` 列，順序與類別由那支腳本決定，這裡不另行排序。 +> 前六欄直接來自 `{CLI_ROOT}/tools/build-todo.sh` 的 `todo` 列，順序與類別由那支腳本決定，這裡不另行排序。 > 「影響」欄由 `jsc-cli:doctor` 補上。`/jsc-cli:setup` 從這張表接手；沒有待修項目時腳本會印一列「無」。 | 順序 | 類別 | 項目 | 範圍 | 現況 | 修法 | 影響 | @@ -53,7 +54,7 @@ ## 未登錄變數 -> 原始碼有用到、`config-spec.tsv` 沒登錄的變數。體檢不判定它們，只提醒維護者補登錄。 +> 原始碼有用到、`{CLI_ROOT}/tools/config-spec.tsv` 沒登錄的變數。體檢不判定它們，只提醒維護者補登錄。 | 變數 | 出現次數 | | --- | --- | -- 2.53.0 From 56dbffa25c818eeb2c97d03057bf80ca6253b432 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 3 Sep 2026 13:07:07 +0800 Subject: [PATCH 2/2] =?UTF-8?q?chore(plugin):=20=E4=B8=89=E4=BB=BD=20manif?= =?UTF-8?q?est=20=E5=8D=87=E7=89=88=E8=87=B3=200.3.4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 兩支技能的路徑守則要靠版號才傳得到機器端。 三份 manifest 由 sync-skill-manifest.sh 同步，只動版本欄位。 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 30e974e..28f83ee 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-cli", - "version": "0.3.3", + "version": "0.3.4", "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index a349ef3..0eba21b 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-cli", - "version": "0.3.3", + "version": "0.3.4", "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署", "skills": "./skills", "jsc": { diff --git a/plugin.json b/plugin.json index d45fd2a..83278fd 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-cli", - "version": "0.3.3", + "version": "0.3.4", "description": "CLI 偵測、模型能力標籤、子代理派工與技能庫批次部署", "skills": "./skills/", "jsc": { -- 2.53.0