Review Panel（评审团）

通过多agent角色协作，对方案进行结构化评审，克服单AI决策的确认偏误和视角盲区。

核心设计理念

角色分离：主agent在"执行者"和"法官"之间切换，避免自我确认
独立质疑：两个挑战者相互隔离，确保质疑的独立性和多样性
群体评分：评委可讨论但独立打分，提供多维度量化参考
过程透明：最终报告包含所有原始材料，用户可见完整辩论过程
文件持久化：所有产出物以文件形式落盘，子agent按需读取，避免prompt膨胀
Skill可组合：评审团是协作框架，不排斥外部skill。主agent在执行阶段应主动发现并使用相关skill；用户明确指定skill时优先遵从

文件持久化机制

目录结构

.codebuddy/review-panel/{task-name}/
├── scheme.md              # 方案全文（简单方案单文件）
├── scheme/                # 复杂方案拆分目录（与scheme.md二选一）
│   ├── overview.md        # 方案总览（入口文件）
│   ├── architecture.md    # 架构设计
│   ├── api-design.md      # 接口设计
│   └── ...                # 按需拆分
├── code-context.md        # 代码上下文索引
├── design-decisions.md    # 设计决策记录
├── challenger-output/          # 挑战者产出
│   ├── challenger-a.md
│   └── challenger-b.md
├── judge-output/          # 评委产出
│   ├── judge-1.md
│   ├── judge-2.md
│   └── judge-3.md
└── final-report.md        # 最终评审报告

规则

简单方案 → 单文件 scheme.md
复杂方案 → 拆分到 scheme/ 目录，overview.md 为入口
主agent自行判断复杂度选择方式
文件不自动删除，保留为评审过程的完整记录，供用户随时查阅

task-name 命名规则

英文小写 + 短横线，从任务描述中提取 2-4 个关键词
示例：jwt-auth-review、user-api-refactor、payment-flow-design
总长度 ≤ 64 字符
如遇同名目录，追加 -v2 后缀

信息分层传递原则

层级	内容	传递方式
第一层	方案全文、设计决策	文件落盘 → 子agent按需读取
第二层	代码上下文索引（路径+摘要）	文件落盘 → 子agent按需读取，需要时再read_file具体代码
第三层	具体代码实现	子agent根据索引自行读取，不在文件中展开

评审团完整流程

用户提出任务
    │
    ▼
【阶段0：Skill发现】（可选）
    │  用户是否指定了skill？
    │  ├── 是 → 直接加载指定skill
    │  └── 否 → 若任务是编写设计方案且检测到 `design-doc-generator`，默认加载该skill
    │       ├── 是 → 按其规范执行
    │       └── 否 → 主agent扫描可用skill列表，判断是否有相关skill
    │            ├── 有 → 加载相关skill，按其规范执行
    │            └── 无 → 正常进入阶段1
    │
    ▼
【阶段1：执行】主agent（执行者模式）
    │  自由创建子agent完成任务（如已加载skill则在其规范下执行）
    │  产出文件：
    │  ├── scheme.md（或scheme/目录）
    │  ├── code-context.md
    │  └── design-decisions.md
    │
    ▼
【阶段2：质疑】主agent角色转换 → 法官模式
    │  创建团队，并行启动两个挑战者
    │  prompt只含文件路径列表
    │
    ├─→ [挑战者A] 读取文件 → 独立质疑 → 写入 challenger-a.md
    └─→ [挑战者B] 读取文件 → 独立质疑 → 写入 challenger-b.md
        （两者相互隔离，看不到对方的输出）
    │
    ▼
【阶段3：评分】主agent启动评委团
    │  prompt含方案+索引+决策+挑战者产出的文件路径列表
    │  评委需要打分 + 提出改进建议（复杂度、性能、正确性、合理性、安全、目标一致性）
    │
    ├─→ [评委1] 读取文件 → 打分 + 改进建议 → 写入 judge-1.md
    ├─→ [评委2] 读取文件 → 打分 + 改进建议 → 写入 judge-2.md ─┐
    └─→ [评委3] 读取文件 → 打分 + 改进建议 → 写入 judge-3.md ─┤ 可讨论
    │
    ▼
