cfdaily
375 lines
16 KiB
Markdown
375 lines
16 KiB
Markdown
# #01 四相循环实施方案
|
||
|
||
**序号**: #01
|
||
**名称**: 四相循环 — PRD Phase 1~4 完整实现方案
|
||
**版本**: v1.0
|
||
**基于**: PRD-v3.0 §4 四相架构 + architecture-v3.0.md
|
||
**作者**: 庞统（副军师）🐦
|
||
**日期**: 2026-05-29
|
||
**状态**: 待评审
|
||
**评审**: 司马懿
|
||
|
||
---
|
||
|
||
## §1. 背景和问题
|
||
|
||
### 1.1 当前状态
|
||
|
||
moziplus v2.0 已实现：
|
||
- Blackboard 黑板（SQLite 14 表）
|
||
- Comment + @mention 系统
|
||
- Agent 认领（claim API + CAS）
|
||
- Daemon 30s tick 调度循环
|
||
- Guardrail 安全红线
|
||
- SubTask 模型 + Mail Tab
|
||
|
||
### 1.2 核心问题
|
||
|
||
PRD-v3.0 定义了四相架构（需求探索 → 动态规划 → 自主执行 → 主动汇报），但当前代码只实现了"Phase 3 的后半段"——Daemon 调度 Agent 执行。缺失：
|
||
|
||
1. **Phase 2 的讨论涌现**：Agent 不在黑板上讨论，不自主创建任务，完全依赖 Daemon 调度
|
||
2. **Phase 3 的持续指挥**：庞统不在一轮结束时 review，没有方向校正机制
|
||
3. **司马懿全维度质量门控**：当前只有代码评审 skill，缺少需求覆盖、方向一致性、产出物验证等维度
|
||
4. **Phase 3 的完整闭环**：每个 Agent 完成后过司马懿 review（已实现），但一轮结束后的庞统 review + 动态调整 + 循环未实现
|
||
|
||
### 1.3 设计原则
|
||
|
||
> PRD 是目标，T 阶段不是。不按 T 阶段拆分，四相循环一起实现。
|
||
|
||
---
|
||
|
||
## §2. 核心模型：四相循环
|
||
|
||
```
|
||
Phase 1: 需求探索
|
||
用户 + 庞统苏格拉底对话 → 明确 goal
|
||
庞统创建 parent task，goal 写入 must_haves
|
||
│
|
||
▼
|
||
Phase 2: 动态规划（讨论涌现）
|
||
庞统把 goal 写到黑板 → spawn 各 Agent 读黑板
|
||
各 Agent 在黑板上讨论（comment / @mention）
|
||
讨论过程中庞统无形中对齐方向（回答 @ 的问题）
|
||
讨论收敛 → 各 Agent 自主创建 sub task
|
||
不确定时 @ 庞统 进行目标对齐
|
||
│
|
||
▼
|
||
Phase 3: 自主执行（循环）
|
||
┌─────────────────────────────────────────────┐
|
||
│ │
|
||
│ Daemon tick 派发 pending sub tasks │
|
||
│ 各 Agent 自主执行 │
|
||
│ Agent 完成 → 司马懿 review（已有机制） │
|
||
│ review 通过 → sub task done │
|
||
│ review 不通过 → Agent 修改 → 再 review │
|
||
│ │
|
||
│ 一轮结束（parent 下所有 sub 终态） │
|
||
│ ↓ │
|
||
│ 庞统 review 三问： │
|
||
│ 1. Goal 还清晰吗？ │
|
||
│ 2. 成果物覆盖 goal 了吗？ │
|
||
│ 3. 下一轮需要做什么？ │
|
||
│ ↓ │
|
||
│ 庞统决定： │
|
||
│ - 创建新一轮 sub tasks → 回到执行 │
|
||
│ - goal 达成 → 进入 Phase 4 │
|
||
│ - 方向偏离 → 调整 goal + 新一轮 │
|
||
│ │
|
||
└─────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
Phase 4: 主动汇报
|
||
庞统推送成果物摘要 + 关键发现
|
||
用户验收
|
||
```
|
||
|
||
### 2.1 关键设计决策
|
||
|
||
| 决策 | 选择 | 理由 |
|
||
|------|------|------|
|
||
| "一轮"定义 | parent 下所有 sub task 均为终态（done/failed/cancelled） | 方案 A，简洁可靠 |
|
||
| 庞统参与方式 | 讨论阶段通过 @mention 回答问题，一轮结束时 spawn review | 不全程在线（OpenClaw 限制），但关键节点在场 |
|
||
| Agent 自主度 | Auftragstaktik + Autonomy Directive | 给目标不给步骤，Agent 自主决定怎么协作 |
|
||
| 司马懿 review 时机 | 每个 Agent 完成任务后 | 已有机制，不变 |
|
||
| 庞统 review 时机 | 一轮结束时 | 检查整体方向，不介入每个 sub task |
|
||
| 讨论时机 | 随时，不僵化分阶段 | Phase 2 和 Phase 3 都可以在黑板上讨论 |
|
||
|
||
### 2.2 人的参与密度（PRD B4）
|
||
|
||
| Phase | 人的参与 | AI 自主 |
|
||
|-------|---------|--------|
|
||
| Phase 1 | 高（和庞统对话） | 庞统主动提问 |
|
||
| Phase 2 | 可选（可旁观讨论） | Agent 自主讨论、创建任务 |
|
||
| Phase 3 | 几乎不参与 | 只有安全红线才拉人 |
|
||
| Phase 4 | 验收 | AI 主动推送 |
|
||
|
||
---
|
||
|
||
## §3. Agent Spawn Prompt 设计
|
||
|
||
### 3.1 设计理念
|
||
|
||
不是"固定步骤"，不是"庞统规划流程"，而是：
|
||
1. 告诉 Agent 目标和约束（Auftragstaktik）
|
||
2. 告诉 Agent 黑板 API 能力
|
||
3. 告诉 Agent 你是自主的（Autonomy Directive）
|
||
4. 告诉 Agent 行为边界（Boids 四条）
|
||
5. 让 Agent 自己决定怎么协作和讨论
|
||
|
||
### 3.2 优秀实践来源
|
||
|
||
| 实践 | 来源 | 启示 |
|
||
|------|------|------|
|
||
| **Autonomy Directive** | oh-my-codex 实践 #12 | Agent 自主执行，遇阻才问 |
|
||
| **Auftragstaktik 任务式指挥** | moziplus-agent-lifecycle #4 | Intent→End State→Constraints，不指定步骤 |
|
||
| **Boids 群体智能** | moziplus-agent-lifecycle #6 | Separation/Alignment/Cohesion/Boundary |
|
||
| **元认知自评** | moziplus-agent-lifecycle #5 | Agent 产出自带 confidence |
|
||
| **Agent API 契约自描述** | moziplus-agent-lifecycle #9 | API 返回可操作错误信息 |
|
||
| **约束分级**（高/中/低自由） | quality-gate-patterns #2 | 不同场景用不同严格度 |
|
||
|
||
### 3.3 Spawn Prompt 框架
|
||
|
||
```
|
||
## 你的任务
|
||
|
||
{goal_snapshot}
|
||
|
||
## 约束
|
||
|
||
{constraints}
|
||
|
||
## 黑板 API
|
||
|
||
你可以随时：
|
||
- 读黑板：GET /api/projects/{pid}/tasks/{tid}（含 comments、outputs）
|
||
- 写 comment：POST /api/projects/{pid}/tasks/{tid}/comments
|
||
body: { "author": "{agent_id}", "body": "内容", "mentions": ["agent_id"] }
|
||
- 创建 sub task：POST /api/projects/{pid}/tasks
|
||
- 认领任务：POST /api/projects/{pid}/tasks/{tid}/claim
|
||
|
||
## 行为准则
|
||
|
||
1. 你是自主的。读黑板、思考、行动，不要等指令。
|
||
2. 不确定时 @pangtong-fujunshi 对齐目标。
|
||
3. 需要协作时 @ 对应 Agent。
|
||
4. 讨论是随时灵活的，执行过程中也可以在黑板上讨论。
|
||
5. 产出写入 output，完成时通知。
|
||
|
||
## 完成标准
|
||
|
||
{success_criteria}
|
||
```
|
||
|
||
### 3.4 @mention 通知机制
|
||
|
||
Agent 写 comment 时指定 mentions → Daemon tick 扫描新 comments → spawn 被 @ 的 Agent 读黑板。
|
||
|
||
---
|
||
|
||
## §4. 庞统 Review 机制
|
||
|
||
### 4.1 触发条件
|
||
|
||
Daemon 30s tick 检测：parent task 下所有 sub task 均为终态（done/failed/cancelled）。
|
||
|
||
### 4.2 Review 三问（框架，不是限制）
|
||
|
||
庞统被 spawn 后拿到：
|
||
- goal_snapshot：原始 goal
|
||
- round_outputs：本轮所有 sub task 产出物聚合
|
||
- round_comments：本轮黑板讨论记录
|
||
|
||
庞统自主判断，不限于三问，但三问是核心框架：
|
||
|
||
1. **Goal 还清晰吗？** — 是否被静默修改（goal drift）
|
||
2. **成果物覆盖 goal 了吗？** — 逐条检查验收标准
|
||
3. **下一轮需要做什么？** — 创建新一轮 sub tasks / 标记完成 / 调整方向
|
||
|
||
### 4.3 调整能力
|
||
|
||
庞统 review 后可执行的操作（不限制，以下是已知操作类型）：
|
||
|
||
| 操作 | 说明 | 优秀实践来源 |
|
||
|------|------|-------------|
|
||
| 创建新 sub tasks | 补充遗漏工作 | open-multi-agent Goal→DAG |
|
||
| 拆分过大任务 | 任务太大则拆 | moziplus 实践模板骨架+AI填充 |
|
||
| 标记偏离 | 需求被静默丢弃 | GSD Scope Reduction Detection |
|
||
| 调整优先级 | 根据执行进展重排 | Hermes `/goal` 持续锁定 |
|
||
| 修改 goal | 用户改主意时 | PRD B2 "计划可演进" |
|
||
| 终止/重来 | 方向完全偏了 | TradingAgents 动态图构建 |
|
||
|
||
---
|
||
|
||
## §5. 司马懿 Review 扩展
|
||
|
||
### 5.1 机制不变
|
||
|
||
每个 Agent 完成任务后 → 司马懿 review → 通过才算 done。这是已有机制，**不变**。
|
||
|
||
### 5.2 质量维度扩展
|
||
|
||
当前只有代码评审，需要扩展到全维度质量把控。司马懿根据优秀实践自行设计 review skill，以下是调研结果供参考：
|
||
|
||
#### 可用优秀实践
|
||
|
||
| 实践 | 来源 | 司马懿可用场景 |
|
||
|------|------|--------------|
|
||
| **三阶段评估门控**（机械→语义→共识） | quality-gate-patterns #1 | 代码用机械+语义，方向一致性用共识 |
|
||
| **Scope Reduction Detection** | GSD 实践 #2 | 检查需求是否被静默丢弃 |
|
||
| **反合理化表** | quality-gate-patterns #3 | 每个 Skill 内置"常见借口+反驳" |
|
||
| **约束分级**（高/中/低自由） | quality-gate-patterns #2 | brainstorming 高自由，部署低自由 |
|
||
| **Auftragstaktik 三元组** | moziplus-agent-lifecycle #4 | 检查 Intent→End State→Constraints 是否完整 |
|
||
| **元认知自评** | moziplus-agent-lifecycle #5 | Agent 产出自带 confidence，司马懿决定是否升级 |
|
||
| **决策覆盖门禁** | GSD 实践 #5 | 讨论中的决策是否落地到产出 |
|
||
| **产出物验证** | Hermes 幻觉门控 | 产出物是否真实存在、可验证 |
|
||
|
||
#### 建议的 Review 维度
|
||
|
||
| 维度 | 检查内容 | 约束等级 |
|
||
|------|---------|---------|
|
||
| 需求覆盖 | 产出是否覆盖 task 的 must_haves | 中自由 |
|
||
| 设计-代码一致性 | 代码是否和设计文档对齐 | 中自由 |
|
||
| 代码质量 | 规范、安全、边界条件（现有） | 低自由 |
|
||
| 方向一致性 | 是否偏离 parent goal | 中自由 |
|
||
| 产出物真实性 | 文件是否存在、可验证 | 低自由 |
|
||
|
||
### 5.3 司马懿角色定义建议
|
||
|
||
AGENTS.md 中的角色从"质量总监：代码评审、多空辩论、最终验收"调整为：
|
||
|
||
> **质量总监：全维度质量把控**
|
||
> - 需求一致性检查
|
||
> - 设计-代码一致性检查
|
||
> - 代码质量评审
|
||
> - 方向一致性检查
|
||
> - 产出物验证
|
||
> - 不同维度使用不同的 review skill
|
||
> - 反合理化：不做"建议优化"，必须说"第X行有问题，应该改为Y，因为Z"
|
||
|
||
---
|
||
|
||
## §6. 代码改动清单
|
||
|
||
### 6.1 Daemon 层
|
||
|
||
| 文件 | 改动 | 说明 |
|
||
|------|------|------|
|
||
| `ticker.py` | 新增 `_check_round_complete()` | 检测 parent 下所有 sub 终态 |
|
||
| `ticker.py` | 新增 `_spawn_pangtong_review()` | 一轮结束时 spawn 庞统 review |
|
||
| `ticker.py` | 新增 `_process_mentions()` | 扫描新 comments 的 mentions → spawn 被 @ 的 Agent |
|
||
| `dispatcher.py` | 扩展 spawn 类型 | 支持 "discussion" spawn（Phase 2）+ "review" spawn（一轮结束） |
|
||
| `bootstrap.py` | 扩展上下文构建 | 构建 goal + 一轮成果物聚合 + 讨论 history |
|
||
| `spawner.py` | 更新 prompt 模板 | 使用 §3.3 的 spawn prompt 框架 |
|
||
|
||
### 6.2 API 层
|
||
|
||
| 文件 | 改动 | 说明 |
|
||
|------|------|------|
|
||
| `blackboard_routes.py` | 新增成果物聚合端点 | `GET /tasks/{id}/outputs/aggregate` 聚合 parent 下所有 sub 的 outputs |
|
||
|
||
### 6.3 Model 层
|
||
|
||
| 文件 | 改动 | 说明 |
|
||
|------|------|------|
|
||
| `operations.py` | 新增 `get_subtasks_status()` | 批量查询 parent 下所有 sub 状态 |
|
||
| `operations.py` | 新增 `get_mentioned_agents()` | 从 comments 中提取未通知的 mentions |
|
||
|
||
### 6.4 Skill 层
|
||
|
||
| 位置 | 内容 | 说明 |
|
||
|------|------|------|
|
||
| 司马懿 workspace | review skill 文件 | 司马懿基于 §5.2 优秀实践自行设计 |
|
||
| 庞统 bootstrap | review prompt 模板 | 庞统 review 的三问框架 |
|
||
|
||
### 6.5 前端（可选，后续）
|
||
|
||
| 改动 | 说明 |
|
||
|------|------|
|
||
| 黑板讨论面板增强 | 实时显示 comments、@mention 高亮 |
|
||
| 一轮进度指示 | 显示当前轮次、已完成/总计 sub task |
|
||
|
||
---
|
||
|
||
## §7. 安全红线（不变）
|
||
|
||
现有 `guardrails.yaml` 的 6 条红线不变。Phase 3 循环中：
|
||
- 非红线操作 → AI 自主决策，不拉人
|
||
- 红线触发 → `block_and_notify` / `pause_and_escalate`
|
||
|
||
---
|
||
|
||
## §8. 风险和缓解
|
||
|
||
| 风险 | 缓解 |
|
||
|------|------|
|
||
| Agent 讨论不收敛，无限循环 | 庞统兜底：讨论超过 N 轮未收敛 → 庞统裁决创建任务 |
|
||
| 庞统 review 产出质量不稳定 | 司马懿可以 challenge 庞统的 review 结果（rebuttal 机制） |
|
||
| @mention 风暴（互相 @ 导致 spawn 爆炸） | Daemon 去重：同一 Agent 在同一 task 的 pending mention 合并为一次 spawn |
|
||
| 一轮结束检测延迟（最长 30s） | 可接受，30s tick 是当前设计约束 |
|
||
| Agent 创建 sub task 不规范 | 庞统 review 时检查，不合规的 sub task 打回 |
|
||
|
||
---
|
||
|
||
## §9. 验证标准
|
||
|
||
| 标准 | 验证方式 |
|
||
|------|---------|
|
||
| Phase 2 讨论：Agent 能在黑板上写 comment + @mention | E2E：spawn Agent → 检查 comment 写入 |
|
||
| Phase 2 涌现：Agent 能自主创建 sub task | E2E：Agent 通过 API 创建 sub task |
|
||
| @mention 通知：被 @ 的 Agent 能被 spawn | E2E：写 comment @zhaoyun-data → Daemon spawn 赵云 |
|
||
| 一轮结束检测：parent 下所有 sub 终态 → 触发庞统 review | E2E：创建 parent + subs → 完成 subs → 检测庞统 spawn |
|
||
| 庞统 review：能创建新一轮 sub tasks 或标记完成 | E2E：庞统 review 后检查新 sub task 创建 |
|
||
| 司马懿 review：每个 Agent 完成后必须过 review | 已有机制，回归测试 |
|
||
| 安全红线不触发时 AI 全自主 | E2E：正常任务不触发 guardrail |
|
||
|
||
---
|
||
|
||
## 附录 A：讨论过程记忆
|
||
|
||
### A.1 讨论背景
|
||
|
||
基于 PRD-v3.0 四相架构（需求探索→动态规划→自主执行→主动汇报），讨论如何将 PRD 的设计落地到实际代码中。
|
||
|
||
### A.2 关键讨论节点
|
||
|
||
1. **B8/B9 确认移除**：经代码验证，BUG-7（planning 暂停失败）和 BUG-8（cancel→resume 空图完成）是 v1.0 (mozi) 的 bug，moziplus v2.0 没有 `planning` 状态和 `execute_graph`，从 T2 中移除。
|
||
|
||
2. **持续指挥 vs 庞统 native**：初始方案是"庞统全程在场持续指挥"，用户指出风险——"搞不好就是庞统 native"。改为：**Agent 在黑板上讨论涌现**，庞统通过 @mention 回答问题和一轮结束时 review 来参与，不是独裁者而是引导者。
|
||
|
||
3. **"一轮"定义**：确认方案 A——parent task 下所有 sub task 均为终态（done/failed/cancelled）。
|
||
|
||
4. **司马懿角色扩展**：从"代码评审"扩展为"全维度质量把控"（需求覆盖、设计一致性、代码质量、方向一致性、产出物验证）。用户强调"质量包括更广义的范围"。
|
||
|
||
5. **司马懿 review skill 设计方式**：用户要求"基于优秀实践"，不要庞统拍脑袋设计。调研了 quality-gate-patterns、GSD、moziplus-agent-lifecycle 等实践，整理成参考材料供司马懿自行设计。
|
||
|
||
6. **讨论时机灵活化**：用户强调"讨论是随时灵活的，哪怕任务执行过程中也可以随时讨论，不要僵化"。Phase 2 和 Phase 3 的讨论不硬分，黑板讨论贯穿全程。
|
||
|
||
7. **用户不参与触发**：确认 PRD B4 原则——AI 能决定就 AI 决定，人只在安全红线和最终验收时介入。当前 `guardrails.yaml` 已实现 6 条红线。
|
||
|
||
8. **T 阶段不是目标**：用户明确"别被 T2 限制，T2 不是目标，PRD 才是"。四相循环一起实现，不按 T 阶段拆分。
|
||
|
||
9. **评审机制强调**：用户要求庞统和司马懿可以 rebuttal，"我需要更优的方案，不是谁服从谁"。
|
||
|
||
### A.3 优秀实践引用
|
||
|
||
| 来源 | 关键实践 | 引用位置 |
|
||
|------|---------|---------|
|
||
| oh-my-codex | Autonomy Directive | §3.3 Spawn Prompt |
|
||
| moziplus-agent-lifecycle | Auftragstaktik 任务式指挥 | §3.1, §4.3 |
|
||
| moziplus-agent-lifecycle | Boids 群体智能四条 | §3.3 |
|
||
| moziplus-agent-lifecycle | 元认知自评 confidence | §5.2 |
|
||
| moziplus-agent-lifecycle | Agent API 契约自描述 | §3.3 |
|
||
| quality-gate-patterns | 三阶段评估门控 | §5.2 |
|
||
| quality-gate-patterns | 反合理化表 | §5.2 |
|
||
| quality-gate-patterns | 约束分级 | §5.2 |
|
||
| GSD | Scope Reduction Detection | §4.3, §5.2 |
|
||
| GSD | 决策覆盖门禁 | §5.2 |
|
||
| Hermes | 幻觉门控（产出物验证） | §5.2 |
|
||
| PRD-v3.0 | B4 人退到边缘 | §2.2 |
|
||
| PRD-v3.0 | 四相架构 | §2 |
|
||
| architecture-v2.6 | 黑板讨论示例 | §3.3 |
|
||
|
||
### A.4 待确认事项
|
||
|
||
无。本方案为完整设计方案，待司马懿评审后决定下一步。
|