From a4e306b84734e592b73b01c815443548bb38a41a Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 27 May 2026 19:32:58 +0800 Subject: [PATCH] auto-sync: 2026-05-27 19:32:58 --- docs/design/v2.8-executor-prompt-design.md | 218 +++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/design/v2.8-executor-prompt-design.md diff --git a/docs/design/v2.8-executor-prompt-design.md b/docs/design/v2.8-executor-prompt-design.md new file mode 100644 index 0000000..8890cb3 --- /dev/null +++ b/docs/design/v2.8-executor-prompt-design.md @@ -0,0 +1,218 @@ +# v2.8 Prompt 进化设计：executor.md 方案 + +**日期**: 2026-05-27 +**作者**: 庞统 +**状态**: 方案待确认 +**依赖**: v2.8-direction-notes.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 自主决策。 + +--- + +## 二、原始设计 executor.md（课题4）vs v2.8 方案 + +### 原始设计 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 自己决定怎么干。 + +--- + +## 三、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 内容（草案） + +```markdown +# 执行者操作规范 + +你是黑板任务的执行者。你的目标是高质量完成任务产出，并确保下一个接手的人（或 Agent）能无缝衔接。 + +## 你的目标 + +理解任务要求 → 用你的专业能力完成 → 写产出 → 写交接文档 + +## 你能做什么 + +通过 HTTP API（`http://{api_host}:{api_port}`）操作黑板： + +### 必用操作 +| 操作 | 方法 | 说明 | +|------|------|------| +| 读任务详情 | `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 | + +### 协作操作 +| 操作 | 方法 | 说明 | +|------|------|------| +| 写交接文档 | `POST .../comments {"comment_type":"handoff","body":"..."}` | **完成后必须写** | +| 写评论 | `POST .../comments {"body":"..."}` | 讨论或 @mention 协作 | +| 写观察/风险 | `POST .../comments {"comment_type":"observation","body":"..."}` | 发现风险时记录 | +| 读其他任务 | `GET /api/projects/{pid}/tasks` | 了解全局进度 | + +### 状态流转规则 +``` +claimed → working → review → done + │ │ + │ └→ pending（驳回重做） + ├──→ failed + ├──→ blocked + └──→ waiting_human +``` + +## 约束（必须遵守） + +1. **产出是必须的** — 不写产出 = 任务没完成 +2. **交接文档是必须的** — 完成后写 handoff comment，不超过 500 字，包含： + - 做了什么决策、为什么 + - 遇到什么问题、怎么解决的 + - 给下一个 Agent 的建议和注意事项 +3. **失败要说清楚** — failed 时 detail 必须说明原因 +4. **风险要及时报** — 发现潜在问题写 observation，不要等问题爆发 +5. **安全红线** — 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认 + +## 你可以自主决定的事 + +- 用什么方法完成任务（不限制步骤顺序） +- 是否需要读其他任务的产出 +- 是否需要创建子任务 +- 产出文件放在哪里 +- 中途遇到问题是否继续或标 failed + +## 前序信息参考 + +如果任务有前置依赖，你会看到前序 Agent 的交接文档。请先阅读交接文档了解上下文，再开始工作。 +``` + +### 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**：知识注入是动态的，由代码拼装更灵活 | + +--- + +## 四、改动影响范围 + +| 改动 | 文件 | 说明 | +|------|------|------| +| 新建 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` | 可选校验 | + +--- + +## 五、测试计划 + +上线后跑 5 个测试 task，观察： + +| # | 测试场景 | 观察点 | +|---|---------|--------| +| 1 | 简单编码任务 | 张飞是否自主完成，不卡在"不知道下一步" | +| 2 | 有前序依赖的任务 | 是否读了 handoff comment | +| 3 | 失败场景 | 是否正确标 failed + 写原因 | +| 4 | 需要协作的场景 | 是否写了 observation / @mention | +| 5 | Mail 投递 | inform 类型是否正常处理 |