plugins/hooks
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
83170e1b4362223167e2e1015b1e0a4015bdf82a
hooks/README.md
T
jiantw83andClaude Opus 5 83170e1b43 docs(hooks): 同步文件與參考資料 
What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。

Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。

How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。

Who：jsc-meta:skill-check 例行稽核（2026-08-25）。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 14:58:54 +08:00

89 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# jsc-hooks — 跨 CLI Hooks
jsc 技能組的 hooks domain：所有 hook **只放在這個 repo**（技能準則）。腳本為 POSIX shell，同時支援 stdin JSON（Claude 格式）與環境變數輸入，適用 claude / codex / copilot / antigravity / kiro。
## 安裝、更新、移除
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-hooks@jsc`。每個指令一行：
| CLI | 安裝 | 更新 | 移除 |
| --- | --- | --- | --- |
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-hooks@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-hooks@jsc` | `claude plugin uninstall jsc-hooks@jsc` |
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-hooks@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-hooks@jsc` |
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-hooks@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-hooks@jsc` | `copilot plugin uninstall jsc-hooks@jsc` |
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/hooks.git ~/plugins/hooks && agy plugin install ~/plugins/hooks` | `git -C ~/plugins/hooks pull && agy plugin uninstall jsc-hooks && agy plugin install ~/plugins/hooks` | `agy plugin uninstall jsc-hooks` |
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-hooks@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-hooks@jsc` | `kiro-cli plugin uninstall jsc-hooks@jsc` |
> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。
> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
## Hooks
| 腳本 | 事件 | 作用 |
| --- | --- | --- |
| `hooks/ste100-guard.sh` | UserPromptSubmit | 注入 STE100 繁體中文輸出規則（hook > prompt 強制層） |
| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖。子指令：`start` 記起始時間（已有紀錄就不動，給 claude 這種每階段有自己 session id 的 CLI）、`restart` 一律覆寫起始時間（給接不到 session id 的 kiro，不覆寫會把上一階段算進來）、`mark` 更新最後活動時間、`report` 供 `jsc-log:worklog` 取花費時間 |
| `hooks/version-guard.sh` | PreToolUse(Skill) | 技能使用前的版本前置檢查：本機**實際載入**版本落後遠端發佈版本就以 exit 2 擋下該次呼叫並提示更新指令（更新指令依當前 CLI 給）。只擋落後這一種情況：超前放行（開發技能組時本機本來就會超前），讀不到本機版本、推導不出站台、查不到遠端版本也一律放行。逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-cli:models`、`jsc-meta:*` |
| `hooks/skill-usage.sh` | PostToolUse(Skill) | 記錄技能使用與呼叫鏈到 `$JSC_HOME/usage/*.jsonl`，供 `jsc-log:stats` 統計 |
| `hooks/sdlc-gate.sh` | UserPromptSubmit | SDLC 階段能力標籤閘門與模型鎖：`lock {stage}` 由 jsc-sdlc 階段技能呼叫，從 transcript 讀出實際模型 id 比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖；`check` 在模型不符時以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`unlock` 為逃生門 |
Claude 由 `hooks/hooks.json` 自動接線五支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。
> 覆蓋範圍要據實看待：只有 claude 同時有 PreToolUse 與 UserPromptSubmit，五支 hook 全接得上，回報 `wired`。codex、copilot、antigravity、kiro 都沒有 pre-tool hook，接不上 `version-guard.sh` 的版本前置檢查，SDLC 模型鎖也只剩技能步驟檢查，這四個 CLI 一律回報 `degraded`，靠 `/jsc-cli:deploy` 定期更新。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。
> `version-guard.sh report` 是非 hook 的子指令：印出每個已安裝 jsc plugin 的
> 「{domain} {本機} {遠端} {落後｜最新｜超前｜查詢失敗}」，最後一行 `behind {落後個數}`。
> 本機沒有 Claude 的 plugin 註冊檔時改印 `noregistry {路徑}` 再接 `behind 0`，
> 代表這台機器無法做版本檢查，跟「全部最新」是兩件事。查遠端版本走與 hook 同一份快取
> 與同一個 `JSC_VERSION_TTL`，一次部署不會為每個 domain 各打一輪網路。
> `jsc-cli:deploy` 用它決定要不要把「更新」設成推薦選項。
## 工具
| 腳本 | 用途 |
| --- | --- |
| `tools/jsc-wrap.sh` | 沒有完整 hook 系統的 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填。`JSC_CLI` 存 CLI 代號，實際執行的是對應的執行檔（antigravity 是 agy、kiro 是 kiro-cli） |
| `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
| `tools/report-error.sh` | 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 `ERROR_{HASH}`，並在 `ERROR_CONTENTS` 附上一列索引。wiki 位置由 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR` 解析，解析不出來就安靜降級。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） |
| `tools/wire-cli.sh` | 單一 CLI 的接線流程：`{cli}` 對應的設定編輯、包裝別名安裝、hook 檔建立，皆以 `<!-- jsc-hooks -->`（或 `# jsc-hooks`）標記整段取代，重跑不重複。寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、kiro 的 JSON 必須成對且 `on`、`run` 在最上層）；以 `status=wired\|degraded\|skipped\|failed` 回報結果 |
## 失敗回報範本
這兩個模板是失敗回報頁的文案來源，由 `tools/report-error.sh` 填欄位後寫進 wiki。
用法：`tools/report-error.sh --hook {名稱} --exit {碼} --summary {摘要}`，錯誤輸出摘要走標準輸入。
| 範本 | 用途 |
| --- | --- |
| `templates/error-page.md` | 單筆 hook 異常頁 `ERROR_{HASH}`，記錄當次失敗的觸發條件、錯誤摘要與處理結果。 |
| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。 |
## Skills 目錄
呼叫方式：Claude / Antigravity `/jsc-hooks:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
<!-- JSC-SKILLS:START -->
### `hooks-install`
把五支 hook 接線到所有已安裝的 CLI：偵測 CLI 後，逐一呼叫 `tools/wire-cli.sh {cli}` 完成接線（claude 由 `hooks.json` 自動接線，無需寫入）。codex、copilot、antigravity 由該腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍追加到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入；這四個 CLI 沒有 pre-tool hook，版本前置檢查接不上，腳本會在 `reason` 裡講明，只有 claude 回報 `wired`。腳本第一行以 `status=wired|degraded|skipped|failed reason=...` 回報結果；`failed` 由技能改呼叫 `tools/report-error.sh` 寫一頁 `ERROR_{HASH}`。
<!-- JSC-SKILLS:END -->
## 環境變數
| 變數 | 用途 | 未設定時 |
| --- | --- | --- |
| `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
| `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
| `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | `tools/report-error.sh` 安靜降級，不寫 wiki |
| `JSC_VERSION_GUARD` | 設 `off` 完全略過版本前置檢查（離線工作用） | 啟用檢查 |
| `JSC_VERSION_TTL` | 遠端版本查詢的快取秒數 | 預設 600 |
| `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` / `JSC_TOOL_NAME` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供，代替 stdin JSON 的 `session_id`、`skill`、`tool_name`（`version-guard.sh` 也收沒有前綴的 `SKILL`、`TOOL_NAME`） | 安靜降級 |
| `JSC_MODEL` | 非 Claude CLI 的目前模型，供 `sdlc-gate.sh` 比對；優先序在 transcript 實際值與 stdin `model` 之後 | 改讀 `~/.claude/settings.json`，再不行就安靜降級 |
## 相關 domain
- [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：CLI 偵測（`tools/detect-clis.sh`）
- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：讀取本 domain 產出的工時與用量資料
Reference in New Issue View Git Blame Copy Permalink