jiantw83
95c7bb1eee
版本閘門對 11 個 domain 全部回「查詢失敗」，等於完全失效——它擋不下任何版本落後的技能呼叫，而且是無聲的：report 照印表格，只是每一列都寫查詢失敗。 根因是 jsc_gitea_sh 回傳的路徑帶著 ..，而那些 .. 要穿過 current/jsc-hooks 這條符號連結。兩種解析方式對它的答案不同：核心與 [ -f ] 用實體解析、跟著連結走，判定檔案存在；shell 的 cd 用邏輯解析、純文字消去 ..，落到一個不存在的目錄。所以 [ -f ] 檢查通過、路徑交了出去，gitea.sh 的 cd 卻失敗，回結束碼 2 與空輸出，呼叫端就判成查不到。 新增 jsc_abs_path，用 cd -P 加 pwd -P 把路徑正規化成不含 .. 的實體路徑。挑這個做法是因為兩者都是 shell 內建，不必在 PATH 上找執行檔——這些函式會在 cron 那種只剩幾段 PATH 的環境下跑，少一個外部相依就少一個解不出來的理由。jsc_gitea_sh 的四條候選改成尾端統一正規化，正規化失敗就退回原樣路徑，「找得到」的判準不變。 wire-cli.sh 的 HERE 與 ROOT 一併改成實體解析。那是同一個根因的另一種發作方式：ROOT 會被 ln -sfn 當成目標，而這支腳本常常就是經由那條連結被叫起來的，邏輯解析會讓 ROOT 等於連結自己，連結被改成指向自己，全機器 hook 一起失效。這件事實際發生過。原本靠兩道防線擋著：事後的 [ -f ] 檢查，以及文件要求呼叫端先解出實體根目錄。前者要等連結已經被寫壞才攔得到，後者靠人記得。改成實體解析之後這個失敗模式不可能成立。 行為契約第 10 列跟著改：從實體根目錄跑 wire-cli.sh 的規定保留，但性質從必要條件降成多一層保險，並寫明保險為什麼還值得買——舊版腳本還在別的機器上跑。 驗證用同形佈局做：暫存區搭一套一樣形狀的連結農場，先塞原版重現失敗、再塞改版確認修好。真實環境的連結與快取全程沒有動過。
8.2 KiB
8.2 KiB
jsc-hooks 技能行為清單
本頁記錄 jsc-hooks 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
hooks-install
| 項目 | 內容 |
|---|---|
| 觸發時機 | 裝好或更新完 jsc 技能組之後，要把九支 hook 接線到每一支已安裝的 CLI 時用；jsc-cli:deploy 收尾會把偵測到的 CLI 清單交給它。不用於撰寫新的 hook，也不用於單獨修一支壞掉的 hook，那是 jsc-hooks:repair 的事 |
| 關鍵步驟 | 先跑前置步驟解出兩個字面絕對路徑：readlink -f "$JSC_HOME/current" 解出連結農場根目錄（跨 domain 呼叫用它），readlink -f "$JSC_HOME/current/jsc-hooks" 解出 jsc-hooks 的實體根目錄（只有 wire-cli.sh 從這裡跑。它會改寫自己正踩著的那條連結，但它自己已經把 HERE 與 ROOT 解成實體路徑，ln -sfn 不會再把連結指向自己，所以從實體根目錄跑現在是多一層保險、不是唯一防線；照做的理由是舊版腳本還在別的機器上跑，那些版本走連結跑仍會把連結寫成指向自己、全機器 hook 一起失效）、兩個路徑各解一次不重解、各自在同一步用 [ -d ] 查過印出來的目錄真的存在（JSC_HOME 沒設時第一條會印出 /current、結束碼 0，非空又是絕對路徑，只查前三項擋不下來），任何一條解不出來、不是絕對路徑、或目錄不存在就停手回報是哪一條沒解出來並叫人跑 jsc-cli:deploy，不接任何線也不猜路徑、不退回帶版本號的快取路徑、之後每一次腳本呼叫都用解出來的字面絕對路徑開頭、取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 detect-clis.sh）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 {連結農場根}/jsc-hooks 連結）、其餘 CLI 一支一個 sub agent 並行、每支 CLI 依序走 purge、接線、status、smoke、scan 五道關卡、讀每道關卡自己印的第一行判定、任一關卡出錯就寫 ERROR_{HASH} 並轉給 jsc-hooks:repair（異常頁與索引目錄頁分屬兩個存取庫，各自解析；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、目錄頁那一列指向異常頁的連結一律寫成 [{文字}]({連結})，網址取 gitea.sh wiki-url，寫進去之前先過 jsc-gitea/tools/link-check.sh，結束碼 0 才寫連結、驗不過那一格只留純文字頁名而那一列與異常頁照寫（report-error.sh 內部做完，結束碼不變）、逐 CLI 回報五道關卡的結果 |
| 外部呼叫 | readlink -f（前置步驟解兩個根目錄，各一次）、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）、jsc-gitea/tools/gitea.sh wiki-url 與 jsc-gitea/tools/link-check.sh（同樣經 report-error.sh，取目錄頁那一列的網址並驗它連得到）；接線腳本內部另呼叫 hooks/skill-name.sh 與 hooks/deny.sh 做冒煙斷言 |
| 完成條件 | 前置步驟解出的兩個根目錄都是一條存在的絕對路徑（各自用 [ -d ] 查過），而且整個流程沒有任何一次腳本呼叫帶著未展開的變數或波浪號，每一支偵測到的 CLI 都有五道關卡各一行判定，沒有任何一道回結束碼 2，smoke 的 lines 條數與它自己的斷言相符，claude、codex、copilot、antigravity 回 wired 而 kiro 回 degraded（CLI 擋不下技能叫用），四支非 claude 的執行期錯誤掃描一律據實回 unavailable，各 CLI 的形狀與觸發驗證等級分開寫進回報（codex、antigravity、kiro 形狀實證，copilot 形狀未證；kiro 觸發部分實證，其餘未驗證），每一筆錯誤都帶一個 ERROR_{HASH} 結果與一條對 develop 的修正 PR 連結，而且目錄頁那一列的連結驗不過時，回報要講明那一列只有純文字頁名、沒有連結 |
| 可驗證跡象 | 各 CLI 的設定檔多出 jsc 段落：codex 的 config.toml 標記段落、hooks/codex-hooks.json（從 hooks/hooks.json 推導，matcher Skill 換成 Bash）與 .codex-plugin/plugin.json 指過去的 hooks 路徑字串、copilot 的 ~/.copilot/settings.json 頂層 hooks 鍵（matcher skill，合併不覆寫，enabledPlugins 與第三方條目原樣保留）與 $COPILOT_HOME 底下的指引檔、antigravity 的 ~/.gemini/config/hooks.json 的 jsc 段落（PreToolUse 為 Grouped、matcher ^view_file$，PreInvocation 維持 Flat）、kiro 的 ~/.kiro/agents/jsc.json（hooks 為 agentSpawn、userPromptSubmit、stop 三個合法事件加 timeout_ms、兩層 skill:// glob 的 resources、明列的 tools，並通過 kiro-cli agent validate）與 ~/.kiro/settings/cli.json 的 chat.defaultAgent=jsc；四支非 claude 的接線命令都以 JSC_CLI={代號} 前綴自帶 CLI 代號，缺了它兩道閘門解不出技能名、一律安靜放行，所以 status 把它列成單獨一項；另有 {連結農場根}/jsc-hooks 符號連結建立或更新，而且它指向 jsc-hooks 的實體根目錄、不是指向自己（readlink -f 解得出一個存在的目錄，裡面有 hooks/session-timer.sh 與 tools/jsc-wrap.sh）、各 CLI 設定裡存下來的接線命令也都是展開後的字面絕對路徑，只有存放庫自帶的 hooks/hooks.json 保留 ${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks 這段變數寫法，由 hook 自己的 shell 在執行當下展開、$JSC_HOME/backup/hooks/{cli}/{時間戳}/ 留下 purge 前的備份、出錯時 wiki 多一頁 ERROR_{HASH}（落在 JSC_WIKI_REPO_ERROR 解出的存取庫）並在索引目錄頁補一列（落在 JSC_WIKI_REPO_CONTENTS 解出的另一個存取庫，那一列的第 2 格寫成 [{頁名}]({絕對網址})，網址取自 gitea.sh wiki-url 且已經過 link-check.sh 驗到結束碼 0；驗不過那一格只有純文字頁名，report-error.sh 在 stderr 留一行 [jsc] 講明是哪一種原因）、修正路徑留下一條對 develop 的 PR 。接線完成後 $JSC_HOME/usage/events.jsonl 會逐行長出 {kind:hook} 事件，每支 hook 每次執行一筆，欄位含 status 與實際結束碼；跑過技能之後另有 {kind:skill,phase:start}。事件寫不進去不影響任何 hook 的結束碼 |
repair
| 項目 | 內容 |
|---|---|
| 觸發時機 | hooks-install 或 report-error.sh 回報某一支 hook 失敗時用，或是重新接線之後那支 hook 還是一直失敗時用。不用於例行接線，也不用於與 hook 無關的修改 |
| 關鍵步驟 | 從 ERROR_{HASH} 讀失敗情境（沒有頁就讀失敗的 status= 那一行，讀不到就停下來問）、跑 detect-clis.sh、每一支偵測到的 CLI 各開一個唯讀 sub agent 診斷並交回根因、要改的檔案與驗證指令、挑最小的修正改進 hooks 存取庫（技能名解析改 hooks/skill-name.sh、阻擋形態改 hooks/deny.sh，兩支是唯一真實來源，不在閘門裡各補一份）、跑 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。收尾在 $JSC_HOME/usage/events.jsonl 留下這一輪的 skill-end 事件，status 取 ok、blocked、failed、degraded 或 aborted，中途停下的那幾輪也照寫——只有 start 沒有配對 end 會被讀成中斷 |