From 988f7adc9ec6b2705b2076e1fc0d1ddd7fc7c43c Mon Sep 17 00:00:00 2001 From: cfdaily Date: Fri, 15 May 2026 21:21:48 +0800 Subject: [PATCH] auto-sync: 2026-05-15 21:21:48 --- docs/design/architecture-v2.6.md | 351 ++++++++++++++++++++++++++----- 1 file changed, 302 insertions(+), 49 deletions(-) diff --git a/docs/design/architecture-v2.6.md b/docs/design/architecture-v2.6.md index a95c61a..5e7345d 100644 --- a/docs/design/architecture-v2.6.md +++ b/docs/design/architecture-v2.6.md @@ -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 ` | 需要身份+专属工具 | +| 挑战者审查 | Full Agent | `openclaw agent --agent simayi-challenger` | 需要质量守门人角色+多轮 | +| 执行者反驳 | Full Agent（原 Agent） | `openclaw agent --agent <原执行者>` | 需要原执行者身份 | +| 庞统规划/裁决 | Full Agent（隔离session） | `openclaw agent --agent pangtong-fujunshi --session-id ` | 避免主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，论证方案可行性 +反方（挑战者池）：找方案漏洞、风险、遗漏 + ↓ +庞统裁决：综合双方观点 + ├── 认可正方 → 方案通过 + ├── 认可反方 → 方案打回 + └── 综合意见 → 要求修改后重新辩论 +``` + +**挑战者池**（按任务类型选择，不是固定司马懿）： + +| 任务类型 | 默认挑战者 | +|---------|----------| +| 编码 | 司马懿 | +| 风控 | 关羽 | +| 数据 | 赵云（数据质量视角） | +| 部署 | 姜维 | ---