auto-sync: 2026-05-15 21:21:48

2026-05-15 21:21:48 +08:00
parent 813c1d21b6
commit 988f7adc9e
1 changed files with 302 additions and 49 deletions
@@ -1266,75 +1266,328 @@ v2.6 中 Mail 完全退役。黑板的两个操作替代了 Mail 的所有功能

 ---

-## 9. 质量门控(任务完成标准)
+## 9. 质量门控(挑战/评审体系)

-### 9.1 任务完成 = 司马懿评审通过 + 所有问题达成一致 + 修改完成
+### 9.1 设计目标

-一个任务要标记为 `done`,必须满足:
+课题1定义了"谁来判断"（双轨制）和"判断什么"（must_haves三件套、Guardrail吹哨人）。课题3解决"判断结果怎么记录、怎么协商、怎么流转"。

-1. **产出已提交** - Agent 写入 outputs 表
-2. **决策已记录** - 关键决策写入 decisions 表(哪怕是自己的决策也要填一条)
-3. **司马懿审核通过** - spawn 司马懿审核产出,评论中明确写"通过"
-4. **所有问题达成一致** - 审核中提出的问题全部解决,讨论达成共识
-5. **修改已完成** - 审核问题对应的修改已写入产出
+v1.0 三层体系（PAV自律 → 司马懿review → 庞统+司马懿终审）的问题：
+1. PAV 形同虚设——Skill是"菜单"不是"触发器"，Agent可忽略
+2. 每个节点都审过重——没有分级，简单/复杂任务同一个审查标准
+3. 方案阶段没审查——只审产出不审方案
+4. 评审结果不结构化——自然语言评论，无法机器判断
+5. 司马懿角色重叠——节点审一次+终审一次

-### 9.2 达成一致的原则
+### 9.2 分级审查流水线

- **以用户意图为导向** - 任何人(包括司马懿、庞统)说的都不一定对,最终以用户的原始意图为准
- **讨论达成共识** - 不同意见通过黑板评论讨论解决,不是谁职位高谁说了算
- **用户有最终裁量权** - 讨论无法达成一致时,@user 请用户裁定
+> **参考实践**：superpowers 串行双审、TradingAgents 对抗辩论、v1.0 PRD 三层体系

-### 9.3 流程
+| 任务风险等级 | 流水线 | 方案审查 | 产出审查 | 审查模式 | 最大轮次 |
+|------------|--------|---------|---------|---------|---------|
+| **high**（部署/策略/资金） | 三阶段 | ✅ 独立审查 | ✅ 独立审查 + Guardrail | 对抗辩论 | 5 |
+| **standard**（编码/设计） | 二阶段 | ✅ 方案过挑战 | ✅ 产出过挑战 | 单审 | 3 |
+| **low**（文档/格式化/搬运） | 一阶段 | ❌ 跳过 | ⚡ Guardrail 自动检查 | 自动 | 0 |
+| **research**（调研/分析） | 一阶段 | ❌ 跳过 | ✅ 庞统确认方向 | 单审 | 2 |
+
+**风险等级**:庞统创建任务时标注。默认 `standard`。task_type 为 `strategy`/`deploy` 自动设 `high`，`research` 自动设 `research`。
+
+### 9.3 三阶段审查流程
+
+> **参考实践**：superpowers（implementer → spec reviewer → code quality reviewer串行）、TradingAgents（Bull vs Bear辩论）
+
+**阶段 1：方案审查（Plan Review）**——high/standard 任务

 ```
-Agent 完成产出 → status: review
+执行者提交 scope_declaration 到黑板 decisions 表
    ↓
-Daemon tick → spawn 司马懿审核
+挑战者审查方案
+    ├── high：对抗辩论（正方 vs 反方 → 庞统裁决）
+    └── standard：单审（指定挑战者，默认司马懿）
    ↓
-司马懿读黑板(产出 + 决策 + 观察)
-    ↓
-司马懿写评论:
-  - "通过" → status: done
-  - "不通过,原因:XXX" → status: pending(打回重做)+ 评论说明问题
-    ↓
-如果有争议:
-  - 评论中讨论
-  - 讨论不清 → @user 请求裁定
+通过 → 进入执行
+未通过 → 协商修改（max_rounds 轮）
+    └── 超轮次 → 升级用户
 ```

