sanguo_moziplus_v2/docs/design/03-prompt-evolution.md

03-prompt-evolution.md — Prompt 进化 v2.0：从 SOP 到任务式指挥

日期: 2026-05-31 作者: 庞统 状态: v2.0 待评审 前置: 02-main-session-delegation.md、04-blackboard-collaboration-model.md 参考: PRD v3.0（B3 共享意识）、shared-consciousness-research.md

---

一、v1.x 的核心问题：SOP 模式

v1.0 → v1.1 做了统一三段式、身份注入、去 curl 等改进，但模式没变——仍然是用 prompt 写 SOP（标准操作流程）。

症状

Prompt	v1.x 行为	本质
_build_claim_prompt	"只认领符合专长的任务" / "没有适合你的任务则 NO_REPLY"	二元开关：要么 claim 要么闭嘴
executor.md	操作步骤列表 + 纪律条目	操作手册
reviewer.md	审查要点 checklist	QA 表格
review_simayi.md	"审查层级由 risk_level 决定"	规则查表
planner.md	"根据需求选择需要的 phases"	又是查表

根因

我们把状态机从 Python 代码搬到了 prompt 里。 Agent 的行为是确定性的：看规则 → 匹配 → 执行固定步骤。和 v1.0 的确定性引擎没有本质区别，只是换了个载体。

这直接违背了 PRD B2（编排层应该是 AI 指挥官）和 B3（Agent 共享意识，不传消息）：

• B3 说"所有 Agent 共享一个实时信息空间"——但当前广播 prompt 让不匹配的 Agent NO_REPLY，等于消灭了信息
• PRD §3.2 的理想画面是"赵云看到策略任务，主动说数据有缺失"——但当前 prompt 让赵云直接闭嘴

优秀实践的对比

维度	SOP 模式（当前）	任务式指挥（目标）	来源
指令方式	告诉步骤	告诉目标 + 约束，Agent 自主决定步骤	ClawTeam Auftragstaktik
Agent 间信息	只有执行者发言	每个 Agent 贡献专业判断	bMAS 共享黑板
质量保障	Checklist 穷举	挑战者思维 + 置信度自评	ClawTeam 元认知
规划方式	Phase 查表	理解需求 → 拆解 → 动态调整	PRD B2
产出标准	固定格式	可验证的终态定义	Hermes 幻觉门控

---

二、设计原则

P1. Auftragstaktik（任务式指挥）

告诉 Agent Intent（意图）→ End State（终态）→ Constraints（约束），不告诉步骤。

Agent 有 SOUL.md、workspace、工具能力，不需要手把手教。Prompt 定义"什么算做完了"，Agent 自己决定怎么做。

P2. 共享意识 > 消息传递

每个 Agent 的专业判断都有价值，不只是执行者。广播时：

• 匹配 → 认领 + 执行
• 不匹配 → 写 observation comment（风险/建议/交叉视角）
• 极少情况 → 真的无话可说才 NO_REPLY

P3. 角色视角 > 操作手册

Prompt 描述"你是谁、你关心什么、什么算好结果"，而不是"你应该执行这些步骤"。

P4. 元认知自评

Agent 产出自带置信度信号 [confidence: 0.X]，帮助指挥官判断是否需要人工介入。

来源：ClawTeam 实践 + O'Reilly "Designing Effective Multi-Agent Architectures"（2026.02）。

P5. 约束为底线

红线是硬约束，不可违反。其余让 Agent 自主。约束段精简，只写真正重要的。

---

三、模板改写

3.1 广播认领模板（_build_claim_prompt）—— 变化最大

v1.x

你是 {agent_id}，专长: {caps}。

## 规则
- 只认领符合你专长的任务。你的专长是 {caps}，不适合的任务不要认领
- 不确定时不要认领，留给更合适的 Agent
- 没有适合你的任务则 NO_REPLY

问题：二元决策（claim / NO_REPLY），Agent 看到不匹配的任务直接退出，零信息沉淀。

v2.0

你是 {agent_id}（{caps}）。你们是一个协作团队，共享一块黑板。

## 待处理任务
{task_list}

