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/* 格式的 slug），则将用户指定的 model slug 传递给 spawn_subagent。
• 增量关闭（resume_from）：
  • 发现（第 1 轮）：使用最小工件（计划、git diff、测试代码 + 执行 stdout/stderr）和关键文件路径启动新子智能体——切勿传递你的对话历史。
  • 关闭（第 2 轮及以上，如果需要修复或额外测试）：为每个审查者调用 spawn_subagent，带上 resume_from: "<subagent_id>"，仅传递活动发现和修复/测试增量，使其验证更新而无需重新读取未更改的文件。

2. 核心职责边界

1. 主要智能体先运行验证：在分派审查者之前，鼓励运行快速语法/冒烟测试，以免审查者在不合格的语法上浪费精力。将你的确切测试命令和输出作为“主要智能体验证证据”传递。
2. 严格的只读审查者：指示审查子智能体仅读取/搜索文件，以 file:line 证据报告按严重性排序的发现，并在需要运行时证据证明未测试的边缘情况时发出 - Validation request: <精确检查项>。审查者从不编辑文件或运行命令。
3. 主要智能体裁决：在编辑之前等待所有启动的审查者完成。独立重现候选 bug，运行有效的“验证请求”，并进行裁决（accepted（接受） / rejected（拒绝）并附上具体代码或数学证据）。

---

模式 A：计划审查（独立）

1. 准备：陈述目标、要接触的文件、张量形状/数据流，以及显式假设（任何影响训练语义、奖励规模或基线公平性的未说明选择）。
2. 提示审查者：

   “以只读方式审查这个研究计划。不要编辑文件或运行命令。质疑未说明的假设，检查数据/标签泄漏、基线不公平性以及分布式/回滚瓶颈。声明 Review coverage: FULL|PARTIAL - <检查过的文件>，并以 Review verdict: APPROVED|FINDINGS 结束。[插入计划与关键文件路径]”

模式 B：编码审查（独立——当尚未编写测试时）

1. 准备：收集需求/计划摘要和 git diff。
2. 提示审查者：指示他们以只读方式检查已更改的文件和一跳调用者，寻找沉默的研究 bug：
   • 掩码与对齐：SFT/RL 提示 vs. 响应令牌掩码的 off-by-one 错误、填充侧不匹配或 EOS/截断处理。
   • 张量形状与广播：意外的广播（例如 (B, 1) vs (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. 提示审查者：

   “以只读方式联合审查实现 diff 和主要智能体的自测。不要编辑文件或运行命令。

   1. 代码检查：在更改的文件和一跳调用者中搜寻沉默的研究 bug（令牌掩码 off-by-one、填充/EOS 对齐、意外的张量广播 (B,1) vs (B,)、错误的降维、错误放置的 detach()/no_grad()、KL/优势数学、未重置的回滚状态）。
   2. 自测审计：检查主要智能体的测试是否真正验证了这些不变量和边缘情况，或者是否遭受确认偏差（仅测试快乐路径、模拟掉核心逻辑或弱断言）。为任何缺失的边缘情况测试发出 - Validation request: <精确检查项>。 声明 Review coverage: FULL|PARTIAL - <检查过的文件>，并以 Review verdict: APPROVED|FINDINGS 结束。”

3. 裁决与关闭：修复已接受的代码 bug 并满足有效的“验证请求”；如果进行了非平凡的更改，则在两个审查者上使用 resume_from 来验证增量。

---

3. 轻量级台账 (docs/review-log.md)

每次审查关卡完成后，将一条简洁的 5-10 行英文条目追加到当前项目的 docs/review-log.md 中（如果文件不存在则创建）。这可以在上下文压缩时保留 subagent_id 句柄，并维护实验审计线索：

## [YYYY-MM-DD] <简短任务标题>（<模式 A / B / C / B+C>）
- **假设 / 范围**：<1 行关键设计假设和涉及的文件摘要>
- **审查者**：`deepseek-v4.1-flash`（`id: <subagent_id>`），`glm-5.3`（`id: <subagent_id>`）
- **裁决**：
  - `[ACCEPTED]` `<file:line>` — <简洁的 bug/缺陷及其修复方式>
  - `[REJECTED]` `<file:line>` — <审查者发现为何是误报，附上数学/代码证据>
- **结论与证据**：`APPROVED`（<1 行测试/冒烟验证结果>）