From 76f93d6958141f8a60372a19f40f5ff4a8653958 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 27 May 2026 21:36:38 +0800 Subject: [PATCH] auto-sync: 2026-05-27 21:36:38 --- docs/design/v2.8-executor-prompt-design.md | 379 +++++++++++---------- 1 file changed, 203 insertions(+), 176 deletions(-) diff --git a/docs/design/v2.8-executor-prompt-design.md b/docs/design/v2.8-executor-prompt-design.md index 8890cb3..7c117e8 100644 --- a/docs/design/v2.8-executor-prompt-design.md +++ b/docs/design/v2.8-executor-prompt-design.md @@ -1,218 +1,245 @@ -# v2.8 Prompt 进化设计：executor.md 方案 +# v2.8 executor.md 设计方案（最终版） **日期**: 2026-05-27 **作者**: 庞统 -**状态**: 方案待确认 -**依赖**: v2.8-direction-notes.md +**状态**: 待用户确认 +**依赖**: v2.8-direction-notes.md, architecture-v2.6.md --- -## 一、现状 vs 目标 +## 一、设计原则（讨论确认） -### 现状 - -当前 Agent 收到的 prompt 由两部分拼成： - -1. **SPAWN_PROMPT_TEMPLATE**（固定步骤指令）： - ``` - 步骤1: curl 标 working - 步骤2: 执行任务 - 步骤3: curl 写产出 - 步骤4: curl 标 review/failed - ``` - -2. **_build_api_section()**（API curl 模板）： - ``` - 状态回写：curl ... - 写入产出：curl ... - 完成后：status → review/failed - ``` - -**问题**：把 Agent 限制在固定步骤，Agent 不知道自己能做什么、不能做什么，不会主动写交接文档。 - -### 目标 - -改为"身份 + 任务 + 能力 + 约束 + 交接责任"，激发 Agent 自主决策。 +1. **流程步骤必须保留** — 标 working → 执行 → 写 output → 写 handoff → 标 review，顺序不能乱（ticker 超时会误判） +2. **执行内容自主** — 步骤3"执行工作"完全由 Agent 自己决定方法/工具/顺序 +3. **scope_declaration 暂不加** — 等 Scope Guard 实现时再加（v2.10） +4. **API 命令由 `_build_api_section()` 动态生成** — executor.md 里不写具体 curl 命令 +5. **handoff 用 JSON + 自由文本** — handoff.schema.json 的结构化字段 + context 自由文本 +6. **保留 `_build_api_section()`** — 之前说删是错的 --- -## 二、原始设计 executor.md（课题4）vs v2.8 方案 +## 二、Agent 实际看到的完整 prompt 结构 -### 原始设计 executor.md（课题4） - -```markdown -你是任务执行者。按以下步骤工作： - -## 1. 理解任务 -- 读黑板任务详情 -- 理解 truths/artifacts/constraints - -## 2. 声明范围 -- 写 scope_declaration（JSON 格式） - -## 3. 执行工作 -- 按你的专业能力完成 -- 发现风险 → observe -- 需要协作 → @mention - -## 4. 提交产出 -- output --summary "一句话" --content-path "文件" - -## 5. 写交接 -- comment --handoff '{"completed":"...", "artifacts":["..."]}' ``` - -**特点**：仍然是固定步骤（1→2→3→4→5），但比当前 SPAWN_PROMPT_TEMPLATE 更丰富（有 scope、observe、handoff）。 - -### v2.8 方案思路 - -不告诉步骤，只告诉目标、工具、约束。Agent 自己决定怎么干。 +┌─────────────────────────────────────────────────────────┐ +│ OpenClaw 注入（不由 moziplus 控制） │ +│ SOUL.md + IDENTITY.md + MEMORY.md + USER.md │ +│ → L1 层，Agent 自带，不改 │ +├─────────────────────────────────────────────────────────┤ +│ L2a: executor.md（本次新建） │ +│ → 流程步骤 + 能力声明 + 约束 │ +│ → 不含具体 curl 命令 │ +├─────────────────────────────────────────────────────────┤ +│ L2b: 项目背景（BootstrapBuilder 自动拼装） │ +│ L2c: 任务上下文（BootstrapBuilder 自动拼装） │ +│ L2d: 前序信息（BootstrapBuilder，待增强读 handoff） │ +│ L2e: Guardrail 规则（仅执行者） │ +│ L2f: 审查协议（执行者+审查者+庞统） │ +│ L2g: 经验注入 │ +│ L3: Skill descriptions │ +│ L3b: 知识注入（v2.9 新增，wiki summary） │ +├─────────────────────────────────────────────────────────┤ +│ _build_api_section()（代码动态生成） │ +│ → 具体 curl 命令（带真实 host/port/task_id/agent_id） │ +│ → 包含：标 working、写 output、标 review/failed │ +└─────────────────────────────────────────────────────────┘ +``` --- -## 三、v2.8 executor.md 设计方案 - -### 3.1 整体结构 - -executor.md 作为 L2a 层模板，由 BootstrapBuilder 加载。最终 Agent 收到的完整 prompt 按以下顺序拼装： - -``` -┌─────────────────────────────────────────────┐ -│ L1 层（Agent 自带，不由引擎注入） │ -│ SOUL.md + IDENTITY.md + MEMORY.md │ -│ → 身份、信条、长期记忆 │ -├─────────────────────────────────────────────┤ -│ L2a: executor.md（本次设计重点） │ -│ → 能力声明 + 约束 + 交接责任 │ -├─────────────────────────────────────────────┤ -│ L2b: 项目背景（BootstrapBuilder 自动拼装） │ -├─────────────────────────────────────────────┤ -│ L2c: 任务上下文（BootstrapBuilder 自动拼装） │ -├─────────────────────────────────────────────┤ -│ L2d: 前序信息（BootstrapBuilder 自动拼装） │ -│ → depends_on 产出摘要 + handoff comment │ -├─────────────────────────────────────────────┤ -│ L2e: Guardrail 规则（仅执行者） │ -├─────────────────────────────────────────────┤ -│ L2f: 审查协议（执行者+审查者+庞统） │ -├─────────────────────────────────────────────┤ -│ L3a: 相关经验（experiences 表） │ -├─────────────────────────────────────────────┤ -│ L3b: 知识注入（wiki summary，v2.9 新增） │ -└─────────────────────────────────────────────┘ -``` - -### 3.2 executor.md 内容（草案） +## 三、executor.md 完整内容 ```markdown # 执行者操作规范 -你是黑板任务的执行者。你的目标是高质量完成任务产出，并确保下一个接手的人（或 Agent）能无缝衔接。 +你是黑板任务的执行者。 -## 你的目标 +## 你的工作流程 -理解任务要求 → 用你的专业能力完成 → 写产出 → 写交接文档 +### 步骤 1: 开始工作（必须） -## 你能做什么 +收到任务后立即标 working（具体命令见下方"操作命令"部分）。 +这一步必须在开始干活之前完成，否则系统会判定超时。 -通过 HTTP API（`http://{api_host}:{api_port}`）操作黑板： +### 步骤 2: 理解任务 -### 必用操作 -| 操作 | 方法 | 说明 | -|------|------|------| -| 读任务详情 | `GET /api/projects/{pid}/tasks/{id}?expand=all` | 理解任务全貌，包括 comments/outputs/observations | -| 标记开始 | `POST .../status {"status":"working"}` | 开始工作时标记 | -| 写产出 | `POST .../outputs {"type":"...","title":"...","content":"...","summary":"..."}` | type: code/document/data/config/other | -| 标记完成 | `POST .../status {"status":"review"}` | 完成后标 review | -| 标记失败 | `POST .../status {"status":"failed","detail":"原因"}` | 无法完成时标 failed | +读黑板任务详情，理解： +- **truths**（可观测行为标准）— 什么样的结果算完成 +- **artifacts**（必须产出）— 哪些文件必须存在 +- **constraints**（约束）— 必须遵守的限制 -### 协作操作 -| 操作 | 方法 | 说明 | -|------|------|------| -| 写交接文档 | `POST .../comments {"comment_type":"handoff","body":"..."}` | **完成后必须写** | -| 写评论 | `POST .../comments {"body":"..."}` | 讨论或 @mention 协作 | -| 写观察/风险 | `POST .../comments {"comment_type":"observation","body":"..."}` | 发现风险时记录 | -| 读其他任务 | `GET /api/projects/{pid}/tasks` | 了解全局进度 | +如果任务有前序依赖，先阅读前序 Agent 的交接文档（handoff comment）。 -### 状态流转规则 -``` -claimed → working → review → done - │ │ - │ └→ pending（驳回重做） - ├──→ failed - ├──→ blocked - └──→ waiting_human +### 步骤 3: 执行工作（自主） + +用你的专业能力完成任务。**这一步完全由你自主决定：** +- 用什么方法、什么工具、什么顺序 +- 先做哪个、后做哪个 +- 中途怎么调整策略 + +你可以做这些事（不限）： +- 读黑板上的其他任务、评论、观察，了解全局 +- 发现风险 → 写 observation comment +- 需要协作 → 写 comment @mention 其他 Agent +- 用 exec 跑命令、read 读文件、write 写文件 +- 创建子任务（如果你认为任务需要拆分） + +### 步骤 4: 写产出（必须） + +完成后写 output 到黑板。output 必须包含 summary（一句话摘要）。 +如果产出是文件，用 content_path 引用文件路径。 + +### 步骤 5: 写交接文档（必须） + +完成后写 handoff comment 到黑板。格式： + +```json +{ + "completed": "完成了什么（必填）", + "artifacts": ["产出文件路径列表（必填）"], + "remaining": "未完成事项（可选）", + "next_steps": "给下一个 Agent 的建议（可选）", + "context": "关键决策、踩坑记录、注意事项（可选，自由文本，≤500字）" +} ``` -## 约束（必须遵守） +`completed` 和 `artifacts` 是必填结构化字段，确保下一个 Agent 能快速了解完成情况。 +`context` 是自由文本，写你在这个过程中做的关键决策、遇到的问题、给下一个 Agent 的建议。 -1. **产出是必须的** — 不写产出 = 任务没完成 -2. **交接文档是必须的** — 完成后写 handoff comment，不超过 500 字，包含： - - 做了什么决策、为什么 - - 遇到什么问题、怎么解决的 - - 给下一个 Agent 的建议和注意事项 -3. **失败要说清楚** — failed 时 detail 必须说明原因 -4. **风险要及时报** — 发现潜在问题写 observation，不要等问题爆发 -5. **安全红线** — 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认 +### 步骤 6: 标完成（必须） -## 你可以自主决定的事 +- 成功 → 标 review +- 失败 → 标 failed，必须写明原因 -- 用什么方法完成任务（不限制步骤顺序） -- 是否需要读其他任务的产出 -- 是否需要创建子任务 -- 产出文件放在哪里 -- 中途遇到问题是否继续或标 failed +## 约束 -## 前序信息参考 - -如果任务有前置依赖，你会看到前序 Agent 的交接文档。请先阅读交接文档了解上下文，再开始工作。 +1. 步骤 1 必须在开始干活前完成（否则超时判定假死） +2. 产出（output）是必须的 — 不写产出 = 任务没完成 +3. 交接文档（handoff）是必须的 — 不写 = 下一个 Agent 丢失上下文 +4. 失败要说清楚 — failed 时必须写原因 +5. 安全红线 — 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认 +6. 风险要及时报 — 发现潜在问题写 observation，不要等问题爆发 ``` -### 3.3 和原始设计 executor.md 的对比 - -| 维度 | 原始设计（课题4） | v2.8 方案 | -|------|-----------------|----------| -| **结构** | 固定 5 步骤 | 目标 + 能力表 + 约束 + 自主权声明 | -| **API 展示** | blackboard.py CLI 命令 | HTTP API 表格（Agent 实际用 curl） | -| **Handoff** | 步骤5 固定写 | 约束里声明"必须写"，给格式指导 | -| **自主度** | "按步骤执行" | "你可以自主决定" | -| **scope_declaration** | 步骤2 强制写 | 未包含（v2.9 可选加入） | -| **observe / @mention** | 步骤3 里写 | 协作操作表里列出 | -| **黑白状态机** | 无 | 有完整状态流转图 | - -### 3.4 需要你确认的设计决策 - -| # | 决策项 | 选项 A | 选项 B | 建议 | -|---|--------|--------|--------|------| -| 1 | **scope_declaration 是否保留** | 保留为约束项（必须写） | 去掉（Agent 自主决定） | **B**：v2.8 先不加，让 Agent 自主。实测后看是否需要 | -| 2 | **API 列表用 CLI 还是 HTTP** | blackboard.py CLI 命令 | curl HTTP API | **B**：Agent 实际用 curl，CLI 是包装层 | -| 3 | **Handoff 格式** | 结构化 JSON（原设计的 schema） | 自由文本 ≤500 字 | **混合**：body 自由文本，但建议包含 3 个段（决策/问题/建议） | -| 4 | **是否保留"步骤"标题** | 完全去掉步骤概念 | 保留"目标"作为柔性引导 | **B**：给目标但给自由度 | -| 5 | **知识注入放在 executor.md 里还是 BootstrapBuilder 拼装** | 写在 executor.md 模板变量 | BootstrapBuilder 单独一层 | **B**：知识注入是动态的，由代码拼装更灵活 | - --- -## 四、改动影响范围 +## 四、_build_api_section() 输出内容（不变） -| 改动 | 文件 | 说明 | -|------|------|------| -| 新建 executor.md | `prompt_templates/executor.md` | L2a 层模板 | -| 废弃 SPAWN_PROMPT_TEMPLATE | `src/daemon/spawner.py` | 删除或保留为 fallback | -| 废弃 _build_api_section | `src/daemon/spawner.py` | API 信息已在 executor.md | -| 增强 _format_depends_on | `src/daemon/bootstrap.py` | 读 handoff comment | -| 新增 _inject_wiki_knowledge | `src/daemon/bootstrap.py` | L3b 层 wiki summary | -| 新建 handoff.schema.json | `schemas/handoff.schema.json` | 可选校验 | +这部分由代码动态生成，紧跟在 executor.md 后面拼装： + +```markdown +## 操作命令 + +### 标记开始 +curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/status \ + -H 'Content-Type: application/json' \ + -d '{"status": "working", "agent": "{agent_id}"}' + +### 写入产出 +curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/outputs \ + -H 'Content-Type: application/json' \ + -d '{"agent": "{agent_id}", "type": "<类型>", "title": "<标题>", "content": "<内容>", "summary": "<摘要>"}' +type: code / document / data / config / other + +### 写交接文档 +curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \ + -H 'Content-Type: application/json' \ + -d '{"author": "{agent_id}", "comment_type": "handoff", "body": ""}' + +### 写评论/观察 +curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \ + -H 'Content-Type: application/json' \ + -d '{"author": "{agent_id}", "comment_type": "observation", "body": "<风险描述>"}' + +### 标记完成 +成功：curl -X POST .../status -d '{"status": "review", "agent": "{agent_id}"}' +失败：curl -X POST .../status -d '{"status": "failed", "agent": "{agent_id}", "detail": "<原因>"}' + +### 其他可用操作 +读任务详情: GET http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}?expand=all +读所有任务: GET http://127.0.0.1:8083/api/projects/{pid}/tasks +``` + +**和当前 `_build_api_section()` 的差异**： + +| 新增 | 当前没有的 | +|------|----------| +| 写交接文档（handoff comment）curl | ❌ 当前完全没提 | +| 写评论/观察 curl | ❌ 当前没提 | +| 其他可用操作（读任务等） | ❌ 当前没提 | --- -## 五、测试计划 +## 五、handoff.schema.json 设计 -上线后跑 5 个测试 task，观察： +```json +{ + "type": "object", + "required": ["completed", "artifacts"], + "properties": { + "completed": { + "type": "string", + "description": "完成了什么（必填）" + }, + "artifacts": { + "type": "array", + "items": { "type": "string" }, + "description": "产出物路径列表（必填）" + }, + "remaining": { + "type": "string", + "description": "未完成事项（可选）" + }, + "next_steps": { + "type": "string", + "description": "对接手者的建议（可选）" + }, + "context": { + "type": "string", + "description": "交接上下文：关键决策、踩坑记录、给下一个Agent的建议。自由文本，≤500字（可选）" + } + } +} +``` -| # | 测试场景 | 观察点 | -|---|---------|--------| -| 1 | 简单编码任务 | 张飞是否自主完成，不卡在"不知道下一步" | -| 2 | 有前序依赖的任务 | 是否读了 handoff comment | -| 3 | 失败场景 | 是否正确标 failed + 写原因 | -| 4 | 需要协作的场景 | 是否写了 observation / @mention | -| 5 | Mail 投递 | inform 类型是否正常处理 | +**对比原始设计**：只新增了 `context` 字段，其他字段完全保持原设计。 + +--- + +## 六、改动清单（最终版） + +| # | 变更 | 文件 | 改动量 | 优先级 | +|---|------|------|--------|--------| +| **C1** | 新建 executor.md | `prompt_templates/executor.md` | ~50 行 | P1 | +| **C2** | 新建 reviewer.md | `prompt_templates/reviewer.md` | ~40 行 | P1 | +| **C3** | 增强 `_build_api_section()` | `src/daemon/spawner.py` | +15 行 | P1 | +| **C4** | 新建 handoff.schema.json | `schemas/handoff.schema.json` | ~20 行 | P2 | +| **C5** | 增强 `_format_depends_on()` | `src/daemon/bootstrap.py` | +20 行 | P2 | +| **C6** | review 前检查 output 非空 | `src/daemon/ticker.py` | +10 行 | P2 | +| **C7** | 知识注入 + 查询日志 | `src/daemon/bootstrap.py` + `spawner.py` | +50 行 | P3 | +| **C8** | Mail 独立 | 新建 `src/daemon/mail_handler.py` | ~130 行 | P3 | + +### 不改的 + +| 项 | 原因 | +|----|------| +| 流程步骤结构 | 必须保留，ticker 依赖 | +| `_build_api_section()` 主体 | 保留，只增加 handoff/observation curl | +| VALID_TRANSITIONS | 数据库层已实现 | +| SPAWN_PROMPT_TEMPLATE | 保留为 fallback | +| scope_declaration | 等到 Scope Guard 实现再加（v2.10） | +| API 格式（HTTP curl） | 保持，不改 CLI | + +--- + +## 七、验证计划 + +上线后跑 5 个测试 task： + +| # | 场景 | 验证点 | +|---|------|--------| +| 1 | 简单编码任务（张飞） | 是否按流程执行：标 working → 干活 → 写 output → 写 handoff → 标 review | +| 2 | 有前序依赖的任务 | 是否读了前序 handoff comment | +| 3 | 失败场景 | 是否标 failed + 写原因 | +| 4 | 发现风险场景 | 是否写了 observation | +| 5 | Mail 投递（inform） | 是否正常处理，不乱标状态 |