# 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 类型是否正常处理 |