【阶段4：研判】主agent（法官模式）
    │  读取所有产出文件 → 判断是否需要迭代改进
    │  ├── 需要修改 → 修改方案 → 创建挑战者重新评估 → 回到阶段2（最多3次）
    │  ├── 不需要修改 → 记录原因 → 进入阶段5
    │  └── 拿不定主意 → 记录原因 → 进入阶段5
    │
    ▼
【阶段5：输出】完整评审报告交付用户（包含迭代记录）
    │  文件保留在 .codebuddy/review-panel/{task-name}/ 供查阅

阶段0：Skill发现与选择（可选，阶段1前执行）

主agent检查用户是否明确指定了要使用的skill（如"用design-doc-generator写设计文档"）
- 用户指定 → 直接调用 use_skill 加载指定skill，按其规范执行
- 用户未指定 → 若当前任务是编写设计方案/设计文档，则优先检查当前可用skill列表中是否存在 design-doc-generator
  - 检测到 design-doc-generator → 默认调用 use_skill 加载该skill，按其规范产出方案
  - 未检测到 design-doc-generator → 忽略该默认规则，继续扫描当前可用skill列表（<available_skills> 中列出的skill），根据任务描述判断是否存在其他相关skill
    - 发现相关skill → 调用 use_skill 加载，在其规范指导下产出方案
    - 无相关skill → 正常进入阶段1
注意：此步骤仅主agent执行，子agent（挑战者/评委）不涉及skill调用

阶段1：执行——主agent自由产出方案V0

主agent以执行者身份完成任务，可自由创建任意数量子agent辅助
不限制角色、不限制方式，目标是产出高质量方案
产出文件（必须写入磁盘）：
- scheme.md（或 scheme/ 目录）：方案全文
- code-context.md：代码上下文索引
- design-decisions.md：设计决策记录
主agent在执行过程中每查阅一个代码文件，顺势将路径和摘要记录到 code-context.md，避免事后回忆遗漏
完成后，主agent身份切换为法官，进入阶段2

scheme.md 建议结构（非强制，主agent根据任务调整）：

# {任务名称} 方案

## 背景与目标
## 方案概述
## 详细设计
## 技术选型与决策
## 风险与应对
## 实施计划

code-context.md 格式：

# 代码上下文索引

| 文件/模块 | 关键信息摘要 | 评审相关度 |
|-----------|-------------|-----------|
| src/api/user.py | 用户认证接口，JWT签发逻辑 | 高 |
| src/middleware/auth.py | 鉴权中间件，token校验 | 高 |
| src/models/user.py | User模型定义 | 中 |
| src/config.py | 配置项，含token过期时间 | 低 |

design-decisions.md 格式：

# 设计决策记录

- 为什么选JWT而非Session：[原因]
- 为什么token过期时间设30分钟：[原因]
- 为什么不用OAuth2：[原因]

阶段2：质疑——双挑战者独立审查

角色定位：挑战者是"严谨的挑战者"，不是"杠精"。目标是找出方案的不合理之处，而非无差别攻击。

补充职责：挑战者除了指出问题，也应主动补充自己认为值得纳入评审的遗漏场景、边界情况、异常路径、运行环境差异、用户行为分支、兼容性约束等内容。即使某点暂不足以构成反对意见，只要会影响方案完备性，也应明确提出。

创建方式：使用 team_create 创建评审团队，然后用 Task 并行启动两个挑战者子agent。

信息传递（主agent → 挑战者prompt）：

你作为挑战者（Challenger Reviewer），你的职责是：
1. 竭尽全力找出方案中的不合理之处、漏洞、风险
2. 每条反对意见必须附带推理链条，说明"为什么不好"
3. 每条反对意见必须给出对应的替代方案
4. 也必须列出你对原方案的认可点
5. 主动补充你认为当前方案遗漏但值得评审的场景、边界情况、异常路径、用户行为分支、兼容性约束或运行环境差异
请先读取以下文件，然后进行审查：