-### 9.4 决策记录
+方案审查 vs Scope Guard（课题1）：
+- Scope Guard 是过程中的软检查（L2 sub 异步，发现问题写 observation）
+- 方案审查是正式评审（L3 Agent 审查，通过/打回有 verdict）

-Agent 执行过程中的每个关键决策都必须记录在黑板的 decisions 表中:
+**阶段 2：执行 + Guardrail 自动检查**——所有任务

-| 字段 | 含义 |
-|------|------|
-| decider | 谁做的决策 |
-| decision | 决策内容(选了什么) |
-| rationale | 为什么这样选 |
-| alternatives | 被排除的选项 |
+```
+执行者按方案执行
+    ↓
+每次写 output 时 Daemon 自动触发 Guardrail
+    ├── L1 机械检查（文件存在/JSON格式/字段非空）→ 不通过直接打回
+    ├── L2 轻量 AI 检查（Schema校验/artifacts路径验证）→ 不通过写 observation
+    └── L3 安全红线（tripwire：如直接操作生产环境）→ 立即中断
+    ↓
+Guardrail 通过 → 进入产出审查
+```

-**哪怕是自己做的决策也要填一条。** 目的:
- 后续复盘时能追溯"当时为什么这样选"
- 审核时司马懿能理解决策背后的思考
- 经验沉淀的原始素材
+**阶段 3：产出审查（Output Review）**——high/standard 任务

-### 9.5 分级审查矩阵
+```
+执行者提交产出到黑板 outputs 表
+    ↓
+挑战者审查产出（质量/完整性/与方案一致性）
+    ↓
+评审结果结构化记录到 reviews 表
+    ↓
+通过 → status: review → done
+未通过 → status: review → working（打回重做）
+    └── 协商在 comments 表
+    └── 超轮次 → 升级用户
+```

-不是所有任务都值得同等深度的审查。按任务风险等级决定审查深度。
+### 9.4 审查协议注册表（Review Protocol Registry）

-| 风险等级 | 任务类型 | 审查深度 | 参与者 |
-|---------|---------|---------|--------|
-| **高风险** | 量化策略、生产部署、数据删除 | 三阶段审查(方案审查→Output Guardrail→产出审查)+ 可选多视角对抗 | 庞统+司马懿+对应执行者 |
-| **标准** | 编码、数据处理、配置修改 | 二阶段(Output Guardrail + 产出审查) | 司马懿+执行者 |
-| **低风险** | 调研报告、文档更新、日志查看 | 一阶段(Output Guardrail 机械检查) | Daemon 自动 |
-| **调研** | 技术调研、方案探索 | 一阶段(庞统确认方向) | 庞统 |
+> **参考实践**：
+> - **superpowers**：三个独立 prompt 文件（implementer/spec-reviewer/code-quality-reviewer），每个角色有专属模板
+> - **oh-my-claudecode Critic**：Investigation Protocol 分 Phase（预判→验证→多视角→缺口分析→自审），不同 artifact type 自动切换视角
+> - **superpowers spec-reviewer**：prompt 注入对抗性指令（"DO NOT trust the report. Read the actual code."）

-**风险等级**:庞统创建任务时标注。默认值为 `standard`。庞统的 Skill 中内置规则:创建 task_type 为 `strategy` 或 `deploy` 的任务时自动设为 `high`,`research` 类型自动设为 `research`。无需庞统手动判断。
+**问题**：审查者容易陷入局部审查（编码规范/编译通过），漏掉本质问题（需求一致性/语义正确性）。被挑战后一律照改不加思考。

