From bdfb4619af64845712652ebc1d803263a6f31062 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 24 Aug 2026 11:36:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(hooks-install):=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E5=9B=9B=E6=94=AF=20hook=20=E7=9A=84=E6=8E=A5=E7=B7=9A?= =?UTF-8?q?=E8=AA=AA=E6=98=8E=E8=88=87=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 2 +- README.md | 15 ++++++++++++--- skills/hooks-install/SKILL.md | 29 +++++++++++++++-------------- 3 files changed, 28 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 89f890e..5196855 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # jsc-hooks — 給 AI 助理的指引 -本 repo 是 jsc 技能組的 `hooks` domain（跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 +本 repo 是 jsc 技能組的 `hooks` domain（跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 ## 規則 diff --git a/README.md b/README.md index 729910f..1c65465 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,16 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 | `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` 技能接線或降級為規則檔。 +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`，重掃不重複 | ## 失敗回報範本 @@ -44,7 +52,7 @@ Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技 ### `hooks-install` -把三支 hook 接線到所有已安裝的 CLI：偵測 CLI 後逐一套用原生 hook 設定，無 hook 系統的 CLI 降級為規則檔（以 `` 標記整段取代，不重複追加）。 +把四支 hook 接線到所有已安裝的 CLI：偵測 CLI 後逐一套用原生 hook 設定（claude 由 `hooks.json` 自動接線）。copilot、antigravity 改用兩段式：以 `tools/jsc-wrap.sh` 包裝啟動器補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍追加到各自的規則檔（以 `` 標記整段取代，不重複追加）。codex、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入。 @@ -53,7 +61,8 @@ Claude 由 `hooks/hooks.json` 自動接線；其他 CLI 用 `hooks-install` 技 | 變數 | 用途 | 未設定時 | | --- | --- | --- | | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` | -| `JSC_CLI` / `JSC_SESSION_ID` / `JSC_SKILL` | 非 Claude CLI 接線時由 wrapper 設定 | 安靜降級 | +| `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 diff --git a/skills/hooks-install/SKILL.md b/skills/hooks-install/SKILL.md index 4c51e44..867c443 100644 --- a/skills/hooks-install/SKILL.md +++ b/skills/hooks-install/SKILL.md @@ -1,30 +1,31 @@ --- name: hooks-install -description: Wire jsc hooks (STE100 guard, session timer, skill usage logger) into every installed AI CLI. Detect CLIs via jsc-cli detect-clis.sh, then apply native hook config per CLI or fall back to instruction files. Use after installing or updating the jsc plugin set; not for writing new hooks. +description: Wire jsc hooks (STE100 guard, session timer, skill usage logger, SDLC model gate) into every installed AI CLI. Detect CLIs via jsc-cli detect-clis.sh, then apply native hook config, the jsc-wrap.sh launcher, or an instruction-file fallback per CLI. Use after installing or updating the jsc plugin set; not for writing new hooks. --- # hooks-install — wire jsc hooks into every installed CLI -Goal: make the three hooks (`ste100-guard.sh`, `session-timer.sh`, `skill-usage.sh`) effective in every CLI. +Goal: make the four hooks (`ste100-guard.sh`, `session-timer.sh`, `skill-usage.sh`, `sdlc-gate.sh`) effective in every CLI. +Claude wiring is automatic via `hooks.json`. On codex and kiro the SDLC gate degrades to the skill-step check only; the lock file still works because the SDLC skills call `sdlc-gate.sh lock` directly. The detailed flow **MUST run as a sub agent**; the main agent only reports the summary. ## Steps -1. Run `jsc-cli/tools/detect-clis.sh` to get the installed CLIs and their paths. -2. Wire each CLI per the table below (hooks first; degrade to an instruction file when the CLI has no hook system): +1. Run `jsc-cli/tools/detect-clis.sh`. Done when you hold the list of installed CLIs; when the list is empty, report that and stop. +2. Wire each CLI per the table below. A row counts as done only when its verify check passes: -| CLI | Wiring | -| --- | --- | -| claude | the plugin loads `jsc-hooks/hooks/hooks.json` automatically on install; verify only: `claude plugin list` shows `jsc-hooks` and `/hooks` shows the registrations | -| codex | set `notify` in `~/.codex/config.toml` to `session-timer.sh mark` (with `JSC_CLI=codex`); append the STE100 rule to `~/.codex/AGENTS.md` (prompt fallback) | -| copilot | no hook system: append the STE100 rule to `~/.config/copilot/copilot-instructions.md` (prompt fallback) | -| antigravity | no public hook system: append the STE100 rule to the global rules file (prompt fallback) | -| kiro | create an agent hook under the workspace `.kiro/hooks/` that runs the matching script (with `JSC_CLI=kiro`) | +| CLI | Wiring | Verify | +| --- | --- | --- | +| claude | the plugin loads `jsc-hooks/hooks/hooks.json` automatically on install (all four hooks, `sdlc-gate.sh check` included); nothing to write | `claude plugin list` shows `jsc-hooks` and `/hooks` shows the registrations | +| codex | set `notify` in `~/.codex/config.toml` to `session-timer.sh mark` (with `JSC_CLI=codex`); append the STE100 rule block to `~/.codex/AGENTS.md` (prompt fallback) | `config.toml` contains the `notify` entry and `AGENTS.md` contains the block | +| copilot | (a) install the wrapper: add a shell alias or launcher that starts the CLI via `jsc-hooks/tools/jsc-wrap.sh copilot`, so session timing and usage backfill work — `tools/scan-logs.sh` runs automatically at wrapper exit; (b) keep appending the STE100 rule block to `~/.config/copilot/copilot-instructions.md` (prompt fallback for the language rules) | the alias resolves to `jsc-wrap.sh copilot` and the instruction file contains the block | +| antigravity | (a) install the wrapper: add a shell alias or launcher that starts the CLI via `jsc-hooks/tools/jsc-wrap.sh antigravity` — `tools/scan-logs.sh` runs automatically at wrapper exit; (b) keep appending the STE100 rule block to the global rules file (prompt fallback for the language rules) | the alias resolves to `jsc-wrap.sh antigravity` and the rules file contains the block | +| kiro | create an agent hook under the workspace `.kiro/hooks/` that runs the matching script (with `JSC_CLI=kiro`) | the hook file exists under `.kiro/hooks/` and names the script | -3. The appended rule text is always the exact output of `ste100-guard.sh` (a Traditional Chinese literal). Wrap it in `` markers; on re-run, replace the whole block instead of appending again. -4. Report the wiring result for every CLI: succeeded, degraded to prompt, or the skip reason. +3. The appended rule text is always the exact output of `ste100-guard.sh` (a Traditional Chinese literal). Wrap it in `` markers; on re-run, replace the whole block instead of appending again. Done when each touched instruction file contains exactly one `` block. +4. Report the wiring result for every CLI. Done when every detected CLI has exactly one status: succeeded, degraded to prompt, or skipped with a reason. ## Notes -- The hook scripts accept both stdin JSON and environment variables (`JSC_CLI`, `JSC_SESSION_ID`, `JSC_SKILL`); a wrapper only needs to set the variables. +- The hook scripts accept both stdin JSON and environment variables (`JSC_CLI`, `JSC_SESSION_ID`, `JSC_SKILL`, `JSC_MODEL`); `jsc-wrap.sh` sets the first two itself. - Data lands in `$JSC_HOME` (default `~/.jsc`), consumed by `jsc-log:worklog` and `jsc-log:stats`.