feat(異常目錄頁): 索引改成 H2 區塊條列並委派共用工具

What：異常目錄頁的版面從 markdown 表格改成一筆異常一個 H2 區塊，標題就是那一筆的異常頁頁名，時間、頁名、存取庫名稱、觸發 hook、退出碼、摘要六個欄位改成標題底下的一層條列，頁上不再留任何表格。失敗回報腳本不再自己讀回舊頁、附加新列、整頁寫回，改成只組出自己那一個區塊，交給 jsc-gitea 的目錄頁工具做讀回、比對與整頁寫回。範本、技能敘述、行為清單與說明文件一併對齊。 Why：目錄頁有十幾份，各自在自己的腳本裡寫一套「讀得回舊內容才寫」的判斷，錯一次就少一筆紀錄，而且每一頁長出來的樣子都不一樣。版面與寫入語意收回一份正本之後，改一次全部跟著改。表格欄位遇到換行或半形豎線還會被切斷，條列沒有這個問題。 How：失敗回報腳本移除目錄專用存取庫的解析與整頁組裝，改為組出區塊檔之後呼叫共用工具的 upsert，並依它的結束碼分流：3 是目錄頁的存取庫沒設定，找不到那支腳本也走同一條，兩者都只寫異常頁、跳過目錄頁、仍回 0；其餘非零一律以 4 回報。摘要不再替換半形豎線，改成把換行併成一行。傳進去的欄位序號 2 指舊表格版持有內容頁連結的那一欄，只供舊頁自動轉條列時取標題用。 Who：使用 jsc-hooks 失敗回報流程的操作者，以及所有讀異常目錄頁追問題的人。
2026-09-02 18:01:33 +08:00
parent 9adb39d21a
commit 02caedf91e
5 changed files with 79 additions and 74 deletions
@@ -169,7 +169,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}`，並在 `ERROR_CONTENTS` 附上一列索引。目錄頁一律先讀回舊頁再附加新列、整頁寫回，不整頁覆蓋：只有 `wiki-get` 回 4（頁面真的不存在）才用範本建新頁，回 7（金鑰失效）或 8（其他 API 失敗）代表舊內容未知，放棄目錄頁寫入並以 exit 4 回報，免得拿範本蓋掉所有既有列。目錄頁那一列指向異常頁，連結一律寫成 `[{文字}]({連結})`，網址取 `jsc-gitea` 的 `gitea.sh wiki-url` 印出的那一個，不自己組路徑。寫進那一格之前，先把那個網址交給 `jsc-gitea` 的 `tools/link-check.sh` 驗一次，結束碼 0 才寫連結；`link-check.sh` 的路徑由已經解出來的 `gitea.sh` 推得，兩支同一個 tools 目錄。驗不過（含找不到 `link-check.sh`、`GITEA_HOST` 未設定回 3、金鑰失效回 7）就只在那一格留純文字頁名，那一列照寫、異常頁照寫、結束碼照舊，原因走 stderr——回報失敗不該再變成一次失敗。網址在異常頁寫成功之後才取：頁名的 hash 帶時間戳，每次回報都是全新的頁，寫進去之前查一定是 404，先查就只拿得到空字串。取不到網址時只印頁名，原因走 stderr，結束碼照舊回 0。wiki 位置分兩次解析：異常頁走 `jsc-gitea` 的 `gitea.sh wiki-repo ERROR`，目錄頁走 `gitea.sh wiki-repo CONTENTS`，兩者是兩個不同的存取庫。異常頁的存取庫解不出來就整支安靜降級；只有目錄頁的存取庫解不出來，就只寫異常頁、跳過目錄頁更新，仍回 exit 0。由操作者手動執行，或由 `hooks-install` 在 `wire-cli.sh` 回報 `status=failed` 時執行；**不接在失敗的 hook 上自動觸發**（hook 一律安靜 exit 0，自我回報會疊出迴圈） |
+| `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 -->`（或 `# 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<TAB>{數量}`，那是其後 `[jsc]` 結果行的實際條數，與腳本內逐類宣告的預期條數比對，不符就回非零。判定路徑增減時只改腳本裡的預期值，散文一律引用這一行，不另外抄一份數字。`status {cli}` 是唯讀盤點：只讀設定檔判斷段落與 matcher 對不對，不寫檔也不執行 hook，claude、codex、copilot、antigravity 回 `wired`，kiro 回 `degraded` 並在 `reason` 講明那是 CLI 限制；每個接線點印一行 `item<TAB>{項目}<TAB>{路徑}<TAB>{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` 回報 |
@@ -182,7 +182,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | 範本 | 用途 |
 | --- | --- |
 | `templates/error-page.md` | 單筆 hook 異常頁 `ERROR_{HASH}`，記錄當次失敗的觸發條件、錯誤摘要與處理結果。 |
-| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。落在目錄專用存取庫，一律 upsert 附加，連結一律寫成 `[{文字}]({連結})` 且先過 `link-check.sh` 驗過才寫。 |
+| `templates/error-contents.md` | 異常目錄 `ERROR_CONTENTS`，彙整所有異常頁，方便先看最新問題再往下追。版面是 H1 頁名加 `>` 引言，之後一筆一個 H2 區塊，標題就是異常頁頁名，欄位一行一條；範本只留一個示範區塊，用 `{佔位符}` 寫。落在目錄專用存取庫，一律 upsert 附加，連結一律寫成 `[{文字}]({連結})` 且先過 `link-check.sh` 驗過才寫。 |

 ## Skills 目錄

@@ -206,7 +206,7 @@ Claude 由 `hooks/hooks.json` 自動接線九支 hook；其他 CLI 用 `hooks-in
 | --- | --- | --- |
 | `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
 | `JSC_WIKI_REPO_ERROR` | 異常內容頁 `ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`；還是解不出來就整支 `tools/report-error.sh` 安靜降級，不寫 wiki |
-| `JSC_WIKI_REPO_CONTENTS` | 目錄頁 `ERROR_CONTENTS` 所在的 `{owner}/{repo}`。目錄頁與內容頁分屬兩個不同的存取庫，各解各的 | 退回 `JSC_WIKI_REPO`；還是解不出來就只寫內容頁、跳過目錄頁更新，`tools/report-error.sh` 仍回 exit 0 |
+| `JSC_WIKI_REPO_CONTENTS` | 目錄頁 `ERROR_CONTENTS` 所在的 `{owner}/{repo}`，由 `wiki-contents.sh` 解析。目錄頁與內容頁分屬兩個不同的存取庫，各解各的 | 退回 `JSC_WIKI_REPO`；還是解不出來時 `wiki-contents.sh` 回 3，只寫內容頁、跳過目錄頁更新，`tools/report-error.sh` 仍回 exit 0 |
 | `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | `tools/report-error.sh` 安靜降級，不寫 wiki |
 | `COPILOT_HOME` | copilot 的設定根目錄，`hooks/jsc-hooks.json` 與指引檔都寫在它底下 | 預設 `~/.copilot` |
 | `KIRO_HOME` | kiro 的設定根目錄，`agents/jsc.json`、`settings/cli.json` 與 `resources` 的 `skill://` glob 都由它推導 | 預設 `~/.kiro` |