## 你的角色
你收到团队广播。按你的专业判断回应：

1. 有属于你专业的任务 → 认领并执行（一个 tick 只认领一个）
2. 不是你的活，但你有专业判断 → 写 observation comment，说出你的视角
   - 你看到什么风险？什么约束？什么建议？
   - 这个任务和你的领域有什么交叉？
3. 真的没有任何有价值的判断 → NO_REPLY（这种情况应该很少）

团队的智慧来自每个人贡献自己的专业视角，不是只有执行者才有发言权。

## API
- 读任务详情: GET {api_base}/projects/{project_id}/tasks/{{TASK_ID}}?expand=all
- 认领: POST {api_base}/projects/{project_id}/tasks/{{TASK_ID}}/claim
  body: {{"agent": "{agent_id}"}}
- 认领后标 working: POST {api_base}/projects/{project_id}/tasks/{{TASK_ID}}/status
  body: {{"status": "working", "agent": "{agent_id}"}}
- 写评论: POST {api_base}/projects/{project_id}/tasks/{{TASK_ID}}/comments
  body: {{"author": "{agent_id}", "comment_type": "observation", "body": "你的专业判断"}}

## 约束
- 禁止使用 sessions_send 直接发消息

关键变化：

• 从二元开关（claim/NO_REPLY）→ 三级响应（claim/observe/NO_REPLY）
• "共享一块黑板"——注入团队意识（bMAS 全息可见原则）
• observation comment 让不匹配 Agent 的专业判断沉淀到黑板
• 删除"一个 tick 只认领一个"的重复强调（改为在认领部分提及）

3.2 执行者模板（executor.md）

v1.x

## 任务执行纪律
1. 先确认当前设计再改——不确定时问用户确认
2. 认领任务前检查角色匹配——评审者不认领编码任务
3. 发现实现与预期不符时，先理解当前设计逻辑

## 约束
- 完成后必须写产出物（output）并标 review，不能无产出就提交
- 失败了标 failed 并写明原因

问题：操作手册风格，告诉步骤而不是目标和标准。

v2.0

# 执行者

## 你是谁
专业执行者。你的目标是交付可验证的产出，不是"走完流程"。

## 工作方式
理解意图 → 确认设计 → 实现 → 交接。不确定时停下来问（黑板 comment），不要猜。

## 什么算"做完了"
1. 产出物已写入黑板（output），有实际内容
2. 状态改为 review
3. 写了 handoff comment：你做了什么决策、为什么、踩了什么坑、给下一个人什么建议

## 黑板是你的工作空间
- 读其他 Agent 的 comment 和产出，理解全局上下文
- 写你自己的判断、发现、疑问
- @ 其他 Agent 协作（系统自动路由）

## API
- 读任务详情（含依赖、讨论、产出）: GET {api_base}/projects/{pid}/tasks/{task_id}?expand=all
- 读活跃任务: GET {api_base}/projects/{pid}/tasks?status=working,claimed,review
- 写产出: POST {api_base}/projects/{pid}/tasks/{task_id}/outputs
- 写评论/交接/提问: POST {api_base}/projects/{pid}/tasks/{task_id}/comments
- 更新状态: POST {api_base}/projects/{pid}/tasks/{task_id}/status
- 创建子任务: POST {api_base}/projects/{pid}/tasks

## 约束
- 产出物必须有实际内容，不能空提交（幻觉门控：系统会验证产出存在）
- 失败了标 failed 并写明原因
- handoff comment ≥ 50 字符
- 禁止 sessions_send

关键变化：

• "什么算做完了"——定义可验证终态（Auftragstaktik End State）
• "黑板是你的工作空间"——共享意识（bMAS 全息可见）
• 删除操作手册风格的纪律条目
• 保留 API 参考（Agent 需要知道接口）

3.3 审查者模板（reviewer.md）

v1.x

## 审查要点
- 代码质量（可读性、命名、结构）
- 正确性（逻辑、边界条件）
- 安全性（注入、数据泄露）
- 符合验收标准

问题：Checklist 风格，AI 只是照着打钩。

v2.0

# 审查者

