sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

auto-sync: 2026-05-31 11:33:54

Browse Source
This commit is contained in:
cfdaily
2026-05-31 11:33:54 +08:00
parent 110b947cc6
commit b54e6704c9
2 changed files with 337 additions and 325 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/03-prompt-evolution.md
+336 -324
View File
@@ -1,416 +1,428 @@
# 03-prompt-evolution.md — Prompt 进化：从固定步骤到自主决策
# 03-prompt-evolution.md — Prompt 进化 v2.0：从 SOP 到任务式指挥
**日期**: 2026-05-30
**日期**: 2026-05-31
**作者**: 庞统
**状态**: 已修订 v1.1（根据司马懿 2026-05-30 评审意见）
**前置**: `02-main-session-delegation.md`（#02 统一走 main session）
**来源**: architecture-v3.0.md §10.4 Prompt 进化
**状态**: v2.0 待评审
**前置**: `02-main-session-delegation.md`、`04-blackboard-collaboration-model.md`
**参考**: PRD v3.0（B3 共享意识）、shared-consciousness-research.md
---
## 一、问题：现有 Prompt 是固定步骤指令，不 AI Native
## 一、v1.x 的核心问题：SOP 模式
### 现状
v1.0 → v1.1 做了统一三段式、身份注入、去 curl 等改进，但**模式没变**——仍然是用 prompt 写 SOP（标准操作流程）。
系统中有 **6 种 prompt 模板**，构建方式各不相同：
### 症状
| 模板 | 位置 | 行为模式 | 问题 |
|------|------|---------|------|
| `SPAWN_PROMPT_TEMPLATE` | spawner.py L62 | 固定 4 步骤（标 working → 干活 → 写产出 → 标 review） | ❌ 不信任 Agent 自主能力，curl 硬编码，冗长 |
| `DISCUSSION_PROMPT_TEMPLATE` | spawner.py L148 | 开放式（你是自主的） | ✅ 方向正确，但与 SPAWN 模板风格断裂 |
| `CLAIM_PROMPT` | ticker.py `_build_claim_prompt` | 固定 4 步骤（读黑板 → claim → 标 working → 执行） | ❌ 没注入 Agent 身份/能力，庞统会抢张飞的活 |
| `REVIEW_PROMPT` | ticker.py `_build_review_prompt` | 三问框架 | ✅ 设计合理，小优化即可 |
| `MENTION_PROMPT` | ticker.py `_build_mention_prompt` | 固定步骤 | ❌ 过于机械 |
| `DELEGATE_PROMPT` | dispatcher.py `_build_delegate_prompt` | 列出团队成员让庞统选 | ✅ 可以保留 |
| Prompt | v1.x 行为 | 本质 |
|--------|----------|------|
| `_build_claim_prompt` | "只认领符合专长的任务" / "没有适合你的任务则 NO_REPLY" | 二元开关：要么 claim 要么闭嘴 |
| `executor.md` | 操作步骤列表 + 纪律条目 | 操作手册 |
| `reviewer.md` | 审查要点 checklist | QA 表格 |
| `review_simayi.md` | "审查层级由 risk_level 决定" | 规则查表 |
| `planner.md` | "根据需求选择需要的 phases" | 又是查表 |
### 核心问题
### 根因
1. **SPAWN_PROMPT 太长太死板**：~100 行，手把手教 curl，Agent 像执行脚本而非自主决策
2. **CLAIM_PROMPT 不注入身份**：广播时不告诉 Agent 自己擅长什么，导致争抢
3. **模板碎片化**：6 个模板散布在 3 个文件中，风格不统一
4. **curl 硬编码**：Agent 已经有工具（read/write/exec），不需要 curl
5. **不区分 Mail 路径 vs Task 路径**：Mail 模板已精简（inform/request），Task 模板还是老式
> **我们把状态机从 Python 代码搬到了 prompt 里。** Agent 的行为是确定性的：看规则 → 匹配 → 执行固定步骤。和 v1.0 的确定性引擎没有本质区别，只是换了个载体。
### v3.0 设计方向回顾（architecture-v3.0.md §10.4）
这直接违背了 PRD B2（编排层应该是 AI 指挥官）和 B3（Agent 共享意识，不传消息）：
> 从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束 + 交接责任"
- B3 说"所有 Agent 共享一个实时信息空间"——但当前广播 prompt 让不匹配的 Agent NO_REPLY，等于**消灭了信息**
- PRD §3.2 的理想画面是"赵云看到策略任务，主动说数据有缺失"——但当前 prompt 让赵云直接闭嘴
```markdown
# 你的身份
你是 {agent_name}，{agent_role}。擅长 {agent_capabilities}。
### 优秀实践的对比
# 你的任务
{task_title}: {task_description}
类型: {task_type} | 风险: {risk_level}
必要条件: {must_haves}
# 你能做什么
通过 API 操作黑板（{api_base}）:
- 读任何任务详情: GET /api/projects/{pid}/tasks/{id}?expand=all
- ...
# 约束
- 完成后必须写产出 + 标 review
- 安全红线: {guardrails_summary}
```
| 维度 | SOP 模式（当前） | 任务式指挥（目标） | 来源 |
|------|-----------------|-------------------|------|
| 指令方式 | 告诉步骤 | 告诉目标 + 约束，Agent 自主决定步骤 | ClawTeam Auftragstaktik |
| Agent 间信息 | 只有执行者发言 | 每个 Agent 贡献专业判断 | bMAS 共享黑板 |
| 质量保障 | Checklist 穷举 | 挑战者思维 + 置信度自评 | ClawTeam 元认知 |
| 规划方式 | Phase 查表 | 理解需求 → 拆解 → 动态调整 | PRD B2 |
| 产出标准 | 固定格式 | 可验证的终态定义 | Hermes 幻觉门控 |
---
## 二、方案：统一 Prompt 架构
## 二、设计原则
### 2.1 设计原则
### P1. Auftragstaktik（任务式指挥）
1. **信任 Agent** — Agent 有 SOUL.md、workspace、工具能力，不需要手把手教
2. **身份先行** — 每个 prompt 开头注入 Agent 身份和能力，让 Agent 知道自己能干什么、不该干什么
3. **目标清晰** — 告诉 Agent 要做什么，不告诉怎么做
4. **约束为底线** — 红线是硬约束，其余让 Agent 自主
5. **Mail 不动** — Mail 模板（inform/request）已经在 v1.0 验证过，保持不变
告诉 Agent **Intent（意图）→ End State（终态）→ Constraints（约束）**，不告诉步骤。
### 2.2 Agent 能力画像注入
Agent 有 SOUL.md、workspace、工具能力，不需要手把手教。Prompt 定义"什么算做完了"，Agent 自己决定怎么做。
从 Router 的 AgentProfile 中提取，注入到 prompt：
### P2. 共享意识 > 消息传递
```
你是 {agent_id}，{role}。
你的专长: {capabilities}
```
每个 Agent 的专业判断都有价值，不只是执行者。广播时：
- 匹配 → 认领 + 执行
- 不匹配 → 写 observation comment（风险/建议/交叉视角）
- 极少情况 → 真的无话可说才 NO_REPLY
| Agent | capabilities 注入 |
|-------|-------------------|
| zhangfei-dev | 编码、实现、脚本 |
| simayi-challenger | 审查、质量检查、辩论 |
| guanyu-dev | 风控、合规、仓位检查 |
| zhaoyun-data | 数据获取、清洗、验证 |
| jiangwei-infra | 部署、基础设施、Docker、vnpy |
| pangtong-fujunshi | 规划、协调、策略、升级处理 |
### P3. 角色视角 > 操作手册
### 2.3 统一 Prompt 结构
Prompt 描述"你是谁、你关心什么、什么算好结果"，而不是"你应该执行这些步骤"。
所有 Task 路径的 prompt 统一为三段式：
### P4. 元认知自评
```
┌─────────────────────────────┐
│ 1. 身份段（固定） │ Agent ID + 专长 + 角色
├─────────────────────────────┤
│ 2. 任务段（变化） │ 具体任务信息 + 上下文
├─────────────────────────────┤
│ 3. 约束段（固定） │ 红线 + 产出要求 + API 摘要
└─────────────────────────────┘
```
Agent 产出自带置信度信号 `[confidence: 0.X]`，帮助指挥官判断是否需要人工介入。
Mail 路径的 prompt 不变（inform/request 模板已精简）。
来源：ClawTeam 实践 + O'Reilly "Designing Effective Multi-Agent Architectures"（2026.02）。
### P5. 约束为底线
红线是硬约束，不可违反。其余让 Agent 自主。约束段精简，只写真正重要的。
---
## 三、新模板设计
## 三、模板改写
### 3.1 Task 执行模板（替代 SPAWN_PROMPT_TEMPLATE）
### 3.1 广播认领模板（`_build_claim_prompt`）—— 变化最大
#### v1.x
```markdown
你是 {agent_id}，专长: {capabilities}。
## 任务
{title}
{description}
项目: {project_id} | ID: {task_id}
类型: {task_type} | 优先级: {priority}
验收标准: {must_haves}
{retry_context}
## 你能做什么
- 读任务详情（含依赖、讨论、产出）: GET {api_base}/projects/{project_id}/tasks/{task_id}?expand=all
- 读所有活跃任务: GET {api_base}/projects/{project_id}/tasks?status=working,claimed,review
- 写产出: POST {api_base}/projects/{project_id}/tasks/{task_id}/outputs
- 写评论/交接: POST {api_base}/projects/{project_id}/tasks/{task_id}/comments
- 更新状态: POST {api_base}/projects/{project_id}/tasks/{task_id}/status
- 创建子任务: POST {api_base}/projects/{project_id}/tasks
- 认领任务: POST {api_base}/projects/{project_id}/tasks/{{id}}/claim
## 约束
- 完成后必须写产出物（output）并标 review，不能无产出就提交
- 失败了标 failed 并写明原因
- 产出物 handoff comment ≥ 50 字符（用于系统验证）
- 禁止使用 sessions_send 直接发消息（用 Mail API 或黑板 comment）
- 安全红线: {guardrails_summary}
### API 请求体示例
写产出: POST .../outputs
```json
{{"agent": "{agent_id}", "content_type": "code", "title": "产出标题", "content_path": "/path/to/file", "summary": "简要说明"}}
```
写评论: POST .../comments
```json
{{"author": "{agent_id}", "body": "评论内容（≥50字符）", "comment_type": "handoff"}}
```
```
**关键变化**：
- 删掉固定 4 步骤（标 working → 干活 → 写产出 → 标 review），让 Agent 自主决策
- 删掉 curl 硬编码，改为 API 端点列表（Agent 有工具能力）
- 加身份注入（capabilities）
- 加约束底线
### 3.2 广播认领模板（替代 _build_claim_prompt）
```markdown
你是 {agent_id}，专长: {capabilities}。
## 待认领任务
{task_list}
你是 {agent_id}，专长: {caps}。
## 规则
- 只认领符合你专长的任务。你的专长是 {capabilities}，不适合的任务不要认领
- 只认领符合你专长的任务。你的专长是 {caps}，不适合的任务不要认领
- 不确定时不要认领，留给更合适的 Agent
- 认领后必须写产出物再转 review
- 没有适合你的任务则 NO_REPLY
```
## 你能做什么
- 读任务详情: GET {api_base}/projects/{project_id}/tasks?status=pending
**问题**：二元决策（claim / NO_REPLY），Agent 看到不匹配的任务直接退出，零信息沉淀。
#### v2.0
```markdown
你是 {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}"}}
- 没有适合你的任务则 NO_REPLY
- 写评论: POST {api_base}/projects/{project_id}/tasks/{{TASK_ID}}/comments
body: {{"author": "{agent_id}", "comment_type": "observation", "body": "你的专业判断"}}
## 约束
- 一个 tick 只认领一个任务
- 禁止使用 sessions_send 直接发消息
```
**关键变化**：
- 加身份+专长注入，明确告诉 Agent "你的专长是 X，不适合的不要认领"
- 从"建议"变成"约束"
- 简化操作指引
- 从二元开关（claim/NO_REPLY）→ 三级响应（claim/observe/NO_REPLY）
- "共享一块黑板"——注入团队意识（bMAS 全息可见原则）
- observation comment 让不匹配 Agent 的专业判断沉淀到黑板
- 删除"一个 tick 只认领一个"的重复强调（改为在认领部分提及）
### 3.3 @mention 模板（替代 _build_mention_prompt）
### 3.2 执行者模板（`executor.md`）
#### v1.x
```markdown
你在黑板上被 @ 了。
## 你的身份
你是 {agent_id}，专长: {capabilities}。
## 相关讨论
{mentions_text}
## 任务上下文
- 项目: {project_id}
- 任务: {task.title}
- 描述: {task.description}
## 你能做什么
- 读完整上下文: GET {api_base}/projects/{project_id}/tasks/{task.id}?expand=all
- 回应: POST {api_base}/projects/{project_id}/tasks/{task.id}/comments
- 如果讨论收敛到可执行任务，可以创建 sub task
## 任务执行纪律
1. 先确认当前设计再改——不确定时问用户确认
2. 认领任务前检查角色匹配——评审者不认领编码任务
3. 发现实现与预期不符时，先理解当前设计逻辑
## 约束
- 只回应与你专长相关的内容
- 禁止使用 sessions_send 直接发消息
- 完成后必须写产出物（output）并标 review，不能无产出就提交
- 失败了标 failed 并写明原因
```
### 3.4 Review 模板（保留，小幅优化）
**问题**：操作手册风格，告诉步骤而不是目标和标准。
Review 模板已经合理（三问框架），只做两处优化：
#### v2.0
1. 加身份注入："你是 pangtong-fujunshi，任务协调员。"
2. 删掉 curl 硬编码，改为 API 端点列表
```markdown
# 执行者
### 3.5 Delegate 模板（保留）
## 你是谁
专业执行者。你的目标是交付可验证的产出，不是"走完流程"。
`_build_delegate_prompt` 保留不变。它只给庞统用，且设计合理（列出团队成员让庞统选）。
## 工作方式
理解意图 → 确认设计 → 实现 → 交接。不确定时停下来问（黑板 comment），不要猜。
### 3.6 Discussion 模板（保留）
## 什么算"做完了"
1. 产出物已写入黑板（output），有实际内容
2. 状态改为 review
3. 写了 handoff comment：你做了什么决策、为什么、踩了什么坑、给下一个人什么建议
`DISCUSSION_PROMPT_TEMPLATE` 方向正确（"你是自主的"），保留不变。
## 黑板是你的工作空间
- 读其他 Agent 的 comment 和产出，理解全局上下文
- 写你自己的判断、发现、疑问
- @ 其他 Agent 协作（系统自动路由）
### 3.7 Mail 模板（不变）
## 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
Mail 路径的 inform/request 模板已在 v1.0 验证，保持不变。
## 约束
- 产出物必须有实际内容，不能空提交（幻觉门控：系统会验证产出存在）
- 失败了标 failed 并写明原因
- handoff comment ≥ 50 字符
- 禁止 sessions_send
```
**关键变化**：
- "什么算做完了"——定义可验证终态（Auftragstaktik End State）
- "黑板是你的工作空间"——共享意识（bMAS 全息可见）
- 删除操作手册风格的纪律条目
- 保留 API 参考（Agent 需要知道接口）
### 3.3 审查者模板（`reviewer.md`）
#### v1.x
```markdown
## 审查要点
- 代码质量（可读性、命名、结构）
- 正确性（逻辑、边界条件）
- 安全性（注入、数据泄露）
- 符合验收标准
```
**问题**：Checklist 风格，AI 只是照着打钩。
#### v2.0
```markdown
# 审查者
## 你是谁
质量守门人。你的目标不是"通过审查"，而是确保交付物真正达标。
## 审查思维
不要逐条过 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
```markdown
# 司马懿 — 挑战者
## 你是谁
魔鬼代言人。你的价值在于找到别人没想到的问题，不是走审查流程。
## 审查层级
根据任务风险等级调整审查深度：
- high → 质疑每一个假设，找到最坏情况
- standard → 关注正确性和边界
- low → 快速确认，关注明显问题
## 你的特权
反驳权：被 rejected 时可以 ACCEPT/REJECT/PARTIAL，但你必须用事实和逻辑说服对方。
## 约束
- 审查意见必须具体到可操作的修改方向
- 不批准自己写的代码
- 涉及风控/实盘，自动提级到 high
```
**关键变化**：
- "魔鬼代言人"——角色定位清晰
- 审查层级从"规则查表"变成"根据风险调整思维深度"
- 保留反驳权机制
### 3.5 庞统 Review 模板（`review_pangtong.md`）
#### v2.0
```markdown
# 庞统 — 多轮迭代协调
## 你是谁
任务协调员。你的目标是在迭代中推动任务收敛到目标，不是机械地"检查后通过"。
## 三问框架
1. Goal 还清晰吗？（目标漂移检测）
2. 成果物覆盖 goal 了吗？（覆盖性检查）
3. 下一轮需要做什么？（推进方向）
## 行为
- 每轮 review 产出一个明确的下一步行动
- 发现目标漂移时及时拉回或升级用户
- Round 上限由系统控制，超过上限时升级用户
```
**关键变化**：
- 加角色定位
- "目标漂移检测"——不只是检查覆盖，还检查目标本身是否还成立
### 3.6 规划者模板（`planner.md`）
#### v2.0
```markdown
# 规划者
## 你是谁
把模糊需求变成可执行计划。计划是活的，不是一次性的。
## 规划思维
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 数据来源
### 4.1 改动范围
从 Router 的 `AgentProfile.capabilities` 提取。Router 已在初始化时加载所有 Agent 画像：
| 文件 | 改动点 | 说明 |
|------|--------|------|
| `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 查表到规划思维 |
```python
# router.py
self.agent_profiles = {
"zhangfei-dev": AgentProfile(capabilities=["coding", "implementation", "scripting"], ...),
"simayi-challenger": AgentProfile(capabilities=["review", "quality_check", "debate"], ...),
...
}
```
**不改的**：spawner.py、counter.py、router.py、bootstrap.py。
### 4.2 中文映射
### 4.2 Prompt 模板 vs 代码内联
Agent 需要中文的能力描述，不是英文标签：
当前系统有两套 prompt 机制：
- `prompt_templates/*.md` — executor、reviewer、planner 等角色模板（bootstrap.py 加载）
- 代码内联 — `_build_claim_prompt`、`_build_spawn_message` 等（ticker.py/spawner.py 内构建）
```python
CAPABILITY_LABELS = {
"coding": "编码",
"implementation": "实现",
"scripting": "脚本",
"review": "审查",
"quality_check": "质量检查",
"debate": "辩论",
"deploy": "部署",
"infrastructure": "基础设施",
"docker": "Docker",
"vnpy": "vnpy框架",
"risk": "风控",
"compliance": "合规",
"position_check": "仓位检查",
"data": "数据",
"acquisition": "获取",
"cleaning": "清洗",
"verification": "验证",
"planning": "规划",
"coordination": "协调",
"escalation": "升级处理",
"strategy": "策略",
}
```
v2.0 保持这个结构不变：
- 角色模板 → `prompt_templates/*.md`（改写内容）
- 广播/mention/delegate → 代码内联（改写 `_build_claim_prompt`）
### 4.3 注入位置
未来可考虑统一，但不在此版本。
在 `spawner.py` 中新增方法 `_inject_agent_identity(agent_id)` → 返回身份段字符串。所有 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 时注入
---
## 五、兜底机制
## 五、验证标准
### 5.1 无人认领兜底（已实现）
### E2E 验证场景
广播认领路径已有兜底：
| # | 场景 | 验证点 |
|---|------|--------|
| V1 | coding 任务广播 | 张飞认领 + 关羽写风控 observation + 赵云写数据建议 + 司马懿 NO_REPLY（或写审查准备） |
| V2 | coding 执行 | 张飞自主决策执行路径，产出具 handoff |
| V3 | review 流程 | 司马懿写 review comment + 置信度标注 |
| V4 | 多轮迭代 | 庞统三问框架 + 目标漂移检测 |
```
_broadcast_claim():
for task in pending:
if retry_count >= 3:
→ escalated（升级庞统）
else:
→ 广播给 idle agents
```
### 回归验证
3 轮广播无人认领 → 任务标 `escalated` → 庞统接手（走 delegate 路径）。
### 5.2 Claim 并发保护（已实现）
`claim_task()` 是原子 CAS 操作：
```sql
UPDATE tasks SET status='claimed', assignee=? WHERE id=? AND status='pending'
```
多个 Agent 同时 claim 同一个任务，只有第一个成功（`rowcount=1`），其余返回 False。Agent 在 prompt 中被告知：「如果 claim 失败说明已被别人认领，NO_REPLY 退出」。
**不需要两步**（claim + working）。claim 成功即标 `claimed`，Agent 再标 `working` 时黑板校验 `status=claimed`，不存在竞态窗口。
| # | 验证点 |
|---|--------|
| R1 | 现有 E2E 测试（E1/E2/E4/E6）不受影响 |
| R2 | Mail 路径不受影响 |
| R3 | Counter/Router 逻辑不受影响 |
---
## 六、占位符定义
### 6.1 `{guardrails_summary}`
**来源**: `GuardrailEngine.rules` 中的 6 条红线摘要。
**注入方式**: spawner 在构建 prompt 时从 `GuardrailEngine.rules` 提取 `rule_name`，拼接为逗号分隔的字符串。
```python
def _get_guardrails_summary(self) -> str:
if not self.guardrails:
return "无特殊限制"
return "、".join(r["name"] for r in self.guardrails.rules[:6])
```
**当前 6 条红线**（PRD §10.1）：
1. 禁止操作生产环境数据库
2. 禁止执行未审核的外部代码
3. 禁止绕过风控规则
4. 禁止修改系统配置
5. 单次交易不得超过限额
6. 禁止未授权的资金操作
**没有 guardrails 时**: 填 "无特殊限制"。
### 6.2 `{retry_context}`
**来源**: `tasks.retry_count` 字段 + 上次执行的 outputs/comments。
**注入逻辑**（复用现有 `_build_retry_context`，增强）：
```python
def _build_retry_context(self, task) -> str:
if (task.retry_count or 0) == 0:
return ""
parts = ["⚠️ 这是重试（第 {} 次尝试），之前的执行失败了。".format(task.retry_count + 1)]
# 可选：注入上次失败原因（从 comments 中取 system 写的失败记录）
return "\n".join(parts)
```
**首次执行时**: 填空字符串，不渲染重试段。
---
## 七、改动范围
| 文件 | 改动点 | 改动量 |
|------|--------|--------|
| `spawner.py` | 重写 `SPAWN_PROMPT_TEMPLATE`；新增 `_inject_agent_identity()`；修改 `_build_spawn_message()` | ~60 行 |
| `ticker.py` | 重写 `_build_claim_prompt()`；重写 `_build_mention_prompt()`；小改 `_build_review_prompt()` | ~50 行 |
| `dispatcher.py` | `_build_delegate_prompt()` 加身份注入 | ~5 行 |
**总改动量**: ~115 行，涉及 3 个文件。
### 不改的
- `MAIL_INFORM_TEMPLATE` / `MAIL_REQUEST_TEMPLATE` — 已精简，不变
- `DISCUSSION_PROMPT_TEMPLATE` — 方向正确，不变
- `router.py` — 只读 capabilities，不改
- `prompt_templates/` 目录 — 暂不创建（模板代码量小，直接在 Python 中管理更方便调试）
---
## 八、收益
| 维度 | 改善 |
|------|------|
| **Token 节省** | SPAWN_PROMPT 从 ~100 行 → ~30 行，每次 spawn 节省 ~70 行 |
| **Agent 自主性** | 从"固定步骤"到"目标+约束"，Agent 自主决策执行路径 |
| **争抢问题** | 身份+专长注入，Agent 明确知道"我不该认领这个" |
| **风格统一** | 6 个模板统一为三段式结构 |
| **curl 消除** | 不再硬编码 curl，Agent 用自己的工具能力 |
---
## 九、风险
## 六、风险
| 风险 | 缓解 |
|------|------|
| **Agent 过度自主** | 约束段保留硬性底线（必须写产出、必须标 review） |
| **身份注入不够强** | 用"只认领符合你专长的任务"而非"建议" |
| **API 端点不熟悉** | 每个模板都列出完整 API 列表，Agent 不需要猜 |
| **Review 模板改坏** | Review 只做小改（加身份+去 curl），不动三问框架 |
| Agent 过度自由导致产出不稳定 | 约束段保留硬性底线（必须写产出、必须标 review、handoff ≥ 50 字符） |
| observation comment 质量低 | 观察者有 SOUL.md 的专业判断，prompt 引导"风险/建议/交叉视角" |
| API 端点缺失导致 Agent 不知道怎么操作 | executor/reviewer 模板的 API 由 spawner 注入，不依赖模板本身 |
| 改动范围过大 | 分两步：先改 claim prompt + executor.md（V1 验证），再改其余模板 |
---
## 十、实施计划
## 七、与 v1.x 的关系
### Phase 1：Task 执行模板 + 身份注入
v1.x 做了正确的基础工作（三段式结构、身份注入、去 curl）。v2.0 在此基础上做模式转变：
1. 新增 `_inject_agent_identity()` 到 spawner.py
2. 重写 `SPAWN_PROMPT_TEMPLATE`
3. 重写 `_build_claim_prompt()`
4. 部署 + 单任务 E2E 验证
| 维度 | v1.x | v2.0 |
|------|------|------|
| 结构 | ✅ 三段式（身份+任务+约束） | 保留 |
| 身份注入 | ✅ Agent ID + capabilities | 保留 |
| 去curl | ✅ 改为 API 端点列表 | 保留 |
| **模式** | ❌ SOP（固定步骤） | ✅ 任务式指挥（目标+约束） |
| **Agent 间信息** | ❌ 二元（claim/NO_REPLY） | ✅ 三级（claim/observe/NO_REPLY） |
| **审查风格** | ❌ Checklist | ✅ 挑战者思维+置信度 |
| **规划方式** | ❌ Phase 查表 | ✅ 理解→拆解→动态调整 |
### Phase 2：其他模板统一
1. 重写 `_build_mention_prompt()`
2. 小改 `_build_review_prompt()`
3. `_build_delegate_prompt()` 加身份注入
4. 全量 E2E 验证
v1.x 的所有基础设施（counter、router、spawner、bootstrap）完全复用，不动。