fix(doctor,setup): 兩支技能補上路徑守則,呼叫一律字面絕對路徑

這兩支技能的腳本呼叫原本全是裸相對路徑,整份文件沒有任何路徑守則。相對路徑會對著操作者當下的工作目錄解,而那裡從來不是外掛根目錄,所以每一個呼叫點都是模型就地猜前綴的地方。部署技能原本三處相對路徑被補成帶變數路徑,就是同一個機制。

實際掃到的處數比預估多:體檢 18 處、修復 20 處。多出來的是兩類原本沒想到的——裸檔名的 Gitea 呼叫,以及被當成參數傳的資料檔。後者同樣會解錯地方,而且解錯了不會報錯。

兩支各補路徑守則與前置步驟,解出兩條根目錄:跨外掛走 current 那一層(解到那一層就停,再往下解會落到帶版本號的快取路徑,那種路徑進不了允許清單),技能自己的腳本與範本走 CLI 載入技能時講明的外掛基底目錄。

兩支都不靠 current 底下那條 jsc-cli 連結,但理由各自不同,不是照抄部署那一支的。體檢不能靠,因為它正是機器可疑時才跑的技能——觸發時機本身就是連結可能出錯的那幾個時刻,而連結指著舊版時拿到的是舊的掃描腳本與舊的規格表,掃出來的每一列都像真的發現,不會有任何錯誤訊息。修復更不能靠,因為它寫檔,而且它要修的其中一列正是那個決定連結位置的變數:那種機器上根目錄根本解不出來,而修它要用的腳本掛在外掛基底目錄底下、不依賴那個變數,所以解不出來既不停這一輪也不擋那一項修復。何況拿舊的寫入腳本改設定檔,再用同一份舊腳本重驗,兩邊當然對得上,整輪會報成已修。

失敗分支也與部署不同。部署解不出根目錄就停手;這兩支都不停——體檢把它記成一項發現然後跑完不需要跨外掛的檢查,因為唯讀體檢中途停掉操作者什麼都拿不到;修復把它當成待修的那一項,修好再重解一次。

兩份範本與說明文件一併改。範本是這兩支技能在同一輪一起讀的,而且指示寫入,留著裸路徑等於留一個繞過新規則的入口。範本裡另外補掉兩個路徑洞:指向範本自己的佔位符原本沒有路徑,以及一個連目錄都沒有的裸檔名。

行為契約四列跟著改,並補上可稽核的跡象:回報裡的腳本路徑全是字面絕對路徑,跨外掛的路徑中間是 current 那一層而不是帶版本號的快取路徑。
This commit is contained in:
2026-09-03 13:07:07 +08:00
parent 45187f5173
commit 5b0eb784b4
6 changed files with 127 additions and 54 deletions
+3 -3
View File
@@ -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` 是 `<key-col>`,只在頁面還是舊表格、需要自動轉檔時用得到,指舊表格裡持有 `[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` 是 `<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 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` 的本機那一個區塊,兩頁分屬不同存取庫。
<!-- JSC-SKILLS:END -->