| 文件 | 内容说明 | 优先级 |
|------|----------|--------|
| .codebuddy/review-panel/{task-name}/scheme.md | 方案全文 | 必读 |
| .codebuddy/review-panel/{task-name}/code-context.md | 代码上下文索引 | 必读 |
| .codebuddy/review-panel/{task-name}/design-decisions.md | 设计决策记录 | 必读 |

如方案拆分为目录，请先读取 scheme/overview.md 了解全貌，再按需深入各子文件。
如需查看具体代码，根据 code-context.md 中的路径自行读取。

请将审查结果写入：.codebuddy/review-panel/{task-name}/challenger-output/challenger-a.md

挑战者产出格式（写入文件）：

## 反对意见

### 意见1：[标题]
- 反对理由：（推理链条，为什么这是个问题，什么场景下会暴露）
- 严重程度：🔴 致命 / 🟡 重要 / 🟢 建议
- 替代方案：（针对此条的具体替代做法）

### 意见2：[标题]
- 反对理由：...
- 严重程度：...
- 替代方案：...

## 认可点
- （方案中做得好的方面，至少1条）

## 补充场景与情况
- （补充当前方案尚未充分覆盖、但值得纳入评审或设计考虑的场景/情况）

## 整体替代方案（可选）
（仅当你认为整个方案方向有问题时，才提出完整替代方案）

约束：

挑战者A和挑战者B相互完全隔离，不知道对方的存在和输出
两条反对意见中如果出现了相同的点，说明问题严重，在最终报告中需高亮为"共识性反对"

阶段3：评分——三评委独立打分 + 讨论 + 改进建议

角色定位：评委是"公正的评估者"，综合考虑原始方案和各反对意见后给出量化评价，并提出改进建议。

补充职责：评委在评分过程中，也应主动指出自己认为还应补充的场景、边界情况、异常路径、依赖约束、兼容性问题或实施注意事项；这些补充不要求都上升为扣分项，但必须作为评审输入明确表达。

创建方式：用 Task 并行启动3个评委子agent，同属一个team。

信息传递（主agent → 各评委prompt）：

你作为评委（Judge），请对方案和反对意见进行评审。
你可以与其他评委讨论，但最终打分由你独立决定。

请先读取以下文件：

| 文件 | 内容说明 | 优先级 |
|------|----------|--------|
| .codebuddy/review-panel/{task-name}/scheme.md | 原始方案全文 | 必读 |
| .codebuddy/review-panel/{task-name}/code-context.md | 代码上下文索引 | 必读 |
| .codebuddy/review-panel/{task-name}/design-decisions.md | 设计决策记录 | 必读 |
| .codebuddy/review-panel/{task-name}/challenger-output/challenger-a.md | 挑战者A完整审查意见 | 必读 |
| .codebuddy/review-panel/{task-name}/challenger-output/challenger-b.md | 挑战者B完整审查意见 | 必读 |

如需查看具体代码，根据 code-context.md 中的路径自行读取。

评分维度（1-5分）：
- 可行性：方案在技术上是否可实现？（1=不可行，5=完全可行）
- 风险覆盖：方案是否覆盖了主要风险点？（1=风险敞口大，5=风险可控）
- 完整性：方案是否覆盖了所有场景和边界情况？（1=遗漏严重，5=覆盖全面）
- 采纳度：方案对挑战者合理意见的采纳程度？（1=完全不采纳，5=充分采纳）

改进建议维度：
- 复杂度：方案是否过于复杂？能否简化？
- 性能：方案是否有性能瓶颈？能否优化？
- 正确性：方案是否存在逻辑错误或边界条件遗漏？
- 合理性：方案设计是否合理？是否符合最佳实践？
- 安全：方案是否存在安全隐患？是否需要加强安全措施？
- 目标一致性：方案是否与原始需求目标一致？是否偏离了核心目标？

此外，请主动补充你认为还应纳入评审或方案设计的场景、情况和约束，并明确说明这些补充是否应影响评分。

请将评分、理由和改进建议写入：.codebuddy/review-panel/{task-name}/judge-output/judge-1.md

