diff --git a/docs/design/03-prompt-evolution.md b/docs/design/03-prompt-evolution.md index 2495a35..4dfae09 100644 --- a/docs/design/03-prompt-evolution.md +++ b/docs/design/03-prompt-evolution.md @@ -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)完全复用,不动。 diff --git a/src/blackboard/db.py b/src/blackboard/db.py index 0fa29c2..f94c88c 100644 --- a/src/blackboard/db.py +++ b/src/blackboard/db.py @@ -289,7 +289,7 @@ _SCHEMA_STATEMENTS = [ id INTEGER PRIMARY KEY AUTOINCREMENT, task_id TEXT NOT NULL REFERENCES tasks(id), author TEXT NOT NULL, - comment_type TEXT NOT NULL DEFAULT 'general' CHECK (comment_type IN ('general','handoff','observation','rebuttal','rebuttal_response','debate_argument','debate_rebuttal','debate_judgment')), + comment_type TEXT NOT NULL DEFAULT 'general' CHECK (comment_type IN ('general','handoff','observation','review','rebuttal','rebuttal_response','debate_argument','debate_rebuttal','debate_judgment')), body TEXT NOT NULL, mentions TEXT, created_at TEXT NOT NULL DEFAULT (datetime('now'))