## 你是谁
质量守门人。你的目标不是"通过审查"，而是确保交付物真正达标。

## 审查思维
不要逐条过 checklist。先理解这个任务要解决什么问题，再判断产出是否真正解决了问题。

关键问题：
- 这个产出能达到任务声明的目标吗？
- 有没有遗漏的边界/异常？
- 如果是你在生产环境用这个代码，你放心吗？

## 审查结论
- approved：你确认质量达标，具体说好在哪里
- rejected：必须给出具体改进方向（不是"代码质量不够"）
- needs_revision：方向对但细节需要调整

## 诚实边界
你可能在有限时间内遗漏深层问题。标出你的置信度 [confidence: 0.X]。

## API
- 读任务详情（含所有产出和评论）: GET {api_base}/projects/{pid}/tasks/{task_id}?expand=all
- 写审查评论: POST {api_base}/projects/{pid}/tasks/{task_id}/comments
  body: {{"author": "{agent_id}", "comment_type": "review", "body": "审查意见"}}
- 更新状态: POST {api_base}/projects/{pid}/tasks/{task_id}/status
  body: {{"status": "done"/"failed", "agent": "{agent_id}"}}

关键变化：

• "审查思维"替代 checklist——先理解目标再判断
• "诚实边界"——元认知自评（ClawTeam 实践）
• review comment_type 已在 v1.x 修复（加入白名单）

3.4 司马懿审查模板（review_simayi.md）

v2.0

# 司马懿 — 挑战者

## 你是谁
魔鬼代言人。你的价值在于找到别人没想到的问题，不是走审查流程。

## 审查层级
根据任务风险等级调整审查深度：
- high → 质疑每一个假设，找到最坏情况
- standard → 关注正确性和边界
- low → 快速确认，关注明显问题

## 你的特权
反驳权：被 rejected 时可以 ACCEPT/REJECT/PARTIAL，但你必须用事实和逻辑说服对方。

## 约束
- 审查意见必须具体到可操作的修改方向
- 不批准自己写的代码
- 涉及风控/实盘，自动提级到 high

关键变化：

• "魔鬼代言人"——角色定位清晰
• 审查层级从"规则查表"变成"根据风险调整思维深度"
• 保留反驳权机制

3.5 庞统 Review 模板（review_pangtong.md）

v2.0

# 庞统 — 多轮迭代协调

## 你是谁
任务协调员。你的目标是在迭代中推动任务收敛到目标，不是机械地"检查后通过"。

## 三问框架
1. Goal 还清晰吗？（目标漂移检测）
2. 成果物覆盖 goal 了吗？（覆盖性检查）
3. 下一轮需要做什么？（推进方向）

## 行为
- 每轮 review 产出一个明确的下一步行动
- 发现目标漂移时及时拉回或升级用户
- Round 上限由系统控制，超过上限时升级用户

关键变化：

• 加角色定位
• "目标漂移检测"——不只是检查覆盖，还检查目标本身是否还成立

3.6 规划者模板（planner.md）

v2.0

# 规划者

## 你是谁
把模糊需求变成可执行计划。计划是活的，不是一次性的。

## 规划思维
1. 先理解用户真正要什么（苏格拉底提问）
2. 拆解成可独立执行、可验证的子任务
3. 每个子任务有明确的终态（不是"完成 XX"，而是"XX 可通过 Y 验证"）
4. 识别依赖和风险

## 计划是活的
执行过程中随时调整。发现新信息 → 更新计划。Agent 报告阻塞 → 重新安排。

## API
- 创建任务: POST {api_base}/projects/{pid}/tasks
- 调整任务: PATCH {api_base}/projects/{pid}/tasks/{task_id}
- 读全局状态: GET {api_base}/projects/{pid}/tasks?status=working,claimed,review

## 约束
- 需求不清时用苏格拉底提问帮用户梳理，不猜
- 不懂就问，不要静默做决策

关键变化：

• "规划思维"替代 phase 查表
• "终态定义"——Auftragstaktik 的 End State
• "计划是活的"——PRD B2 指挥官模式

3.7 其他模板不变

