sanguo_moziplus_v2/docs/research/v2.6-research-03-challenge-quality.md

# 调研报告：挑战/评审体系 + 质量门控结构化

**日期**: 2026-05-15
**作者**: 庞统士元 (pangtong-fujunshi)
**版本**: v2.6-research-03
**用途**: moziplus v2.6 AI Native DevOps 平台设计参考

---

## 目录

- [课题 3：挑战/评审体系设计](#课题-3挑战评审体系设计)
  - [已有经验](#已有经验知识库wiki--v10-三层实践)
  - [业界优秀实践对比表](#业界优秀实践对比表课题3)
  - [v1.0 三层体系评估](#v10-三层体系评估)
  - [推荐方案](#推荐方案课题3)
- [课题 5：质量门控结构化](#课题-5质量门控结构化)
  - [业界优秀实践对比表](#业界优秀实践对比表课题5)
  - [推荐方案：评审结果存储与结构](#推荐方案评审结果存储与结构)

---

## 课题 3：挑战/评审体系设计

### 已有经验（知识库/wiki + v1.0 三层实践）

#### 知识库已有调研

我们在 `gate-mechanism-research.md`（2026-05-11）中已经做过一轮质量门控调研，识别出四种模式：

| 模式 | 代表项目 | 强制力 | 信任模型 |
|------|---------|--------|---------|
| LLM 自律型 | Claude Code、PAV skill | ❌ 弱 | 信任 LLM |
| 角色分工评审 | oh-my-claudecode | ⚠️ 中 | 不信任，靠隔离 |
| Guardrail 中断 | OpenAI Agents SDK | ✅ 强 | 不信任，靠代码 |
| DAG 条件流转 | TradingAgents / LangGraph | ✅ 强 | 不信任，靠结构 |

**核心结论**（上一轮调研）：
1. 业界共识：不信任 LLM 自律
2. 检查的是产出，不是过程
3. Guard 定义与执行分离（声明式规则 + 代码层执行）
4. 失败处理有层级：block → retry → escalate
5. 不同任务类型不同标准

#### v1.0 三层挑战控制回顾

moziplus v1.0 PRD 定义了三层挑战：

| 层级 | 机制 | 参与者 | 触发时机 |
|------|------|--------|---------|
| **第 1 层**：Agent 自律 PAV | Plan→Act→Verify skill | 执行者自己 | 每个节点开始时 |
| **第 2 层**：节点 review | 司马懿独立评审 | 司马懿（或挑战者池） | 每个节点完成时 |
| **第 3 层**：最终整合审查 | 庞统汇总 + 司马懿终审 | 庞统 + 司马懿 | 任务完成时 |

PRD 的铁律 IR-1 规定：**每个任务至少 2 个 Agent（做 + 挑战）**。IR-2 规定：**每个节点都是 Plan → Execute → Validate**。

#### v2.6 架构现状

v2.6 架构文档中：
- 任务状态流转：`pending → claimed → working → review → done`（review 是状态机中的一个状态）
- review → pending（审核不通过打回）是合法转换
- 挑战者由庞统在黑板上分配（`assigned_by` 字段）
- 评审结果目前只有 `comments` 表（自然语言评论），缺乏结构化

---

### 业界优秀实践对比表（课题3）

#### 1. Superpowers：三阶段审查（implementer → spec reviewer → code quality reviewer）

**项目**: [obra/superpowers](https://github.com/obra/superpowers) — Agentic Skills Framework for Claude Code

**核心机制**:

Superpowers 的 subagent-driven-development 流程采用**两阶段串行审查**（不是三阶段，实际是两个独立 reviewer 串行执行）：

```
Implementer subagent 执行任务
    ↓
Spec Reviewer subagent → 检查实现是否符合计划/需求规格
    ↓ (必须通过)
Code Quality Reviewer subagent → 检查代码质量（clean, tested, maintainable）
    ↓
下一任务
```

**关键设计细节**:

| 维度 | Spec Reviewer | Code Quality Reviewer |
|------|--------------|----------------------|
| **关注点** | 实现是否匹配计划 | 代码是否干净/可测/可维护 |
| **检查内容** | 功能完整性、与计划偏离、遗漏需求 | 单一职责、接口清晰度、测试覆盖 |
| **模型选择** | 用最强模型 | 用最强模型 |
| **顺序** | 先执行（必须通过） | 后执行（spec 通过后才触发） |
| **失败处理** | 标记偏离，返回给 implementer | 修改建议返回给 implementer |

**Implementer 报告四种状态**：
- `task_completed` — 完成且无需修改
- `task_completed_with_notes` — 完成，但有注意事项
- `task_blocked` — 被阻塞，需要人介入
- `task_failed` — 失败

**关键洞察**:
- **审查粒度是每个任务，不是每个文件** — 每个 subagent 完成一个 engineering task 后立即审查
- **串行门控** — spec review 必须通过后才做 code quality review，两个是串联的
- **审查者也是独立 subagent** — 不是同一个 agent 的不同角色，是独立的 spawned agent
- **并行执行但串行审查** — 多个 independent tasks 可以并行执行，但每个 task 的审查是串行的（参考 issue #469）
- **不靠 LLM 自律** — 审查是系统自动触发，不依赖 implementer 自觉

#### 2. TradingAgents：多空辩论（Bull↔Bear + Judge 裁决）

**项目**: [TauricResearch/TradingAgents](https://github.com/TauricResearch/TradingAgents) — Multi-Agent LLM Financial Trading Framework

**核心机制**:

TradingAgents 构建了**5 层结构化对抗**：

```
[4 位分析师并行] → 各自独立分析
    ↓
[Bull Researcher ↔ Bear Researcher] → 多空辩论（交替辩论，最多 max_debate_rounds 轮）
    ↓
[Research Manager] → 裁决，综合双方论据
    ↓
[Trader（3 级风险偏好）] → 根据研究报告做交易决策
    ↓
[Aggressive ↔ Conservative ↔ Neutral] → 风控三方辩论
    ↓
[Portfolio Manager] → 最终决策（Buy/Overweight/Hold/Underweight/Sell）
```

**关键设计细节**:

| 维度 | 研究辩论 | 风控辩论 |
|------|---------|---------|
| **参与者** | Bull vs Bear（2 方） | Aggressive vs Conservative vs Neutral（3 方） |
| **轮次控制** | `max_debate_rounds` 限制 | 条件边 `should_continue_debate` |
| **裁决者** | Research Manager | Portfolio Manager |
| **输出** | 综合研究报告 | 最终交易决策 |

**条件边实现**（LangGraph）：
```python
workflow.add_conditional_edges(
    "Bull Researcher",
    should_continue_debate,
    {
        "Bear Researcher": "Bear Researcher",
        "Research Manager": "Research Manager"
    }
)
```

**关键洞察**:
- **结构化对抗 = 特殊的 Exit Gate** — 不是检查产出文件，而是校验**决策质量**
- **辩论机制天然提供多视角审查** — 不需要额外的 reviewer agent
- **条件边让流转逻辑图化、可验证**
- **适用于需要多角度论证的决策场景** — 投资/交易/方案选择
- **2026-04 v0.2.4 新增**：structured-output agents（Research Manager/Trader/Portfolio Manager），LangGraph checkpoint resume

#### 3. oh-my-claudecode：ralplan（Planner→Architect→Critic 三方共识）

**项目**: [Yeachan-Heo/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) — Teams-first Multi-agent orchestration for Claude Code

**核心机制**:

ralplan（Radical Planning）编排三个专业 Agent，在迭代循环中达成共识：

```
Planner Agent → 输出初始计划
    ↓
Architect Agent → 从架构视角审查/修正
    ↓
Critic Agent → 从批判视角挑战
    ↓
是否达成共识？
    ├── 是 → 输出最终计划
    └── 否 → 回到 Planner，循环继续
```

**三种模式**:

| 模式 | 命令 | 适用场景 |
|------|------|---------|
| 基础模式 | `ralplan "描述"` | 普通规划 |
| 共识模式 | `ralplan --consensus "描述"` | 重要决策 |
| 深思熟虑模式 | `ralplan --deliberate "描述"` | 高风险场景 |

**Critic 角色**（继承自 oh-my-claudecode 的 Critic 设计）：

| 阶段 | 描述 |
|------|------|
| 预判 Pre-commitment | 读代码前先预测 3-5 个最可能的问题 |
| 验证 Verification | 逐一检查每个文件引用和函数调用 |
| 多视角审查 Multi-perspective | 安全/运维/新人三个角度 |
| 缺口分析 Gap analysis | 主动找"缺失的东西" |
| 自审 Self-audit | 低置信度发现降级为 Open Questions |

**Critic 工具限制**：`disallowedTools: Write, Edit` — 硬编码禁用修改工具，保证评审独立性。

**Verdict 只有 4 种**：REJECT / REVISE / ACCEPT-WITH-RESERVATIONS / ACCEPT

**关键洞察**:
- **三方共识比双方更健壮** — Planner(规划) + Architect(架构) + Critic(批判)，三方相互制衡
- **共识模式有明确退出条件** — 达成共识或超时
- **Critic 工具被硬编码禁用** — 不是 prompt 建议，是代码层面的限制
- **适合规划/设计阶段，不适合执行阶段** — ralplan 产出的是计划，不是代码
- **每种模式有不同的严谨程度** — 按风险级别选择

#### 4. OpenAI Agent SDK：OutputGuardrail + 声明式 Guardrail

**项目**: [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/guardrails/) — 官方 Agent 框架

**核心机制**:

OpenAI Agent SDK 提供三种 Guardrail：

| 类型 | 触发时机 | 作用 |
|------|---------|------|
| **Input Guardrail** | Agent 执行前 | 检查输入合法性 |
| **Output Guardrail** | Agent 执行后 | 检查产出达标 |
| **Tool Guardrail** | 每次工具调用前后 | 检查工具调用合法性 |

**Tripwire 机制**：
```python
@output_guardrail
async def guardrail_fn(ctx, agent, output):
    result = await Runner.run(guardrail_agent, output)
    return GuardrailFunctionOutput(
        tripwire_triggered=result.final_output.is_invalid  # True = 立即中断
    )
```

**执行模式**：
- `blocking`（推荐）— Guardrail 先执行，通过后才启动主 Agent
- `parallel` — Guardrail 和主 Agent 同时跑（不适合长任务 Agent，因为 token 已消耗）

**关键洞察**:
- **Guardrail 本身也是 Agent** — 可以用小模型做快速检查，成本可控
- **触发 tripwire = 抛异常 = 流程立即停止** — 代码层面的强制执行
- **声明式定义 + 程序式执行** — 规则声明为函数/配置，执行由框架保证
- **Input Guardrail 只在第一个 Agent 执行，Output Guardrail 只在最后一个 Agent 执行**
- **Tool Guardrail 粒度最细** — 每次工具调用都可以检查

#### 5. 其他优秀实践

##### 5.1 Edict 的门下省审核（封驳打回机制）

**项目**: [cft0808/edict](https://github.com/cft0808/edict) — 三省六部制 Multi-Agent Orchestration

**核心流程**：
```
皇上 → 太子分拣 → 中书省规划 → 门下省审议 → 尚书省派发 → 六部执行 → 回奏
                                  ↑                │
                                  └── 封驳打回 ─────┘
```

**门下省角色**：
- **质量管控中心** — 对中书省方案进行质量评审、风险识别与标准把控
- **封驳权** — 不合格方案可直接"封驳"，打回中书省重新规划
- **状态机**：`已派发 → 执行中 → 待审查 → 已完成`，中间可 `阻塞 Blocked`

**关键洞察**:
- 封驳打回是一种**方向级否决** — 不只是修改建议，而是"方案不对，重来"
- 门下省是**独立于执行链的审核层** — 不参与执行，只负责审核
- 类似 moziplus 中司马懿的角色定位

##### 5.2 wanman 的评估引擎（三阶段 explore→evaluate→execute）

**项目**: [chekusu/wanman](https://github.com/chekusu/wanman) — Agent Matrix Runtime

**核心流程**：
```
Explore 阶段 → 多 Agent 并行探索，收集方案
    ↓
Evaluate 阶段 → 评估引擎打分（4 维度加权）
    ↓
Execute 阶段 → 执行最优方案
```

**评估维度**（据 PRD 中描述）：
- **Feasibility**（可行性）
- **Risk**（风险）
- **Impact**（影响）
- **Cost**（成本）

**信心度机制**：信心度 < 0.7 升级到人工审批。

**关键洞察**:
- **量化评估**比定性评估更可追溯 — 4 维度加权打分，不是"感觉行不行"
- **阈值自动升级** — 信心度低于阈值自动升级，不需要人判断
- **适合方案选择场景** — 多个方案用同一标准评估

##### 5.3 SWE-agent 的 RetryLoop（多次尝试 + Reviewer 选最优）

**项目**: [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) — AI Software Engineering Agent

**核心机制**：

```yaml
agent:
  type: retry
  retry_loop:
    cost_limit: 6.00
    max_attempts: 3
    agent_configs:
      - <config 1>  # 可能用不同的 prompt
      - <config 2>  # 可能用不同的 model
```

- **多次独立尝试** — 可以用不同配置（prompt/model/参数）尝试多次
- **预算继承** — 每次尝试继承上一次失败后剩余的预算，不浪费
- **Reviewer LLM** 选最优 patch（`tools/review_on_submit_m`）
- **Trajectory 审计** — 每次尝试的完整轨迹都保存，可回溯

**关键洞察**:
- **多尝试优于单次完美** — LLM 输出有随机性，多次尝试取最优是务实策略
- **Trajectory 是审计基础** — 完整保留每次尝试的过程，可以对比分析
- **实际效果**：SWE-agent 团队承认 reviewer 有时"rejects correct patches" — LLM 评审不是万能的

#### 综合对比表

| 项目 | 审查模式 | 强制力 | 粒度 | 协商轮次 | 失败处理 | 声明式 |
|------|---------|--------|------|---------|---------|--------|
| **Superpowers** | 串行双审（spec→quality） | ✅ 系统触发 | 每任务 | 0（只审不改） | 返回 implementer | ❌ 硬编码 |
| **TradingAgents** | 多空辩论 + 裁决 | ✅ 图结构 | 每决策 | max_debate_rounds | 裁决者决定 | ✅ 条件边 |
| **oh-my-claudecode** | 三方共识循环 | ⚠️ prompt | 规划阶段 | 共识达成 | 循环/超时 | ❌ prompt |
| **OpenAI Agent SDK** | Input/Output Guardrail | ✅ 代码层 | 每工具调用 | 0（tripwire） | 抛异常停止 | ✅ 声明式 |
| **Edict** | 门下省封驳 | ⚠️ 状态机 | 每方案 | 封驳打回 | 打回中书省 | ✅ 状态机 |
| **wanman** | 量化评估打分 | ✅ 阈值 | 每方案 | 0 | 低于阈值升级 | ✅ 声明式 |
| **SWE-agent** | 多次尝试取最优 | ✅ 代码层 | 每任务 | max_attempts | reviewer 选最优 | ✅ YAML 配置 |

---

### v1.0 三层体系评估

#### 三层体系分析

| 层级 | 机制 | 优点 | 缺点 |
|------|------|------|------|
| **第 1 层：PAV** | Agent 自律 Plan→Act→Verify | 轻量、无额外成本 | 依赖模型自觉，skill 是"菜单"不是"触发器"，实践中经常被忽略 |
| **第 2 层：节点 review** | 司马懿独立评审 | 独立视角、有结构化 verdict | **每个节点都审过重**（成本高、延迟大），协商轮次固定 3 轮不够灵活 |
| **第 3 层：最终整合审查** | 庞统汇总 + 司马懿终审 | 全局视角、质量兜底 | 和第 2 层重复（司马懿审了两次），庞统的角色定位模糊 |

#### 三层是否高效？

**结论：不够高效，主要体现在**：

1. **第 1 层形同虚设** — PAV 是 prompt 层面的约束，模型可以忽略。张飞调查报告（Mail #214）已证明 skill 是"菜单"不是"触发器"
2. **第 2 层过重** — 每个节点产出都过司马懿，对于简单任务（如格式化输出、数据搬运）是过度审查
3. **第 2 层和第 3 层重复** — 司马懿既审每个节点又审最终整合，角色重叠
4. **没有任务类型适配** — 编码任务、调研任务、数据任务用同一个审查标准，不灵活

#### 三层是否足够？

**结论：在特定场景下不够**：

1. **缺少方案阶段审查** — 只审产出，不审方案。编码前的方案设计没有独立审查
2. **缺少量化评估** — 只有 pass/fail/revise，没有打分机制，难以对比多方案
3. **缺少安全红线** — 没有 tripwire 机制，危险操作没有代码级拦截
4. **缺少并行审查** — 只有一个审查者（司马懿），没有多视角对抗

#### 三层是否过重？

**结论：在简单任务上过重，在复杂任务上不够** — 需要分级。

---

### 推荐方案（课题3）

基于以上调研，为 moziplus v2.6 推荐以下挑战/评审体系：

#### 设计原则

1. **声明式 + 代码执行分离** — 审查规则声明在 YAML/JSON 中，执行由框架保证
2. **分级审查** — 按任务类型和风险级别选择审查深度
3. **方案先审，产出后审** — 关键节点先审方案，再审产出
4. **多视角可选** — 支持单审、对抗、共识三种模式
5. **有限协商 + 自动升级** — 超过轮次自动升级

#### 分级审查矩阵

| 任务类型 | 方案审查 | 产出审查 | 审查模式 | 最大轮次 |
|---------|---------|---------|---------|---------|
| **高风险**（生产部署/资金操作） | ✅ 必须独立审查 | ✅ 独立审查 + 安全 Guardrail | 对抗（多空辩论） | 5 轮 |
| **标准**（编码/设计/架构） | ✅ 方案过挑战 | ✅ 产出过挑战 | 单审（指定挑战者） | 3 轮 |
| **低风险**（文档/格式化/数据搬运） | ❌ 跳过 | ⚡ 轻量 Guardrail（格式检查） | 自动检查 | 0 轮 |
| **调研/分析** | ❌ 跳过 | ✅ 结论过挑战 | 单审 | 2 轮 |

#### 三阶段审查流程（关键节点）

参考 superpowers 的串行双审和 TradingAgents 的对抗辩论，对高风险和标准任务采用：

```
阶段 1：方案审查（Plan Review）
    ├── 执行者提交方案到黑板
    ├── 挑战者审查方案（可行性/风险/遗漏）
    ├── 高风险：多视角对抗辩论
    └── 通过 → 进入执行
    └── 未通过 → 协商修改（最多 max_rounds 轮）
                └── 超轮次 → 升级用户

阶段 2：执行 + Output Guardrail
    ├── 执行者按方案执行
    ├── 系统自动运行 Output Guardrail（声明式规则检查）
    │   ├── 文件存在性检查
    │   ├── JSON schema 校验
    │   ├── 代码编译/运行测试
    │   └── 安全红线检查
    └── Guardrail 通过 → 进入产出审查
    └── Guardrail 不通过 → 自动打回（tripwire）

阶段 3：产出审查（Output Review）
    ├── 执行者提交产出到黑板
    ├── 挑战者审查产出（质量/完整性/与方案一致性）
    ├── 审查结果结构化记录
    └── 通过 → 流转下一节点
    └── 未通过 → 协商修改
```

#### 声明式 Guardrail 规则示例

```yaml
# guardrails.yaml — 声明式质量门控规则
task_types:
  coding:
    plan_review:
      required: true
      reviewer: challenger  # 挑战者池分配
      max_rounds: 3
    output_guardrails:
      - name: file_exists
        check: "output.files | length > 0"
        severity: blocking
      - name: tests_pass
        check: "output.test_result == 'passed'"
        severity: blocking
      - name: code_quality
        check: "output.lint_score >= 8"
        severity: warning  # 不阻塞，但记录
    output_review:
      required: true
      reviewer: challenger
      max_rounds: 3

  deploy:
    plan_review:
      required: true
      reviewer: challenger
      mode: debate  # 对抗辩论模式
      max_rounds: 5
    output_guardrails:
      - name: no_direct_production
        check: "output.target_env != 'production'"
        severity: tripwire  # 立即中断
      - name: rollback_plan_exists
        check: "output.rollback_plan != null"
        severity: blocking
    output_review:
      required: true
      reviewer: challenger
      max_rounds: 5
      escalate_to: user  # 超轮次升级用户

  data:
    plan_review:
      required: false
    output_guardrails:
      - name: format_check
        check: "output.format in ['csv', 'parquet', 'json']"
        severity: blocking
    output_review:
      required: false  # 低风险，Guardrail 自动检查即可
```

#### 对 v1.0 三层体系的改进

| 改进点 | v1.0 | v2.6 推荐 |
|--------|------|----------|
| **第 1 层 PAV** | 依赖模型自律 | 替换为**声明式 Output Guardrail** — 系统自动执行，不依赖模型 |
| **第 2 层节点 review** | 每个节点都审 | **分级审查** — 按任务类型和风险级别选择审查深度 |
| **第 3 层最终整合** | 司马懿再审一次 | **保留但简化** — 只在高风险任务终审，标准任务由最后节点的审查覆盖 |
| **方案审查** | ❌ 无 | ✅ 新增**方案先审** — 关键节点先审方案再执行 |
| **量化评估** | ❌ 无 | ✅ 可选 — 支持打分机制（参考 wanman），信心度 < 0.7 升级 |
| **对抗辩论** | ❌ 无 | ✅ 高风险任务启用多视角对抗（参考 TradingAgents） |

---

## 课题 5：质量门控结构化

### 业界优秀实践对比表（课题5）

#### 1. Control Center 的 Task Store（artifacts + rollback + review 结构）

**项目**: [keshrath/agent-tasks](https://github.com/keshrath/agent-tasks)（参考 Control Center 模式）

**核心结构**：

```
Task
├── definitionOfDone（完成标准）
├── artifacts[]（产出物列表，按 stage 组织）
│   ├── id, stage, type, path, metadata
│   └── version（版本化）
├── comments[]（评论，结构化）
├── dependencies[]（依赖关系）
└── pipeline（流水线配置）
    └── stages[]（阶段定义 + 审查规则）
```

**API 设计**：
- `GET /api/tasks/:id/artifacts` — 按 stage 过滤产出物
- `PUT /api/tasks/:id/stage` — 推进/回退阶段（支持 regress）
- `POST /api/tasks/:id/comments` — 添加评论

**关键洞察**:
- **Artifacts 按 stage 组织** — 每个阶段有独立的产出物列表
- **支持阶段回退（regress）** — 不只是前进，可以打回
- **definitionOfDone 是结构化的** — 不是自然语言描述，是可验证的条件列表

#### 2. SWE-agent 的 Trajectory 审计

**项目**: [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent)

**核心机制**:

SWE-agent 的每次尝试产生一个 **Trajectory**（轨迹），是完全线性的事件序列：

```
Trajectory = [
  { step: 1, action: "open_file", args: {...}, observation: "..." },
  { step: 2, action: "search", args: {...}, observation: "..." },
  { step: 3, action: "edit", args: {...}, observation: "..." },
  ...
  { step: N, action: "submit", args: {...}, observation: "patch applied" }
]
```

- **线性追加** — 每个步骤只是追加到 messages，不修改历史
- **轨迹 = 消息** — trajectory 和传给 LLM 的 messages 是同一个东西
- **可回溯** — 完整保留每次尝试的所有步骤
- **Trajectory Inspector** — 命令行工具，可以滚动查看数百条轨迹

**在 RetryLoop 模式下**：
- 多次尝试产生多条 Trajectory
- Reviewer LLM 对比多条 Trajectory，选择最优 patch
- 所有 Trajectory 都保存，可用于后续分析

**关键洞察**:
- **审计粒度是每步操作** — 不是每任务，是每个 action
- **不可变追加** — 不修改历史记录，只追加新记录
- **多次尝试可对比** — 重试机制下保留所有尝试的轨迹

#### 3. Hermes 的 Comment 线程 + 结构化状态

**项目**: [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) — Kanban Multi-Agent Board

**核心结构**：

Hermes 的 Kanban 系统中，**Comment 是持久化标注通道**：

```sql
kanban_comment:
  - id, task_id, author, body, metadata JSON, created_at
```

**关键设计**:

| 机制 | 描述 |
|------|------|
| **Comment 即审计** | 所有审计相关字段（changed_files, tests_run, diff_path, PR url, decisions）都放在 comment 的 metadata 中 |
| **Block with reason** | `kanban_block` 带理由，reason 前缀 `review-required:` 表示等待审查 |
| **Bulk-close guard** | 不允许批量 close 多个 task 用同一个 summary — 因为每个 task 的元数据是不同的 |
| **Worker lanes** | 每次执行产生独立的 worker lane，reviewer 看到完整的 comment thread |
| **Structured metadata** | 接受标准（acceptance criteria）写在 spec metadata 中，engineer 的 worker 自动看到 |

**审查流程**：
```
Engineer 完成工作
    → 写 structured metadata 到 kanban_comment
        (changed_files, tests_run, diff_path, decisions)
    → kanban_block "review-required: 等待审查"
    → Reviewer 看到 comment thread + metadata
    → Reviewer 批准: kanban_unblock
    → Reviewer 要求修改: 再写 comment，下次 worker 运行时看到
```

**关键洞察**:
- **Comment 是主要通信和审计通道** — 不只是讨论，是结构化数据的载体
- **metadata JSON 承载结构化数据** — body 是人类可读的，metadata 是机器可读的
- **Block reason 前缀约定** — 用前缀区分 block 类型（review-required / blocked-by / waiting-on）
- **每次执行独立的 worker lane** — 不同次执行的结果不会混淆

#### 4. 其他优秀实践

##### 4.1 PRD 中定义的 review_result JSON

moziplus PRD v1.0 已定义了结构化评审结果：

```json
{
  "review_id": "uuid",
  "task_id": "uuid",
  "stage_id": "coding",
  "reviewer": "simayi",
  "verdict": "approved|rejected|needs_revision",
  "issues": [
    {
      "severity": "critical|major|minor",
      "location": "文件:行号 或 方案:章节",
      "description": "问题描述",
      "suggestion": "修改建议"
    }
  ],
  "round": 1,
  "max_rounds": 3,
  "consensus_reached": true
}
```

**优点**：结构清晰，verdict 明确，issues 可追溯
**不足**：没有信心度/评分，没有关联到产出物，没有历史版本

##### 4.2 GitHub PR Review 的结构化模式

GitHub PR Review API 提供了业界最成熟的结构化审查模式：

```
Pull Request Review:
├── event: APPROVE | REQUEST_CHANGES | COMMENT
├── body: "总结性评论"
└── comments[]:
    ├── path: "src/file.py"
    ├── position: 42
    ├── body: "这行有问题"
    ├── in_reply_to_id: (支持嵌套回复)
    └── side: LEFT | RIGHT
```

**关键特性**：
- **三种 verdict**：APPROVE / REQUEST_CHANGES / COMMENT — 明确表达意图
- **行级定位**：comment 精确到文件+行号
- **嵌套回复**：支持 comment 线程中的子讨论
- **review 和 comment 分离**：review 是整体评审，comment 是行级细节
- **多 reviewer 支持**：多个 reviewer 可以各自提交独立的 review

##### 4.3 代码审查工具的结构化输出模式

业界代码审查工具（SonarQube / CodeClimate / reviewdog）的共同模式：

```
Review Output:
├── summary: { verdict, score, total_issues }
├── issues[]:
│   ├── severity: critical | major | minor | info
│   ├── rule_id: "S1234" (规则 ID，可查文档)
│   ├── location: { file, line, column }
│   ├── message: "问题描述"
│   └── suggestion: "修改建议"
└── metadata:
    ├── tool_version
    ├── analyzed_files
    └── duration_ms
```

**共同特点**：
- severity 有标准分级（critical/major/minor/info）
- location 精确到文件+行+列
- rule_id 关联到可查的规则文档
- summary 包含总体评分和统计

#### 综合对比表（课题5）

| 项目 | 评审存储位置 | 结构化程度 | 可追溯性 | 多轮支持 | 关联产出 |
|------|-----------|-----------|---------|---------|---------|
| **Control Center** | Task Store（内置） | ✅ artifacts + stage | ✅ 版本化 | ⚠️ 阶段回退 | ✅ artifact 关联 |
| **SWE-agent** | Trajectory 文件 | ✅ 每步结构化 | ✅ 线性追加 | ✅ 多次尝试 | ✅ patch 关联 |
| **Hermes** | Comment metadata JSON | ✅ 结构化 metadata | ✅ 追加写入 | ✅ worker lanes | ✅ 手动关联 |
| **moziplus PRD** | comments 表 | ⚠️ 自然语言为主 | ❌ 无版本 | ❌ 无 | ❌ 无 |
| **GitHub PR Review** | Review API | ✅ 行级定位 | ✅ 嵌套回复 | ✅ 多 reviewer | ✅ diff 关联 |
| **代码审查工具** | 独立输出 | ✅ rule_id + severity | ✅ 标准化 | ❌ 单次 | ⚠️ 工具特定 |

---

### 推荐方案：评审结果存储与结构

#### 设计原则

1. **黑板索引 + 文件详情** — 黑板存储结构化摘要（索引），文件系统存储完整评审记录（详情）
2. **追加写入，不修改历史** — 每轮评审是新的记录，不覆盖旧记录
3. **结构化 verdict** — 评审结论必须是枚举值，不是自然语言
4. **关联产出物** — 评审记录通过 output_id 关联到具体产出
5. **人类可读 + 机器可读** — body 给人看，metadata 给程序用

#### 推荐的评审结果结构

```sql
-- ===== 评审结果表 =====
-- 评审是追加写入的，每轮评审一条新记录
CREATE TABLE IF NOT EXISTS reviews (
    id TEXT PRIMARY KEY,                     -- rev-001
    task_id TEXT NOT NULL,
    output_id TEXT,                          -- 关联的产出物（outputs 表）
    reviewer TEXT NOT NULL,                  -- 审查者 agent id
    review_type TEXT NOT NULL,               -- plan_review | output_review | guardrail
    CHECK (review_type IN ('plan_review', 'output_review', 'guardrail', 'final_review')),

    -- 评审结论（必须是枚举，不是自然语言）
    verdict TEXT NOT NULL,
    CHECK (verdict IN ('approved', 'rejected', 'needs_revision', 'approved_with_reservations')),

    -- 评分（可选，用于量化评估场景）
    confidence REAL,                         -- 0.0-1.0 信心度
    scores TEXT,                             -- JSON: {"feasibility": 0.9, "risk": 0.7, "impact": 0.8, "quality": 0.85}

    -- 协商轮次
    round INTEGER NOT NULL DEFAULT 1,
    max_rounds INTEGER NOT NULL DEFAULT 3,
    consensus_reached BOOLEAN DEFAULT FALSE,

    -- 摘要（黑板索引）
    summary TEXT NOT NULL,                   -- 一句话评审结论（人可读）

    -- 详情路径（文件详情）
    detail_path TEXT,                        -- 指向完整评审报告文件

    -- 时间
    created_at TEXT NOT NULL DEFAULT (datetime('now')),

    FOREIGN KEY (task_id) REFERENCES tasks(id),
    FOREIGN KEY (output_id) REFERENCES outputs(id)
);

CREATE INDEX IF NOT EXISTS idx_reviews_task ON reviews(task_id);
CREATE INDEX IF NOT EXISTS idx_reviews_output ON reviews(output_id);
CREATE INDEX IF NOT EXISTS idx_reviews_reviewer ON reviews(reviewer);
```

#### 评审详情文件结构

```
tasks/{task_id}/
├── output.md                          # 任务产出
├── output.json                        # 产出元数据
└── reviews/
    ├── rev-001-round1.json            # 第 1 轮评审
    ├── rev-001-round2.json            # 第 2 轮评审（协商后修改）
    └── rev-001-round3.json            # 第 3 轮评审（最终通过）
```

**评审详情 JSON**：

```json
{
  "review_id": "rev-001",
  "task_id": "task-001",
  "output_id": "out-001",
  "reviewer": "simayi-challenger",
  "review_type": "output_review",
  "verdict": "needs_revision",
  "confidence": 0.65,
  "round": 1,
  "max_rounds": 3,
  "summary": "代码逻辑正确但缺少错误处理和单元测试",
  "issues": [
    {
      "id": "iss-001",
      "severity": "critical",
      "category": "correctness",
      "location": "src/trading.py:42",
      "description": "未处理网络超时异常",
      "suggestion": "添加 try-except 包装，设置 30s 超时",
      "rule_id": "ERR-001"
    },
    {
      "id": "iss-002",
      "severity": "major",
      "category": "testing",
      "location": "tests/",
      "description": "缺少单元测试",
      "suggestion": "至少覆盖正常路径和异常路径",
      "rule_id": "TEST-001"
    }
  ],
  "positives": [
    "代码结构清晰，职责分离做得好",
    "命名规范，可读性强"
  ],
  "metadata": {
    "model": "zhipu/glm-5.1",
    "duration_ms": 12500,
    "files_reviewed": ["src/trading.py", "src/utils.py"],
    "total_lines_reviewed": 150
  },
  "created_at": "2026-05-15T10:30:00Z"
}
```

#### Guardrail 自动检查结果

Guardrail 检查结果也存入 reviews 表（`review_type = 'guardrail'`），但来源是系统自动执行：

```json
{
  "review_id": "rev-auto-001",
  "reviewer": "system",
  "review_type": "guardrail",
  "verdict": "rejected",
  "issues": [
    {
      "severity": "blocking",
      "rule_id": "GUARD-FILE-EXISTS",
      "description": "产出文件不存在: output.md",
      "location": null
    }
  ],
  "metadata": {
    "guardrail_config": "guardrails.yaml#coding.output_guardrails",
    "checks_run": 3,
    "checks_passed": 2,
    "checks_failed": 1
  }
}
```

#### 评审产出物与任务产出物的关系

```
Task (task-001)
├── Output 1 (out-001) → 编码产出
│   ├── Review 1 (rev-001, plan_review, round 1) → 方案评审
│   ├── Review 2 (rev-002, guardrail, round 1) → 自动 Guardrail
│   └── Review 3 (rev-003, output_review, round 1) → 产出评审
│       └── Review 4 (rev-004, output_review, round 2) → 协商后再审
└── Output 2 (out-002) → 测试报告
    └── Review 5 (rev-005, output_review, round 1) → 测试产出评审
```

**关系规则**：
- **一个 output 可以有多个 review**（多轮协商）
- **一个 review 关联一个 output**（不跨产出）
- **review 按时间追加**，不修改历史（round 递增）
- **黑板只存摘要**（verdict + summary + round），完整详情在文件

#### 多轮协商的追溯

```sql
-- 查看某个任务的所有评审历史
SELECT r.id, r.round, r.verdict, r.summary, r.created_at
FROM reviews r
WHERE r.task_id = 'task-001'
ORDER BY r.created_at ASC;

-- 查看某个产出的最新评审
SELECT * FROM reviews
WHERE output_id = 'out-001'
  AND review_type = 'output_review'
ORDER BY round DESC
LIMIT 1;
```

#### 对比现有 comments 表的改进

| 维度 | 现有 comments 表 | 推荐 reviews 表 |
|------|----------------|----------------|
| **数据类型** | 自然语言 | 结构化 JSON |
| **结论** | 无（靠读 body 推断） | ✅ verdict 枚举 |
| **关联产出** | ❌ 只关联 task | ✅ 关联 output |
| **评分** | ❌ 无 | ✅ confidence + scores |
| **轮次追踪** | ❌ 无 | ✅ round + max_rounds |
| **评审类型** | ❌ 无 | ✅ plan_review / output_review / guardrail / final_review |
| **详情** | ❌ body 只有自然语言 | ✅ body + detail_path 文件 |

**comments 表保留用途**：日常讨论、@ mention、非结构化沟通。reviews 表专注评审。

---

## 附录：关键参考源码

### A. Superpowers 串行双审
```
skills/subagent-driven-development/SKILL.md
skills/requesting-code-review/code-reviewer.md
skills/subagent-driven-development/code-quality-reviewer-prompt.md
```

### B. TradingAgents 辩论条件边
```python
# tradingagents/graph/trading_graph.py
workflow.add_conditional_edges(
    "Bull Researcher",
    should_continue_debate,
    {"Bear Researcher": ..., "Research Manager": ...}
)
```

### C. oh-my-claudecode Critic 工具限制
```yaml
# agents/critic.md
disallowedTools: Write, Edit
```

### D. OpenAI Agents SDK Tripwire
```python
# agents/guardrails.py
@output_guardrail
async def guardrail_fn(ctx, agent, output):
    return GuardrailFunctionOutput(
        tripwire_triggered=output.is_invalid
    )
```

### E. SWE-agent RetryLoop
```yaml
# config.yaml
agent:
  type: retry
  retry_loop:
    cost_limit: 6.00
    max_attempts: 3
```

### F. Hermes Kanban Comment
```sql
-- kanban_comment with structured metadata
INSERT INTO kanban_comment (task_id, author, body, metadata)
VALUES (?, ?, ?, json(?))
-- metadata: {"changed_files": [...], "tests_run": 5, "tests_passed": 5, "diff_path": "..."}
```