sanguo/sanguo_moziplus_v2

Fork 0

Files

T

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

2026-05-27 19:32:58 +08:00

9.3 KiB

Raw Blame History

v2.8 Prompt 进化设计：executor.md 方案

日期: 2026-05-27
作者: 庞统
状态: 方案待确认
依赖: v2.8-direction-notes.md

一、现状 vs 目标

现状

当前 Agent 收到的 prompt 由两部分拼成：

SPAWN_PROMPT_TEMPLATE（固定步骤指令）：

步骤1: curl 标 working
步骤2: 执行任务
步骤3: curl 写产出
步骤4: curl 标 review/failed

_build_api_section()（API curl 模板）：

状态回写：curl ...
写入产出：curl ...
完成后：status → review/failed

问题：把 Agent 限制在固定步骤，Agent 不知道自己能做什么、不能做什么，不会主动写交接文档。

目标

改为"身份 + 任务 + 能力 + 约束 + 交接责任"，激发 Agent 自主决策。

二、原始设计 executor.md（课题4）vs v2.8 方案

原始设计 executor.md（课题4）

你是任务执行者。按以下步骤工作：

## 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 内容（草案）

# 执行者操作规范

你是黑板任务的执行者。你的目标是高质量完成任务产出，并确保下一个接手的人（或 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 类型是否正常处理

9.3 KiB Raw Blame History Unescape Escape