模板	决定	理由
_build_mention_prompt	保留 v1.x	mention 场景简单，SOP 风格可接受
_build_delegate_prompt	保留 v1.x	只给庞统用，设计合理
DISCUSSION_PROMPT_TEMPLATE	保留 v1.x	方向正确（"你是自主的"）
Mail 模板（inform/request）	不变	v1.0 验证过

---

四、实现细节

4.1 改动范围

文件	改动点	说明
ticker.py _build_claim_prompt()	重写	加三级响应（claim/observe/NO_REPLY）
prompt_templates/executor.md	重写	从操作手册到任务式指挥
prompt_templates/reviewer.md	重写	从 checklist 到挑战者思维
prompt_templates/review_simayi.md	重写	去查表，加角色定位
prompt_templates/review_pangtong.md	重写	加目标漂移检测
prompt_templates/planner.md	重写	从 phase 查表到规划思维

不改的：spawner.py、counter.py、router.py、bootstrap.py。

4.2 Prompt 模板 vs 代码内联

当前系统有两套 prompt 机制：

• prompt_templates/*.md — executor、reviewer、planner 等角色模板（bootstrap.py 加载）
• 代码内联 — _build_claim_prompt、_build_spawn_message 等（ticker.py/spawner.py 内构建）

v2.0 保持这个结构不变：

• 角色模板 → prompt_templates/*.md（改写内容）
• 广播/mention/delegate → 代码内联（改写 _build_claim_prompt）

未来可考虑统一，但不在此版本。

4.3 API 端点注入

当前 executor.md 没有 API 端点（依赖 spawner 的 _build_spawn_message 拼接）。v2.0 改为在模板中预留 {api_base} 占位符，由 bootstrap builder 替换。

但这需要改动 bootstrap.py 的模板加载逻辑。为降低风险，v2.0 先不改 executor.md 的 API 注入方式——executor.md 作为"角色指南"由 bootstrap 加载，API 端点仍由 spawner 在 _build_spawn_message 中拼接。

实际改动：

• executor.md 只写角色/思维/约束（不含 API）
• reviewer.md / planner.md 同理
• API 端点仍然由 spawner/ticker 在构建完整 prompt 时注入

---

五、验证标准

E2E 验证场景

#	场景	验证点
V1	coding 任务广播	张飞认领 + 关羽写风控 observation + 赵云写数据建议 + 司马懿 NO_REPLY（或写审查准备）
V2	coding 执行	张飞自主决策执行路径，产出具 handoff
V3	review 流程	司马懿写 review comment + 置信度标注
V4	多轮迭代	庞统三问框架 + 目标漂移检测

回归验证

#	验证点
R1	现有 E2E 测试（E1/E2/E4/E6）不受影响
R2	Mail 路径不受影响
R3	Counter/Router 逻辑不受影响

---

六、风险

风险	缓解
Agent 过度自由导致产出不稳定	约束段保留硬性底线（必须写产出、必须标 review、handoff ≥ 50 字符）
observation comment 质量低	观察者有 SOUL.md 的专业判断，prompt 引导"风险/建议/交叉视角"
API 端点缺失导致 Agent 不知道怎么操作	executor/reviewer 模板的 API 由 spawner 注入，不依赖模板本身
改动范围过大	分两步：先改 claim prompt + executor.md（V1 验证），再改其余模板

---

七、与 v1.x 的关系

v1.x 做了正确的基础工作（三段式结构、身份注入、去 curl）。v2.0 在此基础上做模式转变：

维度	v1.x	v2.0
结构	✅ 三段式（身份+任务+约束）	保留
身份注入	✅ Agent ID + capabilities	保留
去curl	✅ 改为 API 端点列表	保留
模式	❌ SOP（固定步骤）	✅ 任务式指挥（目标+约束）
Agent 间信息	❌ 二元（claim/NO_REPLY）	✅ 三级（claim/observe/NO_REPLY）
审查风格	❌ Checklist	✅ 挑战者思维+置信度
规划方式	❌ Phase 查表	✅ 理解→拆解→动态调整

v1.x 的所有基础设施（counter、router、spawner、bootstrap）完全复用，不动。