Files
cli/templates/check-page.md
jiantw83 5b0eb784b4 fix(doctor,setup): 兩支技能補上路徑守則,呼叫一律字面絕對路徑
這兩支技能的腳本呼叫原本全是裸相對路徑,整份文件沒有任何路徑守則。相對路徑會對著操作者當下的工作目錄解,而那裡從來不是外掛根目錄,所以每一個呼叫點都是模型就地猜前綴的地方。部署技能原本三處相對路徑被補成帶變數路徑,就是同一個機制。

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

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

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

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

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

行為契約四列跟著改,並補上可稽核的跡象:回報裡的腳本路徑全是字面絕對路徑,跨外掛的路徑中間是 current 那一層而不是帶版本號的快取路徑。
2026-09-03 13:07:07 +08:00

2.7 KiB
Raw Permalink Blame History

執行環境體檢 — {hostname}/{使用者帳號}

由 jsc-cli:doctor 維護。這是體檢頁 CHECK_{HASH},只保留最新一次結果,重跑就整頁覆寫。 修復請執行 /jsc-cli:setup,它讀這頁的「待修項目」逐項處理。 底下提到的腳本都以字面絕對路徑呼叫,不留 $JSC_HOME、不留波浪號,也不留裸的相對路徑;{CLI_ROOT} 是 CLI 載入技能時講明的 jsc-cli 外掛基底目錄,技能開跑時取一次,之後逐字代入。

  • 體檢時間:{yyyy-MM-dd HH:mm}
  • 工作目錄:{絕對路徑}
  • 執行 CLI:{claude、codex、copilot、antigravity、kiro 五選一}

結論

分類 通過 待修 略過
技能版本 {n} {n} {n}
Hook 接線 {n} {n} {n}
全域設定 {n} {n} {n}
自我設定 {n} {n} {n}

技能版本

Domain 本機 遠端 狀態
{domain} {版本} {版本} {落後、最新、超前、查詢失敗、無法驗證}

Hook 接線

CLI 狀態 缺漏項目 說明
{cli} {wired、degraded、unwired、skipped} {項目名,逗號分隔;無則寫「無」} {降級原因或未偵測到執行檔}

全域設定

項目 必要 現況 期望 修法 判定
{變數或檔案} {是、否} {實際值或未設定} {該是什麼} {自動、詢問、手動} {通過、走預設、未設定、缺漏、設錯、略過}

自我設定

工作目錄:{絕對路徑}

項目 必要 現況 期望 修法 判定
{變數或檔案} {是、否} {實際值或未設定} {該是什麼} {自動、詢問、手動} {通過、走預設、未設定、缺漏、設錯、略過}

待修項目

前六欄直接來自 {CLI_ROOT}/tools/build-todo.sh 的 todo 列,順序與類別由那支腳本決定,這裡不另行排序。 「影響」欄由 jsc-cli:doctor 補上。/jsc-cli:setup 從這張表接手;沒有待修項目時腳本會印一列「無」。

順序 類別 項目 範圍 現況 修法 影響
{n} {missing、invalid、unwired、落後、無} {變數、檔案、接線項目或 plugin 名} {global、project、cli 代號、版本} {實際值、缺少接線的檔案或本機與遠端版本} {auto、ask、manual 或接手的技能名} {不修的話哪些技能跑不動}

未登錄變數

原始碼有用到、{CLI_ROOT}/tools/config-spec.tsv 沒登錄的變數。體檢不判定它們,只提醒維護者補登錄。

變數 出現次數
{變數名} {n}