jzjizhe/research-review

研究審查（模組化與組合審查閘門）

計劃、編碼和測試可以獨立執行或組合執行：

• 如果您只做了計劃，請執行模式 A（計劃審查）。
• 如果您編寫了程式碼並立即編寫/執行了測試（自然的流程），請執行模式 B+C 組合（程式碼與測試聯合審查），在單一平行審查回合中完成——不要浪費時間連續啟動兩個獨立的審查回合。
• 如果您只編寫了程式碼而沒有測試，或只針對現有程式碼編寫/執行了測試，請分別執行模式 B 或模式 C。

1. 審查者子代理調度 (spawn_subagent)

• 預設審查者 (channel=mcli)：同時呼叫 spawn_subagent 啟動兩個平行審查者，並透過 get_command_or_subagent_output 等待兩者完成：
  • 子代理 1：model: "deepseek-v4.1-flash" (mcli 頻道)
  • 子代理 2：model: "glm-5.3" (mcli 頻道)
• 使用者覆寫：如果使用者指定了其他模型（例如 kimi-k3.1-pro、MiniMax-M3.1-Flash、deepseek-v4-pro 或 friday/* / catpaw-ide/* 格式），則將使用者指定的 model 傳遞給 spawn_subagent。
• 增量閉合 (resume_from)：
  • 發現（第 1 回合）：使用最低限度的產出（計劃、git diff、測試程式碼 + 執行 stdout/stderr）和關鍵檔案路徑啟動全新的子代理——切勿傳遞您的對話歷史。
  • 閉合（第 2 回合以上，如果需要修正或額外測試）：為每個審查者呼叫帶有 resume_from: "<subagent_id>" 的 spawn_subagent，僅傳遞活躍的發現和修正/測試差異，以便他們驗證更新而無需重新讀取未變更的檔案。

2. 核心角色邊界

1. 主代理先執行驗證：鼓勵在調度審查者之前執行快速的語法/冒煙測試，以免審查者在破碎的語法上浪費精力。將您的確切測試命令和輸出作為 主代理驗證證據 傳遞。
2. 嚴格的唯讀審查者：指示審查者子代理僅讀取/grep 檔案，報告帶有 file:line 證據的按嚴重性排序的發現，並在未經測試的邊界情況需要運行時證明時發出 - Validation request: <exact check>。審查者從不編輯檔案或執行命令。
3. 主代理裁決：在所有啟動的審查者完成後再進行編輯。獨立重現候選錯誤，執行有效的 Validation requests，並（接受 / 拒絕）並附上具體程式碼或數學證據進行裁決。

---

模式 A：計劃審查（獨立）

1. 準備：說明目標、要觸及的檔案、張量形狀/資料流以及明確的假設（任何影響訓練語義、獎勵尺度或基線公平性的未陳述選擇）。
2. 提示審查者：

   "對這個研究計劃進行唯讀審查。請勿編輯檔案或執行命令。質疑未陳述的假設，檢查資料/標籤洩漏、基線不公平性以及分散式/推出瓶頸。最後請聲明 Review coverage: FULL|PARTIAL - <已檢查的檔案> 並以 Review verdict: APPROVED|FINDINGS 結束。 [插入計劃和關鍵檔案路徑]"

模式 B：編碼審查（獨立——當尚未撰寫測試時）

1. 準備：收集需求/計劃摘要和 git diff。
2. 提示審查者：指示他們以唯讀方式檢查已變更的檔案和一跳呼叫者，尋找隱藏的研究錯誤：
   • 遮罩與對齊：SFT/RL 提示與回應令牌遮罩的 off-by-one 錯誤、填充側不匹配或 EOS/截斷處理。
   • 張量形狀與廣播：非預期的廣播（例如 (B, 1) 與 (B,)）、歸約維度錯誤（在序列 vs. 批次上進行 mean/sum）。
   • 梯度與狀態衛生：錯誤放置的 detach()/no_grad()、KL 方向、優勢標準化範圍或跨推出的未重設代理環境狀態。
   • 要求提供 Review coverage 和 Review verdict: APPROVED|FINDINGS。

模式 C：測試審查（獨立——當為現有程式碼新增/稽核測試時）

1. 準備：收集測試檔案路徑、目標模組路徑以及實際的測試執行 stdout/stderr。
2. 提示審查者：

   "對這個測試及其執行輸出進行唯讀稽核。請勿編輯檔案或執行命令。它是否真正驗證了核心數學/張量不變量和邊界情況，或者它是否透過模擬來繞過實際邏輯/削弱斷言以通過測試？如果某個邊界情況未經測試，請發出 - Validation request: ...。請聲明 Review coverage 並以 Review verdict: APPROVED|FINDINGS 結束。"

模式 B+C：聯合編碼與測試審查（當主代理在一次操作中編碼並自我測試時）

1. 準備：打包需求/計劃摘要、實現 + 測試 git diff 以及 主代理驗證證據（確切的測試命令及其 stdout/stderr）。
2. 提示審查者：

   "對實現差異和主代理的自我測試進行唯讀聯合審查。請勿編輯檔案或執行命令。

   1. 程式碼檢查：在已變更的檔案和一跳呼叫者中尋找隱藏的研究錯誤（令牌遮罩 off-by-one、填充/EOS 對齊、非預期的張量廣播 (B,1) 與 (B,)、錯誤的歸約維度、錯誤放置的 detach()/no_grad()、KL/優勢數學、未重設的推出狀態）。
   2. 自我測試稽核：檢查主代理的測試是否真正驗證了這些不變量和邊界情況，或者它是否存在確認偏差（僅測試快樂路徑、模擬核心邏輯或使用薄弱斷言）。對於任何缺失的邊界情況測試，請發出 - Validation request: <exact check>。 請聲明 Review coverage: FULL|PARTIAL - <已檢查的檔案> 並以 Review verdict: APPROVED|FINDINGS 結束。"

3. 裁決與閉合：修正已接受的程式碼錯誤並履行有效的 Validation requests；如果進行了非微不足道的變更，則對兩位審查者使用 resume_from 來驗證差異。

---

3. 輕量級帳本 (docs/review-log.md)

每次審查閘門完成後，在當前專案的 docs/review-log.md 中附加一個簡潔的 5–10 行英文條目（如果檔案不存在則建立）。這可以在上下文壓縮後保留 subagent_id 句柄，並維護實驗稽核軌跡：

## [YYYY-MM-DD] <簡短任務標題> (<模式 A / B / C / B+C>)
- **假設 / 範圍**：<關鍵設計假設和觸及檔案的一行摘要>
- **審查者**：`deepseek-v4.1-flash` (`id: <subagent_id>`)、`glm-5.3` (`id: <subagent_id>`)
- **裁決**：
  - `[ACCEPTED]` `<file:line>` — <簡潔的錯誤/缺陷以及如何修正>
  - `[REJECTED]` `<file:line>` — <為什麼審查者的發現是誤報，附上數學/程式碼證據>
- **判決與證明**：`APPROVED` (<一行測試/冒煙驗證結果>)