diff --git a/docs/design/09-rebuttal-and-goal-gate.md b/docs/design/09-rebuttal-and-goal-gate.md new file mode 100644 index 0000000..2d7f115 --- /dev/null +++ b/docs/design/09-rebuttal-and-goal-gate.md @@ -0,0 +1,200 @@ +# #09 Rebuttal 流程自动化 + 目标一致性 Gate + +> 版本: v1.0 +> 日期: 2026-06-03 +> 作者: 庞统(副军师) +> 状态: 待评审 +> 前置: #04 黑板协作(@mention)+ #08 Classify Outcome +> 关联: T4 审查体系完善 + +--- + +## 一、问题陈述 + +### 1.1 Rebuttal 缺失 + +当前审查流程: + +``` +Agent 完成 → review → 司马懿审查 → verdict(approved/rejected/needs_revision) → 结束 +``` + +**问题**:审查结论是单方面的。Agent 对 rejected/needs_revision 没有反驳渠道。尤其是: +- 复杂设计方案,司马懿可能误判 +- 需求降级场景,agent 认为自己做了正确的事但被 reviewer 要求改回去 +- 没有 1-2 轮辩论,结论质量无法保证 + +**已有基础**: +- `RebuttalManager` 类已实现(2 轮反驳,round 1→司马懿重审,round 2→庞统仲裁) +- `comment_type` 支持 `rebuttal`、`rebuttal_response`、`debate_argument` 等 +- `reviews` 表结构完整 + +**缺什么**:ticker/dispatcher 层面没有自动串联 rebuttal 流程。`submit_rebuttal` 存在但无人调用。 + +### 1.2 目标一致性 Gate + +当前 agent 遇到需求不清晰时: +- executor prompt 说"不确定时停下来问(黑板 comment)" +- @mention 机制可以把庞统 spawn 起来 + +**缺什么**: +1. executor/reviewer prompt 没有明确指引"需求不清晰时 @pangtong-fujunshi 提问" +2. 庞统收到提问时,没有注入原始任务目标和验收标准来校准回答 +3. 庞统的回复可能无意中做了需求降级("这个太复杂了,简化一下吧") + +--- + +## 二、设计方案 + +### 2.1 Rebuttal 自动化流程 + +#### 流程图 + +``` +Agent 完成任务 → review + → 司马懿审查 → verdict + ├─ approved → done(无争议) + ├─ rejected/needs_revision → 通知被审 agent + │ → Agent 选择: + │ ├─ 接受 verdict → 按 verdict 修改 → 重新提交 review + │ └─ 反驳 → submit_rebuttal(黑板 comment_type=rebuttal) + │ → Ticker 检测到 rebuttal → spawn 司马懿重审(round 2) + │ ├─ 司马懿改判 → done/needs_revision + │ └─ 司马懿坚持 → 通知庞统仲裁(round 3,最终轮) + │ → 庞统裁决 → done/needs_revision/创建新任务 + └─ (rebuttal 最多 2 轮,超限庞统最终裁决) +``` + +#### 触发机制 + +**关键设计决策:谁触发 rebuttal?** + +不是 daemon 自动触发,而是 **agent 自主选择**。流程: + +1. 司马懿审查完成 → verdict 写入 reviews 表 + comment_type=review +2. Ticker 检测到新 review verdict → 通知被审 agent(@mention agent) +3. Agent 看到 verdict + 自己的产出 → 决定接受或反驳 +4. 如果反驳 → agent 写 comment_type=rebuttal + @simayi-challenger +5. Ticker 的 mention 处理循环 spawn 司马懿重审 +6. 司马懿重审后如果坚持 → @pangtong-fujunshi 请求仲裁 +7. 庞统仲裁 → 最终结论 + +**这个流程几乎不需要新代码**——主要靠 @mention 现有机制 + prompt 引导。 + +#### 需要改的代码 + +| 文件 | 改动 | 说明 | +|------|------|------| +| `ticker.py` `_handle_review_conclusion` | 修改 | verdict 非 approved 时 @mention 被审 agent | +| `prompt_templates/reviewer.md` | 修改 | 加入 rebuttal 流程指引 | +| `prompt_templates/executor.md` | 修改 | 加入"需求不清晰时 @pangtong-fujunshi 提问" | +| `prompt_templates/review_pangtong.md` | 修改 | 加入仲裁指引 + 目标一致性检查 | + +#### _handle_review_conclusion 改动细节 + +当前逻辑: +```python +if is_achieved: + # GOAL_ACHIEVED → done +else: + # continue → working +``` + +这是庞统 round review 的处理。需要区分两个场景: +1. **庞统 round review**(现有)— 检查全局目标 +2. **司马懿 code review**(新增)— verdict 非 approved 时通知 agent + +对于场景 2,不在 `_handle_review_conclusion` 里处理(那是庞统 round review 的回调),而是在 dispatcher 的 review task dispatch 流程中: + +``` +review task → spawn 司马懿 → 司马懿完成 → classify outcome + → verdict 写入 reviews 表 + → 如果 verdict != approved → 写 comment @被审agent 通知 + → 被审 agent 自主决定接受或反驳 +``` + +**实现位置**:dispatcher 中 review task 的 on_complete 回调。 + +#### 防止无限循环 + +- RebuttalManager.MAX_ROUNDS = 2(已有) +- 超过 2 轮 → 庞统最终裁决 +- 每个 review 记录在 reviews 表中,rebuttal_count 可追溯 + +### 2.2 目标一致性 Gate + +#### Agent 端 + +**executor.md 改动**: + +在"工作方式"和"约束"之间新增一节: + +```markdown +## 需求不清晰时的处理 +- 任务描述有歧义、验收标准不明确、多个理解方式 → @pangtong-fujunshi 提问 +- 不要自行假设。宁可多问一句,也不要做错方向 +- 提问时:列出你的理解、可能的选项、你倾向的方案,让庞统确认 +- 庞统回复后,以回复为准继续执行 +``` + +#### 庞统端 + +**review_pangtong.md 改动**: + +新增"代理提问处理"部分: + +```markdown +## 回答 Agent 提问时的原则 +- 对照原始任务目标和验收标准回答,不做需求降级 +- 如果 agent 觉得目标太难 → 讨论替代方案,但必须说清楚代价(缩小的范围、降低的质量) +- 如果原始目标确实不可行 → 升级用户,不要自己做主降级 +- 回答要具体到可操作,不要给模糊方向 +``` + +#### Bootstrap 注入 + +当庞统被 @mention spawn 回答问题时,bootstrap 已经会注入任务上下文(#05 L2 层)。不需要额外改动。 + +### 2.3 司马懿 Rebuttal 处理 + +**reviewer.md / review_simayi.md 改动**: + +```markdown +## Rebuttal 处理 +- 被反驳时,重新审视自己的结论 +- 如果 agent 的反驳有理有据 → 改判 +- 如果坚持原判 → 给出更具体的理由,不要只说"我认为不行" +- Rebuttal 不是对抗,是共同追求正确答案 +- 第 2 轮 rebuttal 如果仍无法达成一致 → @pangtong-fujunshi 请求仲裁 +``` + +--- + +## 三、改动总览 + +| 文件 | 改动 | 行数 | +|------|------|------| +| `src/daemon/ticker.py` | review verdict 非 approved 时 @mention 被审 agent | ~15 行 | +| `prompt_templates/executor.md` | 新增"需求不清晰时 @pangtong-fujunshi" | ~8 行 | +| `prompt_templates/reviewer.md` | 新增 rebuttal 处理指引 | ~8 行 | +| `prompt_templates/review_pangtong.md` | 新增仲裁指引 + 反需求降级 | ~10 行 | +| `prompt_templates/review_simayi.md` | 新增 rebuttal 处理指引 | ~8 行 | +| **净增** | | **~49 行** | + +--- + +## 四、验收标准 + +1. 司马懿审完 rejected/needs_revision → 自动 @mention 被审 agent +2. Agent prompt 明确引导"需求不清晰 → @pangtong-fujunshi" +3. 庞统回复时对照原始目标,不做需求降级 +4. Rebuttal 最多 2 轮,超限庞统裁决 +5. 现有测试不 regression + +--- + +## 五、不做的事 + +- 不做 daemon 层面的自动 rebuttal 触发(靠 agent 自主 + @mention) +- 不做专门的 rebuttal API 端点(复用 comment + mention) +- 不做 rebuttal 状态机扩展(复用 RebuttalManager 已有逻辑)