auto-sync: 2026-05-27 19:32:58

2026-05-27 19:32:58 +08:00
parent 43cf6df53e
commit a4e306b847
1 changed files with 218 additions and 0 deletions
@@ -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 类型是否正常处理 |