设计 code-bee 的 coder-reviewer loop 契约与兜底规则

[JiGuangWorker]

背景

code-bee 的核心不是替智能体理解需求，而是作为外层 loop orchestrator，在编码智能体与审查智能体之间持续调度，直到任务满足 Issue 要求后结束。

因此，必须定义一套明确的 loop 契约，确保：

• 不能只凭编码智能体“自认为完成”就结束
• 必须由审查智能体确认是否满足要求
• 当无法确认是否满足要求时，系统有清晰的兜底规则，而不是误判通过或无限空转

目标

为 code-bee 设计一套最小可执行的双角色循环契约：

1. code-bee 调度 编码智能体 -> 审查智能体
2. 编码智能体负责开发、修复、补证据
3. 审查智能体负责判断当前结果是否满足 Issue 要求
4. 只有审查结果明确通过，loop 才能结束
5. 如果无法确认，则进入补证据或人工接管兜底

角色职责

1. code-bee

• 负责外层 loop
• 负责在编码智能体和审查智能体之间切换
• 负责解析结构化回报
• 负责决定继续、结束或转人工

2. 编码智能体

• 查看 Issue
• 完成开发、修复、自验
• 产出结构化回报
• 在审查失败或不确定时补实现或补证据

3. 审查智能体

• 根据 Issue 要求审查当前结果
• 判断是否满足验收标准
• 判断缺失的是实现还是证据
• 输出结构化审查结果

最小状态机

CODER -> REVIEWER -> PASS => EXIT
CODER -> REVIEWER -> FAIL => 回到 CODER
CODER -> REVIEWER -> UNKNOWN => 回到 CODER 补证据
CODER -> REVIEWER -> BLOCKED => 停止自动循环，进入人工介入

契约

1. 编码智能体回报契约

编码智能体每轮必须返回结构化结果，至少包含：

• STATUS: DONE | IN_PROGRESS | BLOCKED
• SUMMARY: 本轮完成内容
• EVIDENCE: 当前可验证证据
• ACCEPTANCE_CHECK: 按验收标准逐条自验
• NEXT_ACTION: 下一步动作

2. 审查智能体回报契约

审查智能体每轮必须返回结构化结果，至少包含：

• STATUS: PASS | FAIL | UNKNOWN | BLOCKED
• SUMMARY: 审查结论总结
• CHECK_RESULT: 按验收标准逐条判断结果
• MISSING: 当前缺失项
• NEXT_ACTION: 下一轮对编码智能体的要求

退出规则

loop 仅在以下条件同时满足时结束：

• 审查智能体返回 PASS
• 验收项已被逐条覆盖
• 存在最小可验证证据

如果审查结果不是明确 PASS，loop 不能结束。

证据要求

“完成”必须可验证，不能只靠主观声明。最小证据可包括：

• 代码改动
• 测试 / lint / build 结果
• PR / commit / issue comment 记录
• 验收项与实现结果的逐条映射

兜底规则

1. 不确定不算通过

• UNKNOWN 不能视为 PASS

2. UNKNOWN 进入补证据

• 如果审查智能体无法确认是否满足要求，下一轮优先补证据，而不是盲目继续改代码

3. 连续不确定触发人工兜底

建议第一版规则：

• 连续 2 次 UNKNOWN：强制进入证据补全模式
• 连续 3 轮仍未 PASS：输出 MANUAL_REQUIRED

4. BLOCKED 立即停止自动循环

出现以下情况时，应停止自动循环并转人工：

• 权限不足
• 环境缺失
• 依赖外部信息但无法自动获取
• 审查无法继续推进

验收标准

• code-bee 采用 编码智能体 -> 审查智能体 的双角色 loop
• loop 的退出条件是审查智能体返回 PASS，而不是编码智能体自报完成
• FAIL / UNKNOWN / BLOCKED 三种状态有明确区分和后续动作
• UNKNOWN 不会被误判为通过
• 系统具备连续不确定时的兜底规则
• 系统具备自动循环失败后的人工接管出口