From cd4cd8b936f08d74b76085830947d99734f20cdc Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 7 Sep 2026 11:14:41 +0800 Subject: [PATCH] =?UTF-8?q?feat(hooks):=20=E5=B7=A5=E4=BD=9C=E9=9A=8E?= =?UTF-8?q?=E6=AE=B5=E9=96=8B=E5=A7=8B=E6=99=82=E6=8A=8A=E5=8A=A9=E7=90=86?= =?UTF-8?q?=E7=9A=84=E6=9C=AA=E8=AE=80=E6=8F=90=E9=86=92=E5=B8=B6=E5=88=B0?= =?UTF-8?q?=E5=89=8D=E6=99=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 助理算得出哪幾筆到期、哪幾筆逾期，但那些結果只寫在監控頁上——人要自己 去翻，或自己跑一次狀態查詢。這一支把它帶到前景。 session-reminder.sh 只讀助理那一輪寫好的提醒佇列，一個判定都不做。 自己拿 due 欄與 next_run 去跟現在比就是第二套到期判定，跟助理那一套遲早 對不上，而對不上的那一天兩邊都說自己是對的。它也要快：這一支跑在每一個 工作階段的開頭。 只印佇列換來一個新的失效模式，正面處理：助理停了，佇列就不再更新，而一份 舊佇列讀起來跟新的一模一樣。所以佇列檔頭帶那一輪的時間戳與 epoch，這裡 算出它多舊；超過心跳門檻或心跳不新鮮，就明說這批提醒是多久以前算的、 助理現在的心跳是什麼狀態。門檻與狀態都取 heartbeat.sh 印的那一行。 佇列空又過期的那一種分兩路：待辦簿有東西才說話，零筆就安靜——人自己按停 也算零筆那一種，對著一個刻意的決定每個工作階段催一次是噪音不是提醒。 助理狀態目錄根本不存在時整支安靜退出，那台機器從沒啟動過助理。 一個工作階段只提一次，記號是 sessions/{代號}.reminded。接不到 session id 的 CLI 全部共用 default，所以 session-timer.sh 的 restart 分支順手清掉那個 記號——不清的話那支 CLI 從第二個工作階段起再也收不到提醒。清除掛在那裡 不掛在這裡：「這是不是新的工作階段」的判準只有那一支知道。 接線與檢核一起改，不留一支沒人驗的 hook：hooks.json 與推導出來的 codex-hooks.json 各加一條、kiro 的 agentSpawn 加一條、claude 的 status 逐支列舉加一項、冒煙測試加一條並把預期條數從 17 改成 18、執行期錯誤掃描 的 jsc 判定加一支腳本名，還有散在文件與回報字串裡的「九支 hook」十處 全部改成十支。 Co-Authored-By: Claude Opus 5 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- README.md | 9 ++- hooks/codex-hooks.json | 4 + hooks/hooks.json | 4 + hooks/session-reminder.sh | 153 +++++++++++++++++++++++++++++++++++++ hooks/session-timer.sh | 8 ++ plugin.json | 2 +- references/behaviors.md | 2 +- tools/scan-hook-errors.sh | 5 +- tools/wire-cli.sh | 32 ++++---- 11 files changed, 198 insertions(+), 25 deletions(-) create mode 100755 hooks/session-reminder.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9ee879e..6c69d1a 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.4.7", + "version": "0.4.8", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index f9089a2..f21c608 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "hooks": "./hooks/codex-hooks.json", "name": "jsc-hooks", - "version": "0.4.7", + "version": "0.4.8", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門", "skills": "./skills", "jsc": { diff --git a/README.md b/README.md index a0c5a75..933f586 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | --- | --- | --- | | `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` 取花費時間。`start` 與 `restart` 判定為新工作階段時，另外呼叫 `restart-gate.sh clear` 放下部署後的重啟閘門——新工作階段代表 CLI 行程是新起的，新版一定已經載入。清除的範圍只有跑到這支腳本的那一支 CLI 自己那一份狀態檔，別支沒重啟就繼續被擋 | +| `hooks/session-reminder.sh` | SessionStart | 把助理算好的未讀提醒帶到前景。只讀 `$JSC_HOME/assistant/reminders.tsv`（`jsc-assist` 的巡檢每一輪重寫），逾期的排前面、到期的只提醒項在後，最多列 8 筆，另加一行「有幾筆待辦連續失敗」。**這一支一個判定都不做**：自己拿 `due` 欄與 `next_run` 去跟現在比就是第二套到期判定，跟助理那一套遲早對不上。一個工作階段只提一次，記號是 `$JSC_HOME/sessions/{代號}.reminded`，接不到 session id 的 CLI 由 `session-timer.sh restart` 清掉那個記號。佇列檔頭帶那一輪的時間戳與 epoch，超過心跳門檻或心跳不新鮮就明說「這批提醒是多久以前算的、助理現在的心跳是什麼狀態」——一份沒有人更新的佇列讀起來跟新的一模一樣，而「沒有提醒」與「沒有人算提醒」不可以長得一樣。助理狀態目錄不存在時一個字都不印：那台機器從沒啟動過助理，每個工作階段催一次不是提醒是噪音。子指令 `peek` 只印不記號，給人重看與檢核用。永遠 exit 0 | | `hooks/skill-name.sh` | 不直接接線，由 `version-guard.sh` 與 `restart-gate.sh` 呼叫 | 從各 CLI 的 hook 負載解析出這一次要用哪一支 jsc 技能，一支 CLI 一個子命令，印一行「{domain}{技能名}」，解析不出來就印空字串。取值來源：claude 讀 stdin JSON 的 `skill` 欄位、codex 讀 `tool_input.command` 裡那條 `SKILL.md` 路徑（Codex 沒有 Skill 工具，技能是模型自己用 Bash 讀 `SKILL.md` 載入的）、copilot 讀 `toolArgs`（字串化的 JSON，要先剝一層跳脫）、antigravity 讀 `toolCall.args.AbsolutePath` 另收提示字串（斜線指令不產生工具呼叫）、kiro 讀 `prompt` 開頭那個斜線指令；五支都先看環境變數 `JSC_SKILL`、`SKILL`。永遠 exit 0：閘門那一端一律 fail-open，而且 copilot 的 command hook 是 fail-closed 的，回非零等於拒絕。規則只有這一份，兩支閘門都不重寫第二套 | | `hooks/deny.sh` | 不直接接線，由 `version-guard.sh` 與 `restart-gate.sh` 呼叫 | 產出各 CLI 認得的阻擋輸出，訊息從參數或標準輸入進。claude、codex、copilot 訊息寫 stderr 並回 exit 2；antigravity 印 stdout 的 `{"decision":"deny","reason":"..."}` 並固定回 0——那支 CLI 的結束碼語意兩邊文件都沒寫，靠結束碼會變成「判定擋下、CLI 照樣放行」的無聲失效，所以 stdout 只准有那一行；kiro 擋不下技能叫用，改印警告後回 0；認不得的代號走 stderr 加 2 這個保守預設 | | `hooks/version-guard.sh` | PreToolUse：claude matcher `Skill`、codex matcher `Bash`、copilot matcher `skill`、antigravity matcher `^view_file$` 加 `PreInvocation`；kiro `userPromptSubmit`（只注入警告） | 技能使用前的版本前置檢查，擋兩種情況，兩種都擋下該次呼叫並提示更新指令（更新指令依當前 CLI 給；技能名解析交給 `hooks/skill-name.sh`、阻擋輸出形態交給 `hooks/deny.sh`，兩支的規則見上面兩列，這裡不重寫第二套）：一是本機**實際載入**版本落後遠端發佈版本，二是技能所屬 plugin 的 manifest 在 `jsc.requires` 宣告的相依 plugin 版本落後——相依那一項讀 `installPath` 底下那份 `plugin.json`，逐項比對相依 plugin 的本機實際載入版本，訊息講明哪一個 plugin、需要哪一版、目前哪一版、怎麼補。相依檢查排在遠端比對之前，全部讀本機檔案，離線也判得動；判定邏輯自己實作，不呼叫 `jsc-cli/tools/check-requires.sh`，免得 hook 散落到別的 domain，也免得跟已宣告相依 `jsc-hooks` 的 `jsc-cli` 做出循環相依。部署那端照樣更新、只回報，阻擋落在這支 hook。兩種都只擋確定落後：超前放行（開發技能組時本機本來就會超前），讀不到本機版本、推導不出站台、查不到遠端版本、解不出安裝路徑、讀不到 manifest、manifest 沒有 `jsc.requires`、讀不到相依 plugin 的本機載入版本也一律放行。遠端版本快取在 `$JSC_HOME/version-cache/{CLI 代號}/{domain}`，一支 CLI 一份；舊路徑 `$JSC_HOME/version-cache/{domain}` 會在第一次讀取時複製到新路徑。逃生門 `JSC_VERSION_GUARD=off`。豁免 `jsc-cli:deploy`、`jsc-hooks:hooks-install`、`jsc-hooks:repair`、`jsc-cli:models`、`jsc-meta:*`、`jsc-ask:ask`、`jsc-gitea:wiki`——共 7 項，兩種擋人情況共用同一份，相依落後不另立短清單；清單的唯一來源是 `hooks/version-guard.sh` 的檔頭，那裡一項一個理由 | @@ -36,7 +37,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | `hooks/sdlc-gate.sh` | UserPromptSubmit、PreToolUse(Skill) | SDLC 階段能力標籤閘門與模型鎖：`lock {stage}` 由 jsc-sdlc 階段技能呼叫，從可驗證來源讀出模型 id，比對該階段必要標籤（`$JSC_HOME/model-tags.tsv`），不符就拒絕上鎖。**來源依 CLI 分流**，一支 CLI 只讀自己的紀錄：claude 讀 transcript 與 hook stdin JSON，codex 讀 hook stdin JSON 與自己的 session 記錄，copilot、antigravity、kiro 本機沒有可讀的模型紀錄，判不出 CLI 時不採用任何自動來源；所有 CLI 最後都接受 `JSC_MODEL` 人工覆寫，且回報會標明人工覆寫。政策是 **fail-closed**：不知道能力就擋下，三種情形一律擋——判不出 CLI、判不出模型、模型不在能力標籤表上；每一則擋下的訊息都會印出兩條逃生門（設 `JSC_MODEL`，或執行 `sdlc-gate.sh unlock {狀態檔}`）。`check` 在上述任一情形以 exit 2 擋下該輪提示（其他 hook 一律 exit 0，此處是刻意例外）；`report` 印出階段、必要標籤、模型 id、模型來源與判定結果；`unlock` 為逃生門，不帶參數清這個工作階段的新舊兩份，帶參數只清指定的那一支。階段鎖狀態檔是 `$JSC_HOME/sessions/{CLI 代號}-{sid}.stage`，舊路徑 `$JSC_HOME/sessions/{sid}.stage` 仍讀得到。另含工作包 PR 閘門：`wp-lock {owner}/{repo} {index} [{工作包代號}]` 記下一筆未結清的工作包 PR、`wp-unlock {owner}/{repo} {index}` 結清那一筆（檔案不存在也算成功）、`wp-claim {owner}/{repo} {工作包代號} [{PR 編號}] [{分析頁頁名}]` 記下這個存取庫目前領取哪一包、`wp-unclaim {owner}/{repo}` 交回、`wp-report` 印出所有未結清、`wp-check {prompt｜skill}` 為 hook 模式。狀態檔一個工作包一支，在 `$JSC_HOME/wp/{owner}-{repo}-{index}.pr`，**刻意不綁 session**——PR 沒合併時換一個工作階段照樣要擋；一個工作包一支鎖檔是為了讓好幾個互不相依的工作包能同時記在案，不會互相覆蓋掉對方的鎖。`wp-check prompt` 只注入提醒、絕不擋提示（擋了連「去修那支 PR」的對話都送不出去）；`wp-check skill` 在有未結清 PR 時以 exit 2 擋下 `analyze` 與 `maintain`，但一律放行 `implement`（結清 PR 正是 implement 的步驟，擋它會鎖死流程），也放行 `plan`，只注入提醒（plan 是純邏輯階段、不碰程式碼，而這道閘門只知道「有 PR 未合併」、判不出跟新計畫有沒有關聯；放棄的是在製品上限，`analyze` 與 `maintain` 兩道仍在，上限晚一個階段才生效）——這一層是整個存取庫共用的粗粒度提醒，「某個候選工作包能不能挑」的細粒度判斷在 `jsc-sdlc/tools/wp-gate.sh check-deps`，不是這裡。另外會比對歸屬：未結清的 PR 不屬於目前領取的工作包時，`prompt` 多注入一行「那幾支交給領取它的工作階段」，`skill` 在擋下 `analyze`、`maintain` 時一併點名，`plan` 與 `implement` 仍放行但收到同一則提醒。逃生門 `JSC_WP_GATE=off`。這道閘門只讀檔案、不打網路，PR 的真實合併狀態由 `jsc-sdlc/tools/wp-gate.sh` 查證 | | `hooks/write-guard.sh` | PreToolUse(Write、Edit、MultiEdit)、PreToolUse(Bash) | 寫入與提交閘門，共三種擋人模式，目前只接在 claude 上；codex、copilot、antigravity 三支已經有可用的 pre-tool hook（見上面「各 CLI 的 pre-tool 接線位置」），只是這三種模式還沒接過去，kiro 則是本來就擋不下來。另有一個不接 hook 的 `release` 解除模式。`stage`：`sdlc-gate.sh` 的階段鎖鎖在 `plan` 或 `analyze` 時，以 exit 2 擋下 `Write`、`Edit`、`MultiEdit`——那兩個階段的產出是計畫頁與分析頁，不是檔案。階段鎖狀態檔沿用 `sdlc-gate.sh` 那一份，這裡只讀不寫。`review`：目前技能是 `jsc-review:code-review` 或 `jsc-review:api-doc` 時擋下寫入，那兩支只回報發現、不改程式碼。技能名先讀環境變數，取不到才讀 `skill-usage.sh` 記下的那一份；沒有「技能結束」事件可讀，所以紀錄超過 `JSC_WRITE_GUARD_TTL` 秒就當那支技能早已跑完。`jsc-review:comment-cleanup` **刻意不擋**：它本來就要改檔，只是限定僅註解行，而精確判定要解析工具參數裡整份新內容再逐語言判斷哪幾行是註解，判錯會擋掉合法的清理，代價比漏擋大，所以那條界線留給技能內文與後續審查。`commit`：擋下「同一道指令把全部變更一次加進索引再提交」，也擋下含簡體字、亂碼或非 UTF-8 編碼的提交訊息（判定整段轉呼叫 `lang-guard.sh`，字表仍是 `hooks/simplified.txt`，這裡不留第二份樣式）。跨兩次工具呼叫的 `git add -A` 不擋：那要記跨呼叫狀態，而被擋下的人沒有辦法讓那個狀態自己消失，閘門會把解除自己的路徑一起鎖掉。`release`：刪掉 `review` 模式認人用的那份紀錄，一律 exit 0，由 `jsc-review:code-review` 與 `jsc-review:api-doc` 在收尾時各呼叫一次。有這個模式是因為那份紀錄記的是「最近一次載入的技能」不是「還在跑的技能」——稽核收尾後呼叫端本來就要動手改，那時紀錄仍寫著稽核技能，TTL 內每一次寫入都被擋，解除路徑只剩逃生門或空等；閘門不得把解除自己的路徑一起鎖掉。逃生門 `JSC_WRITE_GUARD=off`（`release` 不受它影響，清紀錄擋不到任何人） | -Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。寫進使用者設定的長期命令一律指向 `$JSC_HOME/current/jsc-hooks`，不指向帶版號的 plugin 快取目錄，也不指向開發存取庫。 +Claude 由 `hooks/hooks.json` 自動接線十支 hook；其他 CLI 用 `hooks-install` 技能接線、改裝包裝啟動器，或降級為規則檔。寫進使用者設定的長期命令一律指向 `$JSC_HOME/current/jsc-hooks`，不指向帶版號的 plugin 快取目錄，也不指向開發存取庫。 ### 各 CLI 的 pre-tool 接線位置 @@ -65,7 +66,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in - **kiro** 擋不下技能叫用，這是 CLI 的限制，不是我們接錯。技能走 `ResolveSkill` 這個 agent 內部請求，不經工具管線，`preToolUse` 攔不到；`userPromptSubmit` 的非零結束碼也不會擋下那一輪。唯一可用的介入是 `userPromptSubmit` 的 stdout 注入，所以兩道閘門只印警告。hook 宣告只認 **agent 設定檔的 `hooks` 鍵**，`.kiro/hooks/` 目錄不在它的設定目錄常數裡，一份都不會被讀。同一份 agent 檔還要寫 `resources` 的**兩層** `skill://` glob（預設只掃一層，jsc 的技能在 `jsc-{domain}/{name}/SKILL.md` 第二層，少了那一條一支都載不到）與**明列的 `tools`**（自訂 agent 沒宣告時可用工具會受限），並把 `chat.defaultAgent` 設成 `jsc`，那個 agent 才會被選用。 -> 覆蓋範圍其餘部分仍要據實看待：只有 claude 同時有 PreToolUse、PostToolUse 與 UserPromptSubmit，九支 hook 全接得上。codex、copilot、antigravity 三支目前接上的是版本前置檢查與部署後重啟閘門兩道；`write-guard.sh` 的三種模式還沒接線，SDLC 模型鎖仍只剩技能步驟檢查，註解範圍與繁中編碼仍是 `sweep`。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。 +> 覆蓋範圍其餘部分仍要據實看待：只有 claude 同時有 PreToolUse、PostToolUse 與 UserPromptSubmit，十支 hook 全接得上。codex、copilot、antigravity 三支目前接上的是版本前置檢查與部署後重啟閘門兩道；`write-guard.sh` 的三種模式還沒接線，SDLC 模型鎖仍只剩技能步驟檢查，註解範圍與繁中編碼仍是 `sweep`。codex 另外沒有工作階段開始事件，計時改由 `tools/jsc-wrap.sh` 的 `codex` 別名在啟動當下開始；沒走別名啟動時，時間從第一輪回應算起。 ### 驗證等級 @@ -170,7 +171,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in | `tools/jsc-wrap.sh` | 沒有完整 hook 系統的 CLI 的包裝啟動器：匯出 `JSC_CLI`、`JSC_SESSION_ID`，前後接 `session-timer.sh`，結束時自動跑 `scan-logs.sh` 回填，再依序跑一次 `comment-scope.sh sweep` 與 `lang-guard.sh sweep` 掃整個 git 工作區的註解範圍與繁中編碼（copilot 與 antigravity 沒有任何逐輪事件，整個工作階段只有這裡掃得到）。兩次收尾掃描一律不影響結束碼：包裝器原樣回傳 CLI 自己的結束碼，`sweep` 命中只把警告印到 stderr。`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}`，並在異常目錄頁附上一個索引區塊。目錄頁一筆一個 H2 區塊，標題就是那一頁的頁名 `ERROR_{HASH}`，欄位是標題底下的一層條列（時間、頁名、存取庫名稱、觸發 hook、退出碼、摘要各一條，格式 `- {欄位名}：{值}`），頁上不留 markdown 表格。目錄頁的讀回、比對與整頁寫回交給 `jsc-gitea` 的 `tools/wiki-contents.sh upsert ERROR 2 {頁名} {區塊檔} {範本}`，本腳本只組自己那一個區塊：同一筆已經有區塊就整塊換掉，沒有才附加到頁尾，一律 upsert，不整頁覆蓋，也不動別人的區塊；那個 `2` 是舊表格版目錄頁裡持有身分的欄位序號（第 2 欄是頁名），舊頁自動轉條列時要靠它取標題。「讀得回舊內容才寫」的判斷由 `wiki-contents.sh` 一手包辦，只有 `wiki-get` 回 4（頁面真的不存在）才用範本建新頁。區塊裡「頁名」那一條指向異常頁，連結一律寫成 `[{文字}]({連結})`，網址取 `jsc-gitea` 的 `gitea.sh wiki-url` 印出的那一個，不自己組路徑。寫進那一條之前，先把那個網址交給 `jsc-gitea` 的 `tools/link-check.sh` 驗一次，結束碼 0 才寫連結；`link-check.sh` 與 `wiki-contents.sh` 的路徑都由已經解出來的 `gitea.sh` 推得，三支同一個 tools 目錄。驗不過（含找不到 `link-check.sh`、`GITEA_HOST` 未設定回 3、金鑰失效回 7）就只在那一條留純文字頁名，那一條照寫、異常頁照寫、結束碼照舊，原因走 stderr——回報失敗不該再變成一次失敗。網址在異常頁寫成功之後才取：頁名的 hash 帶時間戳，每次回報都是全新的頁，寫進去之前查一定是 404，先查就只拿得到空字串。取不到網址時只印頁名，原因走 stderr，結束碼照舊回 0。wiki 位置分兩處解析：異常頁走 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR`，目錄頁由 `wiki-contents.sh` 自己走 `wiki-repo CONTENTS`，兩者是兩個不同的存取庫。異常頁的存取庫解不出來就整支安靜降級；只有目錄頁的存取庫解不出來（`wiki-contents.sh` 回 3）或那支腳本不在磁碟上，就只寫異常頁、跳過目錄頁更新，仍回 exit 0；其餘結束碼（1 組不出內容或寫入失敗、2 用法錯誤、4 沒範本、7 金鑰失效、8 其他 API 失敗）都以 exit 4 回報。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） | -| `tools/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共四個用法。`{cli}` 是接線：先建立或更新 `$JSC_HOME/current/jsc-hooks` 指向目前這版 plugin，接著把對應的設定編輯、包裝別名安裝、hook 檔建立成穩定路徑，皆以 ``（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、`.codex-plugin/plugin.json` 的 matcher 必須是 `Bash`、copilot 必須是小寫 `skill` 且沒有第二種大小寫的事件名、antigravity 的 matcher 必須帶錨點 `^view_file$` 且有 `PreInvocation`、kiro 的 agent JSON 必須成對且 `hooks`、`resources`、`tools` 在最上層並含兩層 `skill://` glob），也會確認寫入路徑能解到既有腳本。matcher 本身要單獨驗：鍵在、matcher 卻錯的形態最難查，回報會說接好了，實際一次都不會被叫用。檔案系統不能建立 symlink 時，會明確回報並退回目前根目錄，不會靜默寫出壞路徑。`status=wired\|degraded\|skipped\|failed` 回報接線結果。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除；移除標記段落時會先去掉標記行前後空白，所以縮排或尾端補空白的 jsc 區塊一樣會移除；移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：九支 hook 的每個接線模式各跑一次，非零退出即為錯誤，另外把五支 CLI 的真實負載各餵進 `skill-name.sh` 一次驗技能名解析、四種阻擋形態各驗一次 `deny.sh`，再把那些負載直接餵進 `restart-gate.sh` 驗「解析→判定→輸出形態」整條串得起來（含 fail-open、豁免放行與 kiro 的注入路徑）——前兩組分開看都會顯示正常，中間接不上照樣是全程放行，那正是先前三支 CLI 失效的樣子；另外用一份暫時的 `$JSC_HOME` 狀態檔把模型來源與階段鎖、工作包歸屬、部署後重啟閘門與寫入提交閘門的每條判定路徑各跑一次並比對結束碼（模型來源的每個案例各自指定 CLI 代號，不跟著這一輪接線的 CLI 走——偵測鏈已依 CLI 分流；「不知道能力就擋下」的三種情形連訊息裡的逃生門一起驗，只比結束碼的話訊息漏掉逃生門也是綠燈），再用一份暫時的 `HOME`（假的 `installed_plugins.json` 與各 plugin 的 manifest）把 `version-guard.sh` 相依版本檢查的每條路徑跑一次——相依落後的擋人與訊息內容、相等與超前的放行、豁免技能在相依落後時照樣放行、四種 fail-open、逃生門，另加一條回歸：多行縮排的 manifest，`jsc.requires` 的最後一個鍵也要解得到。驗的是判定結果本身，不只是腳本跑得完（例外有四個：`sdlc-gate.sh check` 的 exit 2 是階段鎖的設計行為，`comment-scope.sh`、`lang-guard.sh` 掃描模式與 `write-guard.sh` 三種模式的 exit 2 是命中違規的設計行為——`sweep` 在髒工作區本來就會回 2，`write-guard.sh` 在機器剛好鎖在 `plan` 階段時也會回 2，都不算 hook 壞掉），以 `status=ok\|failed` 回報。**結果行數由腳本自己數、自己斷言**：`status=` 之後緊接一行 `lines{數量}`，那是其後 `[jsc]` 結果行的實際條數，與腳本內逐類宣告的預期條數比對，不符就回非零。判定路徑增減時只改腳本裡的預期值，散文一律引用這一行，不另外抄一份數字。`status {cli}` 是唯讀盤點：只讀設定檔判斷段落與 matcher 對不對，不寫檔也不執行 hook，claude、codex、copilot、antigravity 回 `wired`，kiro 回 `degraded` 並在 `reason` 講明那是 CLI 限制；每個接線點印一行 `item{項目}{路徑}{present\|missing\|unverified}`，也會把帶版號快取路徑、開發存取庫路徑與不存在的腳本列為缺項。狀態有三格不是兩格：`unverified` 是「這一項驗不了」，只有 `missing` 才算缺項——`kiro-cli agent validate` 在沒登入時印的是環境問題，不是這個檔案的問題，報 `present` 會讓沒驗到的東西看起來像通過，報 `missing` 會把沒登入算成接線缺漏；`status claude` 讀 Claude Code 實際載入的 `installed_plugins.json`，不再檢查目前腳本旁邊那份 `hooks.json`。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境；那道限制另有程式層把關，`JSC_READONLY=1` 之下只准 `status` 與 `smoke`，`purge` 與接線一律以 exit 6 拒絕並回報 `status=readonly`，環境不會被動到 | +| `tools/wire-cli.sh` | 單一 CLI 的 hook 生命週期，共四個用法。`{cli}` 是接線：先建立或更新 `$JSC_HOME/current/jsc-hooks` 指向目前這版 plugin，接著把對應的設定編輯、包裝別名安裝、hook 檔建立成穩定路徑，皆以 ``（或 `# jsc-hooks`）標記整段重寫，重跑等同先移除再重裝；寫完每個檔案會重讀驗證位置正確才回報成功（codex 的 `notify` 必須是根層鍵、`.codex-plugin/plugin.json` 的 matcher 必須是 `Bash`、copilot 必須是小寫 `skill` 且沒有第二種大小寫的事件名、antigravity 的 matcher 必須帶錨點 `^view_file$` 且有 `PreInvocation`、kiro 的 agent JSON 必須成對且 `hooks`、`resources`、`tools` 在最上層並含兩層 `skill://` glob），也會確認寫入路徑能解到既有腳本。matcher 本身要單獨驗：鍵在、matcher 卻錯的形態最難查，回報會說接好了，實際一次都不會被叫用。檔案系統不能建立 symlink 時，會明確回報並退回目前根目錄，不會靜默寫出壞路徑。`status=wired\|degraded\|skipped\|failed` 回報接線結果。`purge {cli}` 是移除：把該 CLI 的**所有** hook 清掉，含非 jsc 的第三方項目，動到的檔案先原樣備份到 `$JSC_HOME/backup/hooks/{cli}/{yyyyMMdd_HHmmss}/`，備份失敗就不移除；移除標記段落時會先去掉標記行前後空白，所以縮排或尾端補空白的 jsc 區塊一樣會移除；移除後重讀驗證，驗不過自動還原備份，以 `status=purged\|skipped\|failed` 回報。`smoke {cli}` 是執行期冒煙測試：十支 hook 的每個接線模式各跑一次，非零退出即為錯誤，另外把五支 CLI 的真實負載各餵進 `skill-name.sh` 一次驗技能名解析、四種阻擋形態各驗一次 `deny.sh`，再把那些負載直接餵進 `restart-gate.sh` 驗「解析→判定→輸出形態」整條串得起來（含 fail-open、豁免放行與 kiro 的注入路徑）——前兩組分開看都會顯示正常，中間接不上照樣是全程放行，那正是先前三支 CLI 失效的樣子；另外用一份暫時的 `$JSC_HOME` 狀態檔把模型來源與階段鎖、工作包歸屬、部署後重啟閘門與寫入提交閘門的每條判定路徑各跑一次並比對結束碼（模型來源的每個案例各自指定 CLI 代號，不跟著這一輪接線的 CLI 走——偵測鏈已依 CLI 分流；「不知道能力就擋下」的三種情形連訊息裡的逃生門一起驗，只比結束碼的話訊息漏掉逃生門也是綠燈），再用一份暫時的 `HOME`（假的 `installed_plugins.json` 與各 plugin 的 manifest）把 `version-guard.sh` 相依版本檢查的每條路徑跑一次——相依落後的擋人與訊息內容、相等與超前的放行、豁免技能在相依落後時照樣放行、四種 fail-open、逃生門，另加一條回歸：多行縮排的 manifest，`jsc.requires` 的最後一個鍵也要解得到。驗的是判定結果本身，不只是腳本跑得完（例外有四個：`sdlc-gate.sh check` 的 exit 2 是階段鎖的設計行為，`comment-scope.sh`、`lang-guard.sh` 掃描模式與 `write-guard.sh` 三種模式的 exit 2 是命中違規的設計行為——`sweep` 在髒工作區本來就會回 2，`write-guard.sh` 在機器剛好鎖在 `plan` 階段時也會回 2，都不算 hook 壞掉），以 `status=ok\|failed` 回報。**結果行數由腳本自己數、自己斷言**：`status=` 之後緊接一行 `lines{數量}`，那是其後 `[jsc]` 結果行的實際條數，與腳本內逐類宣告的預期條數比對，不符就回非零。判定路徑增減時只改腳本裡的預期值，散文一律引用這一行，不另外抄一份數字。`status {cli}` 是唯讀盤點：只讀設定檔判斷段落與 matcher 對不對，不寫檔也不執行 hook，claude、codex、copilot、antigravity 回 `wired`，kiro 回 `degraded` 並在 `reason` 講明那是 CLI 限制；每個接線點印一行 `item{項目}{路徑}{present\|missing\|unverified}`，也會把帶版號快取路徑、開發存取庫路徑與不存在的腳本列為缺項。狀態有三格不是兩格：`unverified` 是「這一項驗不了」，只有 `missing` 才算缺項——`kiro-cli agent validate` 在沒登入時印的是環境問題，不是這個檔案的問題，報 `present` 會讓沒驗到的東西看起來像通過，報 `missing` 會把沒登入算成接線缺漏；`status claude` 讀 Claude Code 實際載入的 `installed_plugins.json`，不再檢查目前腳本旁邊那份 `hooks.json`。體檢類技能（`/jsc-cli:doctor`）只能用這個子命令，另外三個都會動到環境；那道限制另有程式層把關，`JSC_READONLY=1` 之下只准 `status` 與 `smoke`，`purge` 與接線一律以 exit 6 拒絕並回報 `status=readonly`，環境不會被動到 | | `tools/report-status.sh` | 技能與 hook 的執行狀態事件流，寫進 `$JSC_HOME/usage/events.jsonl`，一次一行。`skill-start`、`skill-end`、`hook-end` 三個記錄子命令；`drain` 印出上次排空之後的新事件（位移存在 `usage/scan-state/events.offset`，檔案比位移小就當作輪替過、從頭讀，不比對 inode——五支 CLI 與容器裡的行程看到的 inode 不保證一致）；`rotate` 超過 5 MiB 就改名成 `.1` 並把位移歸零，只留一份舊的。`status` 是 `ok`、`blocked`、`failed`、`degraded`、`aborted` 五選一。**三個記錄子命令一律回 0，寫檔失敗也是 0**：回報機制自己壞掉，不可以讓被回報的東西跟著壞——hook 的結束碼是閘門的判準，被記錄動到就等於閘門行為被記錄改寫。參數檢查是例外，那是呼叫端的程式錯誤，寫進去只會汙染事件流，所以以 2 擋在記錄之前。本檔不讀 stdin：技能由 Bash 呼叫它，stdin 可能是還沒關閉的管線，讀下去會卡住宿主，所有資訊一律走參數。輪替不放在每次寫入，那等於每次提示多一次系統呼叫；改由巡檢排空之後呼叫。為什麼不直接寫 wiki：hook 每次提示都跑，網路寫入會拖垮宿主 CLI，而且失敗的 hook 自我回報會疊出迴圈，`report-error.sh` 因此刻意不接在失敗的 hook 上，這裡沿用同一條線 | | `tools/scan-hook-errors.sh` | 掃 CLI 原生紀錄找 hook 的執行期錯誤（接線寫對、跑起來出錯）。只有 claude 有 hook 結果紀錄，掃 `~/.claude/projects/**/*.jsonl` 的 `hook_non_blocking_error` 與非空 `hookErrors`；codex、copilot、antigravity、kiro 沒有等價紀錄，一律回報 `unavailable` 並指向 `wire-cli.sh smoke {cli}`。每筆錯誤附加一行 JSON 到 `$JSC_HOME/errors/hooks.jsonl`，`jsc` 欄位標明是不是 jsc 自己的 hook（第三方 hook 的錯誤只回報，不由 jsc 修正）；去重與 `scan-logs.sh` 同法，重掃只讀新增段落，以 `status=clean\|errors\|unavailable` 回報 | @@ -192,7 +193,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in ### `hooks-install` -把九支 hook 接線到所有已安裝的 CLI，每個 CLI 走五道關卡：先 `tools/wire-cli.sh purge {cli}` 備份後移除所有 hook（含非 jsc 的第三方項目，乾淨起跑才分得清後續失敗是誰的），再 `tools/wire-cli.sh {cli}` 接線（claude 由 `hooks.json` 自動接線，無需寫入；其他 CLI 的持久命令會寫成 `$JSC_HOME/current/jsc-hooks` 穩定路徑），接著 `tools/wire-cli.sh status {cli}` 唯讀盤點接線結果，再 `tools/wire-cli.sh smoke {cli}` 驗執行期，最後 `tools/scan-hook-errors.sh --cli {cli}` 掃原生紀錄。第一支 CLI 的管線單獨跑完（`$JSC_HOME/current/jsc-hooks` 連結由它統一更新），其餘各 CLI 的管線才並行。codex、copilot、antigravity 由接線腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍重寫到各自的規則檔（以 `` 標記整段取代，等同先移除再重裝，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入。版本前置檢查與部署後重啟閘門在 codex、copilot、antigravity 三支都擋得下來，各自接在自己的 pre-tool 位置（見上面「各 CLI 的 pre-tool 接線位置」），三支回報 `wired`；kiro 擋不下技能叫用，只注入警告，回報 `degraded`，那是 CLI 的限制。`write-guard.sh` 的三種模式目前仍只接在 claude。這四個 CLI 都沒有 post-tool hook，`comment-scope.sh` 接不到逐檔即時掃描，改用 `sweep` 掃整個 git 工作區——codex 每輪結束、kiro 每輪提示送出時、copilot 與 antigravity 只有工作階段結束時掃一次，腳本會在 `reason` 裡講明各自的時機，也只有 claude 掃得到執行期錯誤紀錄。antigravity 與 kiro 的 hook 觸發都沒有實跑驗證（前者 quota 用盡、後者未登入），回報時要把「接線已驗」與「觸發未驗」分開講。任一關卡出錯（purge、接線、冒煙失敗，或掃到 `jsc=true` 的執行期錯誤）就先寫 `ERROR_{HASH}`，再交給 `repair` 技能接手並以 `develop` PR 收尾；此時允許中止剩下的安裝，但修正一定要開始。掃到 `jsc=false` 的第三方 hook 錯誤只回報，不轉修正。 +把十支 hook 接線到所有已安裝的 CLI，每個 CLI 走五道關卡：先 `tools/wire-cli.sh purge {cli}` 備份後移除所有 hook（含非 jsc 的第三方項目，乾淨起跑才分得清後續失敗是誰的），再 `tools/wire-cli.sh {cli}` 接線（claude 由 `hooks.json` 自動接線，無需寫入；其他 CLI 的持久命令會寫成 `$JSC_HOME/current/jsc-hooks` 穩定路徑），接著 `tools/wire-cli.sh status {cli}` 唯讀盤點接線結果，再 `tools/wire-cli.sh smoke {cli}` 驗執行期，最後 `tools/scan-hook-errors.sh --cli {cli}` 掃原生紀錄。第一支 CLI 的管線單獨跑完（`$JSC_HOME/current/jsc-hooks` 連結由它統一更新），其餘各 CLI 的管線才並行。codex、copilot、antigravity 由接線腳本裝上 `tools/jsc-wrap.sh` 包裝別名補上計時與用量回填（結束時自動跑 `tools/scan-logs.sh`），語言規則仍重寫到各自的規則檔（以 `` 標記整段取代，等同先移除再重裝，不重複追加）。codex、copilot、antigravity、kiro 的 SDLC 模型鎖降級為技能步驟檢查，鎖檔仍由 SDLC 技能直接呼叫 `sdlc-gate.sh lock` 寫入。版本前置檢查與部署後重啟閘門在 codex、copilot、antigravity 三支都擋得下來，各自接在自己的 pre-tool 位置（見上面「各 CLI 的 pre-tool 接線位置」），三支回報 `wired`；kiro 擋不下技能叫用，只注入警告，回報 `degraded`，那是 CLI 的限制。`write-guard.sh` 的三種模式目前仍只接在 claude。這四個 CLI 都沒有 post-tool hook，`comment-scope.sh` 接不到逐檔即時掃描，改用 `sweep` 掃整個 git 工作區——codex 每輪結束、kiro 每輪提示送出時、copilot 與 antigravity 只有工作階段結束時掃一次，腳本會在 `reason` 裡講明各自的時機，也只有 claude 掃得到執行期錯誤紀錄。antigravity 與 kiro 的 hook 觸發都沒有實跑驗證（前者 quota 用盡、後者未登入），回報時要把「接線已驗」與「觸發未驗」分開講。任一關卡出錯（purge、接線、冒煙失敗，或掃到 `jsc=true` 的執行期錯誤）就先寫 `ERROR_{HASH}`，再交給 `repair` 技能接手並以 `develop` PR 收尾；此時允許中止剩下的安裝，但修正一定要開始。掃到 `jsc=false` 的第三方 hook 錯誤只回報，不轉修正。 ### `repair` diff --git a/hooks/codex-hooks.json b/hooks/codex-hooks.json index 5b64e35..5984fc3 100644 --- a/hooks/codex-hooks.json +++ b/hooks/codex-hooks.json @@ -6,6 +6,10 @@ { "type": "command", "command": "sh -c 'JSC_CLI=codex; export JSC_CLI; root=\"${CLAUDE_PLUGIN_ROOT:-${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks}\"; exec sh \"$root/hooks/session-timer.sh\" start'" + }, + { + "type": "command", + "command": "sh -c 'JSC_CLI=codex; export JSC_CLI; root=\"${CLAUDE_PLUGIN_ROOT:-${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks}\"; exec sh \"$root/hooks/session-reminder.sh\"'" } ] } diff --git a/hooks/hooks.json b/hooks/hooks.json index 7ce5dcf..8c6227a 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -6,6 +6,10 @@ { "type": "command", "command": "sh -c 'root=\"${CLAUDE_PLUGIN_ROOT:-${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks}\"; exec sh \"$root/hooks/session-timer.sh\" start'" + }, + { + "type": "command", + "command": "sh -c 'root=\"${CLAUDE_PLUGIN_ROOT:-${JSC_HOME:-$HOME/.jsc}/current/jsc-hooks}\"; exec sh \"$root/hooks/session-reminder.sh\"'" } ] } diff --git a/hooks/session-reminder.sh b/hooks/session-reminder.sh new file mode 100755 index 0000000..44ee8aa --- /dev/null +++ b/hooks/session-reminder.sh @@ -0,0 +1,153 @@ +#!/usr/bin/env sh +# session-reminder.sh — 工作階段開始時，把助理算好的未讀提醒帶到前景。 +# +# 用法: +# session-reminder.sh # SessionStart：印出未讀提醒，並記下這個工作階段提過了 +# session-reminder.sh peek # 只印，不記。人要重看一次時用，也給檢核用 +# +# 結束碼：0=一律成功，只有這一種。這一支接在工作階段開始那個事件上，它的產出走 stdout， +# 不走結束碼——那個事件的 stdout 會成為額外 context。佇列不在、讀不到、格式對不上， +# 一律印一行說明然後 exit 0；一支在每個工作階段開頭都會跑的 hook 絕對不可以擋人。 +# 唯一的非零來源是 `. lib.sh` 載入失敗，那時 sh 自己回 2。 +# +# --- 這一支不做判定 --- +# +# 提醒該不該送、哪幾筆該送，全由助理那一輪算完寫進佇列（jsc-assist 的 tools/patrol.sh +# 每一輪重寫 $JSC_HOME/assistant/reminders.tsv）。這裡只把那份檔案印出來。 +# 不自己判的理由有兩個。一是快：這一支跑在每一個工作階段的開頭，讀一個檔案就回來。 +# 二是不漂移：自己拿 due 欄與 next_run 去跟現在比，就是第二套到期判定，跟助理那一套遲早 +# 對不上，而對不上的那一天兩邊都說自己是對的。 +# +# --- 「沒有提醒」與「沒有人算提醒」不可以長得一樣 --- +# +# 只印佇列換來一個新的失效模式：助理停了，佇列就不再更新，而一份舊佇列讀起來跟新的一模一樣。 +# 所以佇列檔頭帶著那一輪的時間戳，這裡算出它多舊，超過心跳門檻就明說「這份提醒是多久以前 +# 算的、助理現在的心跳是什麼狀態」。門檻與狀態都取 heartbeat.sh 印的那一行，不自己定一套。 +# +# 助理的狀態目錄根本不存在時，這一支一個字都不印：那代表這台機器從沒啟動過助理， +# 每個工作階段開頭都催一次「你要不要啟動助理」不是提醒，是噪音。 +# +# --- 一個工作階段只提一次 --- +# +# 記號檔是 $JSC_HOME/sessions/{工作階段}.reminded。工作階段開始那個事件在續接同一階段時 +# 會再觸發，沒有記號就會每次都再提一次同一批。 +# 接不到工作階段代號的 CLI（記號都落在 default 上）另有一條路：session-timer.sh 的 restart +# 分支會把這個記號刪掉。判定「這是不是新的工作階段」只有那一支知道，所以刪除掛在那裡， +# 這裡不自己再判一次。 +HERE=$(dirname "$0"); . "$HERE/lib.sh" +hook_trace "session-reminder ${1:-}" +read_stdin +sid=$(session_id) + +MODE="${1:-show}" +STATE_DIR="$JSC_HOME/assistant" +QUEUE="$STATE_DIR/reminders.tsv" +MARK="$JSC_HOME/sessions/$sid.reminded" +MAX_ROWS=8 + +# 助理沒啟動過就整支安靜退出。 +[ -d "$STATE_DIR" ] || exit 0 + +# 這個工作階段提過了就不再提。peek 一律印，那是人自己要重看。 +if [ "$MODE" != peek ] && [ -f "$MARK" ]; then + exit 0 +fi + +mark_done() { + [ "$MODE" = peek ] && return 0 + mkdir -p "$JSC_HOME/sessions" 2>/dev/null || return 0 + now_epoch >"$MARK" 2>/dev/null || true + return 0 +} + +if [ ! -f "$QUEUE" ]; then + echo "[jsc] 助理的狀態目錄在，但還沒有提醒佇列（$QUEUE）。跑過一輪巡檢才會產生，所以這裡沒有提醒**不代表沒有事要做**——要現在看就跑 /jsc-assist:assistant status。" + mark_done + exit 0 +fi + +TAB=$(printf '\t') + +# 檔頭。第一行不是 round 就是格式不對，或者檔案被別的東西蓋掉了，兩種都照實說。 +_head=$(head -n1 "$QUEUE" 2>/dev/null) +_kind=$(printf '%s' "$_head" | cut -f1) +if [ "$_kind" != round ]; then + echo "[jsc] 提醒佇列（$QUEUE）的第一行不是輪次資訊，這一份讀不了。助理下一輪會重寫；在那之前要看待辦就跑 /jsc-assist:assistant status。" + mark_done + exit 0 +fi +_iso=$(printf '%s' "$_head" | cut -f3) +_failing=$(printf '%s' "$_head" | cut -f4) +_epoch=$(printf '%s' "$_head" | cut -f5) +_tasks=$(printf '%s' "$_head" | cut -f6) +case "${_failing:-}" in ''|*[!0-9]*) _failing=0 ;; esac +case "${_tasks:-}" in ''|*[!0-9]*) _tasks=0 ;; esac + +# 佇列有多舊。門檻與心跳狀態一律取 heartbeat.sh 印的那一行：那是這台機器判定「助理還在跑」 +# 的唯一一套規則，這裡再定一套就會出現兩個說法。 +_age='' +case "${_epoch:-}" in + ''|*[!0-9]*) ;; + *) _age=$(( $(now_epoch) - _epoch )) ;; +esac +_hb=$(sh "$HERE/heartbeat.sh" report /dev/null || true) +_hbstate=$(printf '%s' "$_hb" | sed -n 's/^state=\([a-z]*\).*/\1/p') +_ttl=$(printf '%s' "$_hb" | sed -n 's/.*[[:space:]]ttl=\([0-9]*\).*/\1/p') +case "${_ttl:-}" in ''|*[!0-9]*) _ttl=300 ;; esac + +_rows=$(awk -F"$TAB" '$1 == "overdue" || $1 == "remind" { n++ } END { print n + 0 }' "$QUEUE" 2>/dev/null) +case "${_rows:-}" in ''|*[!0-9]*) _rows=0 ;; esac + +_stale=0 +if [ -n "$_age" ] && [ "$_age" -gt "$_ttl" ]; then _stale=1; fi +[ "$_hbstate" = fresh ] || _stale=1 + +if [ "$_rows" -eq 0 ] && [ "$_failing" -eq 0 ]; then + # 佇列是新的而且空的：這才是真的「沒有提醒」，安靜退出。 + # 過期又空的那一種要分兩路。待辦簿有東西，就代表「有事而現在沒有人在算它到期沒到期」， + # 那要說一句；零筆就只是助理閒著，人自己按停也算這一種——對著一個刻意的決定每個工作階段 + # 催一次，那是噪音不是提醒。 + if [ "$_stale" -eq 1 ] && [ "$_tasks" -gt 0 ]; then + _agetxt='年紀算不出來' + [ -n "$_age" ] && _agetxt="$(( _age / 60 )) 分鐘前" + echo "[jsc] 助理的提醒清單是 ${_iso:-未知時間}（$_agetxt）那一輪算的，那一輪沒有提醒；心跳現在是「${_hbstate:-讀不到}」。待辦簿還有 $_tasks 筆，**助理停著的時候沒有人再判它們到期了沒有**，所以這裡安靜不等於沒事。要現況就跑 /jsc-assist:assistant status。" + fi + # 記號一律記：不記的話同一個工作階段每次觸發都會再讀一次、再說一次同一句話。 + mark_done + exit 0 +fi + +if [ "$_stale" -eq 1 ]; then + _agetxt='年紀算不出來' + [ -n "$_age" ] && _agetxt="$(( _age / 60 )) 分鐘前算的" + echo "[jsc] 下面這批提醒是 ${_iso:-未知時間}（$_agetxt）那一輪算出來的，助理現在的心跳是「${_hbstate:-讀不到}」，門檻 $_ttl 秒。**助理停著的時候這份清單不會更新**，所以它現在說什麼都只描述那一輪，不描述現在。要現況就跑 /jsc-assist:assistant status。" +fi + +# 逾期排前面：那幾筆的截止時間已經過了，比「該做了」更急。 +# +# 先把兩種併成一份有序清單，再用 head 截筆數，不在迴圈裡自己數。 +# 理由是那個迴圈接在管線後面，殼會把它放進子殼跑——在子殼裡加的計數，回到外面就沒了， +# 於是那道「只列前幾筆」的上限看起來寫了，實際上一次都沒生效。 +_ordered=$( + awk -F"$TAB" '$1 == "overdue" { print }' "$QUEUE" 2>/dev/null + awk -F"$TAB" '$1 == "remind" { print }' "$QUEUE" 2>/dev/null +) +printf '%s\n' "$_ordered" | head -n "$MAX_ROWS" | while IFS="$TAB" read -r _k _id _why _title; do + [ -n "$_id" ] || continue + if [ "$_k" = overdue ]; then + echo "[jsc] 逾期 $_id：${_title:--} —— 已經逾期 ${_why:--}" + else + echo "[jsc] 到期 $_id：${_title:--} —— ${_why:--}" + fi +done + +if [ "$_rows" -gt "$MAX_ROWS" ]; then + echo "[jsc] 這一批共 $_rows 筆，上面只列了 $MAX_ROWS 筆。其餘的跑 /jsc-assist:assistant status 看得到全部。" +fi + +if [ "$_failing" -gt 0 ]; then + echo "[jsc] 另有 $_failing 筆待辦連續失敗，每一輪都在重試而且不會自動暫停。跑 /jsc-assist:assistant status 看是哪幾筆。" +fi + +mark_done +exit 0 diff --git a/hooks/session-timer.sh b/hooks/session-timer.sh index 273ffb4..cf3aa98 100755 --- a/hooks/session-timer.sh +++ b/hooks/session-timer.sh @@ -18,6 +18,9 @@ # restart 給接不到 session id 的 CLI（kiro）。那些 CLI 的紀錄共用 default， # 不覆寫就會把上一個工作階段的起始時間算進來，花費時間虛胖。 # +# restart 另外清掉提醒記號（$JSC_HOME/sessions/{代號}.reminded）：那個記號讓提醒一個工作 +# 階段只提一次，而共用 default 代號的 CLI 不清就等於只提第一次、往後永遠不提。 +# # 這兩個子命令另外兼一件事：判定為「新的工作階段」時清除部署後的重啟閘門 # （restart-gate.sh clear）。新工作階段代表 CLI 行程是新起的，新版技能組一定已經載入。 # 判準只有這裡知道——start 分支的「起始檔不存在」就是這個 session id 第一次開始， @@ -46,6 +49,11 @@ case "${1:-mark}" in restart) now_epoch > "$JSC_HOME/sessions/$sid.start" rm -f "$JSC_HOME/sessions/$sid.end" + # 提醒記號一起清。那個記號讓提醒一個工作階段只提一次，而接不到 session id 的 CLI + # 全部共用 default 這一個代號——不清的話第一個工作階段提過之後，往後每一個工作階段 + # 都會被當成「已經提過」，那支 CLI 從此再也收不到任何提醒。 + # 清除掛在這裡不掛在提醒那一支：「這是不是新的工作階段」的判準只有這一支知道。 + rm -f "$JSC_HOME/sessions/$sid.reminded" clear_restart_gate ;; # 接不到 session id 的 CLI 每次工作階段開始都算新的，一律清 mark) now_epoch > "$JSC_HOME/sessions/$sid.end" ;; diff --git a/plugin.json b/plugin.json index 5dab0f2..7729ec4 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-hooks", - "version": "0.4.7", + "version": "0.4.8", "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄、SDLC 模型鎖、版本前置檢查、註解範圍守門、繁中編碼守門、部署後強制重啟、寫入與提交閘門", "skills": "./skills/", "jsc": { diff --git a/references/behaviors.md b/references/behaviors.md index 55471dc..df2e5a4 100644 --- a/references/behaviors.md +++ b/references/behaviors.md @@ -6,7 +6,7 @@ | 項目 | 內容 | | --- | --- | -| 觸發時機 | 裝好或更新完 jsc 技能組之後，要把九支 hook 接線到每一支已安裝的 CLI 時用；`jsc-cli:deploy` 收尾會把偵測到的 CLI 清單交給它。不用於撰寫新的 hook，也不用於單獨修一支壞掉的 hook，那是 `jsc-hooks:repair` 的事 | +| 觸發時機 | 裝好或更新完 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`（異常頁與索引目錄頁分屬兩個存取庫，各自解析：異常頁由 `report-error.sh` 走 `wiki-repo ERROR`，目錄頁由 `wiki-contents.sh` 走 `wiki-repo CONTENTS`；只解不出目錄頁的存取庫時異常頁照寫、索引跳過，回報要講明那一頁沒被索引）、目錄頁上這一筆是一個 H2 區塊，標題就是異常頁頁名，時間、頁名、存取庫名稱、觸發 hook、退出碼、摘要各一條條列，寫成 `- {欄位名}：{值}`，頁上不留 markdown 表格、「頁名」那一條指向異常頁的連結一律寫成 `[{文字}]({連結})`，網址取 `gitea.sh wiki-url`，寫進去之前先過 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫連結、驗不過那一條只留純文字頁名而那一條與異常頁照寫（`report-error.sh` 內部做完，結束碼不變）、目錄頁的讀回、比對與整頁寫回一律交給 `jsc-gitea/tools/wiki-contents.sh upsert ERROR 2 {頁名} {區塊檔} {範本}`，`report-error.sh` 只組自己那一個區塊，找得到同名 H2 就整塊換掉、找不到就附加到頁尾、逐 CLI 回報五道關卡的結果、最後由主代理呼叫一次 `tools/report-status.sh skill-end jsc-hooks:hooks-install {status} {結束碼} {detail}` 記下整輪怎麼結束。腳本在同一個存取庫，用 `tools/` 相對路徑；這一筆只由主代理寫一次，寫在並行的各 CLI sub agent 裡會變成五筆互相矛盾的結局。腳本不在就安靜跳過，回報失敗不得變成接線失敗 | | 外部呼叫 | `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`，取目錄頁那一條的網址並驗它連得到）、`jsc-gitea/tools/wiki-contents.sh upsert`（同樣經 `report-error.sh`，把那一個 H2 區塊 upsert 進索引目錄頁）；接線腳本內部另呼叫 `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 連結，而且目錄頁那一條的連結驗不過時，回報要講明那一條只有純文字頁名、沒有連結 | diff --git a/tools/scan-hook-errors.sh b/tools/scan-hook-errors.sh index 0fda335..ee98c8e 100755 --- a/tools/scan-hook-errors.sh +++ b/tools/scan-hook-errors.sh @@ -18,7 +18,7 @@ # # 產出: 每筆錯誤附加一行 JSON 到 $JSC_HOME/errors/hooks.jsonl（格式比照 hooks/skill-usage.sh）： # {ts,cli,hook,event,exit,detail,jsc} -# jsc 欄位：command 或 stderr 命中九支 hook 腳本任一支，或命中 jsc-hooks 路徑，就是 true， +# jsc 欄位：command 或 stderr 命中十支 hook 腳本任一支，或命中 jsc-hooks 路徑，就是 true， # 否則 false。分得出來才用得上——非 jsc 的 hook 錯誤不是 jsc 該修的，hooks-install 只回報、 # 不轉 jsc-hooks:repair。 # @@ -52,7 +52,7 @@ case "$cli" in codex|copilot|antigravity|kiro) printf 'status=unavailable reason=%s\n' "$cli 沒有 hook 結果紀錄，執行期錯誤掃不到" echo "[jsc] $cli：原生紀錄只留工作階段與提示內容，沒有記下 hook 的退出碼與 stderr。" - echo "[jsc] $cli：改跑 tools/wire-cli.sh smoke $cli，主動執行九支 hook 驗執行期。" + echo "[jsc] $cli：改跑 tools/wire-cli.sh smoke $cli，主動執行十支 hook 驗執行期。" exit 0 ;; esac @@ -98,6 +98,7 @@ extract_errors() { # 第三方的，只回報不修正。 function is_jsc(t) { if (index(t, "ste100-guard.sh") || index(t, "session-timer.sh") \ + || index(t, "session-reminder.sh") \ || index(t, "skill-usage.sh") || index(t, "sdlc-gate.sh") \ || index(t, "version-guard.sh") || index(t, "restart-gate.sh") \ || index(t, "comment-scope.sh") || index(t, "lang-guard.sh") \ diff --git a/tools/wire-cli.sh b/tools/wire-cli.sh index f649fbd..0ac8a7b 100755 --- a/tools/wire-cli.sh +++ b/tools/wire-cli.sh @@ -3,7 +3,7 @@ # 用法: # wire-cli.sh {claude|codex|copilot|antigravity|kiro} 接線 # wire-cli.sh purge {claude|codex|copilot|antigravity|kiro} 備份後移除該 CLI 的所有 hook -# wire-cli.sh smoke {claude|codex|copilot|antigravity|kiro} 跑一輪九支 hook，驗執行期 +# wire-cli.sh smoke {claude|codex|copilot|antigravity|kiro} 跑一輪十支 hook，驗執行期 # wire-cli.sh status {claude|codex|copilot|antigravity|kiro} [--verdict] # 唯讀盤點接線現況，不寫檔也不執行 hook。 # --verdict 只換結束碼語意，輸出一字不變 @@ -37,7 +37,7 @@ # 就好，不必在 SKILL.md 或 README 各抄一份——抄了就會在加減判定路徑時漂移。 # # 接線行為（依 CLI 而定，皆為冪等：重跑只取代既有的 jsc 段落，不會重複疊加）： -# claude — 什麼都不用寫，hooks/hooks.json 已自動接線九支 hook（PreToolUse matcher Skill） +# claude — 什麼都不用寫，hooks/hooks.json 已自動接線十支 hook（PreToolUse matcher Skill） # codex — pre-tool hook 寫在 .codex-plugin/plugin.json 的 hooks 鍵，做 Codex 專屬覆寫 # （PreToolUse matcher Bash，接 restart-gate.sh 與 version-guard.sh）。 # Claude 用的 hooks/hooks.json 完全不動：那一份是 Skill matcher，而 Codex @@ -74,7 +74,7 @@ # # 覆蓋範圍要據實回報，不得暗示每個 CLI 都有保護，也不得再說「沒有 pre-tool hook」—— # 五支裡有四支都有，先前失效的原因是接錯位置，不是沒有位置可接： -# claude 九支 hook 全接，回報 wired +# claude 十支 hook 全接，回報 wired # codex、copilot、antigravity 版本前置檢查與部署後重啟閘門都擋得下來，回報 wired。 # SDLC 模型鎖仍是技能步驟檢查，write-guard.sh 三種模式尚未接線， # 註解範圍與繁中編碼仍是 sweep，reason 要逐項講明。 @@ -544,7 +544,8 @@ kiro_agent_json() { ], "hooks": { "agentSpawn": [ - { "command": "JSC_CLI=kiro sh \\"$WIRE_HOOKS/session-timer.sh\\" restart /dev/null then st_item "$_h" "$claude_hooks" present else st_item "$_h" "$claude_hooks" missing; fi @@ -2529,7 +2531,7 @@ if [ "$action" = status ]; then then st_item "event-$_e" "$kr_agent" present else st_item "event-$_e" "$kr_agent" missing; fi done - for _g in session-timer.sh restart-gate.sh version-guard.sh ste100-guard.sh comment-scope.sh lang-guard.sh; do + for _g in session-timer.sh session-reminder.sh restart-gate.sh version-guard.sh ste100-guard.sh comment-scope.sh lang-guard.sh; do if [ -f "$kr_agent" ] && grep -qF "$_g" "$kr_agent" 2>/dev/null then st_item "${_g%.sh}" "$kr_agent" present else st_item "${_g%.sh}" "$kr_agent" missing; fi @@ -2577,7 +2579,7 @@ case "$cli" in done printf 'status=wired reason=%s\n' "hooks.json 自動接線" echo "$WIRE_PATH_NOTE" - echo "[jsc] claude：由 hooks/hooks.json 自動接線全部九支 hook，無需寫入設定。" + echo "[jsc] claude：由 hooks/hooks.json 自動接線全部十支 hook，無需寫入設定。" echo "[jsc] claude：只有 claude 有 pre-tool hook，版本前置檢查、部署後重啟閘門與 write-guard.sh 的三種模式只在這裡擋得下來；其他四個 CLI 這幾道閘門都接不上。" echo "[jsc] claude：只有 claude 有 post-tool hook，comment-scope.sh 與 lang-guard.sh 的逐檔即時掃描只在這裡接得上；其他四個 CLI 改用 sweep 掃整個工作區，時機晚一輪或晚到工作階段結束。" exit 0 ;; @@ -2800,7 +2802,7 @@ case "$cli" in # 兩層 glob 是技能看不看得到的關鍵：預設只掃一層，jsc 的技能在第二層。 grep -qF '/skills/*/*/SKILL.md' "$kr_agent" 2>/dev/null \ || fail "$kr_agent 的 resources 少了兩層 glob，jsc 技能一支都載不到" - for _s in session-timer.sh restart-gate.sh version-guard.sh ste100-guard.sh comment-scope.sh lang-guard.sh; do + for _s in session-timer.sh session-reminder.sh restart-gate.sh version-guard.sh ste100-guard.sh comment-scope.sh lang-guard.sh; do grep -qF "$_s" "$kr_agent" 2>/dev/null || fail "$kr_agent 的 hooks 沒有接到 $_s" done # 這個 agent 要被選用才算數，所以還要設 chat.defaultAgent。內建 agent 改不了，