2026-08-31 08:18:51 +00:00
1 changed files with 23 additions and 0 deletions
@@ -0,0 +1,23 @@
+# jsc-hooks 技能行為清單
+
+本頁記錄 jsc-hooks 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
+
+## hooks-install
+
+| 項目 | 內容 |
+| --- | --- |
+| 觸發時機 | 裝好或更新完 jsc 技能組之後，要把九支 hook 接線到每一支已安裝的 CLI 時用；`jsc-cli:deploy` 收尾會把偵測到的 CLI 清單交給它。不用於撰寫新的 hook，也不用於單獨修一支壞掉的 hook，那是 `jsc-hooks:repair` 的事 |
+| 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/jsc-hooks` 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 `ERROR_{HASH}` 並轉給 `jsc-hooks:repair`、逐 CLI 回報五道關卡的結果 |
+| 外部呼叫 | `tools/wire-cli.sh purge`、`tools/wire-cli.sh {cli}`、`tools/wire-cli.sh status`、`tools/wire-cli.sh smoke`、`tools/scan-hook-errors.sh`、`tools/report-error.sh`、`jsc-cli/tools/detect-clis.sh`、`jsc-hooks:repair` 技能、`jsc-gitea:wiki`（寫 `ERROR_{HASH}` 時經 `report-error.sh`） |
+| 完成條件 | 每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 `lines` 條數與它自己的斷言相符，codex、copilot、antigravity、kiro 四支據實回報 `degraded` 與 `unavailable`，而且每一筆錯誤都帶一個 `ERROR_{HASH}` 結果與一條對 `develop` 的修正 PR 連結 |
+| 可驗證跡象 | 各 CLI 的設定檔多出 `<!-- jsc-hooks -->` 標記區塊（codex 的 `config.toml`、copilot 與 antigravity 的別名檔、kiro 的 `.kiro/hooks/jsc-hooks.json`）、`$JSC_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}` 並在 `ERROR_CONTENTS` 補一列、修正路徑留下一條對 `develop` 的 PR |
+
+## repair
+
+| 項目 | 內容 |
+| --- | --- |
+| 觸發時機 | `hooks-install` 或 `report-error.sh` 回報某一支 hook 失敗時用，或是重新接線之後那支 hook 還是一直失敗時用。不用於例行接線，也不用於與 hook 無關的修改 |
+| 關鍵步驟 | 從 `ERROR_{HASH}` 讀失敗情境（沒有頁就讀失敗的 `status=` 那一行，讀不到就停下來問）、跑 `detect-clis.sh`、每一支偵測到的 CLI 各開一個唯讀 sub agent 診斷並交回根因、要改的檔案與驗證指令、挑最小的修正改進 hooks 存取庫、跑 `wire-cli.sh smoke {cli}` 驗到 exit 0、跑 `sync-skill-manifest.sh .` 同步版本、以 `jsc-git:pr` 對 `develop` 開 PR |
+| 外部呼叫 | `jsc-gitea:wiki`、`jsc-cli/tools/detect-clis.sh`、`tools/wire-cli.sh smoke`、`jsc-meta/tools/sync-skill-manifest.sh`、`jsc-git:pr`；診斷階段另以 sub agent 叫用各支已安裝的 AI CLI |
+| 完成條件 | 修正已經落在磁碟上、`wire-cli.sh smoke` 對受影響的 CLI 回 exit 0、`sync-skill-manifest.sh` 回 exit 0 而且三份 manifest 版本一致，最後拿到一條對 `develop` 的 PR 連結；開不出 PR 時要講明修正已套用但尚未合併、帶上分支名與失敗原因 |
+| 可驗證跡象 | hooks 存取庫多一個修正提交與一條推上去的分支、`develop` 上多一條 PR、三份 manifest 與 README 技能清單版本一致、`wire-cli.sh smoke` 由失敗轉為 exit 0 |