From 302ceb9e8b6aeb1fc345efeeb116e5469b579cb0 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Fri, 15 May 2026 20:39:44 +0800 Subject: [PATCH] auto-sync: 2026-05-15 20:39:44 --- .../topic3-challenge-review-proposal.md | 432 ++++++++++++++++++ 1 file changed, 432 insertions(+) create mode 100644 docs/design/topic3-challenge-review-proposal.md diff --git a/docs/design/topic3-challenge-review-proposal.md b/docs/design/topic3-challenge-review-proposal.md new file mode 100644 index 0000000..6c60a45 --- /dev/null +++ b/docs/design/topic3-challenge-review-proposal.md @@ -0,0 +1,432 @@ +# 课题3 设计方案：挑战/评审体系 + 质量门控结构化 + +**作者**: 庞统士元 +**日期**: 2026-05-15 +**状态**: 方案待确认 +**前置**: 课题1（AI决策者参与）、课题2（事件驱动+上下文传递）已结题 + +--- + +## 1. 设计目标 + +课题1已定义了"谁来判断"（双轨制：Daemon系统保护 + Coordinator AI决策）和"判断什么"（must_haves三件套、幻觉门控、Scope Guard）。课题2定义了"怎么触发判断"（Tick+Inbox事件驱动、Handoff Comment无缝接手）。 + +**课题3要解决的问题是：判断的结果怎么记录、怎么协商、怎么流转。** + +具体来说： +1. 评审结果怎么结构化存储（不是散落在 comments 里的自然语言） +2. 挑战/评审的协商流程怎么设计（几轮、升级条件、对抗模式） +3. 评审体系和现有状态机（pending→working→review→done）怎么对齐 + +## 2. v1.0 三层体系的问题 + +| 问题 | v1.0 做法 | 根因 | +|------|----------|------| +| PAV自律形同虚设 | Plan→Act→Verify 靠 Skill 文本约束 | Skill 是"菜单"不是"触发器"，Agent 可忽略 | +| 每个节点都审过重 | 司马懿审所有节点 | 没有分级，简单任务和复杂任务同一个审查标准 | +| 方案阶段没审查 | 只审产出不审方案 | 编码前的设计方案没有独立审查 | +| 评审结果不结构化 | 司马懿写自然语言评论 | 无法机器判断"通过还是没通过"，只能人读 | +| 司马懿角色重叠 | 节点审一次 + 终审一次 | 重复劳动 | + +## 3. 设计决策 + +### D3-1：评审体系由三层改为"分级 + 流水线" + +> **参考实践**： +> - **superpowers**：串行双审（spec reviewer → code quality reviewer），先审方案再审代码 +> - **TradingAgents**：多空对抗辩论（Bull vs Bear → Research Manager 裁决） +> - **OpenAI Agent SDK**：Guardrail 是 tripwire（检测到违规立即中断，不是建议） +> - **Hermes v0.13**：Comment 的 metadata JSON 承载结构化数据（changed_files / tests_run / diff_path） +> - **v1.0 PRD**：review_result JSON 结构（verdict + issues + round + max_rounds） +> - **GitHub PR Review**：APPROVE / REQUEST_CHANGES / COMMENT 三种明确 verdict + +**核心思路**：不搞三层并行，而是每个任务按风险等级走不同的审查流水线。 + +| 任务风险等级 | 流水线 | 方案审查 | 产出审查 | 审查模式 | 最大轮次 | +|------------|--------|---------|---------|---------|---------| +| **high**（部署/策略/资金） | 三阶段 | ✅ 独立审查 | ✅ 独立审查 + Guardrail | 对抗辩论 | 5 | +| **standard**（编码/设计） | 二阶段 | ✅ 方案过挑战 | ✅ 产出过挑战 | 单审 | 3 | +| **low**（文档/格式化/搬运） | 一阶段 | ❌ 跳过 | ⚡ Guardrail 自动检查 | 自动 | 0 | +| **research**（调研/分析） | 一阶段 | ❌ 跳过 | ✅ 庞统确认方向 | 单审 | 2 | + +**和课题1的分级审查矩阵对齐**：课题1的 §9.5 已定义了四级风险等级和审查深度，课题3 补充的是每个等级内部的具体流程。 + +### D3-2：评审三阶段流水线（high/standard 任务） + +> **参考实践**： +> - **superpowers**：implementer → spec reviewer（必须通过） → code quality reviewer +> - **TradingAgents**：多空辩论 + Manager 裁决，用 `add_conditional_edges` 实现 +> - **OpenAI Agent SDK**：OutputGuardrail 是并行运行的轻量 AI Agent，不是 if-else 规则 + +**阶段 1：方案审查（Plan Review）**——只对 high/standard 任务 + +``` +执行者提交方案（scope_declaration）到黑板 decisions 表 + ↓ +挑战者审查方案 + ├── high：对抗辩论（正方 vs 反方 → 庞统裁决） + └── standard：单审（指定挑战者，默认司马懿） + ↓ +通过 → 进入执行阶段 +未通过 → 协商修改（最多 max_rounds 轮） + └── 超轮次 → 升级用户 +``` + +方案审查和课题1的 Scope Guard 关系： +- Scope Guard（L2 sub 异步检查）是吹哨人——发现偏离写 observation +- 方案审查（L3 Agent 正式审查）是正式评审——通过/打回有 verdict +- 两者互补：Scope Guard 是过程中的软检查，方案审查是阶段门 + +**阶段 2：执行 + Guardrail 自动检查**——所有任务 + +``` +执行者按方案执行 + ↓ +每次写 output 时，Daemon 自动触发 Guardrail + ├── L1 机械检查（文件存在、JSON 格式、字段非空）→ 不通过直接打回 + ├── L2 轻量 AI 检查（Schema 校验、artifacts 路径验证）→ 不通过写 observation + └── L3 安全红线（tripwire：如直接操作生产环境）→ 立即中断 + ↓ +Guardrail 通过 → 进入产出审查 +Guardrail 不通过 → 自动打回（tripwire 直接 block） +``` + +**阶段 3：产出审查（Output Review）**——high/standard 任务 + +``` +执行者提交产出到黑板 outputs 表 + ↓ +挑战者审查产出（质量/完整性/与方案一致性） + ↓ +评审结果结构化记录到 reviews 表 + ↓ +通过 → status: review → done +未通过 → status: review → working（打回重做） + └── 协商在 comments 表讨论 + └── 超轮次 → 升级用户 +``` + +### D3-3：评审结果结构化存储（reviews 表） + +> **参考实践**： +> - **Hermes**：Comment 的 metadata JSON 承载结构化数据 +> - **SWE-agent**：Trajectory 线性追加，不修改历史 +> - **v1.0 PRD**：review_result JSON（verdict + issues + round） +> - **GitHub PR Review**：APPROVE / REQUEST_CHANGES / COMMENT 三种 verdict +> - **Control Center**：artifacts 按 stage 组织，支持阶段回退 + +**设计原则**： +1. **追加写入不修改历史**（SWE-agent 模式）——每轮评审是新记录 +2. **黑板索引 + 文件详情**（课题2 原则）——黑板存摘要，文件存详情 +3. **结构化 verdict**（GitHub PR Review 模式）——枚举值，不是自然语言 +4. **关联产出物**（Control Center 模式）——review 关联到具体 output + +```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 或 'system' + review_type TEXT NOT NULL, + 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 + + -- 协商轮次 + 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); +``` + +**评审详情文件**（detail_path 指向）： + +```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 超时" + } + ], + "positives": ["代码结构清晰，职责分离做得好"], + "metadata": { + "files_reviewed": ["src/trading.py", "src/utils.py"], + "total_lines_reviewed": 150 + } +} +``` + +### D3-4：Guardrail 检查结果也入 reviews 表 + +> **参考实践**： +> - **OpenAI Agent SDK**：Guardrail 的 tripwire_triggered 是结构化输出 +> - **Hermes 幻觉门控**：系统验证产出是否真实存在 + +Guardrail 自动检查结果存入 reviews 表（`reviewer='system'`, `review_type='guardrail'`）： + +```json +{ + "review_id": "rev-auto-001", + "reviewer": "system", + "review_type": "guardrail", + "verdict": "rejected", + "summary": "Guardrail 检查失败：产出文件不存在", + "issues": [ + { + "severity": "blocking", + "description": "产出文件不存在: output.md" + } + ] +} +``` + +**和课题1的 Guardrail 吹哨人机制对齐**： +- L1 机械检查失败 → 直接入 reviews 表（verdict=rejected）+ 打回 +- L2 轻量 AI 检查发现问题 → 写 observation（课题1设计）+ 入 reviews 表（verdict=needs_revision） +- L3 tripwire → 直接入 reviews 表（verdict=rejected）+ block 任务 + +### D3-5：对抗辩论模式（high 风险任务） + +> **参考实践**： +> - **TradingAgents**：Bull Researcher vs Bear Researcher → Research Manager 裁决 +> - **MetaGPT**：Engineer Agent 隐式 supervisor，按 SOP 产出 +> - **oh-my-claudecode Critic**：Critic 被禁止 Write/Edit 工具，只能读和评论 + +**high 风险任务的方案审查和产出审查都走对抗模式**： + +``` +方案审查（对抗模式）： + 正方（执行者）：写 scope_declaration，论证方案可行性 + 反方（挑战者池中的一人）：找方案漏洞、风险、遗漏 + ↓ + 庞统裁决：综合双方观点，做最终判断 + ├── 认可正方 → 方案通过 + ├── 认可反方 → 方案打回 + └── 综合意见 → 要求修改后重新辩论 +``` + +**挑战者池**：不是固定司马懿一个人，而是按任务类型选择： +- 编码任务 → 司马懿 +- 风控任务 → 关羽 +- 数据任务 → 赵云（数据质量视角） +- 部署任务 → 姜维 + +庞统在黑板上创建任务时指定 reviewer（`assigned_by` 字段已有）。 + +### D3-6：协商流程与状态机对齐 + +> **参考实践**： +> - **superpowers**：implementer 报告四种状态（task_completed / task_completed_with_notes / task_blocked / task_failed） +> - **Hermes**：block with reason 前缀约定（review-required: / blocked-by:） +> - **v1.0 PRD**：三轮协商上限，超轮次升级用户 + +**现有状态机**：`pending → claimed → working → review → done` + +**和评审流水线的对齐**： + +``` +pending → claimed → working + ↓ + [方案审查]（high/standard） + ├── approved → 继续 working + └── needs_revision → 继续 working（修改方案） + └── 超轮次 → 升级用户 + ↓ + [执行 + Guardrail] + ├── guardrail rejected → back to working（自动打回） + └── guardrail passed → 继续 + ↓ + 写 output → status: review + ↓ + [产出审查]（high/standard） + ├── approved → status: done + ├── needs_revision → status: working（协商在 comments） + └── rejected → status: working（打回重做） + └── 超轮次 → 升级用户 + +low 风险任务：working → [Guardrail 自动检查] → done（跳过 review 状态） +research 任务：working → [庞统确认] → review → done +``` + +**新状态机扩展**（在现有 8 状态基础上，不增加新状态）： + +| 状态转换 | 触发条件 | 对应阶段 | +|---------|---------|---------| +| working → working | 方案审查 needs_revision | 阶段 1 | +| working → review | 写 output + Guardrail 通过 | 阶段 2→3 | +| working → working | Guardrail rejected（自动打回） | 阶段 2 | +| review → done | 产出审查 approved | 阶段 3 | +| review → working | 产出审查 needs_revision | 阶段 3 | +| review → blocked | 超轮次升级 | 阶段 3 | + +### D3-7：comments 表和 reviews 表的职责分离 + +| 表 | 职责 | 内容类型 | verdict | +|---|------|---------|---------| +| **comments** | 讨论、@mention、协商过程 | 自然语言 | ❌ 无 | +| **reviews** | 正式评审结论 | 结构化 JSON | ✅ 必须有 | + +评审协商过程（"这里有个问题，建议这样改"）写在 comments。 +评审结论（"通过" / "不通过，原因见 issues"）写在 reviews。 + +两者关联：reviews.detail_path 指向的完整报告可以引用 comments 中的讨论。 + +### D3-8：声明式 Guardrail 配置（YAML） + +> **参考实践**： +> - **OpenAI Agent SDK**：`@output_guardrail` 装饰器声明检查函数 +> - **v1.0 M4 Guard**：entry/exit guard + skill 化检查逻辑 +> - **SonarQube / CodeClimate**：rule_id 关联可查规则文档 + +```yaml +# guardrails.yaml +task_types: + coding: + output_guardrails: + - name: file_exists + check: "output.files | length > 0" + severity: blocking + layer: L1 # Daemon 直接操作 + - name: json_valid + check: "output.json_schema_valid" + severity: blocking + layer: L1 + - name: artifacts_exist + check: "output.artifacts_paths all exist" + severity: blocking + layer: L1 # CLI 附加校验 + - name: code_quality + check: "scope_declaration vs task.truths" + severity: warning + layer: L2 # spawn sub 检查 + output_review: + required: true + mode: single_reviewer # 单审 + max_rounds: 3 + + deploy: + plan_review: + required: true + mode: debate # 对抗辩论 + max_rounds: 5 + output_guardrails: + - name: no_direct_production + check: "output.target_env != 'production'" + severity: tripwire # 立即中断 + layer: L1 + - name: rollback_plan_exists + check: "output.rollback_plan != null" + severity: blocking + layer: L1 + output_review: + required: true + mode: debate + max_rounds: 5 + + data: + output_guardrails: + - name: format_check + check: "output.format in ['csv', 'parquet', 'json']" + severity: blocking + layer: L1 + output_review: + required: false # 低风险，Guardrail 自动检查 + + research: + output_review: + required: true + reviewer: "pangtong-fujunshi" # 庞统确认方向 + mode: single_reviewer + max_rounds: 2 +``` + +## 4. 评审记录与 Handoff Comment 的关系 + +> **对齐课题2设计** + +Handoff Comment（课题2）是 Agent 结束时写的交接信息。评审记录（课题3）是挑战者写的审查结论。 + +两者在黑板上的关系： + +``` +Agent A 完成产出 + → 写 Handoff Comment（comments 表，type=handoff） + → 写 output（outputs 表） + → 通知 Daemon（inbox JSONL） + ↓ +Daemon 触发 Guardrail 自动检查 + → 结果写入 reviews 表（reviewer='system', review_type='guardrail'） + → 通过 → 进入产出审查 + → 不通过 → 打回 + ↓ +Daemon spawn 挑战者 + → 挑战者读黑板：L1 含 Agent A 的 Handoff Comment + output summary + → 挑战者做审查 + → 写 review（reviews 表，verdict + summary + detail_path） + → 写 comment（comments 表，协商讨论） + → 通过 → status: done + → 不通过 → status: working + Agent A 被 spawn 重做 +``` + +下一个 Agent（如果需要）的 L1 消息中包含： +1. Agent A 的 Handoff Comment（最近3条评论之一） +2. 挑战者的 review summary（reviews 表最新一条） +3. 协商过程的 comments（L2 按需读取） + +## 5. 遗留 TODO + +| # | 待解决事项 | 归属 | 说明 | +|---|----------|------|------| +| T3-1 | reviews 表的 CLI 命令（blackboard.py review） | Phase 2 | 写入/查询评审结果 | +| T3-2 | Guardrail YAML 解析 + 执行引擎 | Phase 2 | 读取 guardrails.yaml 并按 layer 执行 | +| T3-3 | 对抗辩论模式的具体黑板协议 | Phase 3 | 正方/反方如何在黑板上交互 | +| T3-4 | 挑战者池的选择策略 | Phase 2 | 按任务类型自动选择挑战者 | +| T3-5 | confidence 低于阈值自动升级 | Phase 2 | 如 confidence < 0.7 升级庞统 | +| T3-6 | 评审详情文件的 Schema 定义 | Phase 2 | detail_path 指向的 JSON 结构 | +| T3-7 | low 风险任务 Guardrail 自动通过的流控 | Phase 2 | 自动跳过 review 状态 | + +## 6. 和现有设计的对齐检查 + +| 已有设计 | 课题3 补充 | 一致性 | +|---------|-----------|--------| +| §9.5 分级审查矩阵（课题1） | D3-1 分级流水线（补充每级内部流程） | ✅ 四级风险对应四级流水线 | +| §4.7 Guardrail 吹哨人（课题1） | D3-4 Guardrail 结果入 reviews 表 | ✅ 吹哨后写 observation + 入 reviews | +| §3.7 Schema 校验（课题2） | D3-8 Guardrail YAML 和 Schema 对齐 | ✅ L1 检查用 Schema，YAML 声明规则 | +| §4.2 Tick+Inbox（课题2） | 评审触发也走 inbox 通知 | ✅ 挑战者 review 写完后通知 Daemon | +| §5.1 Handoff Comment（课题2） | §4 评审与 Handoff 关系 | ✅ Handoff 是执行者写的，review 是挑战者写的 | +| §3.2 SQLite Schema | reviews 表新增 | ✅ 独立新表，不修改现有表 |