jiantw83
d472f81cd2
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
34 lines
10 KiB
Markdown
34 lines
10 KiB
Markdown
# jsc-review 技能行為清單
|
||
|
||
本頁記錄 jsc-review 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
|
||
|
||
## api-doc
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 觸發時機 | 控制器改完之後叫用，或工作包實作完成之後叫用。`jsc-sdlc:implement` 在收尾時與 `jsc-review:code-review` 並排叫用它。專案沒有啟用 Swagger 就不跑，這一點由步驟 1 的腳本判定，不由人判斷。原始碼註解合約歸 `jsc-review:code-review` 第 5 組，這支技能只看 Swagger 文件屬性。資安、邏輯錯誤、測試涵蓋率歸 CLI 內建審查。 |
|
||
| 關鍵步驟 | 跑 `tools/swagger-detect.sh` 偵測 Swagger 套件與掛載，讀退出碼 0、1、2 分流、退出碼 1 回報「本專案未啟用 Swagger 文件，略過 API 文件稽核」並停止、退出碼 2 照三種原因回報並停止、列出稽核範圍（全專案控制器，或 `git diff` 指定的變更控制器）、`git diff` 失敗就原文回報 git 的 stderr 並停止、開兩個 sub agent 平行稽核兩個面向（面向 1 狀態碼與回應型別宣告、面向 2 描述與範例並遞迴走訪資料模型）、每個面向回傳六欄 TSV 或「無發現」、把兩個面向的 TSV 依序餵給 `tools/merge-findings.sh` 合併、依退出碼 0、1、2、3 分流、繁體中文逐列回報、跑 `jsc-hooks/hooks/write-guard.sh release` 解鎖、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-review:api-doc {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
|
||
| 外部呼叫 | `tools/swagger-detect.sh`、`tools/merge-findings.sh`、`jsc-hooks/hooks/write-guard.sh`（`review` 模式擋寫入工具、`release` 模式解鎖）、`jsc-hooks/tools/report-status.sh skill-end`（收尾狀態事件）、`git diff`、`references/smells.md` 的嚴重度分級、2 個稽核 sub agent。沒有 Gitea API 呼叫。 |
|
||
| 完成條件 | 偵測結果、範圍清單、兩個面向的回傳、合併結果四段都有結論。合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以腳本錯誤收尾。報告交給呼叫方，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路，修不修由呼叫方決定。收尾一定要寫一筆 `skill-end` 狀態事件：兩個面向都回來且合併清單交出去是 `ok`（`merge-findings.sh` 回 1 的「無發現」也是 `ok`，那是稽核過而沒東西可報），偵測不到 Swagger 而跳過是 `blocked`（偵測腳本回 2、`git diff` 被拒也歸這裡），解鎖沒清掉 `lastskill` 是 `degraded`，`merge-findings.sh` 回 2 或連兩次回 3 是 `failed`，控制器清單是空的、根本沒有可審的變更是 `aborted`。 |
|
||
| 可驗證跡象 | 不改任何程式碼。唯一的環境寫入是解鎖：`$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可以直接檢查該檔是否還在。舊版 `jsc-hooks` 不認得 `release`，該檔會留到逾時，這也是可檢查的狀態。另一個寫入跡象是狀態事件：跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-review:api-doc`，`status` 與 `exit` 兩欄對得上上一列講的判準；沒有 Swagger 那一輪看得到 `blocked`，沒有可審變更那一輪看得到 `aborted`，兩者和稽核過而無發現的 `ok` 一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。除這兩處外沒有寫入跡象，只有回報內容。 |
|
||
|
||
## code-review
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 觸發時機 | 一個檔案或一組相關檔案改完之後叫用，或工作包的所有待辦做完之後叫用。`jsc-sdlc:implement` 在工作包最後一項待辦之後、提交與開 PR 之前叫用它。資安、邏輯錯誤、測試涵蓋率不在範圍內，那些歸 CLI 內建審查。Swagger 文件稽核歸 `jsc-review:api-doc`，兩支技能不重複回報同一個缺口。 |
|
||
| 關鍵步驟 | 用一道指令把 `git diff`（未提交變更）或 `git diff {base}...HEAD`（比對基底分支）導進 `${TMPDIR:-/tmp}/jsc-code-review.$$.diff` 快照檔並印出展開後的路徑、git 非零退出碼就原文回報 stderr 並停止、快照檔空的就刪檔並回報「無發現」、開六個 sub agent 平行審查六組氣味（1 膨脹、2 晦澀、3 耦合、4 冗贅與其他、5 註解合約、6 淺模組）、六組都只讀步驟 1 的同一份快照、每組回傳六欄 TSV 或「無發現」、六組全數回傳後才把 TSV 依組序餵給 `tools/merge-findings.sh`、依退出碼 0、1、2、3 分流、繁體中文逐列回報、刪掉快照檔、跑 `jsc-hooks/hooks/write-guard.sh release` 解鎖、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-review:code-review {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
|
||
| 外部呼叫 | `git diff`、`tools/merge-findings.sh`、`jsc-hooks/hooks/write-guard.sh`（`review` 模式擋寫入工具、`release` 模式解鎖）、`references/smells.md`、`references/comment-scope.md`（第 2 組的禁列與允列來源）、`jsc-hooks/tools/report-status.sh skill-end`（收尾狀態事件）、6 個審查 sub agent。沒有 Gitea API 呼叫。 |
|
||
| 完成條件 | 六組全部回傳，合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以 git 或腳本的錯誤收尾。報告交給呼叫方，快照檔已刪除，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路。修不修由呼叫方決定，實作流程內高與中通常必修，低看情況。收尾一定要寫一筆 `skill-end` 狀態事件：六組都回來且合併清單交出去是 `ok`（`merge-findings.sh` 回 1 的「無發現」也是 `ok`），`git diff` 被拒、審查範圍根本建不出來是 `blocked`，快照檔沒刪掉或解鎖沒清掉 `lastskill` 是 `degraded`，`merge-findings.sh` 回 2 或連兩次回 3 是 `failed`，快照檔是空的、沒有可審的變更是 `aborted`。 |
|
||
| 可驗證跡象 | 不改任何程式碼。過程中產生 `${TMPDIR:-/tmp}/jsc-code-review.$$.diff` 快照檔，收尾時刪除，跑完該檔不應該還在，殘留就代表沒收尾。解鎖後 `$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可直接檢查。第三個檔案跡象是狀態事件：跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-review:code-review`，`status` 與 `exit` 兩欄對得上上一列講的判準；空 diff 那一輪看得到 `aborted`，和六組審完而無發現的 `ok` 一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。除這三個檔案狀態外沒有寫入跡象，只有回報內容。 |
|
||
|
||
## comment-cleanup
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 觸發時機 | 使用者要求清註解、移除審查痕跡、不要留審查產物時叫用。提交前 `jsc-hooks` 回報註解範圍警告時叫用，或變更的註解明顯帶著流程細節時叫用。預設只處理這次變更碰到的註解，使用者明講要清舊註解才擴大範圍。 |
|
||
| 關鍵步驟 | 在待清的儲存庫內跑 `tools/changed-comments.sh` 取得範圍（不帶參數看未提交變更，帶 `{base}` 比對基底分支）、依退出碼 0、1、2 分流、退出碼 1 回報「無發現」並停止、退出碼 2 原文回報 stderr 並停止且不手讀 diff 代替、一個檔案開一個 sub agent 平行改寫、每個 sub agent 拿到自己的檔案路徑與該檔的註解列並比對 `references/comment-scope.md`、移除流程細節並保留程式碼存在的理由、只剩流程細節的註解整段刪除、每個 sub agent 回傳前重讀自己改過的區域確認句子完整且沒有殘句、只改註解與文件字串不動行為、全部 sub agent 回傳後跑一次最小的建置或測試指令、失敗就判斷是否本輪造成並依規則重跑一次或還原、依類別回報清理結果、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-review:comment-cleanup {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
|
||
| 外部呼叫 | `tools/changed-comments.sh`、`references/comment-scope.md`、專案自己的建置或測試指令（沒有就改跑受影響腳本的語法檢查）、`git diff`、每個檔案一個改寫 sub agent。這支技能不呼叫 `jsc-hooks/hooks/write-guard.sh`，也不在它的 `review` 模式擋下範圍內：那支腳本的檔頭寫明 comment-cleanup 一律放行，因為精確判定註解列要解析整份新內容再逐語言判斷，判錯會擋掉合法清理。寫入範圍改由步驟 4 與後續審查把關。收尾另外呼叫 `jsc-hooks/tools/report-status.sh skill-end` 寫狀態事件。沒有 Gitea API 呼叫。 |
|
||
| 完成條件 | 範圍內每一列註解都有結果：維持原樣並說明理由、改寫、或刪除。每個 sub agent 都確認過自己的檔案且沒有未解決的殘句。`git diff` 只顯示註解與文件字串的變更。驗證指令退出碼 0，或報告寫明指令、退出碼與失敗歸屬，或寫明缺哪一個指令。報告說明移除了哪些類別、動了哪些檔案、驗證有沒有過。收尾一定要寫一筆 `skill-end` 狀態事件：範圍內每一列都有結果且驗證退出碼 0 是 `ok`，`changed-comments.sh` 回 2 讓範圍算不出來、什麼都沒改是 `blocked`，改完了但沒有驗證指令可跑、失敗判給既有問題、或有殘句沒解決是 `degraded`，驗證失敗歸本輪且重跑一次仍失敗而還原了該檔是 `failed`，`changed-comments.sh` 回 1 代表這次變更沒動到任何註解、沒有可清的東西，是 `aborted`。 |
|
||
| 可驗證跡象 | 這是三支技能裡唯一會改檔的。跑完在工作區留下實際的檔案修改，`git diff` 看得到被清理的註解列，且變更只涵蓋註解與文件字串，不涉及識別字、控制流程、資料結構。還原情境下 `git diff` 會看到該檔的本輪修改被撤回。跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-review:comment-cleanup`，`status` 與 `exit` 兩欄對得上上一列講的判準；沒有註解可清那一輪看得到 `aborted`，還原那一輪看得到 `failed`，兩者和清乾淨的 `ok` 一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。除這一筆事件外，不寫 wiki 頁、不開 PR、不改其他狀態檔。 |
|