From 4662de4457e686deffd02809082b0ea93696d8eb Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 27 May 2026 22:40:23 +0800 Subject: [PATCH] auto-sync: 2026-05-27 22:40:23 --- docs/design/v2.8-executor-prompt-design.md | 153 +++++++++++---------- 1 file changed, 78 insertions(+), 75 deletions(-) diff --git a/docs/design/v2.8-executor-prompt-design.md b/docs/design/v2.8-executor-prompt-design.md index f1645a0..a906766 100644 --- a/docs/design/v2.8-executor-prompt-design.md +++ b/docs/design/v2.8-executor-prompt-design.md @@ -1,20 +1,23 @@ -# v2.8 executor.md 设计方案（最终版） +# v2.8 executor.md 设计方案(最终版) -**日期**: 2026-05-27 -**作者**: 庞统 -**状态**: 待用户确认 +**日期**: 2026-05-27 +**作者**: 庞统 +**状态**: 待用户确认 **依赖**: v2.8-direction-notes.md, architecture-v2.6.md --- ## 一、设计原则（讨论确认） -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()`** — 之前说删是错的 +1. **流程步骤必须保留** — 标 working → 感知上下文 → 自主执行 → 写 output → 写 handoff → 标 review，顺序不能乱（ticker 超时会误判） +2. **步骤 2 面向 v3.0“感知上下文”** — Agent 不只是理解自己的任务，而是感知黑板全局、其他 Agent 的状态 +3. **步骤 3 面向 v3.0“自主协作”** — 不只是执行任务，而是主动发起协作、发现风险、建议重新分配 +4. **执行内容自主** — 步骤3“自主执行”完全由 Agent 自己决定方法/工具/顺序 +5. **scope_declaration 暂不加** — 等 Scope Guard 实现时再加（v2.10） +6. **API 命令由 `_build_api_section()` 动态生成** — executor.md 里不写具体 curl 命令 +7. **handoff 用 JSON + 自由文本** — handoff.schema.json 的结构化字段 + context 自由文本 +8. **保留 `_build_api_section()`** — 之前说删是错的 +9. **面向 v3.0 目标，在 v2.7 实现上工作** — v3.0 的 Phase 1/2 是更大系统级改动，不在 v2.8 范围 --- @@ -22,26 +25,26 @@ ``` ┌─────────────────────────────────────────────────────────┐ -│ OpenClaw 注入（不由 moziplus 控制） │ +│ OpenClaw 注入(不由 moziplus 控制) │ │ SOUL.md + IDENTITY.md + MEMORY.md + USER.md │ -│ → L1 层，Agent 自带，不改 │ +│ → L1 层,Agent 自带,不改 │ ├─────────────────────────────────────────────────────────┤ -│ L2a: executor.md（本次新建） │ +│ L2a: executor.md(本次新建) │ │ → 流程步骤 + 能力声明 + 约束 │ │ → 不含具体 curl 命令 │ ├─────────────────────────────────────────────────────────┤ -│ L2b: 项目背景（BootstrapBuilder 自动拼装） │ -│ L2c: 任务上下文（BootstrapBuilder 自动拼装） │ -│ L2d: 前序信息（BootstrapBuilder，待增强读 handoff） │ -│ L2e: Guardrail 规则（仅执行者） │ -│ L2f: 审查协议（执行者+审查者+庞统） │ +│ L2b: 项目背景(BootstrapBuilder 自动拼装) │ +│ L2c: 任务上下文(BootstrapBuilder 自动拼装) │ +│ L2d: 前序信息(BootstrapBuilder,待增强读 handoff) │ +│ L2e: Guardrail 规则(仅执行者) │ +│ L2f: 审查协议(执行者+审查者+庞统) │ │ L2g: 经验注入 │ │ L3: Skill descriptions │ -│ L3b: 知识注入（v2.9 新增，wiki summary） │ +│ L3b: 知识注入(v2.9 新增,wiki summary) │ ├─────────────────────────────────────────────────────────┤ -│ _build_api_section()（代码动态生成） │ -│ → 具体 curl 命令（带真实 host/port/task_id/agent_id） │ -│ → 包含：标 working、写 output、标 review/failed │ +│ _build_api_section()(代码动态生成) │ +│ → 具体 curl 命令(带真实 host/port/task_id/agent_id) │ +│ → 包含:标 working、写 output、标 review/failed │ └─────────────────────────────────────────────────────────┘ ``` @@ -56,76 +59,76 @@ ## 你的工作流程 -### 步骤 1: 开始工作（必须） +### 步骤 1: 开始工作(必须) -收到任务后立即标 working（具体命令见下方"操作命令"部分）。 -这一步必须在开始干活之前完成，否则系统会判定超时。 +收到任务后立即标 working(具体命令见下方"操作命令"部分)。 +这一步必须在开始干活之前完成,否则系统会判定超时。 ### 步骤 2: 感知上下文 -你不是一个孤立的执行者，你是一个协作群的成员。开始工作前： -- 读黑板任务详情（你被分配的具体任务） -- 读前序 Agent 的交接文档（handoff comment） -- 读任务的评论、观察、决策（了解全局发生了什么） -- 理解 **truths**（可观测行为标准）、**artifacts**（必须产出）、**constraints**（约束） +你不是一个孤立的执行者,你是一个协作群的成员。开始工作前: +- 读黑板任务详情(你被分配的具体任务) +- 读前序 Agent 的交接文档(handoff comment) +- 读任务的评论、观察、决策(了解全局发生了什么) +- 理解 **truths**(可观测行为标准)、**artifacts**(必须产出)、**constraints**(约束) -### 步骤 3: 自主执行（AI Native） +### 步骤 3: 自主执行(AI Native) -用你的专业能力完成任务。**这一步完全由你自主决定：** +用你的专业能力完成任务。**这一步完全由你自主决定:** - 用什么方法、什么工具、什么顺序 - 先做哪个、后做哪个 - 中途怎么调整策略 -你可以做的（不限于此）： -- 读黑板上的其他任务、评论、观察，了解全局 +你可以做的(不限于此): +- 读黑板上的其他任务、评论、观察,了解全局 - 发现风险 → 写 observation comment - 需要协作 → 写 comment @mention 其他 Agent - 发现任务需要拆分 → 创建子任务 - 发现自己不是最合适的人 → 写 comment 建议重新分配 - 用 exec 跑命令、read 读文件、write 写文件 -### 步骤 4: 写产出（必须） +### 步骤 4: 写产出(必须) -完成后写 output 到黑板。output 必须包含 summary（一句话摘要）。 -如果产出是文件，用 content_path 引用文件路径。 +完成后写 output 到黑板。output 必须包含 summary(一句话摘要)。 +如果产出是文件,用 content_path 引用文件路径。 -### 步骤 5: 写交接文档（必须） +### 步骤 5: 写交接文档(必须) -完成后写 handoff comment 到黑板。格式： +完成后写 handoff comment 到黑板。格式: ```json { - "completed": "完成了什么（必填）", - "artifacts": ["产出文件路径列表（必填）"], - "remaining": "未完成事项（可选）", - "next_steps": "给下一个 Agent 的建议（可选）", - "context": "关键决策、踩坑记录、注意事项（可选，自由文本，≤500字）" + "completed": "完成了什么(必填)", + "artifacts": ["产出文件路径列表(必填)"], + "remaining": "未完成事项(可选)", + "next_steps": "给下一个 Agent 的建议(可选)", + "context": "关键决策、踩坑记录、注意事项(可选,自由文本,≤500字)" } ``` -`completed` 和 `artifacts` 是必填结构化字段，确保下一个 Agent 能快速了解完成情况。 -`context` 是自由文本，写你在这个过程中做的关键决策、遇到的问题、给下一个 Agent 的建议。 +`completed` 和 `artifacts` 是必填结构化字段,确保下一个 Agent 能快速了解完成情况。 +`context` 是自由文本,写你在这个过程中做的关键决策、遇到的问题、给下一个 Agent 的建议。 -### 步骤 6: 标完成（必须） +### 步骤 6: 标完成(必须) - 成功 → 标 review -- 失败 → 标 failed，必须写明原因 +- 失败 → 标 failed,必须写明原因 ## 约束 -1. 步骤 1 必须在开始干活前完成（否则超时判定假死） -2. 产出（output）是必须的 — 不写产出 = 任务没完成 -3. 交接文档（handoff）是必须的 — 不写 = 下一个 Agent 丢失上下文 -4. 失败要说清楚 — failed 时必须写原因 -5. 安全红线 — 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认 -6. 风险要及时报 — 发现潜在问题写 observation，不要等问题爆发 +1. 步骤 1 必须在开始干活前完成(否则超时判定假死) +2. 产出(output)是必须的 - 不写产出 = 任务没完成 +3. 交接文档(handoff)是必须的 - 不写 = 下一个 Agent 丢失上下文 +4. 失败要说清楚 - failed 时必须写原因 +5. 安全红线 - 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认 +6. 风险要及时报 - 发现潜在问题写 observation,不要等问题爆发 ``` --- -## 四、_build_api_section() 输出内容（不变） +## 四、_build_api_section() 输出内容(不变) -这部分由代码动态生成，紧跟在 executor.md 后面拼装： +这部分由代码动态生成,紧跟在 executor.md 后面拼装: ```markdown ## 操作命令 @@ -152,21 +155,21 @@ curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \ -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": "<原因>"}' +成功: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()` 的差异**： +**和当前 `_build_api_section()` 的差异**: | 新增 | 当前没有的 | |------|----------| -| 写交接文档（handoff comment）curl | ❌ 当前完全没提 | +| 写交接文档(handoff comment)curl | ❌ 当前完全没提 | | 写评论/观察 curl | ❌ 当前没提 | -| 其他可用操作（读任务等） | ❌ 当前没提 | +| 其他可用操作(读任务等) | ❌ 当前没提 | --- @@ -179,34 +182,34 @@ curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \ "properties": { "completed": { "type": "string", - "description": "完成了什么（必填）" + "description": "完成了什么(必填)" }, "artifacts": { "type": "array", "items": { "type": "string" }, - "description": "产出物路径列表（必填）" + "description": "产出物路径列表(必填)" }, "remaining": { "type": "string", - "description": "未完成事项（可选）" + "description": "未完成事项(可选)" }, "next_steps": { "type": "string", - "description": "对接手者的建议（可选）" + "description": "对接手者的建议(可选)" }, "context": { "type": "string", - "description": "交接上下文：关键决策、踩坑记录、给下一个Agent的建议。自由文本，≤500字（可选）" + "description": "交接上下文:关键决策、踩坑记录、给下一个Agent的建议。自由文本,≤500字(可选)" } } } ``` -**对比原始设计**：只新增了 `context` 字段，其他字段完全保持原设计。 +**对比原始设计**:只新增了 `context` 字段,其他字段完全保持原设计。 --- -## 六、改动清单（最终版） +## 六、改动清单(最终版) | # | 变更 | 文件 | 改动量 | 优先级 | |---|------|------|--------|--------| @@ -223,23 +226,23 @@ curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \ | 项 | 原因 | |----|------| -| 流程步骤结构 | 必须保留，ticker 依赖 | -| `_build_api_section()` 主体 | 保留，只增加 handoff/observation curl | +| 流程步骤结构 | 必须保留,ticker 依赖 | +| `_build_api_section()` 主体 | 保留,只增加 handoff/observation curl | | VALID_TRANSITIONS | 数据库层已实现 | | SPAWN_PROMPT_TEMPLATE | 保留为 fallback | -| scope_declaration | 等到 Scope Guard 实现再加（v2.10） | -| API 格式（HTTP curl） | 保持，不改 CLI | +| scope_declaration | 等到 Scope Guard 实现再加(v2.10) | +| API 格式(HTTP curl) | 保持,不改 CLI | --- ## 七、验证计划 -上线后跑 5 个测试 task： +上线后跑 5 个测试 task: | # | 场景 | 验证点 | |---|------|--------| -| 1 | 简单编码任务（张飞） | 是否按流程执行：标 working → 干活 → 写 output → 写 handoff → 标 review | +| 1 | 简单编码任务(张飞) | 是否按流程执行:标 working → 干活 → 写 output → 写 handoff → 标 review | | 2 | 有前序依赖的任务 | 是否读了前序 handoff comment | | 3 | 失败场景 | 是否标 failed + 写原因 | | 4 | 发现风险场景 | 是否写了 observation | -| 5 | Mail 投递（inform） | 是否正常处理，不乱标状态 | +| 5 | Mail 投递(inform) | 是否正常处理,不乱标状态 |