sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily 302ceb9e8b auto-sync: 2026-05-15 20:39:44

2026-05-15 20:39:44 +08:00

17 KiB

Raw Blame History

课题3 设计方案：挑战/评审体系 + 质量门控结构化

作者: 庞统士元日期: 2026-05-15 状态: 方案待确认前置: 课题1（AI决策者参与）、课题2（事件驱动+上下文传递）已结题

1. 设计目标

课题1已定义了"谁来判断"（双轨制：Daemon系统保护 + Coordinator AI决策）和"判断什么"（must_haves三件套、幻觉门控、Scope Guard）。课题2定义了"怎么触发判断"（Tick+Inbox事件驱动、Handoff Comment无缝接手）。

课题3要解决的问题是：判断的结果怎么记录、怎么协商、怎么流转。

具体来说：

评审结果怎么结构化存储（不是散落在 comments 里的自然语言）
挑战/评审的协商流程怎么设计（几轮、升级条件、对抗模式）
评审体系和现有状态机（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 组织，支持阶段回退

设计原则：

追加写入不修改历史（SWE-agent 模式）——每轮评审是新记录
黑板索引 + 文件详情（课题2 原则）——黑板存摘要，文件存详情
结构化 verdict（GitHub PR Review 模式）——枚举值，不是自然语言
关联产出物（Control Center 模式）——review 关联到具体 output

-- ===== 评审结果表 =====
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 指向）：

{
  "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'）：

{
  "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 关联可查规则文档

# 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 消息中包含：

Agent A 的 Handoff Comment（最近3条评论之一）
挑战者的 review summary（reviews 表最新一条）
协商过程的 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 表新增	✅ 独立新表，不修改现有表

17 KiB Raw Blame History Unescape Escape