auto-sync: 2026-05-31 11:40:10

docs/design/03-prompt-evolution.md

@@ -2,7 +2,7 @@
 
 **日期**: 2026-05-31
 **作者**: 庞统
-**状态**: v2.0 待评审
+**状态**: v2.1 修订中（司马懿评审意见已纳入）
 **前置**: `02-main-session-delegation.md`、`04-blackboard-collaboration-model.md`
 **参考**: PRD v3.0（B3 共享意识）、shared-consciousness-research.md
 
@@ -426,3 +426,73 @@ v1.x 做了正确的基础工作（三段式结构、身份注入、去 curl）
 | **规划方式** | ❌ Phase 查表 | ✅ 理解→拆解→动态调整 |
 
 v1.x 的所有基础设施（counter、router、spawner、bootstrap）完全复用，不动。
+
+---
+
+## 附录 A：司马懿评审意见及回应（2026-05-31）
+
+### FATAL-1: observation 边界未定义 → **采纳，改为"跨领域专业建议"**
+
+**司马懿原文**：observation 要有明确触发条件，不是"有专业判断就写"。纯粹不匹配（如司马懿看编码任务）应 NO_REPLY。建议只有领域有实际交叉时才写。
+
+**决定**：完全采纳。修改 claim prompt 的第 2 级响应：
+
+```
+2. 不是你的活，但你的专业领域和这个任务有实际交叉 → 写 observation comment
+   - 你看到什么风险？（从你的专业视角）
+   - 有什么跨领域建议？（数据依赖、风控约束、部署兼容等）
+   - 如果纯粹"不匹配"（你的领域和任务无交叉），NO_REPLY
+```
+
+**关键变化**：从"有专业判断就写"改为"领域有实际交叉才写"。这样只有关羽看风控相关编码任务、赵云看数据依赖相关任务时才写 observation，纯不匹配的仍然 NO_REPLY。
+
+### WARN-1: "一个 tick 只认领一个"约束位置 → **采纳**
+
+**司马懿原文**：v2.0 把这条约束放在认领动作描述中，不在约束段。建议保留在约束段。
+
+**决定**：在约束段恢复"一个 tick 只认领一个任务"。
+
+### WARN-2: executor.md API 策略自相矛盾 → **采纳**
+
+**司马懿原文**：§4.3 说 executor.md 不含 API，但 §3.2 的模板包含 API。实际 API 由 spawner 拼接。
+
+**决定**：executor.md 模板去掉 API 段，和 §4.3 保持一致。API 由 spawner._build_api_section() 注入。
+
+### WARN-3: 置信度标注无解析机制 → **采纳，暂缓**
+
+**司马懿原文**：标了 [confidence: 0.X] 但系统不解析，浪费 token。
+
+**决定**：v2.1 先不在 reviewer 模板中要求置信度标注。等 ticker 的 review 完成逻辑有解析能力后再加。当前审查者的角色定位和思维转变（从 checklist 到挑战者）已经足够。
+
+### INFO-1: planner 的苏格拉底提问路径 → **采纳，明确路径**
+
+**司马懿原文**：planner 是被 spawn 的 Agent，不是直接和用户对话。怎么提问？
+
+**决定**：planner 模板明确提问路径："需求不清时在黑板 comment 中提问（系统会通知用户），或发 Mail 给用户。"
+
+### Design-1: observe 性能量化 → **评估**
+
+**司马懿原文**：每轮广播最多多少 observe comment？对上下文长度的影响？
+
+**评估**：采纳 FATAL-1 的边界定义后，observe comment 大幅减少。典型场景：5 个任务 × 6 个 Agent，只有跨领域交叉才会产生 observe。估算每轮最多 3-5 条 observation（而非之前最坏的 25 条）。每条限制 200 字以内。对上下文影响可控。
+
+**补充机制**：如果未来 comment 膨胀成为问题，可在 expand=all 时只加载最近 N 条 comment（已有 precedent：Depends-on 产出摘要用了类似机制）。
+
+### Design-2: 分三步实施 → **采纳**
+
+**司马懿原文**：建议分三步逐步验证。
+
+**决定**：采纳三步方案：
+1. Phase 1: claim prompt（三级响应 + observe 边界）—— 变化最大，先验证
+2. Phase 2: executor.md + reviewer.md —— 核心执行/审查流程
+3. Phase 3: review_simayi.md + review_pangtong.md + planner.md —— 特殊角色
+
+### Risk-1: observe 影响 ticker 状态流转 → **不存在**
+
+**司马懿原文**：observe comment 可能被系统当作"Agent 对任务有响应"，触发不同的完成逻辑。
+
+**验证结果**：代码核实确认不存在此风险。广播场景下 `_broadcast_claim` 调用 `spawn_full_agent` 时没有传 `on_complete` 回调（为 None）。Agent 的所有行为（claim、写 comment）都通过 API 直接操作黑板，系统不根据 Agent 回复内容做状态流转。Agent 进程退出后只做 counter release。所以 observe comment 完全不影响状态机。
+
+### Risk-2: token 成本 → **评估**
+
+claim prompt v2.1 比 v1.x 增加约 100 token（"共享黑板"解释 + observe 路径 + comment API）。6 个 Agent × 每轮一次 = +600 token / tick。按 30 秒间隔，一小时 +72000 token ≈ +$0.15（按 GPT-4 级别估算）。可接受。