From 813c1d21b635bb2a8138014023ca475cf966359a Mon Sep 17 00:00:00 2001 From: cfdaily Date: Fri, 15 May 2026 21:19:39 +0800 Subject: [PATCH] auto-sync: 2026-05-15 21:19:39 --- .../topic3-challenge-review-proposal.md | 231 ++++++++++++++++++ 1 file changed, 231 insertions(+) diff --git a/docs/design/topic3-challenge-review-proposal.md b/docs/design/topic3-challenge-review-proposal.md index 6c60a45..ba6c80e 100644 --- a/docs/design/topic3-challenge-review-proposal.md +++ b/docs/design/topic3-challenge-review-proposal.md @@ -408,6 +408,234 @@ Daemon spawn 挑战者 2. 挑战者的 review summary（reviews 表最新一条） 3. 协商过程的 comments（L2 按需读取） +### D3-9：审查协议注册表（Review Protocol Registry） + +> **参考实践**： +> - **superpowers**：三个独立 prompt 文件——`implementer-prompt.md`、`spec-reviewer-prompt.md`、`code-quality-reviewer-prompt.md`，每个角色有专属模板，不是笼统的"请审查" +> - **oh-my-claudecode Critic**：Investigation Protocol 分 Phase 执行（预判→验证→多视角→缺口分析→自审），不同 artifact type 自动切换视角（代码→安全/新人/运维，方案→执行者/利益相关者/怀疑论者） +> - **superpowers spec-reviewer**：prompt 注入对抗性指令——"DO NOT trust the report. Read the actual code.""Compare to requirements line by line." + +**问题**：审查者不知道自己该审什么，容易陷入局部审查（编码规范、编译通过），漏掉本质问题（需求一致性、语义正确性）。或者被挑战后一律照改，不加思考。 + +**根因**：审查指令是笼统的"请审查"，审查者靠"自觉"决定审什么。Skill 是软引导，可看可不看。 + +**方案**：审查协议是代码注入的，不是靠 Agent 自己去找的。Daemon spawn 审查者时，根据任务类型 + 审查类型动态加载协议模板，注入到 bootstrap 消息中。 + +``` +review_protocols/ +├── plan_review.yaml # 方案审查协议 +├── output_review.yaml # 产出审查协议 +├── guardrail_l2.yaml # L2 轻量AI检查协议 +└── analysis_review.yaml # 分析/调研审查协议 +``` + +每个协议文件定义四个维度： + +**维度1：审查维度（审什么）** + +```yaml +# review_protocols/output_review.yaml（示例片段） +dimensions: + - id: requirement_traceability + description: "每个 must_have truth 是否被覆盖" + weight: critical + method: "逐条比对 truths → 产出代码/文件" + + - id: scope_alignment + description: "产出是否与 scope_declaration 一致" + weight: critical + method: "对比 decisions.scope_declaration vs 实际产出" + + - id: correctness + description: "逻辑是否正确" + weight: major + method: "追踪执行路径，验证关键逻辑" + + - id: completeness + description: "是否有遗漏" + weight: major + method: "缺口分析：什么缺失了？什么假设未被验证？" + + - id: constraint_compliance + description: "是否遵守约束" + weight: major + method: "逐条检查 tasks.constraints" +``` + +**维度2：审查方法（怎么审）**——参考 oh-my-claudecode Critic 的 Investigation Protocol + +```yaml +investigation_protocol: + phases: + - name: pre_commitment + instruction: > + 先不读产出，凭领域经验预测3-5个最可能出问题的点。 + 写下预测。然后逐个验证。这迫使主动搜索而非被动阅读。 + + - name: verification + instruction: > + 读实际产出（不是报告），逐条验证每个 truth。 + 提取所有文件引用、函数名、API 调用，逐一对照源码验证。 + 模拟执行每个步骤，不只读文字描述。 + + - name: multi_perspective + instruction: > + 从不同角色看这份产出： + - 安全视角：什么信任边界被跨越？什么输入没校验？ + - 新人视角：不熟悉代码的人能理解吗？什么上下文被假设但没说明？ + - 运维视角：规模化后怎样？依赖失败时怎样？爆炸半径多大？ + + - name: gap_analysis + instruction: > + 不只看"什么有问题"，还看"什么缺失了"。 + 问：什么会破坏这个？什么边界情况没处理？什么假设可能是错的？ + + - name: self_audit + instruction: > + 给自己的每个 finding 打 confidence（HIGH/MEDIUM/LOW）。 + LOW confidence → 降级为 Open Question。 + "作者能立刻反驳吗？"如果能 → 降级。 + "这是真正的缺陷还是风格偏好？"如果是偏好 → 降级。 +``` + +不同审查类型用不同的 multi_perspective 视角集（参考 Critic 的代码视角 vs 方案视角分离）： + +| 审查类型 | 多视角集合 | +|---------|----------| +| `output_review`（代码产出） | 安全 / 新人 / 运维 | +| `plan_review`（方案） | 执行者 / 利益相关者 / 怀疑论者 | +| `analysis_review`（调研分析） | 领域专家 / 实践者 / 反方辩手 | +| `guardrail_l2`（轻量检查） | 无多视角（单一维度快速检查） | + +**维度3：对抗性指令（防止走过场）**——参考 superpowers spec-reviewer 的"DO NOT trust"指令 + +```yaml +adversarial_instructions: + - "DO NOT trust the implementer's report. Read the actual code/files." + - "If something looks correct on the surface, verify it works in context." + - "Not just what's wrong — also check what's MISSING." + - "Accept findings only with evidence (file:line or specific quote). No evidence = opinion." + - "If you find 1 CRITICAL or 3+ MAJOR issues, escalate to adversarial mode: actively hunt for more problems, challenge every design decision, expand scope to adjacent code." + - "Also check for EXTRA/UNNEEDED work that wasn't requested." +``` + +**维度4：输出格式** + +```yaml +output_schema: "schemas/review-output.schema.json" +verdict_options: ["approved", "rejected", "needs_revision", "approved_with_reservations"] + +required_fields: + - verdict + - summary + - issues[] (each with severity, description, evidence) + - confidence (0.0-1.0) +``` + +**Daemon 拼接逻辑**： + +```python +def build_reviewer_bootstrap(task, review_type): + # 1. 加载协议模板 + protocol = load_protocol(f"review_protocols/{review_type}.yaml") + + # 2. 注入任务上下文（ truths, constraints, scope_declaration） + protocol.inject_context(task) + + # 3. 拼接成 L1 bootstrap 消息 + # 审查者收到的消息 = 角色定义 + 审查协议 + 任务上下文 + 必读材料 + return format_reviewer_bootstrap(protocol, task) +``` + +**防止"一律照改"——反驳权（Rebuttal Phase）**： + +审查不是单向的。审查者提交 review 后，Daemon spawn 原执行者做反驳： + +``` +审查者提交 review（issues 列表） + ↓ +Daemon spawn 原执行者，注入反驳指令： + "你收到了一份审查意见。对每个 issue，你必须明确表态： + ACCEPT（接受并修改）/ REJECT（拒绝，说明为什么）/ PARTIAL（部分接受） + 不允许全部接受不加思考。" + ↓ +执行者 response 写入 comments 表 + ↓ +如果是 REJECT → Daemon spawn 审查者看 response → 继续协商 +如果全部 ACCEPT → 修改后重新提交 → 审查者 re-review +``` + +### D3-10：OpenClaw 集成——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 分配任务 + +**问题**：什么任务需要完整的 Agent 身份（SOUL/IDENTITY/MEMORY），什么任务只需要无身份的 AI Worker？ + +**判据：五个问题** + +| 问题 | 走 Full Agent | 走 Subagent | Daemon 直接执行 | +|------|-------------|-----------|--------------| +| 需要独立身份/人格吗？ | ✅ 司马懿的"质量守门人" | ❌ | ❌ | +| 需要 Agent 专属工具吗？ | ✅ 关羽的风控工具 | ❌ 通用 exec/read 就够 | 不需要 AI | +| 任务复杂度 | 编码、审查、调研、决策 | 单一检查、快速评估 | 格式校验、文件存在检查 | +| 需要写黑板吗？ | ✅ 写 review/output/decision | ❌ 只返回 pass/fail | 只改状态 | +| 需要多轮交互吗？ | ✅ 协商、反驳、辩论 | ❌ 一次性的 | 一次性的 | + +**对应到我们的场景**： + +| 场景 | 走什么 | OpenClaw API | 理由 | +|------|--------|-------------|------| +| 张飞编码 | Full Agent | `openclaw agent --agent zhangfei-dev` | 需要身份、编码工具 | +| 司马懿产出审查 | Full Agent | `openclaw agent --agent simayi-challenger` | 需要质量守门人角色、多轮协商 | +| 执行者反驳审查 | Full Agent（原 Agent） | `openclaw agent --agent <原执行者>` | 需要原执行者的身份和上下文 | +| 庞统任务规划 | Full Agent | `openclaw agent --agent pangtong-fujunshi` | 需要副军师角色、决策能力 | +| 庞统冲突裁决 | Full Agent（隔离 session） | `openclaw agent --agent pangtong-fujunshi --session-id ` | 避免主 session 上下文膨胀 | +| 赵云数据下载 | Full Agent | `openclaw agent --agent zhaoyun-data` | 需要数据工具、NAS 操作 | +| 姜维部署 | Full Agent | `openclaw agent --agent jiangwei-infra` | 需要 Docker/PM2 工具 | +| L2 Guardrail AI 检查 | Subagent | `sessions_spawn(task=...)` | 单一检查、不需要身份 | +| Scope Guard 异步检查 | Subagent | `sessions_spawn(task=...)` | 轻量、一次性 | +| L1 机械校验（文件存在/JSON格式） | **不走 AI** | Daemon 直接执行 | 纯机械操作，不需要 AI | + +**简化规则**：黑板上有名字的角色（庞统/司马懿/张飞/关羽/赵云/姜维）走 Full Agent。没有名字的一次性检查走 Subagent。纯机械检查 Daemon 自己做。 + +**OpenClaw spawn 具体实现**： + +```python +def spawn_agent(agent_id, task_id, mandate): + """Spawn Full Agent（有身份、有专属工具）""" + session_id = f"moziplus-{task_id}-{agent_id}-{uuid4().hex[:8]}" + bootstrap_msg = format_mandate_message(mandate) + + subprocess.run([ + "openclaw", "agent", + "--agent", agent_id, + "--session-id", session_id, + "--message", bootstrap_msg + ], capture_output=True, text=True) + + # 记录到黑板 events 表 + blackboard.execute( + "INSERT INTO events (task_id, event_type, data) VALUES (?, 'agent_spawned', ?)", + task_id, json.dumps({"session_id": session_id, "agent_id": agent_id}) + ) + +def spawn_subagent(task_id, task_description, context=None): + """Spawn Subagent（无身份、通用工具、一次性）""" + # 通过 OpenClaw API spawn 轻量 worker + # 返回结果直接处理，不写入黑板 reviews 表 + # 适用于 L2 Guardrail、Scope Guard 等轻量检查 + pass +``` + +**庞统主 session 的隔离策略**： + +庞统主 session 做轻量调度（L1 构建、状态检查、黑板 tick 处理）。复杂的任务拆解和裁决 spawn 一个 pangtong-fujunshi 的隔离 session，避免主 session 上下文膨胀（课题2 D2-6：不需要 Auto-compact，但庞统是唯一可能有累积的 session）。 + +--- + ## 5. 遗留 TODO | # | 待解决事项 | 归属 | 说明 | @@ -419,6 +647,9 @@ Daemon spawn 挑战者 | T3-5 | confidence 低于阈值自动升级 | Phase 2 | 如 confidence < 0.7 升级庞统 | | T3-6 | 评审详情文件的 Schema 定义 | Phase 2 | detail_path 指向的 JSON 结构 | | T3-7 | low 风险任务 Guardrail 自动通过的流控 | Phase 2 | 自动跳过 review 状态 | +| T3-8 | Review Protocol 模板文件编写 | Phase 2 | 4个 YAML 协议文件 + Daemon 加载逻辑 | +| T3-9 | 反驳权（Rebuttal Phase）的 Daemon 流控 | Phase 2 | review 提交后自动 spawn 原执行者反驳 | +| T3-10 | Full Agent vs Subagent 的 Daemon 调度逻辑 | Phase 2 | 根据任务类型自动选择 spawn 方式 | ## 6. 和现有设计的对齐检查