评委讨论机制：

评委之间可通过 send_message 相互讨论
不指定侧重领域，每个评委从所有评分维度全面评估
通过讨论聚焦争议点，最终独立给出分数
每个评委独立给出最终分数，写入各自文件
每个评委必须提出改进建议，从复杂度、性能、正确性、合理性、安全、目标一致性等角度

阶段4：研判——主agent判断是否需要迭代改进

主agent读取所有 judge-output/ 和 challenger-output/ 文件，执行以下步骤：

步骤4.1：评委讨论终止条件

首先检查评委讨论是否满足任一终止条件：

条件	说明
评分收敛	各维度评分中，任意维度的最高分与最低分差距 ≤ 1
覆盖完整	所有方案（V0 + 替代方案A/B）都已获得评分
讨论轮次	评委讨论已达 2-3 轮
意见枯竭	新增讨论不再产生实质性新意见

满足任一条件 → 评委讨论终止，进入步骤4.2。否则 → 回到阶段3继续讨论。

步骤4.2：主agent迭代决策

评委讨论终止后，主agent根据评委的改进建议，判断是否需要迭代改进：

决策逻辑：

评估改进建议与补充内容：主agent分析评委和挑战者提出的改进建议、补充场景与补充情况，判断其合理性、必要性和纳入价值
判断是否需要修改：
- 需要修改：改进建议或补充内容合理且必要，值得纳入方案，进入步骤4.3（迭代改进）
- 不需要修改：改进建议或补充内容不合理、不必要，或纳入收益不足，记录原因，进入阶段5
- 拿不定主意：无法判断补充内容是否值得纳入，记录原因，进入阶段5

决策记录格式：

## 迭代决策记录

### 决策结果
- [ ] 需要修改
- [ ] 不需要修改
- [ ] 拿不定主意

### 决策原因
（详细说明决策原因，包括：
- 评估了哪些改进建议
- 为什么认为需要/不需要修改
- 如拿不定主意，说明不确定的地方）

### 迭代轮次
当前迭代轮次：{n}/3

步骤4.3：迭代改进（如需要修改）

如果主agent判断需要修改，执行以下步骤：

修改方案：主agent根据评委的改进建议，修改原始方案
更新文件：将修改后的方案写入 scheme.md（或 scheme/ 目录）
记录修改：将修改记录写入 design-decisions.md
创建挑战者：创建新的挑战者，对修改后的方案进行重新评估
回到阶段2：挑战者重新评估后，再次进入阶段3、阶段4

迭代限制：最多迭代3次，超过3次自动终止，记录原因

迭代记录格式：

## 迭代记录

### 迭代轮次：{n}

#### 修改内容
- 修改1：[描述修改内容]
- 修改2：[描述修改内容]
- ...

#### 修改原因
- 原因1：[描述修改原因]
- 原因2：[描述修改原因]
- ...

#### 挑战者重新评估
- 挑战者A意见：[简要总结]
- 挑战者B意见：[简要总结]

#### 主agent再次判断
- [ ] 需要继续修改
- [ ] 不需要继续修改
- [ ] 拿不定主意

#### 决策原因
（详细说明决策原因）

步骤4.4：迭代终止

迭代在以下情况终止：

主agent判断不需要修改：进入阶段5
主agent拿不定主意：进入阶段5
迭代轮次达到3次：自动终止，记录原因，进入阶段5

完成后，调用 team_delete() 清理团队

阶段5：输出——完整评审报告

主agent读取所有产出文件，汇总后按以下结构向用户交付最终报告：

评审报告直接以对话形式输出给用户
报告同时写入 .codebuddy/review-panel/{task-name}/final-report.md
用户可随时查看中间产物文件

# 评审报告：{任务名称}

## 一、原始方案
（读取 scheme.md 或 scheme/overview.md 展示）

## 二、挑战者审查意见

### 挑战者A
（读取 challenger-a.md 展示：反对意见 + 逐条替代方案 + 认可点）

### 挑战者B
（读取 challenger-b.md 展示：反对意见 + 逐条替代方案 + 认可点）

