cfdaily
219 lines
9.3 KiB
Markdown
219 lines
9.3 KiB
Markdown
# 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 类型是否正常处理 |
|