本文档是对 v2 架构的深度技术解读，面向希望理解系统设计原理的开发者和研究者。
本系统的核心结构是一个五阶段顺序流水线，每个阶段由专职 Agent 主导，阶段间通过 orchestrator 做决策切换：
用户需求
│
▼
┌─────────────────────────────────────────────────────────┐
│ orchestrator（瘦身后主控器） │
│ │
│ 不做执行，只做： │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 上下文同步 │ │ 结果收集 │ │ 全局监听 │ │ 阶段切换 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 打回路由 │ │ 用户交互 │ │ 复盘沉淀 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────┬───────────────────────────────────┘
│
┌─────────────────┼──────────────────┐
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────────┐
│ Phase 1│ │ Phase 2│ │ Phase 3 │
│ 需求拆解│ ───→ │ 原型定型│ ────→ │ 架构开发测试 │
│ │ │ │ │ │
│analyst │ │designer│ │ runner │
│planner │ │ │ │ ├─coder │
│ │ │ │ │ ├─researcher│
│ │ │ │ │ └─writer │
└────────┘ └────────┘ └────────────┘
↑ ↑ ↑
│ ┌────────────────┐ │
└───────│ Phase 4 │──────────┘
│ 打回循环 │
│ (最小回退) │
└───────┬────────┘
▼
┌────────────────┐
│ Phase 5 │
│ 整合交付+复盘 │
└────────────────┘
Layer 1: orchestrator（全局调度）
└── 只管"谁在哪个阶段做什么"，不管"怎么做"
└── spawn Phase 1~3 的主导 Agent，监听结果，决策阶段切换
Layer 2: pm-runner（开发阶段二级调度）
└── 管理开发阶段的子Agent生命周期
└── 按DAG批次调度 coder/researcher/writer
└── 策略引擎自动处理阻塞/恢复
Layer 3: pm-coder/researcher/writer（执行层）
└── 实际干活的人
└── 被 runner 调度，结果上报给 runner
关键设计：runner 不能自行决定打回，只能上报 orchestrator。这避免了局部视角导致的错误回退。
| Agent | 阶段 | 层级 | 核心产出 | 对齐校准 |
|---|---|---|---|---|
| pm-orchestrator | 全局 | L1调度 | HEARTBEAT + 决策 | Goal constraints |
| pm-analyst | P1 | L2执行 | product.md + goal.md + requirements.md | 用户追问≥3轮 |
| pm-planner | P1 | L2执行 | modules.md + dependency-dag.md + tasks.md + skills-needed.md | Goal success_criteria |
| pm-designer | P2 | L2执行 | wireframe.html + component-tree.md + routes.md | Goal + Modules 全覆盖 |
| pm-runner | P3 | L2调度 | 架构方案评估 + 任务调度 + 产出整合 | 原型设计（校准基准） |
| pm-coder | P3 | L3执行 | 可运行代码 + 测试 | 原型 + 架构方案 |
| pm-researcher | P3 | L3执行 | 调研报告 | 任务需求 |
| pm-writer | P3 | L3执行 | PRD + 技术文档 | Goal + 代码产出 |
问题：传统开发流程中，需求→编码是直通的，常出现"编码完了发现方向不对"的浪费。
解决：在需求和编码之间插入独立的原型设计阶段（Phase 2）。
传统流程： 需求 ──────────────────→ 编码 ──→ 测试
↑ 方向不对时才发现，浪费巨大
v2流程： 需求 ──→ 原型(校准基石) ──→ 编码 ──→ 测试
↑ ↑
用户确认 编码必须对齐原型
方向在此锁定 偏差在此发现
原理：原型阶段相当于一个低成本的快速试错点。修改线框图的成本远低于修改代码。原型经 orchestrator + 用户双重确认后，成为后续所有开发工作的"真北"。
落地机制：
- pm-coder 的 spawn prompt 首行注入"请读取原型设计，你的开发必须对齐原型"
- RC-P3-02 验证点：每完成一个模块，自动检查代码 vs 原型一致性
- 代码与原型不符 → 不通过验证，打回该模块修复
问题：Agent 链式推理中，早期错误会沿链路放大（错误级联效应）。比如需求理解偏差 → 原型方向偏 → 代码全错。
灵感来源：DeepSeek-R1 的"推理链检查点"思想。
解决：在关键决策节点设置9个验证点，Agent 必须暂停推理、输出显式验证步骤：
Agent 执行流程:
Step 1 → Step 2 → [验证点] → Step 3 → Step 4 → [验证点] → Step 5
│ │
暂停推理 暂停推理
输出验证步骤 输出验证步骤
通过才继续 通过才继续
9个验证点分布：
| 验证点 | 阶段 | 验什么 | 防什么 |
|---|---|---|---|
| RC-P1-01 | P1 | 需求理解是否准确 | 需求偏差级联 |
| RC-P1-01b | P1 | 拆解是否完整 | 漏掉模块 |
| RC-P2-01 | P2 | 原型是否覆盖所有功能 | 功能遗漏 |
| RC-P2-02 | P2 | 用户是否确认原型 | 方向错误 |
| RC-P3-01 | P3 | 架构方案是否可行 | 技术死胡同 |
| RC-P3-02 | P3 | 代码是否对齐原型 | 实现偏差 |
| RC-P3-02a | P3 | 代码与原型一致性 | 代码漂移 |
| RC-P4-01 | P4 | 打回原因是否准确 | 错误回退 |
| RC-P5-01 | P5 | 模块间是否一致 | 集成问题 |
关键设计：验证点不通过时的动作是最小范围修复，不是全盘重来。例如 RC-P3-02 不通过 → 只打回该模块修复，不影响已验收模块。
问题：如果只评估个体产出质量，Agent 可能"自顾自"——产出自己看着好但下游没法用的东西。
灵感来源：协作强化学习的"团队奖励"思想（ReSo 论文）。
解决：奖励信号 = 个体质量(50%) + 协作正外部性(50%) + 惩罚
total_reward = IQ(50%) + CE(50%) + PN(-)
IQ（个体质量）:
├─ 交付物质量 (30%) ← 三角验证置信度
└─ 约束合规 (20%) ← 硬/软约束违反次数
CE（协作正外部性）:
├─ 下游便利度 (20%) ← 下游是否无需额外澄清
├─ 信息同步 (10%) ← HEARTBEAT更新及时率
├─ 可复用性 (10%) ← 产出是否可跨模块复用
└─ 冲突避免 (10%) ← 是否主动避免文件冲突
PN（惩罚）:
├─ 下游阻塞 (-30%) ← 导致下游无法继续
└─ 打回连锁 (-20%) ← 导致跨阶段打回
归一化: total_reward ∈ [-0.5, 1.0]
使用方式：奖励分数不用于实时决策（避免过拟合），只用于 Phase 5 复盘时：
- 低分 Agent → Skill 规范优先改进
- 连续3项目低分 → 触发 Skill 重写
- 高分模式 → 沉淀为最佳实践
问题：传统做法是让2个 Agent 各提一个方案然后对比，但真实架构决策往往涉及多个独立的决策点（状态管理、数据层、路由架构等），每个点又有多种选择。简单两路对比会错过最优组合。
灵感来源：MARTI-MARS² 论文的"树搜索"思想。
解决：将架构讨论建模为多决策点的树搜索：
架构讨论（树搜索）:
Step 1: 识别决策点
┌─ 决策点1: 状态管理
├─ 决策点2: 数据层
└─ 决策点3: 路由架构
Step 2: 每个决策点生成候选
决策点1: Pinia / Vuex4 / Zustand
决策点2: REST+SWR / GraphQL / tRPC
决策点3: 文件路由 / 配置路由
Step 3: 局部评估 + 剪枝
对每个决策点独立评分，剪除低分选项
决策点1: Pinia(0.9) ✅ / Vuex4(0.7) ❌ / Zustand(0.85) ✅
决策点2: REST+SWR(0.85) ✅ / GraphQL(0.65) ❌
决策点3: 文件路由(0.8) ✅ / 配置路由(0.75) ✅
Step 4: 全局组合优化
组合A: Pinia + REST+SWR + 文件路由 → 一致性检查 ✅
组合B: Zustand + REST+SWR + 配置路由 → 一致性检查 ✅
Step 5: 上报 orchestrator 最终决策
与简单对比的区别：
- 简单对比：2个完整方案 → 选一个 → 可能某个方案在A点好但在B点差
- 树搜索：N个决策点 × M个候选 → 局部剪枝 → 全局组合 → 最优组合可能来自不同方案的不同部分
问题：传统验收要么是任务级的（太细碎），要么是项目级的（太晚发现问题）。打回要么不分范围全退，要么不知退到哪里。
解决：
验收粒度：以模块为单位验收，而不是以任务为单位。一个模块包含多个任务，模块验收更有实际意义——用户不关心"登录API写完了"，关心的是"认证模块可以用了"。
打回路由：orchestrator 维护一张打回路由表，每次打回退到"最小必要回退点"：
问题类型 → 最小回退目标
─────────────────────────────────
原型不通过 → Phase 1 局部需求补充（不是全部重来）
架构不可行 → Phase 2 原型调整
代码与原型不符 → Phase 3 架构调整（不动原型）
测试不通过 → Phase 3 开发修复（不动架构）
模块验收不通过 → 最小必要回退点
关键约束：
- 每模块最多打回3次
- 打回必须有反馈
- runner 不能自行决定打回，只能上报（避免局部视角误判）
- 已验收通过的模块不受打回影响
问题：同一个 LLM 扮演不同角色时，容易"串台"——分析师开始写代码，编码者开始做架构决策。
解决：每个 Agent 的 Harness 定义了差异化约束，从运行层面限制行为边界：
# 分析师：不允许产出代码，必须追问
analyst_harness:
mode: "default" # 需要与用户交互
max_turns: 25
constraints:
- 只能产出需求文档，不能产出代码
- 必须追问至少3轮才可结束澄清
# 编码者：允许写代码，但必须对齐原型
coder_harness:
mode: "acceptEdits" # 需要创建/修改文件
max_turns: 50
constraints:
- 开发必须对齐原型设计
- 代码与原型不符需主动上报原理：Harness 约束在 prompt 层面注入，相当于给每个 Agent 一套"行为宪法"。约束不是建议，是硬规则——违反硬约束会触发 constraint_escalate 策略，立即通知用户。
子Agent 的 prompt 不是一个大字符串，而是按三层组织：
┌─────────────────────────────────┐
│ Layer 1 — Identity（身份层） │ SKILL.md 核心内容 + Goal 定义
│ ┌─────────────────────────────┐│ 静态，永不改变
│ │ Layer 2 — Narrative（叙事层）││ 从 HEARTBEAT + 上下文池动态构建
│ │ ┌─────────────────────────┐││ 每次子Agent启动时拼接
│ │ │ Layer 3 — Focus（焦点层）││ 具体任务 + 输出格式 + 工具约束
│ │ │ │││ 每次切换任务时替换
│ │ └─────────────────────────┘││
│ └─────────────────────────────┘│
└─────────────────────────────────┘
好处：
- 身份层不变，确保 Agent 角色稳定
- 叙事层动态更新，确保上下文同步
- 焦点层精确聚焦，确保任务清晰
- 避免每次重写完整 prompt，减少 token 浪费
用户："帮我做一个个人知识管理工具"
│
▼
┌──── orchestrator ────┐
│ 创建 HEARTBEAT.md │
│ 创建 context_pool/ │
│ │
│ spawn pm-analyst ────┼──→ 【追问3轮】
│ │ Q: 什么类型？Web/桌面？
│ │ Q: 核心功能？编辑/搜索/存储？
│ │ Q: 技术偏好？用户群？
│ │
│ │ ←── goal.md + product.md + requirements.md
│ │
│ [RC-P1-01] 验证需求理解
│ ├── 需求摘要 → 用户确认 ✅
│ └── In/Out Scope 一致性 ✅
│ │
│ spawn pm-planner ────┼──→ 【颗粒化拆解】
│ │ 功能点提取 → 模块分组 → 依赖DAG
│ │ Skills分析 → 批次规划
│ │
│ │ ←── modules.md + dependency-dag.md + tasks.md + skills-needed.md
│ │
│ [RC-P1-01b] 验证拆解完整性
│ ├── 每个模块≤5功能点 ✅
│ ├── DAG无环 ✅
│ └── 每模块有验收标准 ✅
│ │
│ 审核通过 → 进入 Phase 2 │
└──────────────────────┘
关键文件流转：
analyst 写 → context_pool/goal.md ← planner 读
analyst 写 → context_pool/product.md ← planner 读
analyst 写 → context_pool/requirements.md ← planner 读
planner 写 → context_pool/modules.md ← designer 读
planner 写 → context_pool/dependency-dag.md ← runner 读
planner 写 → context_pool/tasks.md ← runner 读
planner 写 → context_pool/skills-needed.md ← runner 读
┌──── orchestrator ────┐
│ spawn pm-designer ───┼──→ 【原型设计】
│ │ 读取 goal.md + modules.md
│ │ 交互流程设计（Mermaid图）
│ │ 组件树定义（语义化命名）
│ │ 页面路由规划
│ │ 低保真线框图（HTML+CSS）
│ │
│ 多方案设计（可选） │ 核心分歧点 → 2-3种方案
│ │ 方案A: 保守（成熟模式）
│ │ 方案B: 创新（更好但有风险）
│ │ 方案C: 简化（快速实现）
│ │
│ │ ←── wireframe.html + component-tree.md + routes.md
│ │
│ [RC-P2-01] 原型覆盖度验证
│ ├── 逐条对照 goal.md success_criteria ✅
│ ├── 逐模块对照 modules.md ✅
│ └── 交互流程完整性 ✅
│ │
│ [RC-P2-02] 原型用户确认
│ ├── 展示原型给用户
│ └── 用户确认 ✅ → 原型锁定为校准基石
│ │
│ 原型定型 → 进入 Phase 3│
└──────────────────────┘
原型为什么是校准基石：
- Phase 3 的所有 coder spawn prompt 首行注入"请读取原型，开发必须对齐"
- RC-P3-02 验证点：代码 vs 原型一致性检查
- 原型定型后不可绕过，任何偏离都需要显式验证
┌──── orchestrator ────┐
│ spawn pm-runner ─────┼──→ 【开发阶段管理】
│ │
│ ┌─── pm-runner ─────┼──────────────────────────┐
│ │ │ │
│ │ Step 1: 架构讨论（树搜索） │
│ │ spawn coder-A ──┼──→ 保守方案 │
│ │ spawn coder-B ──┼──→ 进取方案 │
│ │ spawn coder-C ──┼──→ 极简方案 │
│ │ │ │
│ │ [RC-P3-01] 架构可行性验证 │
│ │ ├── 覆盖原型所有组件 ✅ │
│ │ ├── 技术栈满足约束 ✅ │
│ │ └── 方案间无矛盾 ✅ │
│ │ │ │
│ │ 树搜索: │
│ │ 局部剪枝 → 全局组合 → 上报 orchestrator │
│ │ │ │
│ │ Step 2: Skills安装与验证 │
│ │ 检查 → ClawHub搜索 → 安装 → 验证 │
│ │ │ │
│ │ Step 3: 按DAG批次调度 │
│ │ Batch 1: [M001用户认证] │
│ │ spawn coder-T001 ──→ JWT认证API │
│ │ spawn coder-T002 ──→ 登录页面 │
│ │ │ │
│ │ Batch 2: [M002数据展示]（依赖M001） │
│ │ spawn coder-T003 ──→ 数据列表组件 │
│ │ spawn researcher ─→ 图表库选型 │
│ │ │ │
│ │ [RC-P3-02] 每模块完成时验证 │
│ │ 代码 vs 原型一致性 ← 校准基石发挥作用 │
│ │ │ │
│ │ Step 4: 模块测试 │
│ │ Step 5: 文档编写 │
│ │ │ │
│ │ 全部完成 → send_message 给 orchestrator │
│ └───────────────────┘ │
│ │ │
│ orchestrator 监听: │ │
│ ├── 三角验证（自验证+语义评估+人工判断） │
│ ├── 健康度监控（<30立即介入） │
│ └── 策略引擎（自动解阻塞/恢复/预警） │
└──────────────────────┘
模块验收不通过
│
▼
┌──── orchestrator 决策 ────┐
│ │
│ 1. 分析打回原因 │
│ 2. [RC-P4-01] 验证根因 │
│ ├── 原因准确？ │
│ ├── 回退目标是最小必要？ │
│ └── 不影响已验收模块？ │
│ │
│ 3. 按路由表执行 │
│ ├── 原型不通过 → P1局部 │
│ ├── 架构不可行 → P2调整 │
│ ├── 代码不符 → P3架构 │
│ └── 测试不通过 → P3修复 │
│ │
│ 4. 打回限制 │
│ ├── 每模块最多3次 │
│ └── 必须附带反馈 │
└───────────────────────────┘
┌──── 整合交付 ────┐
│ │
│ 1. 模块化讨论验收 │
│ 多Agent交叉验收 │
│ 每个模块独立评分 │
│ │
│ [RC-P5-01] 整合一致性验证
│ ├── 模块间接口一致 │
│ ├── 数据模型一致 │
│ └── 用户体验一致 │
│ │
│ 2. 协作奖励评估 │
│ IQ + CE + PN │
│ 低分 → Skill改进 │
│ 高分 → 最佳实践 │
│ │
│ 3. 复盘与经验沉淀 │
│ L1 微模式 │
│ L2 规则强化 │
│ L3 Skill增强 │
│ L4 独立Skill │
│ │
│ 4. team_delete 清理│
└───────────────────┘
文件 analyst planner designer runner subAgents
─────────────────────────────────────────────────────────────
goal.md 读写 只读 只读 只读 —
product.md 读写 只读 只读 只读 —
modules.md — 读写 只读 只读 —
dependency-dag.md — 读写 — 读写 —
prototype/ — — 读写 只读 只读
architecture.md — — — 读写 只读
progress/*.md — — — 读写 读写
子Agent → runner:
task_complete / task_progress / task_blocked / task_failed
task_partial_success / recovery_attempt
runner → orchestrator:
开发阶段完成 / 需要决策 / 建议打回
orchestrator → 用户:
原型确认 / 架构决策 / 预算预警 / 硬约束违规
| 创新 | 解决的问题 | 核心机制 |
|---|---|---|
| 原型校准基石 | 编码完发现方向不对 | Phase 2 锁定原型，Phase 3 必须对齐 |
| 推理验证点 | 错误级联放大 | 9个RC强制暂停验证 |
| 协作奖励模型 | Agent"自顾自" | IQ+CE+PN三维评估 |
| 树搜索架构讨论 | 简单两路对比错过最优 | 多决策点→局部剪枝→全局组合 |
| 模块化验收+最小回退 | 验收粒度不当/打回范围失控 | 模块级验收+路由表+最小回退 |
| Harness方向盘 | Agent角色串台 | 差异化约束注入行为边界 |
| 三层Prompt洋葱 | prompt臃肿/重复 | 身份+叙事+焦点三层分离 |
- 不替代人类决策：关键节点（原型确认、架构决策、硬约束违规）均需人工确认
- 奖励模型不实时使用：协作奖励仅用于事后复盘，避免过拟合
- 打回有上限：每模块最多3次打回，超过需人工介入
- runner 无打回决策权：只能上报，避免局部视角误判
- Phase 3 阻塞：必须等 P1+P2 走完，不可跳过原型阶段
本文档随 v2 架构同步更新，最后修订：2026-04-22