-**设计推导**:
- v1.0 实践:每个节点都要司马懿审查,简单任务过重
- superpowers:三阶段审查(implementer → spec reviewer → code quality reviewer),不同阶段不同深度
- Hermes:per-task retry budget,任务级别差异化
+**方案**：审查协议是代码注入的，不是靠 Agent 自己找 Skill。Daemon spawn 审查者时动态加载协议模板。
+
+```
+review_protocols/
+├── plan_review.yaml          # 方案审查协议
+├── output_review.yaml        # 产出审查协议
+├── guardrail_l2.yaml         # L2 轻量AI检查协议
+└── analysis_review.yaml      # 分析/调研审查协议
+```
+
+每个协议定义四个维度：
+
+| 维度 | 内容 | 参考 |
+|------|------|------|
+| 审查维度（审什么） | dimensions 列表，每个有 weight（critical/major/minor）和 method | superpowers 三种 reviewer 各自的关注点 |
+| 审查方法（怎么审） | investigation_protocol 分阶段执行 | oh-my-claudecode Critic 五阶段 Protocol |
+| 多视角 | 按 artifact type 切换视角集 | Critic 代码视角（安全/新人/运维） vs 方案视角（执行者/利益相关者/怀疑论者） |
+| 对抗性指令 | adversarial_instructions 防止走过场 | superpowers spec-reviewer "DO NOT trust" 指令 |
+
+**Investigation Protocol 通用模式**（参考 Critic，各协议按场景裁剪）：
+
+```
+Phase 1 预判（Pre-commitment）：先不读产出，凭领域经验预测3-5个最可能出问题的点
+Phase 2 验证（Verification）：读实际产出（不是报告），逐条验证
+Phase 3 多视角（Multi-perspective）：从不同角色看产出
+Phase 4 缺口分析（Gap Analysis）：不只看"什么有问题"，还看"什么缺失了"
+Phase 5 自审（Self-audit）：给每个 finding 打 confidence，低 confidence 降级
+```
+
+**多视角矩阵**：
+
+| 审查类型 | 多视角集合 |
+|---------|----------|
+| output_review（代码） | 安全 / 新人 / 运维 |
+| plan_review（方案） | 执行者 / 利益相关者 / 怀疑论者 |
+| analysis_review（调研） | 领域专家 / 实践者 / 反方辩手 |
+| guardrail_l2（轻量） | 无多视角 |
+
+### 9.5 反驳权（Rebuttal Phase）
+
+> **参考实践**：TradingAgents Bull vs Bear 模式——双方都有表达权
+
+审查不是单向的。审查者提交 review 后，Daemon spawn 原执行者做反驳：
+
+```
+审查者提交 review（issues 列表）
+    ↓
+Daemon spawn 原执行者，注入反驳指令：
+    "对每个 issue，明确表态：ACCEPT / REJECT / PARTIAL
+     不允许全部接受不加思考。"
+    ↓
+执行者 response 写入 comments 表
+    ↓
+REJECT → Daemon spawn 审查者看 response → 继续协商
+全部 ACCEPT → 修改后重提交 → 审查者 re-review
+```
+
+### 9.6 评审结果结构化存储（reviews 表）
+
+> **参考实践**：
+> - **Hermes**：Comment 的 metadata JSON 承载结构化数据
+> - **SWE-agent**：Trajectory 线性追加，不修改历史
+> - **GitHub PR Review**：APPROVE / REQUEST_CHANGES / COMMENT 三种 verdict
+
+**设计原则**：追加写入不修改历史（SWE-agent），黑板索引+文件详情（课题2），结构化 verdict（GitHub PR Review）。
+
+```sql
+CREATE TABLE IF NOT EXISTS reviews (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL,
+    output_id TEXT,
+    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);
+```
+
+**Guardrail 检查结果也入 reviews 表**（`reviewer='system'`, `review_type='guardrail'`）。
+
+**comments 表和 reviews 表职责分离**：
+
+| 表 | 职责 | 内容 | verdict |
+|---|------|------|---------|
+| comments | 讨论、@mention、协商过程 | 自然语言 | ❌ 无 |
+| reviews | 正式评审结论 | 结构化 JSON | ✅ 必须有 |
+
+### 9.7 协商流程与状态机对齐
+
+**现有状态机**：`pending → claimed → working → review → done`
+
+| 状态转换 | 触发条件 | 对应阶段 |
+|---------|---------|---------|
+| 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 |
+
+low 风险任务：working → [Guardrail 自动检查] → done（跳过 review 状态）
+research 任务：working → [庞统确认] → review → done
+
+### 9.8 声明式 Guardrail 配置
+
+> **参考实践**：OpenAI Agent SDK `@output_guardrail` 装饰器、v1.0 M4 Guard、SonarQube rule_id 模式
+
+```yaml
+# guardrails.yaml
+task_types:
+  coding:
+    output_guardrails:
+      - name: file_exists
+        check: "output.files | length > 0"
+        severity: blocking
+        layer: L1
+      - 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
+      - name: code_quality
+        check: "scope_declaration vs task.truths"
+        severity: warning
+        layer: L2
+    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
+
+  research:
+    output_review:
+      required: true
+      reviewer: "pangtong-fujunshi"
+      mode: single_reviewer
+      max_rounds: 2
+```
+
+### 9.9 Full Agent vs Subagent vs Daemon 直接执行
+
+> **参考实践**：
+> - **superpowers**：Implementer/Spec Reviewer/Code Quality Reviewer 都是 Task tool dispatch 的 subagent，各自独立 prompt 和模型
+> - **oh-my-claudecode**：Critic 被禁止 Write/Edit 工具（disallowedTools），角色隔离
+> - **open-multi-agent**：TaskQueue 维护 agent pool，scheduler 按 capability-match 分配
+
+**判据**：
+
+| 问题 | Full Agent | Subagent | Daemon 直接执行 |
+|------|-----------|---------|----------------|
+| 需要独立身份/人格？ | ✅ | ❌ | ❌ |
+| 需要 Agent 专属工具？ | ✅ | ❌ 通用工具 | 不需要 AI |
+| 任务复杂度 | 编码/审查/调研/决策 | 单一检查/快速评估 | 格式校验/文件检查 |
+| 需要写黑板？ | ✅ | ❌ 只返回 pass/fail | 只改状态 |
+| 需要多轮交互？ | ✅ | ❌ 一次性 | 一次性 |
+
+**场景映射**：
+
+| 场景 | 方式 | OpenClaw API | 理由 |
+|------|------|-------------|------|
+| 执行者编码/数据/部署 | Full Agent | `openclaw agent --agent <id>` | 需要身份+专属工具 |
+| 挑战者审查 | Full Agent | `openclaw agent --agent simayi-challenger` | 需要质量守门人角色+多轮 |
+| 执行者反驳 | Full Agent（原 Agent） | `openclaw agent --agent <原执行者>` | 需要原执行者身份 |
+| 庞统规划/裁决 | Full Agent（隔离session） | `openclaw agent --agent pangtong-fujunshi --session-id <new>` | 避免主session上下文膨胀 |
+| L2 Guardrail AI 检查 | Subagent | `sessions_spawn(task=...)` | 单一检查、无身份 |
+| Scope Guard 异步检查 | Subagent | `sessions_spawn(task=...)` | 轻量一次性 |
+| L1 机械校验 | 不走 AI | Daemon 直接执行 | 纯机械操作 |
+
+**简化规则**：黑板上有名字的角色走 Full Agent。无名字的一次性检查走 Subagent。纯机械检查 Daemon 自己做。
+
+**庞统主 session 隔离策略**：主 session 做轻量调度（L1构建、状态检查）。复杂的任务拆解和裁决 spawn 隔离 session，避免上下文膨胀。
+
+### 9.10 对抗辩论模式（high 风险任务）
+
+> **参考实践**：TradingAgents Bull vs Bear → Research Manager 裁决
+
+```
+正方（执行者）：scope_declaration，论证方案可行性
+反方（挑战者池）：找方案漏洞、风险、遗漏
+    ↓
+庞统裁决：综合双方观点
+    ├── 认可正方 → 方案通过
+    ├── 认可反方 → 方案打回
+    └── 综合意见 → 要求修改后重新辩论
+```
+
+**挑战者池**（按任务类型选择，不是固定司马懿）：
+
+| 任务类型 | 默认挑战者 |
+|---------|----------|
+| 编码 | 司马懿 |
+| 风控 | 关羽 |
+| 数据 | 赵云（数据质量视角） |
+| 部署 | 姜维 |

 ---