cfdaily
656 lines
34 KiB
Markdown
656 lines
34 KiB
Markdown
# #01 四相循环实施方案
|
||
|
||
**序号**: #01
|
||
**名称**: 四相循环 — PRD Phase 1~4 完整实现方案
|
||
**版本**: v1.3（实现完成，待 E2E 验证）
|
||
**基于**: PRD-v3.0 §4 四相架构 + architecture-v3.0.md
|
||
**作者**: 庞统（副军师）🐦
|
||
**日期**: 2026-05-29
|
||
**状态**: 实现完成，待 E2E 验证
|
||
**评审**: 司马懿
|
||
|
||
---
|
||
|
||
## §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. **不重复别人的工作。**动手前先读黑板看谁在做什么（Separation）。
|
||
3. **保持方向对齐。**你的产出方向和 parent goal 对齐，不确定时 @pangtong-fujunshi（Alignment）。
|
||
4. **产出可共享。**产出写入黑板，让其他人能看到你的成果（Cohesion）。
|
||
5. **不越界。**安全红线不要碰，超出能力的 @ 庞统升级（Boundary）。
|
||
6. **随时讨论。**执行过程中需要协作时 @ 对应 Agent，讨论是灵活的不是固定阶段的。
|
||
|
||
## 完成标准
|
||
|
||
{success_criteria}
|
||
```
|
||
|
||
### 3.4 @mention 通知机制
|
||
|
||
Agent 写 comment 时指定 mentions → Daemon tick 扫描新 comments → spawn 被 @ 的 Agent 读黑板。
|
||
|
||
**通知可靠性保障**：
|
||
|
||
新增 `mention_queue` 表，记录 mentions 的通知状态：
|
||
```sql
|
||
CREATE TABLE IF NOT EXISTS mention_queue (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
comment_id INTEGER NOT NULL,
|
||
task_id TEXT NOT NULL,
|
||
mentioned_agent TEXT NOT NULL,
|
||
status TEXT NOT NULL DEFAULT 'pending', -- pending / notified / failed
|
||
retry_count INTEGER NOT NULL DEFAULT 0,
|
||
created_at TEXT NOT NULL DEFAULT (datetime('now')),
|
||
notified_at TEXT,
|
||
FOREIGN KEY (comment_id) REFERENCES comments(id)
|
||
);
|
||
```
|
||
|
||
流程：
|
||
1. Agent 写 comment 带 mentions → 写入 `mention_queue`（status=pending）
|
||
2. Daemon tick 扫描 pending mentions → 尝试 spawn
|
||
3. spawn 成功 → status=notified
|
||
4. spawn 失败（Agent busy）→ 保持 pending，下次 tick 重试
|
||
5. 超过 N 次重试仍失败 → status=failed，记录事件
|
||
|
||
**备选方案**（更轻量）：走 Inbox JSONL 方式通知，不 spawn，Agent 读 inbox 即可。MVP 阶段先用 tick 扫描 + 重试，后续视性能再升级。
|
||
|
||
---
|
||
|
||
## §4. 庞统 Review 机制
|
||
|
||
### 4.1 触发条件
|
||
|
||
Daemon 30s tick 检测：parent task 下所有 sub task 均为终态（done/failed/cancelled）。
|
||
|
||
**终态区分**：
|
||
|
||
传给庞统的状态摘要包含维度信息：
|
||
```json
|
||
{ "done": 3, "failed": 1, "cancelled": 0, "total": 4 }
|
||
```
|
||
|
||
庞统 review prompt 中增加指引：
|
||
> 有 sub task failed 时，优先判断是应该重试（同一 Agent）、换人（换 Agent）、还是调整方案（修改 goal/约束）。
|
||
|
||
### 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 "计划可演进" |
|
||
### 4.4 一轮结束后的执行顺序
|
||
|
||
Ticker tick 串行执行，明确顺序避免冲突：
|
||
```
|
||
1. 超时检测（claimed 超时 → 重置 pending，executing 超时 → failed）
|
||
2. 依赖推进（检查 blocker 完成 → 推进状态）
|
||
3. 调度 pending（含 review 类型的 task）
|
||
4. 一轮结束检测（在调度之后，确保 review 结果已生效）
|
||
5. 庞统 review spawn
|
||
```
|
||
|
||
关键：步骤 4 在步骤 3 之后，确保司马懿 review 打回的 sub task 已重新进入 working 状态，不会误触发一轮结束。
|
||
|
||
### 4.5 防止庞统 review 无限循环
|
||
|
||
庞统 review 后创建新 sub task → sub 全部 done → 又触发一轮结束 → 又 spawn 庞统 review → 无限循环。
|
||
|
||
缓解方案：
|
||
- parent task 新增 `round_count` 字段，每触发一次庞统 review +1
|
||
- round_count 上限（如 5 轮），超过后强制进入 Phase 4 汇报给用户
|
||
- 或：庞统 review 后标记 parent 为 `reviewing`，一轮结束检测跳过 `reviewing` 状态的 parent
|
||
|
||
MVP 阶段用 round_count 上限，简单可靠。
|
||
|
||
### 4.6 任务状态机完整流转
|
||
|
||
两层 review（司马懿 + 庞统）在状态机中的完整路径：
|
||
|
||
```
|
||
─── Sub Task（执行 Agent）───
|
||
|
||
pending → claimed → working
|
||
│
|
||
▼ Agent 完成 + 三信号检查通过
|
||
review
|
||
│
|
||
▼ 司马懿 review（_dispatch_reviews 确定性路由）
|
||
┌── done ──┐
|
||
│ │
|
||
review 通过 review 不通过 → working（打回重做）
|
||
│
|
||
▼
|
||
（sub task 终态）
|
||
|
||
─── Parent Task（庞统三问）───
|
||
|
||
parent 下所有 sub task 终态
|
||
│
|
||
▼ _check_round_complete 检测
|
||
reviewing（防重复触发）
|
||
│
|
||
▼ _spawn_pangtong_review
|
||
│
|
||
├── GOAL_ACHIEVED → done（项目完成）
|
||
├── 创建新 sub task → working（新一轮执行）
|
||
└── 方向偏离 → 调整 goal + working
|
||
```
|
||
|
||
**关键规则**：
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| sub task 终态 = done / failed / cancelled | 司马懿 review 通过 → done；不通过 → 打回 working |
|
||
| 司马懿 review 是 sub task 的必经关卡 | 每个 sub task 完成后必须过司马懿，通过才算 done |
|
||
| 庞统 review 是 parent task 的关卡 | 一轮结束后庞统三问，决定继续还是完成 |
|
||
| 司马懿 spawn 完成后不再触发 _auto_complete | 审查 Agent（司马懿）的 on_complete 回调直接标 done/failed，不走 _task_auto_complete |
|
||
| 庞统 spawn 完成后走 _handle_review_conclusion | 解析 GOAL_ACHIEVED 或继续新一轮 |
|
||
|
||
**为什么审查 Agent 完成后不再触发 _auto_complete**：
|
||
|
||
`_auto_complete` 的设计意图是检测"执行 Agent 是否真的完成了工作"（三层幻觉门控）。而审查 Agent（司马懿）是被派来 review 的，他的完成意味着 review 本身完成了，不应该再走一遍"检测是否完成 → 标 review → 又派审查 Agent"的循环。
|
||
|
||
实现方式：`_dispatch_reviews` 在 dispatch 审查 Agent 时，通过 `spawn_full_agent` 的 `on_complete` 回调直接标 done/failed，绕过 `_task_auto_complete`。
|
||
|
||
---
|
||
|
||
## §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()` | 扫描 mention_queue → spawn 被 @ 的 Agent | ✅ 已实现 |
|
||
| `ticker.py` | 新增 `_build_mention_prompt()` | 构建 @mention 通知 prompt | ✅ 已实现 |
|
||
| `ticker.py` | tick 流程明确顺序（§4.4） | 超时→依赖→调度→聚合 parent→一轮结束→mention 通知→写事件→健康检查（8 步） | ✅ 已实现 |
|
||
| `dispatcher.py` | 扩展 spawn 类型 | 支持 "discussion" + "review"（spawn_type 参数） | ✅ 已实现 |
|
||
| `bootstrap.py` | ~~新增 `build_for_review()`~~ | review 上下文构建已内联在 ticker._build_review_prompt 中 | ✅ 已移除（dead code） |
|
||
| `bootstrap.py` | ~~新增 `_format_review_context()`~~ | 同上 | ✅ 已移除（dead code） |
|
||
| `spawner.py` | 新增 `DISCUSSION_PROMPT_TEMPLATE` | §3.3 框架 + Boids 四条 + API 契约 | ✅ 已实现 |
|
||
| `spawner.py` | 新增 `_build_discussion_prompt()` | discussion 类型 prompt 构建 | ✅ 已实现 |
|
||
| `spawner.py` | `build_spawn_message` 新增 `spawn_type` | executor/discussion/review 类型路由 | ✅ 已实现 |
|
||
| `models.py` | parent 新增 `round_count` 字段 | 防止无限循环（§4.5） | ✅ 已实现 |
|
||
|
||
### 6.2 数据库层
|
||
|
||
| 文件 | 改动 | 说明 | 状态 |
|
||
|------|------|------|------|
|
||
| `db.py` | `_SCHEMA_STATEMENTS` 加 `round_count` | tasks 表新增轮次字段 | ✅ 已实现 |
|
||
| `db.py` | 新增 `mention_queue` 表 | id, comment_id, task_id, mentioned_agent, status, retry_count | ✅ 已实现 |
|
||
| `db.py` | mention_queue 索引 | status + (mentioned_agent, status) | ✅ 已实现 |
|
||
|
||
### 6.3 操作层
|
||
|
||
| 文件 | 改动 | 说明 | 状态 |
|
||
|------|------|------|------|
|
||
| `operations.py` | 新增 `get_subtasks_summary()` | 批量查询 parent 下所有 sub 状态摘要 | ✅ 已实现 |
|
||
| `operations.py` | 新增 `get_aggregate_outputs()` | 聚合所有 sub 的产出 | ✅ 已实现 |
|
||
| `operations.py` | 新增 `get_round_comments()` | 获取当前轮次的讨论记录 | ✅ 已实现 |
|
||
| `operations.py` | 新增 `increment_round_count()` | 递增 parent 的 round_count | ✅ 已实现 |
|
||
| `operations.py` | 新增 `record_mentions()` | comment 创建时写入 mention_queue（去重） | ✅ 已实现 |
|
||
| `operations.py` | 新增 `get_pending_mentions()` | 扫描 pending 且未超重试上限的 mentions | ✅ 已实现 |
|
||
| `operations.py` | 新增 `mark_mention_notified()` | 标记 mention 为已通知 | ✅ 已实现 |
|
||
| `operations.py` | 新增 `mark_mention_retry()` | 递增 retry_count（AgentBusyError 除外） | ✅ 已实现 |
|
||
| `operations.py` | 新增 `mark_mention_failed()` | 标记 mention 为失败（超重试上限） | ✅ 已实现 |
|
||
|
||
### 6.4 API 层
|
||
|
||
| 文件 | 改动 | 说明 | 状态 |
|
||
|------|------|------|------|
|
||
| `blackboard_routes.py` | `add_comment` 联动 `record_mentions` | comment 创建后自动写入 mention_queue | ✅ 已实现 |
|
||
| `blackboard_routes.py` | 新增成果物聚合端点 | `GET /tasks/{id}/outputs/aggregate` | ❌ 后续 |
|
||
|
||
### 6.5 Skill 层
|
||
|
||
| 位置 | 内容 | 说明 | 状态 |
|
||
|------|------|------|------|
|
||
| 司马懿 workspace | review skill 文件 | 司马懿基于 §5.2 优秀实践自行设计 | ❌ 独立 |
|
||
| 庞统 bootstrap | review prompt 模板 | 庞统 review 的三问框架 | ✅ 已实现（ticker._build_review_prompt） |
|
||
|
||
### 6.6 前端（可选，后续）
|
||
|
||
| 改动 | 说明 |
|
||
|------|------|
|
||
| 黑板讨论面板增强 | 实时显示 comments、@mention 高亮 |
|
||
| 一轮进度指示 | 显示当前轮次、已完成/总计 sub task |
|
||
|
||
### 6.7 运维修复
|
||
|
||
| 文件 | 改动 | 说明 | 状态 |
|
||
|------|------|------|------|
|
||
| `sanguo_git_sync/auto-sync.sh` | Step 5 兜底 catch-all | 修复 fswatch 漏检文件变化 | ✅ 已实现 |
|
||
|
||
---
|
||
|
||
## §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 |
|
||
| @mention 通知丢失（Agent busy 时 spawn 失败） | mention_queue 表 + 重试机制（见 §3.4） |
|
||
| 一轮结束检测延迟（最长 30s） | 可接受，30s tick 是当前设计约束 |
|
||
| Agent 创建 sub task 不规范 | 庞统 review 时检查，不合规的 sub task 打回 |
|
||
| 庞统 review 后创建新 sub 触发无限循环 | parent 新增 `reviewing` 状态，庞统 review 期间不触发一轮结束检测；或设 round 上限（如 5 轮） |
|
||
| Agent 创建 sub task 缺少 assignee | Agent 创建 sub task 时 capability 必填（用于路由），assignee 可选（认领时填） |
|
||
| 讨论阶段 token 消耗高 | 设上下文预算：每个 Agent 读黑板 comments 不超过最近 50 条，goal summary 不超过 2KB |
|
||
|
||
---
|
||
|
||
## §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：完整讨论过程记忆（2026-05-28 ~ 05-29）
|
||
|
||
### A.1 讨论起因
|
||
|
||
2026-05-28，基于 architecture-v3.0.md v3.0.1 完成的背景，启动 T2（持续指挥 + 动态规划）的调研和设计。目标是补齐 PRD-v3.0 四相架构中未实现的 Phase 2（动态规划）和 Phase 3（持续指挥）。
|
||
|
||
### A.2 阶段一：T2 前置清理（2026-05-28）
|
||
|
||
**#1 B8/B9 确认移除**：庞统验证代码发现，BUG-7（planning 暂停失败）和 BUG-8（cancel→resume 空图完成）是 v1.0 (mozi) 的 bug。moziplus v2.0 没有 `planning` 状态（v2 状态机 11 个状态不含 planning）和 `execute_graph` 函数（执行模型完全不同）。结论：从 T2 遗留问题清单中移除。
|
||
|
||
**#2 architecture-v3.0.md 升级至 v3.0.1**：新增 4 个设计方向章节（§6.5 广播认领、§10.4~10.6）和 §21 T 阶段规划（T1~T8），为后续迭代建立路线图。
|
||
|
||
**#3 司马懿评审通过**（Mail #1779979934362, #1779980383850, #1779981185745）：修复广播认领状态矛盾、BUG-22/25/26 确认、采纳 5 条建议改进。
|
||
|
||
**#4 AGENTS.md 更新**：补充 request vs inform 判断标准——"对方收到后是否需要回复/确认/采取行动？需要→request，不需要→inform"。
|
||
|
||
### A.3 阶段二：持续指挥与动态规划调研（2026-05-28 ~ 05-29）
|
||
|
||
庞统三路调研（NAS 知识库 → 代码 → 优秀实践）：
|
||
|
||
**#5 NAS 知识库搜索**：搜索 wiki-vault/practices/ 中关于"持续指挥"和"动态规划"的内容，找到 get-shit-done、claude-code、hermes、multi-agent-collaboration 等相关实践文件。
|
||
|
||
**#6 代码实现程度调研**：
|
||
- `ticker.py`（960 行）：30s tick 只做 4 件事——超时检测、僵尸回收、pending 任务派发、review 匹配
|
||
- `dispatcher.py`（653 行）：spawn Agent 执行，无黑板讨论环节
|
||
- `router.py`（195 行）：LLMDriver 路由（v3.0-router-refactor 计划改为广播认领）
|
||
- 庞统 spawn 时机：只在 Router 模糊路由时被 delegate spawn，每次新建隔离 session，无上下文延续
|
||
- 结论：当前只有 Phase 3 的后半段，缺失 Phase 2（讨论涌现）和完整闭环
|
||
|
||
**#7 优秀实践调研**（8 个来源，详见 A.5 引用表）：
|
||
- get-shit-done：Wave Execution、Scope Reduction Detection、决策覆盖门禁
|
||
- claude-code：四级权限（default/auto/bypass/yolo）、Dream 记忆系统
|
||
- hermes：幻觉门控、心跳+reclaim
|
||
- oh-my-codex：Autonomy Directive（自主指令）
|
||
- moziplus-agent-lifecycle：Auftragstaktik 任务式指挥、Boids 群体智能、元认知自评
|
||
- quality-gate-patterns：三阶段评估门控、反合理化表、约束分级
|
||
- supervision-practices：分层审批策略
|
||
- multi-agent-collaboration-patterns：4 种编排模式 × 3 种通信协议
|
||
|
||
### A.4 阶段三：初始设计方向讨论（2026-05-29）
|
||
|
||
庞统提出初始方案：Iterative Execution Loop（迭代执行环）—— Daemon 检测一轮结束 → 自动 spawn 庞统 review → 庞统自主决定调整方案 → 司马懿质量门控（计划放 T4）。
|
||
|
||
用户提出四个关键问题：
|
||
|
||
**#8 "一轮"定义**：用户倾向方案 A——parent 下所有 sub task 均为终态。确认采纳。
|
||
|
||
**#9 司马懿角色不是代码评审**：用户明确"司马懿角色不是代码评审，是质量把控，这个质量是需要包括更广义的范围的，比如需求、代码设计一致性，不能仅仅局限在代码评审"。司马懿应该有多种 review skill，不同类型的评审用不同类型的 skill。
|
||
|
||
**#10 庞统 review 调整能力**：用户问"这块也可以参考更多优秀实践吧？给庞统明确的指导，但是不是限制，和司马懿一样，他可以有很多 skill 来应对不同的任务 review"。庞统调研后给出 6 种调整能力（创建新任务、拆分、标记偏离、调整优先级、修改 goal、终止），每种都有优秀实践来源。
|
||
|
||
**#11 用户不参与触发**：用户问"肯定不是用户参与，以前设计过，如果 AI 能决定，就不要让用户参与，用户的角色已经定义过了"。庞统确认 PRD B4 已定义——安全红线（guardrails.yaml 6 条）才拉人，其余 AI 自主。代码已实现。
|
||
|
||
### A.5 阶段四：关键转折——黑板讨论涌现（2026-05-29）
|
||
|
||
**#12 "庞统 native"风险**：用户指出初始方案"庞统苏格拉底对话 → 明确 goal + 创建 parent task + 初始 sub tasks"中，"这个度在哪里，搞不好就是庞统 native 了"。如果庞统既定 goal 又规划任务，和 v1.0 的确定性编排有什么区别？
|
||
|
||
**#13 黑板讨论涌现**：用户提出核心思路——"能否这样，让 AI 之间也进行沟通，庞统和用户明确 goal 和初始需求，然后大家可以进行黑板探讨啊，有 comments 和 @ 功能啊，大家探讨的过程其实也在黑板上留痕了，最终都拉齐后，Agent 创建子任务到黑板上，这个时候如果不确定任务是否正确，也可以 @ 庞统进行目标对齐，这样黑板的作用就发挥出来了"。
|
||
|
||
**#14 庞统无形对齐**：用户指出"庞统其实在讨论的过程中也就无形地把目标对齐了"——不需要庞统主动规划一切，而是在 Agent 讨论过程中通过回答 @ 问题自然对齐方向。
|
||
|
||
庞统搜了 PRD-v3.0 和 architecture-v2.6，确认：
|
||
- PRD Phase 3 已有完整的共享意识空间设计（每个 Agent 随时读全局状态、写状态、感知变化、主动发起协作）
|
||
- architecture-v2.6 已有黑板讨论示例和 @mention API + comment_type 8 种类型
|
||
- 但代码里这些基础设施虽已实现，Agent 仍未主动使用
|
||
|
||
### A.6 阶段五：最终纠偏（2026-05-29）
|
||
|
||
用户提出三个决定性纠正：
|
||
|
||
**#15 司马懿 review 时机不变**："司马懿质量门控发生在每个 Agent 完成自己任务之后，必须要找司马懿 review 才能算是完成，这个设计不要变。"
|
||
|
||
**#16 Skill 基于优秀实践**："司马懿和庞统的 review 的 skill 我不要你设计，我要优秀实践基础上。"庞统改为整理调研结果供司马懿参考，让司马懿自行设计。
|
||
|
||
**#17 讨论随时灵活**："讨论是随时，哪怕任务执行过程中，也可以随时讨论，不要僵化，尽量灵活，这个 prompt 看看是否有优秀实践可以参考。"
|
||
|
||
**#18 T 阶段不是目标**："别被 T2 限制，T2 不是目标，PRD 才是。"
|
||
|
||
**#19 一起做完**："我不同意一个事情放到不同的 T 阶段实现，要做就一起做完。"
|
||
|
||
**#20 评审 rebuttal**："做完发给司马懿评审，我们再考虑下一步，注意，你们可以 rebuttal，我需要更优的方案，不是谁服从谁。"
|
||
|
||
### A.7 关键设计决策溯源
|
||
|
||
| 方案中的决策 | 触发讨论 | 最终结论 |
|
||
|-------------|---------|---------|
|
||
| Agent 自主讨论涌现（§2 Phase 2） | #12 庞统 native 风险 → #13 用户提出黑板讨论 | Agent 在黑板讨论 → 自主创建任务 |
|
||
| 庞统通过 @mention 参与（§2） | #14 庞统无形对齐 | 不全程在场，但关键节点通过 @ 响应 |
|
||
| 一轮 = 所有 sub 终态（§2.1） | #8 用户倾向方案 A | 方案 A，简洁可靠 |
|
||
| 司马懿每个 sub 完成后 review（§5.1） | #15 用户纠正 | 不变，已有机制 |
|
||
| 司马懿全维度质量把控（§5.2） | #9 用户扩展角色 | 需求/设计/代码/方向/产出物 5 维度 |
|
||
| Skill 基于优秀实践（§5.2） | #16 用户要求 | 整理调研结果供司马懿自行设计 |
|
||
| 讨论 Phase 2+3 贯穿（§2.1） | #17 用户灵活化 | 不僵化分阶段，随时讨论 |
|
||
| 四相循环一起实现（§1.3） | #18 #19 用户纠正 | 不按 T 阶段拆分 |
|
||
| Spawn prompt 用实践指导（§3） | #17 用户问 prompt 实践 | Autonomy Directive + Auftragstaktik + Boids |
|
||
| Rebuttal 机制（§8） | #20 用户要求 | 庞统和司马懿可以互相 challenge |
|
||
|
||
### A.8 优秀实践引用索引
|
||
|
||
| 来源 | 关键实践 | 方案引用位置 |
|
||
|------|---------|-------------|
|
||
| oh-my-codex | Autonomy Directive（自主指令） | §3.3 Spawn Prompt |
|
||
| oh-my-codex | 需求清晰度量化评分 | §3.1 设计理念 |
|
||
| 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 |
|
||
| moziplus-agent-lifecycle | Agent 崩溃自动恢复 | §8 风险参考 |
|
||
| moziplus-agent-lifecycle | 成本追踪 Token 自报 | §8 风险参考 |
|
||
| quality-gate-patterns | 三阶段评估门控 | §5.2 |
|
||
| quality-gate-patterns | 反合理化表 | §5.2 |
|
||
| quality-gate-patterns | 约束分级 | §5.2 |
|
||
| quality-gate-patterns | 门控记录与追溯 | §9 验证 |
|
||
| get-shit-done | Scope Reduction Detection | §4.3, §5.2 |
|
||
| get-shit-done | 决策覆盖门禁 | §5.2 |
|
||
| get-shit-done | Nyquist 验证层 | §9 验证 |
|
||
| get-shit-done | 上下文工程（Context Rot） | §8 风险 |
|
||
| hermes | 幻觉门控（产出物验证） | §5.2 |
|
||
| hermes | 心跳+reclaim+僵尸检测 | §8 风险 |
|
||
| claude-code | 四级权限体系 | §7 安全红线 |
|
||
| claude-code | Dream 记忆整合系统 | §4 长期参考 |
|
||
| supervision-practices | 分层审批策略 | §7 安全红线 |
|
||
| multi-agent-collaboration | 4 种编排 × 3 种通信协议 | §2 模型 |
|
||
| open-multi-agent | Goal→DAG 动态图构建 | §4.3 调整能力 |
|
||
| TradingAgents | 动态图构建 | §4.3 调整能力 |
|
||
| PRD-v3.0 | B4 人退到边缘 | §2.2 |
|
||
| PRD-v3.0 | 四相架构（§4） | §2 |
|
||
| PRD-v3.0 | Phase 3 共享意识空间 | §2, §3 |
|
||
| architecture-v2.6 | 黑板讨论示例 | §3.3 |
|
||
| architecture-v2.6 | @mention API + comment_type | §3.4 |
|
||
| v3.0-router-refactor | 广播认领 + 确定性交接 | §2 模型 |
|
||
| guardrails.yaml | 6 条安全红线 | §7 |
|
||
|
||
### A.9 调研文件清单
|
||
|
||
| 调研对象 | 路径 |
|
||
|---------|------|
|
||
| PRD v3.0 | `docs/PRD-v3.0.md` |
|
||
| architecture v3.0.1 | `docs/design/architecture-v3.0.md` |
|
||
| architecture v2.6（archive） | `docs/design/archive-2.0/architecture-v2.6.md` |
|
||
| v3.0 router refactor | `docs/design/archive-2.0/v3.0-router-refactor.md` |
|
||
| topic7 交互设计 | `docs/design/archive-2.0/topic7-interaction-dashboard-proposal.md` |
|
||
| ticker.py | `src/daemon/ticker.py`（960 行） |
|
||
| dispatcher.py | `src/daemon/dispatcher.py`（653 行） |
|
||
| router.py | `src/daemon/router.py`（195 行） |
|
||
| blackboard_routes.py | `src/api/blackboard_routes.py` |
|
||
| guardrails.yaml | `config/guardrails.yaml` |
|
||
| GSD practices | `wiki-vault/practices/get-shit-done-practices.md` |
|
||
| quality-gate practices | `wiki-vault/practices/quality-gate-patterns.md` |
|
||
| oh-my-codex practices | `wiki-vault/practices/oh-my-codex-practices.md` |
|
||
| agent lifecycle practices | `wiki-vault/practices/moziplus-agent-lifecycle-practices.md` |
|
||
| multi-agent collaboration | `wiki-vault/practices/multi-agent-collaboration-patterns.md` |
|
||
| claude-code insights | `wiki-vault/practices/claude-code-architecture-insights.md` |
|
||
| supervision practices | `wiki-vault/practices/supervision-practices.md` |
|
||
| skill engineering practices | `wiki-vault/practices/moziplus-skill-engineering-practices.md` |
|
||
|
||
### A.10 待确认事项
|
||
|
||
无。本方案为完整设计方案，待司马懿评审后决定下一步。
|
||
|
||
### A.11 司马懿评审记录（v1.2 修复）
|
||
|
||
**评审结论**：通过，需修复 3 个设计问题。
|
||
|
||
**3 个设计问题修复**：
|
||
|
||
| # | 问题 | 修复方案 | 位置 |
|
||
|---|------|---------|------|
|
||
| 1 | @mention 通知丢失（Agent busy 时 spawn 失败，mention 永远收不到） | 新增 `mention_queue` 表 + 重试机制 + 通知状态追踪 | §3.4 |
|
||
| 2 | 一轮结束检测不区分 done/failed/cancelled | 传给庞统的状态摘要包含维度信息 {done, failed, cancelled}，prompt 增加失败处理指引 | §4.1 |
|
||
| 3 | 司马懿 review 和庞统 review 执行顺序未定义 | tick 流程明确 8 步顺序，一轮结束检测在调度之后，mention 在 review 之后 | §4.4 |
|
||
|
||
**4 条建议采纳**：
|
||
|
||
| # | 建议 | 采纳情况 |
|
||
|---|------|---------|
|
||
| 4 | Spawn Prompt 补充 Boids 四条具体行为描述 | ✅ 已映射为 Separation/Alignment/Cohesion/Boundary 四条准则 |
|
||
| 5 | 代码改动清单缺少 MVP 优先级标注 | ✅ 每行加 MVP 列（✅ 必须 / ❌ 后续） |
|
||
| 6 | 风险表缺少 3 个关键风险（无限循环/assignee 缺失/token 消耗） | ✅ 新增 3 条风险 + 缓解方案 |
|
||
| 7 | 司马懿 review skill 设计方向 | ✅ 记录为参考，司马懿独立设计不阻塞 #01 |
|
||
|
||
**v1.2 新增章节**：
|
||
- §4.4 一轮结束后的执行顺序
|
||
- §4.5 防止庞统 review 无限循环
|
||
- §3.4 扩展 @mention 通知可靠性保障
|
||
|
||
**Rebuttal 备注无**——3 个设计问题全部接受，无争议。
|