### 共识性反对
（A和B独立发现的相同问题，需高亮标注，说明问题严重性）

## 三、评委评分与理由

| 评委 | 可行性 | 风险覆盖 | 完整性 | 采纳度 | 综合意见 |
|------|--------|----------|--------|--------|----------|
| 评委1 | X/5 | X/5 | X/5 | X/5 | 简要理由 |
| 评委2 | X/5 | X/5 | X/5 | X/5 | 简要理由 |
| 评委3 | X/5 | X/5 | X/5 | X/5 | 简要理由 |

**评委讨论要点**：（如有讨论，摘录关键分歧和共识）

## 四、主agent最终判断

- **采纳**：哪些挑战者意见或评委建议被采纳，为什么
- **拒绝**：哪些挑战者意见或评委建议未被采纳，为什么
- **补充纳入**：哪些新增场景、情况或约束值得加入方案，为什么
- **补充搁置**：哪些新增场景、情况或约束暂不纳入，为什么
- **存疑**：哪些问题需要用户最终决策
- **改进建议**：综合各方意见后的优化方向

## 五、迭代改进记录

### 迭代决策
- **决策结果**：需要修改 / 不需要修改 / 拿不定主意
- **决策原因**：（详细说明决策原因）

### 迭代轮次（如有迭代）
- **迭代轮次**：{n}/3
- **修改内容**：（简要说明修改了什么）
- **修改原因**：（简要说明为什么修改）
- **挑战者重新评估**：（简要总结挑战者意见）
- **主agent再次判断**：需要继续修改 / 不需要继续修改 / 拿不定主意
- **决策原因**：（详细说明决策原因）

### 迭代终止原因
- [ ] 主agent判断不需要修改
- [ ] 主agent拿不定主意
- [ ] 迭代轮次达到3次
- **终止原因**：（详细说明终止原因）

## 六、评审过程文件
所有中间产物保存在：`.codebuddy/review-panel/{task-name}/`
用户可直接查看各文件的完整内容。

异常处理与边界情况

子agent失败：单个挑战者/评委失败时，主agent可选择重试或跳过该角色继续流程
产出为空：子agent未产出内容时，主agent记录"该角色未响应"，不影响其他角色继续
超时控制：建议单个子agent执行时间不超过5分钟，超时由主agent主动终止
用户中断：用户随时可要求停止评审，主agent清理团队并输出当前阶段的中间结果

循环控制机制

评委讨论循环

评委讨论最多进行3轮（初始1轮 + 追加2轮）
每轮讨论后主agent检查终止条件
需要继续时，主agent通过 send_message 向各评委发送"请继续讨论"指令，并附上需要聚焦的问题
各评委更新自己的 judge-{n}.md 文件
如需继续讨论，回到阶段3

迭代改进循环

迭代最多进行3次
主agent根据评委改进建议判断是否需要迭代改进
需要迭代时，主agent修改方案，创建挑战者重新评估
迭代终止条件：
1. 主agent判断不需要修改
2. 主agent拿不定主意
3. 迭代轮次达到3次
迭代终止后进入阶段5输出最终报告

角色设计原则

挑战者：不指定侧重领域，两个挑战者全面审查。独立发现相同问题时标记为"共识性反对"；除挑出问题外，也应主动补充遗漏场景、边界情况和异常路径
评委：不指定侧重，每个评委从所有评分维度评估。通过讨论聚焦争议点；在评分同时也应主动补充值得纳入方案的场景、约束和实施注意事项
主agent：不仅汇总问题与分数，也要判断这些新增补充是否值得写回方案或最终报告
理由：独立重复是验证质量的手段，指定侧重可能创造新的盲区；主动补漏可以提升评审的完整性

技术实现指引

所用工具

工具	用途
`team_create`	创建评审团队（阶段2开始时）
`Task`（team模式）	启动挑战者和评委子agent
`send_message`	评委间讨论、子agent回报结果
`team_delete`	评审完成后清理团队
`write_to_file`	主agent/子agent将产出写入文件
`read_file`	子agent按需读取方案、代码等文件

