auto-sync: 2026-05-30 10:18:56

2026-05-30 10:18:56 +08:00
parent 180facdb19
commit ab6328adfc
1 changed files with 330 additions and 0 deletions
@@ -0,0 +1,330 @@
+# 03-prompt-evolution.md — Prompt 进化：从固定步骤到自主决策
+
+**日期**: 2026-05-30
+**作者**: 庞统
+**状态**: 待评审
+**前置**: `02-main-session-delegation.md`（#02 统一走 main session）
+**来源**: architecture-v3.0.md §10.4 Prompt 进化
+
+---
+
+## 一、问题：现有 Prompt 是固定步骤指令，不 AI Native
+
+### 现状
+
+系统中有 **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` | 列出团队成员让庞统选 | ✅ 可以保留 |
+
+### 核心问题
+
+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 模板还是老式
+
+### v3.0 设计方向回顾（architecture-v3.0.md §10.4）
+
+> 从"固定步骤指令"变成"身份 + 目标 + 能做什么 + 约束 + 交接责任"
+
+```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}
+```
+
+---
+
+## 二、方案：统一 Prompt 架构
+
+### 2.1 设计原则
+
+1. **信任 Agent** — Agent 有 SOUL.md、workspace、工具能力，不需要手把手教
+2. **身份先行** — 每个 prompt 开头注入 Agent 身份和能力，让 Agent 知道自己能干什么、不该干什么
+3. **目标清晰** — 告诉 Agent 要做什么，不告诉怎么做
+4. **约束为底线** — 红线是硬约束，其余让 Agent 自主
+5. **Mail 不动** — Mail 模板（inform/request）已经在 v1.0 验证过，保持不变
+
+### 2.2 Agent 能力画像注入
+
+从 Router 的 AgentProfile 中提取，注入到 prompt：
+
+```
+你是 {agent_id}，{role}。
+你的专长: {capabilities}
+```
+
+| Agent | capabilities 注入 |
+|-------|-------------------|
+| zhangfei-dev | 编码、实现、脚本 |
+| simayi-challenger | 审查、质量检查、辩论 |
+| guanyu-dev | 风控、合规、仓位检查 |
+| zhaoyun-data | 数据获取、清洗、验证 |
+| jiangwei-infra | 部署、基础设施、Docker、vnpy |
+| pangtong-fujunshi | 规划、协调、策略、升级处理 |
+
+### 2.3 统一 Prompt 结构
+
+所有 Task 路径的 prompt 统一为三段式：
+
+```
+┌─────────────────────────────┐
+│ 1. 身份段（固定）            │  Agent ID + 专长 + 角色
+├─────────────────────────────┤
+│ 2. 任务段（变化）            │  具体任务信息 + 上下文
+├─────────────────────────────┤
+│ 3. 约束段（固定）            │  红线 + 产出要求 + API 摘要
+└─────────────────────────────┘
+```
+
+Mail 路径的 prompt 不变（inform/request 模板已精简）。
+
+---
+
+## 三、新模板设计
+
+### 3.1 Task 执行模板（替代 SPAWN_PROMPT_TEMPLATE）
+
+```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}
+```
+
+**关键变化**：
+- 删掉固定 4 步骤（标 working → 干活 → 写产出 → 标 review），让 Agent 自主决策
+- 删掉 curl 硬编码，改为 API 端点列表（Agent 有工具能力）
+- 加身份注入（capabilities）
+- 加约束底线
+
+### 3.2 广播认领模板（替代 _build_claim_prompt）
+
+```markdown
+你是 {agent_id}，专长: {capabilities}。
+
+## 待认领任务
+{task_list}
+
+## 规则
+- 只认领符合你专长的任务。你的专长是 {capabilities}，不适合的任务不要认领
+- 不确定时不要认领，留给更合适的 Agent
+- 认领后必须写产出物再转 review
+
+## 你能做什么
+- 读任务详情: GET {api_base}/projects/{project_id}/tasks?status=pending
+- 认领: 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
+
+## 约束
+- 一个 tick 只认领一个任务
+- 禁止使用 sessions_send 直接发消息
+```
+
+**关键变化**：
+- 加身份+专长注入，明确告诉 Agent "你的专长是 X，不适合的不要认领"
+- 从"建议"变成"约束"
+- 简化操作指引
+
+### 3.3 @mention 模板（替代 _build_mention_prompt）
+
+```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
+
+## 约束
+- 只回应与你专长相关的内容
+- 禁止使用 sessions_send 直接发消息
+```
+
+### 3.4 Review 模板（保留，小幅优化）
+
+Review 模板已经合理（三问框架），只做两处优化：
+
+1. 加身份注入："你是 pangtong-fujunshi，任务协调员。"
+2. 删掉 curl 硬编码，改为 API 端点列表
+
+### 3.5 Delegate 模板（保留）
+
+`_build_delegate_prompt` 保留不变。它只给庞统用，且设计合理（列出团队成员让庞统选）。
+
+### 3.6 Discussion 模板（保留）
+
+`DISCUSSION_PROMPT_TEMPLATE` 方向正确（"你是自主的"），保留不变。
+
+### 3.7 Mail 模板（不变）
+
+Mail 路径的 inform/request 模板已在 v1.0 验证，保持不变。
+
+---
+
+## 四、能力注入机制
+
+### 4.1 数据来源
+
+从 Router 的 `AgentProfile.capabilities` 提取。Router 已在初始化时加载所有 Agent 画像：
+
+```python
+# router.py
+self.agent_profiles = {
+    "zhangfei-dev": AgentProfile(capabilities=["coding", "implementation", "scripting"], ...),
+    "simayi-challenger": AgentProfile(capabilities=["review", "quality_check", "debate"], ...),
+    ...
+}
+```
+
+### 4.2 中文映射
+
+Agent 需要中文的能力描述，不是英文标签：
+
+```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": "策略",
+}
+```
+
+### 4.3 注入位置
+
+在 `spawner.py` 中新增方法 `_inject_agent_identity(agent_id)` → 返回身份段字符串。所有 prompt 构建方法调用此方法获取身份段。
+
+---
+
+## 五、改动范围
+
+| 文件 | 改动点 | 改动量 |
+|------|--------|--------|
+| `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），不动三问框架 |
+
+---
+
+## 八、实施计划
+
+### Phase 1：Task 执行模板 + 身份注入
+
+1. 新增 `_inject_agent_identity()` 到 spawner.py
+2. 重写 `SPAWN_PROMPT_TEMPLATE`
+3. 重写 `_build_claim_prompt()`
+4. 部署 + 单任务 E2E 验证
+
+### Phase 2：其他模板统一
+
+1. 重写 `_build_mention_prompt()`
+2. 小改 `_build_review_prompt()`
+3. `_build_delegate_prompt()` 加身份注入
+4. 全量 E2E 验证