@@ -7,10 +7,10 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 裝好或更新完 jsc 技能組之後，要把九支 hook 接線到每一支已安裝的 CLI 時用；`jsc-cli:deploy` 收尾會把偵測到的 CLI 清單交給它。不用於撰寫新的 hook，也不用於單獨修一支壞掉的 hook，那是 `jsc-hooks:repair` 的事 |
-| 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/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 回報五道關卡的結果 |
-| 外部呼叫 | `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` 做冒煙斷言 |
-| 完成條件 | 每一支偵測到的 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_HOME/current/jsc-hooks` 符號連結建立或更新、`$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 的結束碼 |
+| 關鍵步驟 | 取得 CLI 清單（呼叫端交來的優先，沒有才自己跑 `detect-clis.sh`）、第一支 CLI 單獨跑完整條管線（它負責更新共用的 `$JSC_HOME/current/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/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` 做冒煙斷言 |
+| 完成條件 | 每一支偵測到的 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_HOME/current/jsc-hooks` 符號連結建立或更新、`$JSC_HOME/backup/hooks/{cli}/{時間戳}/` 留下 purge 前的備份、出錯時 wiki 多一頁 `ERROR_{HASH}`（落在 `JSC_WIKI_REPO_ERROR` 解出的存取庫）並在索引目錄頁補一個 H2 區塊（落在 `JSC_WIKI_REPO_CONTENTS` 解出的另一個存取庫，由 `wiki-contents.sh` upsert 進去；H2 標題就是那一頁的頁名，底下六條條列依序是時間、頁名、存取庫名稱、觸發 hook、退出碼、摘要，「頁名」那一條寫成 `[{頁名}]({絕對網址})`，網址取自 `gitea.sh wiki-url` 且已經過 `link-check.sh` 驗到結束碼 0；驗不過那一條只有純文字頁名，`report-error.sh` 在 stderr 留一行 `[jsc]` 講明是哪一種原因；那一頁上不會有 markdown 表格）、修正路徑留下一條對 `develop` 的 PR 。接線完成後 `$JSC_HOME/usage/events.jsonl` 會逐行長出 `{kind:hook}` 事件，每支 hook 每次執行一筆，欄位含 `status` 與實際結束碼；跑過技能之後另有 `{kind:skill,phase:start}`。事件寫不進去不影響任何 hook 的結束碼 |

 ## repair

@@ -75,7 +75,7 @@ The detailed flow **MUST run as a sub agent**; the main agent only reports the s
   5. `tools/scan-hook-errors.sh --cli {cli}` — only claude keeps hook results in its native records and can answer `clean` or `errors`; codex, copilot, antigravity and kiro answer `unavailable`, and their runtime evidence comes from the smoke stage alone. Exit 0 covers both `clean` and `unavailable`, exit 1 is `errors` and every entry with `jsc=true` goes to step 3, exit 2 is a bad CLI name.

   Done when every detected CLI has exactly one verdict line per stage, no stage exited 2, the smoke stage's `lines` count matches its own assertion, the four non-claude CLIs are reported as `unavailable` rather than clean on the scan stage, and antigravity and kiro carry the note that their hook firing is unverified.
-3. For each error — a failed purge, a failed wiring, an `unwired` status, a failed smoke, or a scanned error with `jsc=true` — run `tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli}` with the script's `[jsc]` output on stdin, then hand the failure to `jsc-hooks:repair`, which **MUST run as a sub agent** and must finish by opening a PR against `develop`. Aborting the remaining installs here is allowed as long as the repair starts. The error page and the error directory page live in two different wiki repos, resolved separately: the page through `wiki-repo ERROR`, the directory through `wiki-repo CONTENTS`. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; the same exit 0 with a `[jsc]` line on stderr still means the page landed, and that line says what is missing — the directory repo would not resolve, so nothing indexes the page; the page URL could not be read back, so the page name comes out on its own; or the URL failed the reachability check, so the directory row carries the page name as plain text with no link — carry that note into step 4. Every link on that row is written as `[{text}]({url})` with the URL from `gitea.sh wiki-url`, and the script checks it with `jsc-gitea/tools/link-check.sh` before writing: exit 0 writes the link, anything else keeps the row and drops the link, and none of it changes the exit code — this is the failure-reporting path, so a failed report must never become a second failure. Exit 0 with no output at all means the run ended on one of the quiet-degradation reasons listed in the script's own header — no `gitea.sh` on the path, the error page's wiki repo unresolved, the hash not computed, or a temp file not created — so no page was written at all and that reason goes into step 4 instead; exit 2 means the call itself was malformed — `--hook` or `--summary` is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the script refusing to write the error directory page because it could not read the old one back. That directory is appended to, never overwritten: every row on it is somebody else's error report, so the script reads the page, adds this run's row, and writes the whole page. Only a genuine 404 (`wiki-get` exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old rows unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one `ERROR_{HASH}` result — a page name with its URL, a page name plus the reason the URL is missing, or the recorded reason no page was written — and one repair PR URL against `develop`.
+3. For each error — a failed purge, a failed wiring, an `unwired` status, a failed smoke, or a scanned error with `jsc=true` — run `tools/report-error.sh --hook {script name} --exit {code} --summary "{reason}" --cli {cli}` with the script's `[jsc]` output on stdin, then hand the failure to `jsc-hooks:repair`, which **MUST run as a sub agent** and must finish by opening a PR against `develop`. Aborting the remaining installs here is allowed as long as the repair starts. The error page and the error directory page live in two different wiki repos, resolved separately: the page through `wiki-repo ERROR` in `report-error.sh` itself, the directory through `wiki-repo CONTENTS` inside `wiki-contents.sh`. Exit 0 with an `ERROR_{HASH}` page name and URL on stdout means the page was written; the same exit 0 with a `[jsc]` line on stderr still means the page landed, and that line says what is missing — the directory repo would not resolve (or `wiki-contents.sh` is not on disk), so nothing indexes the page; the page URL could not be read back, so the page name comes out on its own; or the URL failed the reachability check, so the directory entry's page-name bullet carries the page name as plain text with no link — carry that note into step 4. One error report is one H2 block on the directory page: the heading is that report's own page name, `ERROR_{HASH}`, and the fields sit under it as one bullet each — time, page name, repo, hook, exit code, summary, written `- {field}：{value}` — with no markdown table anywhere on the page. Every link inside that block is written as `[{text}]({url})` with the URL from `gitea.sh wiki-url`, and the script checks it with `jsc-gitea/tools/link-check.sh` before writing: exit 0 writes the link, anything else keeps the bullet and drops the link, and none of it changes the exit code — this is the failure-reporting path, so a failed report must never become a second failure. Exit 0 with no output at all means the run ended on one of the quiet-degradation reasons listed in the script's own header — no `gitea.sh` on the path, the error page's wiki repo unresolved, the hash not computed, or a temp file not created — so no page was written at all and that reason goes into step 4 instead; exit 2 means the call itself was malformed — `--hook` or `--summary` is missing — so fix the arguments and rerun the same call; exit 4 means the wiki record did not land, so report the failure text and still start the repair — a page that could not be written is no reason to leave a broken hook wired. Exit 4 covers two cases, and the report has to say which: a failed write, or the directory page left untouched because the old one could not be read back. The directory page itself is not assembled here: `report-error.sh` builds only its own block and hands it to `jsc-gitea/tools/wiki-contents.sh upsert ERROR 2 {page name} {block file} {template}`, so the read, the key match and the whole-page write have exactly one owner. That page is upserted, never overwritten: every block on it is somebody else's error report, so the tool reads the page, replaces the block whose heading equals this page name or appends a new block at the end, and writes the page back. Only a genuine 404 (`wiki-get` exit 4) means the page is not there yet and lets it build one from the template. An invalid key (exit 7) or any other API failure (exit 8) leaves the old blocks unknown, so it skips the directory write and names the code instead — writing a fresh template over a directory it never read would erase every earlier report, with no merge and no backup behind it. A scanned error with `jsc=false` belongs to a third-party hook: report it and leave it alone. Skip this step when every CLI passed all five stages. Done when every error carries one `ERROR_{HASH}` result — a page name with its URL, a page name plus the reason the URL is missing, or the recorded reason no page was written — and one repair PR URL against `develop`.
 4. Report five results per CLI — purge, wiring, status, smoke, scan — each with the reason its script printed, plus the smoke `lines` count, any `ERROR_{HASH}` page name and every repair PR URL. Done when every detected CLI appears with one verdict per stage and every repair has a PR against `develop`.

 ## Notes
@@ -4,14 +4,17 @@
 >
 > 存放位置：本頁落在 `JSC_WIKI_REPO_CONTENTS` 解出的目錄專用存取庫，與異常頁的存取庫是兩個不同的存取庫。
 >
-> 寫入語意：一列代表一次 hook 異常回報。寫入前先讀回整頁，同一筆異常已經有列就更新那一列，沒有才在文末附加一列，最後整頁寫回。一律 upsert 附加，禁止整頁覆蓋，也不得改動別人的列。
+> 寫入語意：一個區塊代表一次 hook 異常回報。H2 標題就是那一筆的異常頁頁名 `ERROR_{HASH}`，欄位是標題底下的一層條列，一個欄位一條。寫入前先讀回整頁，同一筆異常已經有區塊就整塊換掉，沒有才在文末附加一個新區塊，最後整頁寫回。一律 upsert 附加，禁止整頁覆蓋，也不得改動別人的區塊。
 >
 > 連結寫法：一律寫成 `[{文字}]({絕對網址})`，網址取 `jsc-gitea/tools/gitea.sh wiki-url` 印出的那一個，不自己組路徑。wiki 自己那種雙中括號寫法只在同一個 wiki 裡解得開，寫錯不會報錯，畫面上看起來像正常文字或死連結。
 >
-> 寫入前驗證：這一列要放進去的連結，先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才把連結寫進那一格。驗不過就只留純文字頁名，那一列照寫，異常紀錄不因為一條連結整份丟掉。驗證走 API，不看網頁狀態碼——私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把還在的頁判成死連結。結束碼 7 是金鑰失效，不算死連結，也不改寫任何既有列。
+> 寫入前驗證：要放進條列的連結，先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才把連結寫進那一條。驗不過就只留純文字頁名，那一條照寫，異常紀錄不因為一條連結整份丟掉。驗證走 API，不看網頁狀態碼——私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把還在的頁判成死連結。結束碼 7 是金鑰失效，不算死連結，也不改寫任何既有區塊。

-## 異常清單
+## ERROR_{HASH}

-| 時間 | 頁名 | 存取庫名稱 | 觸發 hook | 退出碼 | 摘要 |
-| --- | --- | --- | --- | --- | --- |
-| {yyyy-MM-dd HH:mm:ss} | [{頁名}]({wiki-url 印出的絕對網址}) | {owner}/{repo} | {hook_name} | {exit_code} | {error_summary} |
+- 時間：{yyyy-MM-dd HH:mm:ss}
+- 頁名：[{頁名}]({wiki-url 印出的絕對網址})
+- 存取庫名稱：{owner}/{repo}
+- 觸發 hook：{hook_name}
+- 退出碼：{exit_code}
+- 摘要：{error_summary}
@@ -1,8 +1,10 @@
 #!/usr/bin/env sh
 # report-error.sh — 失敗回報流程：把一筆 hook 或工具異常寫成 wiki 的 ERROR_{HASH}，
-# 並在 ERROR_CONTENTS 附上一列索引。頁面內容套用 templates/ 的兩份範本，
+# 並在異常目錄頁附上一個索引區塊。頁面內容套用 templates/ 的兩份範本，
 # 範本是文案的唯一來源，本腳本只填欄位；真正寫進 wiki 前，還會先走
 # Gitea 寫入確認。
+# 目錄頁的讀回、比對與整頁寫回一律交給 jsc-gitea 的 tools/wiki-contents.sh，本腳本只組出
+# 自己那一個區塊。目錄頁版面只留一份正本，十幾個目錄頁才不會各長一種樣子。
 #
 # 用法:
 #   report-error.sh --hook {名稱} --exit {碼} --summary {摘要}
@@ -20,23 +22,24 @@
 #     3. 算不出 HASH（hash-id 失敗或回空字串）
 #     4. 建不出暫存檔（mktemp 失敗）
 #   異常頁與目錄頁分屬兩個存取庫，各解各的：解不出異常頁的存取庫就整支降級；解得出
-#   異常頁、只解不出目錄頁的存取庫，就只寫異常頁、跳過目錄頁更新，印出頁名，仍然 exit 0。
+#   異常頁、只解不出目錄頁的存取庫（wiki-contents.sh 回 3），就只寫異常頁、跳過目錄頁
+#   更新，印出頁名，仍然 exit 0。找不到 wiki-contents.sh 也走同一條降級路。
 #   一份寫得成的異常紀錄，不該因為目錄頁沒地方放就整份丟掉。
 #   寫入 wiki 失敗才以 exit 4 回報，訊息走 stderr。
 #
 # 連結:
-#   目錄頁那一列指向異常頁，一律寫成 [{文字}]({連結})，網址取 jsc-gitea 的
-#   gitea.sh wiki-url，不自己組路徑。
-#   寫入前先把那個網址交給 jsc-gitea 的 link-check.sh，結束碼 0 才把連結寫進那一列。
-#   驗不過就只留純文字頁名：那一列照寫、異常頁照寫、結束碼照舊。這一段一律不改結束碼，
+#   目錄頁那個區塊裡的「頁名」那一條指向異常頁，一律寫成 [{文字}]({連結})，網址取
+#   jsc-gitea 的 gitea.sh wiki-url，不自己組路徑。
+#   寫入前先把那個網址交給 jsc-gitea 的 link-check.sh，結束碼 0 才把連結寫進那一條。
+#   驗不過就只留純文字頁名：那一條照寫、異常頁照寫、結束碼照舊。這一段一律不改結束碼，
 #   本腳本是失敗回報路徑，回報失敗不該再變成一次失敗。
 #
 # 結束碼: 0=已寫入異常頁並印出頁名（取得網址就一併印出），或以上列四種安靜降級原因之一
 #           結束、沒有寫出任何頁也沒有任何輸出——回報失敗不該再變成一次失敗
 #         2=用法錯誤（缺 --hook 或 --summary）
 #         4=寫入 wiki 失敗（異常頁與索引目錄頁，任一支寫不進去就算），或目錄頁的舊內容
-#           讀不回來（wiki-get 回 7 金鑰失效、8 其他 API 失敗）而放棄寫入；訊息走 stderr。
-#           讀不回來就不寫，是為了不拿範本蓋掉一份還在的目錄頁
+#           讀不回來（wiki-contents.sh 回 7 金鑰失效、8 其他 API 失敗）而放棄寫入；
+#           訊息走 stderr。讀不回來就不寫，是為了不拿範本蓋掉一份還在的目錄頁
 # 註: 本檔以 `. "$ROOT/hooks/lib.sh"` 載入共用函式，沒有接 `|| true`。lib.sh 讀不到時 sh 會
 #   就地結束並回 2，跟用法錯誤同碼；分不出是哪一種時，先確認 hooks/lib.sh 在不在。
 #
@@ -83,9 +86,8 @@ gsh=$(jsc_gitea_sh) || exit 0
 # 型別。異常頁的存取庫解不出來就整支降級，連異常都沒地方寫，做下去也沒意義。
 wrepo=$(sh "$gsh" wiki-repo ERROR 2>/dev/null) || exit 0
 [ -n "$wrepo" ] || exit 0
-# 目錄頁的存取庫解不出來不算失敗：異常頁照寫，只跳過目錄頁更新，仍然 exit 0。
-# 一份寫得成的異常紀錄，不該因為索引沒地方放就整份丟掉。
-crepo=$(sh "$gsh" wiki-repo CONTENTS 2>/dev/null || true)
+# 目錄頁的存取庫不在這裡解：讀回、比對、整頁寫回都由 wiki-contents.sh 做，它自己解目錄專用
+# 存取庫，這邊再解一次就會有兩份規則。解不出來時它回 3，本腳本照原本的語意降級。

 # 存取庫名稱未指定就取工作目錄的 origin（只用來標記異常屬於哪個存取庫）
 if [ -z "$repo" ]; then
@@ -108,9 +110,10 @@ ts=$(date +'%Y-%m-%d %H:%M:%S')
 ticket_ts=$(date +'%Y%m%d_%H%M%S')
 if [ -t 0 ]; then detail=""; else detail=$(cat 2>/dev/null | tr '\n' ' ' | cut -c1-500); fi
 [ -n "$detail" ] || detail="（無）"
-# 摘要與相關輸出都落在 markdown 表格欄位裡，半形 | 會把欄位切斷，改成全形
+# 相關輸出落在異常頁的表格欄位裡，半形 | 會把欄位切斷，改成全形
 detail=$(printf '%s' "$detail" | sed 's/|/｜/g')
-summary=$(printf '%s' "$summary" | sed 's/|/｜/g')
+# 摘要在目錄頁是一整條條列，換行會把一條拆成兩行，先併成一行
+summary=$(printf '%s' "$summary" | tr '\n' ' ')

 hash=$(sh "$gsh" hash-id "$repo $hook $ts" 2>/dev/null) || exit 0
 [ -n "$hash" ] || exit 0
@@ -121,8 +124,8 @@ esc() { printf '%s' "$1" | tr '\n' ' ' | sed 's/[\\&|]/\\&/g'; }
 fill() { sed "s|$1|$(esc "$2")|g"; }

 tmp_page=$(mktemp) || exit 0
-tmp_list=$(mktemp) || { rm -f "$tmp_page"; exit 0; }
-trap 'rm -f "$tmp_page" "$tmp_list"' EXIT
+tmp_entry=$(mktemp) || { rm -f "$tmp_page"; exit 0; }
+trap 'rm -f "$tmp_page" "$tmp_entry"' EXIT

 fill '{HASH}' "$hash" < "$ROOT/templates/error-page.md" \
  | fill '{yyyy-MM-dd HH:mm:ss}' "$ts" \
@@ -140,16 +143,17 @@ fill '{HASH}' "$hash" < "$ROOT/templates/error-page.md" \
  | fill '{yyyyMMdd}_{HHmmss}' "$ticket_ts" > "$tmp_page"

 # 異常頁先寫，網址後取。頁名的 hash 帶時間戳，每次回報都是一個全新的頁，寫進去之前查網址
-# 一定是 404，拿到的必然是空字串；目錄頁那一列會變成沒有連結的死字，stdout 也少一半。
+# 一定是 404，拿到的必然是空字串；目錄頁那一條會變成沒有連結的死字，stdout 也少一半。
 if ! sh "$gsh" wiki-put "$wrepo" "$page" "$tmp_page" >/dev/null 2>&1; then
  echo "[jsc] 寫入 $page 失敗（$wrepo）。" >&2
  exit 4
 fi

-# 目錄頁那一列指向異常頁，連結一律寫成 [{文字}]({連結})，網址取 gitea.sh wiki-url。
+# 目錄頁那個區塊的「頁名」那一條指向異常頁，連結一律寫成 [{文字}]({連結})，網址取
+# gitea.sh wiki-url。
 # wiki 自己那種雙中括號寫法只在同一個 wiki 裡解得開，寫錯不會報錯，畫面上看起來像正常
 # 文字或死連結，巡不到也修不了。
-# 網址取不到不算失敗：異常頁已經寫成功了，只是這一列少一條連結。這裡把原因記下來走 stderr，
+# 網址取不到不算失敗：異常頁已經寫成功了，只是這一條少一個連結。這裡把原因記下來走 stderr，
 # 結束碼照舊——安靜降級仍是 exit 0，回報失敗不該再變成一次失敗。
 url=$(sh "$gsh" wiki-url "$wrepo" "$page" 2>/dev/null)
 url_code=$?
@@ -162,76 +166,74 @@ if [ "$url_code" -ne 0 ]; then
    7) url_note='金鑰失效或權限不足（wiki-url 回 7）' ;;
    *) url_note="wiki-url 結束碼 $url_code" ;;
  esac
-  echo "[jsc] 取不到 $page 的網址：$url_note。目錄頁那一列與輸出只留頁名。" >&2
+  echo "[jsc] 取不到 $page 的網址：$url_note。目錄頁那一條與輸出只留頁名。" >&2
 fi

 emit() { # 異常頁已經寫成功，頁名一定要印；網址取不到就只印頁名，不印一個空欄位
  if [ -n "$url" ]; then printf '%s %s\n' "$page" "$url"; else printf '%s\n' "$page"; fi
 }

-# 連結先驗證連得到，才寫進目錄頁那一列。沒驗過的連結寫進去，異常頁一樣會在目錄頁長出
-# 死連結，而目錄頁是別人查問題的入口。驗不過就只留純文字頁名，那一列照寫。
-link_cell="$page"
+# 連結先驗證連得到，才寫進目錄頁那一條。沒驗過的連結寫進去，異常頁一樣會在目錄頁長出
+# 死連結，而目錄頁是別人查問題的入口。驗不過就只留純文字頁名，那一條照寫。
+link_text="$page"
 if [ -n "$url" ]; then
  # link-check.sh 與 gitea.sh 同一個 tools 目錄，路徑直接由已經解出來的那一支推得，
  # 不另寫一套搜尋，兩邊才不會一支解到開發版面、一支解到安裝版面。
  lcs="$(dirname "$gsh")/link-check.sh"
  if [ ! -f "$lcs" ]; then
-    echo "[jsc] 找不到 $lcs，這一列的連結沒驗過，只留頁名；$page 已建立。" >&2
+    echo "[jsc] 找不到 $lcs，這一條的連結沒驗過，只留頁名；$page 已建立。" >&2
  else
    sh "$lcs" "$url" >/dev/null 2>&1
    lc_code=$?
    case "$lc_code" in
-      0) link_cell=$(printf '[%s](%s)' "$page" "$url") ;;
+      0) link_text=$(printf '[%s](%s)' "$page" "$url") ;;
      # 7 是金鑰失效，不是死連結。金鑰過期時私有存取庫的回應與「頁不存在」分不出來，
      # 把它當成死連結就會連還在的頁一起判死。
-      7) echo "[jsc] 連結驗證遇上金鑰失效（link-check.sh 回 7），不判成死連結，這一列只留頁名；$page 已建立。" >&2 ;;
-      3) echo "[jsc] GITEA_HOST 未設定（link-check.sh 回 3），連結沒驗過，這一列只留頁名；$page 已建立。" >&2 ;;
-      *) echo "[jsc] 連結驗不過（link-check.sh 結束碼 $lc_code），這一列只留頁名；$page 已建立。" >&2 ;;
+      7) echo "[jsc] 連結驗證遇上金鑰失效（link-check.sh 回 7），不判成死連結，這一條只留頁名；$page 已建立。" >&2 ;;
+      3) echo "[jsc] GITEA_HOST 未設定（link-check.sh 回 3），連結沒驗過，這一條只留頁名；$page 已建立。" >&2 ;;
+      *) echo "[jsc] 連結驗不過（link-check.sh 結束碼 $lc_code），這一條只留頁名；$page 已建立。" >&2 ;;
    esac
  fi
 fi

-row=$(printf '| %s | %s | %s | %s | %s | %s |' \
-  "$ts" "$link_cell" "$repo" "$hook" "$code" "$summary")
+# 目錄頁上這一筆是一個 H2 區塊：標題就是異常頁頁名，欄位一行一條，順序與範本的示範區塊
+# 一致。標題不放連結也不放網址——頁名只由存取庫名稱、hook 與時間決定，換主機或改存取庫
+# 都動不到它，比對鍵才找得到既有那一筆。
+{
+  printf '## %s\n\n' "$page"
+  printf -- '- 時間：%s\n' "$ts"
+  printf -- '- 頁名：%s\n' "$link_text"
+  printf -- '- 存取庫名稱：%s\n' "$repo"
+  printf -- '- 觸發 hook：%s\n' "$hook"
+  printf -- '- 退出碼：%s\n' "$code"
+  printf -- '- 摘要：%s\n' "$summary"
+} > "$tmp_entry"

-build_contents() { # 用範本建一份全新的目錄頁；只有確定舊頁不存在時才可以呼叫
-  # 範本的示範列整列換成本次這一列，不逐格填。連結那一格已經驗過也組好了，拆成頁名與
-  # 網址兩個佔位再填，會在驗不過的時候留下一個空網址的死連結。
-  ROW="$row" awk '
-    index($0, "| {yyyy-MM-dd HH:mm:ss} |") == 1 { print ENVIRON["ROW"]; next }
-    { print }
-  ' "$ROOT/templates/error-contents.md" > "$tmp_list"
-}
-
-if [ -z "$crepo" ]; then
-  echo "[jsc] 目錄頁的 wiki 存取庫解不出來，只寫異常頁，跳過目錄；$page 已建立（$wrepo）。" >&2
+# 目錄頁交給 wiki-contents.sh：它負責解目錄專用存取庫、讀回舊頁、比對 H2 標題找既有區塊、
+# 附加或整塊換掉，再整頁寫回，還會把舊的表格頁轉成條列。頁上每一個區塊都是別人回報的異常，
+# 那套「讀得回舊內容才寫」的判斷只留一份正本，才不會每個目錄頁各寫一套、錯一次少一筆紀錄。
+# 傳進去的那個 2 是 key-col：舊表格版目錄頁裡持有身分的欄位序號。舊版第 2 欄是頁名，
+# 舊頁自動轉條列時要靠它取 H2 標題；頁面已經是條列格式時這個參數用不到。
+# 路徑由已經解出來的 gitea.sh 推得，與 link-check.sh 同一套做法，三支同一個 tools 目錄。
+wcs="$(dirname "$gsh")/wiki-contents.sh"
+if [ ! -f "$wcs" ]; then
+  echo "[jsc] 找不到 $wcs，只寫異常頁，跳過目錄；$page 已建立（$wrepo）。" >&2
  emit
  exit 0
 fi

-# 異常目錄頁一律附加，不整頁覆蓋。頁上每一列都是別人回報的異常，本腳本沒有從別處讀過
-# 那些列，所以先把舊頁讀回來、把新列附在文末（最新一筆在最後），再整頁寫回。
-# 這個語意完全靠「讀得回舊內容」撐著，因此依 wiki-get 的結束碼分流：
-#   0 → 讀到既有內容，附加新列（讀得到但整頁是空的，沒有既有列會被蓋掉，套範本才安全）
-#   4 → 頁面真的還不存在，只有這個碼可以用範本建立新頁
-#   7 → 金鑰失效或權限不足，舊內容未知，放棄目錄頁寫入
-#   8 → 其他 API 失敗，舊內容一樣未知，處置同 7
-# 為什麼 7 與 8 不能當成「頁面不存在」：拿範本蓋掉一份讀不回來的目錄頁，等於刪光所有既有
-# 列，而 wiki-put 不做合併、也不留備份，蓋掉就救不回來。
-sh "$gsh" wiki-get "$crepo" ERROR_CONTENTS > "$tmp_list" 2>/dev/null
-get_code=$?
-case "$get_code" in
-  0) if [ -s "$tmp_list" ]; then printf '%s\n' "$row" >> "$tmp_list"; else build_contents; fi ;;
-  4) build_contents ;;
+sh "$wcs" upsert ERROR 2 "$page" "$tmp_entry" "$ROOT/templates/error-contents.md" >/dev/null
+wc_code=$?
+case "$wc_code" in
+  0) ;;
+  # 3 是目錄頁的存取庫沒設定。異常頁已經寫成功，一份寫得成的異常紀錄不該因為索引沒地方放
+  # 就整份丟掉，所以只跳過目錄頁，結束碼照舊回 0。
+  3) echo "[jsc] 目錄頁的 wiki 存取庫解不出來（wiki-contents.sh 回 3），只寫異常頁，跳過目錄；$page 已建立（$wrepo）。" >&2 ;;
+  # 其餘結束碼都代表這一筆沒進到目錄頁：7 金鑰失效、8 其他 API 失敗都是舊內容未知而中止，
+  # 1 是組不出頁面內容或寫入失敗，2 是用法錯誤，4 是頁面不存在又沒收到範本。
  *)
-    echo "[jsc] 讀取目錄頁失敗（$crepo，wiki-get 結束碼 $get_code），舊內容未知，不寫目錄頁；$page 已建立。" >&2
+    echo "[jsc] 目錄頁寫入失敗（wiki-contents.sh 結束碼 $wc_code），$page 已建立。" >&2
    exit 4 ;;
 esac

-if ! sh "$gsh" wiki-put "$crepo" ERROR_CONTENTS "$tmp_list" >/dev/null 2>&1; then
-  echo "[jsc] 寫入目錄頁失敗（$crepo），$page 已建立。" >&2
-  exit 4
-fi
-
 emit