关键规则

挑战者必须并行启动：两个挑战者之间绝对不能有信息泄露
评委必须并行启动：但允许启动后通过 send_message 相互讨论
文件持久化：所有产出物必须写入文件，prompt中只传路径，不传内容
信息分层：方案和决策完整落盘；代码只存索引（路径+摘要），子agent自行按需读取
方案拆分：主agent根据复杂度自行决定单文件 or 目录拆分，子agent先读 overview
挑战者替代方案逐条绑定：每条反对意见必须附带对应替代方案，而非笼统一个
完成后清理：调用 team_delete 清理团队，但文件保留供用户查阅
循环控制：评委讨论最多3轮，每轮后检查终止条件
异常处理：单个子agent失败不阻塞整体流程，可重试或跳过
输出规范：评审报告同时输出给用户和写入 final-report.md
评委改进建议：评委除了打分外，必须从复杂度、性能、正确性、合理性、安全、目标一致性等角度提出改进建议
迭代决策：主agent根据评委改进建议判断是否需要修改，分为：需要修改、不需要修改、拿不定主意
迭代限制：迭代最多3次，超过3次自动终止，记录原因
迭代闭环：需要修改时，创建挑战者重新评估，形成"评估-改进-再评估"闭环

注意事项

3评委配置是默认值，用户可覆盖
评审流程中的阶段跳过或合并由主agent根据任务复杂度自行决策
普通的"review"、"评审一下"、"帮我检查"等请求，不默认启用本skill；只有用户明确要求使用评审团时才启用
task-name 从任务描述提取，英文小写+短横线，如 jwt-auth-review

使用示例

触发方式

用户明确提到要使用评审团时，才触发评审团。例如：

"用评审团帮我评审一下这个设计方案"
"启动评审团 review 一下这个代码"
"请用 review panel 看看这个架构"
"我想用评审团全面评估一下这个方案"
"用评审团看看有什么问题"

典型流程

用户：帮我评审一下 JWT 认证方案
主agent：用户未指定skill，识别为设计方案场景 → 检测到 design-doc-generator → 默认加载该skill
主agent：按 design-doc-generator 规范产出方案文件（scheme.md、code-context.md、design-decisions.md）
主agent：创建团队，启动两个挑战者
挑战者A/B：独立审查，产出 challenger-a.md、challenger-b.md
主agent：启动三个评委
评委：讨论评分 + 提出改进建议，产出 judge-1.md、judge-2.md、judge-3.md
主agent：研判是否需要迭代改进
- 情况A：不需要修改 → 记录原因，输出最终报告
- 情况B：需要修改 → 修改方案，创建挑战者重新评估 → 再次研判
- 情况C：拿不定主意 → 记录原因，输出最终报告
用户：收到完整评审报告（包含迭代记录），可查看所有中间文件

查看中间产物

所有评审过程文件保存在：.codebuddy/review-panel/{task-name}/

用户可直接打开查看：

原始方案：scheme.md
挑战者意见：challenger-output/challenger-a.md、challenger-output/challenger-b.md
评委评分：judge-output/judge-1.md、judge-output/judge-2.md、judge-output/judge-3.md
最终报告：final-report.md

参考文档

references/review-panel.md — 评审团角色prompt模板和信息传递协议

需求管理集成

当项目配置了 .requirements/config 时，review-panel 评审完成后自动执行以下集成操作：

自动触发条件

项目中存在 .requirements/config 且 storage_path 指向有效目录。

集成步骤（读取型）

获取需求上下文：评审前，如果关联了 REQ-ID，先读取需求信息作为评审参照：

req list --id {REQ-NNN} --deps

写入评审报告到需求目录后，调用 req update 注册文档关联：

req update {REQ-NNN} \
  --docs add review/review-panel.md,review --changelog "完成评审团评审"

错误处理：
- 需求 ID 不存在 → 跳过集成，不影响评审本身
- 文件锁超时 → 自动重试 1 次，仍失败则告知用户

存储路径映射

产出物	存储路径	docs 类型
评审团评审报告	`review/review-panel.md`	`review`