jiantw83andClaude Fable 5
bdfb4619af
What：hooks-install SKILL.md 改寫接線表並加上逐 CLI 驗證欄；README 補上 sdlc-gate、tools 兩支腳本與 JSC_MODEL 變數說明；AGENTS.md 同步 domain 描述。 Why：新增 SDLC 模型鎖與 wrapper 方案後，安裝流程與環境變數契約已改變，文件必須與實作一致，否則接線技能會漏裝。 How：接線表改為三欄（CLI、接線、驗證），copilot 與 antigravity 改兩段式（jsc-wrap.sh 包裝＋規則檔追加），codex 與 kiro 註明模型鎖降級為技能步驟檢查；每步補上完成判準。 Who：執行 hooks-install 技能的 AI 助理與維護 jsc-hooks domain 的開發者。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
71 lines
4.7 KiB
Markdown
71 lines
4.7 KiB
Markdown
# 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/jsc.git），安裝 token 為 `jsc-hooks@jsc`。每個指令一行：
|
||
|
||
| CLI | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/jsc.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/jsc.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/jsc.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/jsc.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`。
|
||
|
||
## Hooks
|
||
|
||
| 腳本 | 事件 | 作用 |
|
||
| --- | --- | --- |
|
||
| `hooks/ste100-guard.sh` | UserPromptSubmit | 注入 STE100 繁體中文輸出規則（hook > prompt 強制層） |
|
||
| `hooks/session-timer.sh` | SessionStart / Stop / SessionEnd | 記錄工作階段起訖；`report` 子指令供 `jsc-log:worklog` 取花費時間 |
|
||
| `hooks/skill-usage.sh` | PostToolUse(Skill) | 記錄技能使用與呼叫鏈到 `$JSC_HOME/usage/*.jsonl`，供 `jsc-log:stats` 統計 |
|
||
| `hooks/sdlc-gate.sh` | UserPromptSubmit | SDLC 每 session 模型鎖：`lock`/`unlock` 由 jsc-sdlc 階段技能呼叫，`check` 在模型與鎖不符時注入拒絕提醒 |
|
||
|
||
Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。
|
||
|
||
## 工具
|
||
|
||
| 腳本 | 用途 |
|
||
| --- | --- |
|
||
| `tools/jsc-wrap.sh` | 無 hook 系統 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填 |
|
||
| `tools/scan-logs.sh` | 離線回填：解析 copilot、antigravity、codex 的原生日誌，把技能用量與階段界線補進 `$JSC_HOME`，重掃不重複 |
|
||
|
||
## 失敗回報範本
|
||
|
||
這兩個模板給外層的 hook 失敗回報流程使用，不改動現有 hook 行為。
|
||
失敗時若要寫入 wiki，套用這兩個檔案即可。
|
||
|
||
| 範本 | 用途 |
|
||
| --- | --- |
|
||
| `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 後逐一套用原生 hook 設定（claude 由 `hooks.json` 自動接線）。copilot、antigravity 改用兩段式：以 `tools/jsc-wrap.sh` 包裝啟動器補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍追加到各自的規則檔（以 `<!-- jsc-hooks -->` 標記整段取代，不重複追加）。codex、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 環境變數
|
||
|
||
| 變數 | 用途 | 未設定時 |
|
||
| --- | --- | --- |
|
||
| `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
|
||
| `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` | 非 Claude CLI 接線時由 `tools/jsc-wrap.sh` 或接線設定提供 | 安靜降級 |
|
||
| `JSC_MODEL` | 非 Claude CLI 的目前模型，供 `sdlc-gate.sh check` 比對 | 改讀 `~/.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 產出的工時與用量資料
|