cfdaily
13 KiB
13 KiB
v2.8 executor.md 设计方案(最终版)
日期: 2026-05-27 作者: 庞统 状态: 待用户确认 依赖: v2.8-direction-notes.md, architecture-v2.6.md
一、设计原则（讨论确认）
- 流程步骤必须保留 — 标 working → 感知上下文 → 自主执行 → 写 output → 写 handoff → 标 review，顺序不能乱（ticker 超时会误判）
- 步骤 2 面向 v3.0“感知上下文” — Agent 不只是理解自己的任务，而是感知黑板全局、其他 Agent 的状态
- 步骤 3 面向 v3.0“自主协作” — 不只是执行任务，而是主动发起协作、发现风险、建议重新分配
- 执行内容自主 — 步骤3“自主执行”完全由 Agent 自己决定方法/工具/顺序
- scope_declaration 暂不加 — 等 Scope Guard 实现时再加（v2.10）
- API 命令由
_build_api_section()动态生成 — executor.md 里不写具体 curl 命令 - handoff 用 JSON + 自由文本 — handoff.schema.json 的结构化字段 + context 自由文本
- 保留
_build_api_section()— 之前说删是错的 - 面向 v3.0 目标，在 v2.7 实现上工作 — v3.0 的 Phase 1/2 是更大系统级改动，不在 v2.8 范围
二、Agent 实际看到的完整 prompt 结构
┌─────────────────────────────────────────────────────────┐
│ OpenClaw 注入(不由 moziplus 控制) │
│ SOUL.md + IDENTITY.md + MEMORY.md + USER.md │
│ → L1 层,Agent 自带,不改 │
├─────────────────────────────────────────────────────────┤
│ L2a: executor.md(本次新建) │
│ → 流程步骤 + 能力声明 + 约束 │
│ → 不含具体 curl 命令 │
├─────────────────────────────────────────────────────────┤
│ L2b: 项目背景(BootstrapBuilder 自动拼装) │
│ L2c: 任务上下文(BootstrapBuilder 自动拼装) │
│ L2d: 前序信息(BootstrapBuilder,待增强读 handoff) │
│ L2e: Guardrail 规则(仅执行者) │
│ L2f: 审查协议(执行者+审查者+庞统) │
│ L2g: 经验注入 │
│ L3: Skill descriptions │
│ L3b: 知识注入(v2.9 新增,wiki summary) │
├─────────────────────────────────────────────────────────┤
│ _build_api_section()(代码动态生成) │
│ → 具体 curl 命令(带真实 host/port/task_id/agent_id) │
│ → 包含:标 working、写 output、标 review/failed │
└─────────────────────────────────────────────────────────┘
注入机制说明
| 层 | 谁生成 | 怎么注入到 Agent | 代码位置 |
|---|---|---|---|
| L1（SOUL/IDENTITY/MEMORY） | OpenClaw Agent 配置 | OpenClaw Gateway 自动加载 Agent workspace 文件 | ~/.openclaw/agents/{agent_id}/workspace/ |
| L2a（executor.md） | moziplus 模板文件 | BootstrapBuilder _load_template("executor.md") |
bootstrap.py |
| L2b（项目背景） | BootstrapBuilder 代码 | build() → _format_project_context() |
bootstrap.py |
| L2c（任务上下文） | BootstrapBuilder 代码 | build() → _format_task_context() |
bootstrap.py |
| L2d（前序信息） | BootstrapBuilder 代码 | build() → _format_depends_on() |
bootstrap.py |
| L2e（Guardrail 规则） | Daemon 从配置加载 | build(guardrail_rules=...) |
spawner.py → bootstrap.py |
| L2f（审查协议） | Daemon 从配置加载 | build(review_protocols=...) |
spawner.py → bootstrap.py |
| L2g（经验注入） | experiences 表 | build(experiences=...) |
spawner.py → bootstrap.py |
| L3（Skill descriptions） | Skill 目录 | build(skill_descriptions=...) |
spawner.py → bootstrap.py |
| L3b（知识注入） | v2.9 新增，grep wiki index.md | build(wiki_knowledge=...) |
spawner.py → bootstrap.py |
| API 命令 | _build_api_section() 代码 |
拼在 bootstrap 后面 | spawner.py |
完整调用链：
ticker.py _dispatch_pending()
│
└── dispatcher.py dispatch(task)
│
├── router.py route(task) → 决定 agent_id
│
└── spawner.py build_spawn_message(task, agent_id)
│
├── bootstrap_builder.build_for_task(task, role="executor")
│ └── build(role, task_context, ...)
│ ├── L2a: _load_template("executor.md") ← 新建这个文件
│ ├── L2b~L2g: 各层自动拼装
│ └── L3: _format_skills()
│
├── _build_api_section(project_id, task_id, agent_id)
│ └── 具体 curl 命令（动态参数）
│
└── 返回完整 message 文本
│
spawner.spawn_full_agent(agent_id, message)
│
└── openclaw agent --agent {agent_id} --message "{message}"
│
└── OpenClaw Gateway 把 message 发到 Agent session
│
└── Agent 在 session 里看到完整 prompt
三、executor.md 完整内容
# 执行者操作规范
你是黑板任务的执行者。
## 你的工作流程
### 步骤 1: 开始工作(必须)
收到任务后立即标 working(具体命令见下方"操作命令"部分)。
这一步必须在开始干活之前完成,否则系统会判定超时。
### 步骤 2: 感知上下文
你不是一个孤立的执行者,你是一个协作群的成员。开始工作前:
- 读黑板任务详情(你被分配的具体任务)
- 读前序 Agent 的交接文档(handoff comment)
- 读任务的评论、观察、决策(了解全局发生了什么)
- 理解 **truths**(可观测行为标准)、**artifacts**(必须产出)、**constraints**(约束)
### 步骤 3: 自主执行(AI Native)
用你的专业能力完成任务。**这一步完全由你自主决定:**
- 用什么方法、什么工具、什么顺序
- 先做哪个、后做哪个
- 中途怎么调整策略
你可以做的(不限于此):
- 读黑板上的其他任务、评论、观察,了解全局
- 发现风险 → 写 observation comment
- 需要协作 → 写 comment @mention 其他 Agent
- 发现任务需要拆分 → 创建子任务
- 发现自己不是最合适的人 → 写 comment 建议重新分配
- 用 exec 跑命令、read 读文件、write 写文件
### 步骤 4: 写产出(必须)
完成后写 output 到黑板。output 必须包含 summary(一句话摘要)。
如果产出是文件,用 content_path 引用文件路径。
### 步骤 5: 写交接文档(必须)
完成后写 handoff comment 到黑板。格式:
```json
{
"completed": "完成了什么(必填)",
"artifacts": ["产出文件路径列表(必填)"],
"remaining": "未完成事项(可选)",
"next_steps": "给下一个 Agent 的建议(可选)",
"context": "关键决策、踩坑记录、注意事项(可选,自由文本,≤500字)"
}
completed 和 artifacts 是必填结构化字段,确保下一个 Agent 能快速了解完成情况。
context 是自由文本,写你在这个过程中做的关键决策、遇到的问题、给下一个 Agent 的建议。
步骤 6: 标完成(必须)
- 成功 → 标 review
- 失败 → 标 failed,必须写明原因
约束
- 步骤 1 必须在开始干活前完成(否则超时判定假死)
- 产出(output)是必须的 - 不写产出 = 任务没完成
- 交接文档(handoff)是必须的 - 不写 = 下一个 Agent 丢失上下文
- 失败要说清楚 - failed 时必须写原因
- 安全红线 - 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认
- 风险要及时报 - 发现潜在问题写 observation,不要等问题爆发
---
## 四、_build_api_section() 输出内容(不变)
这部分由代码动态生成,紧跟在 executor.md 后面拼装:
```markdown
## 操作命令
### 标记开始
curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/status \
-H 'Content-Type: application/json' \
-d '{"status": "working", "agent": "{agent_id}"}'
### 写入产出
curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/outputs \
-H 'Content-Type: application/json' \
-d '{"agent": "{agent_id}", "type": "<类型>", "title": "<标题>", "content": "<内容>", "summary": "<摘要>"}'
type: code / document / data / config / other
### 写交接文档
curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \
-H 'Content-Type: application/json' \
-d '{"author": "{agent_id}", "comment_type": "handoff", "body": "<handoff JSON>"}'
### 写评论/观察
curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \
-H 'Content-Type: application/json' \
-d '{"author": "{agent_id}", "comment_type": "observation", "body": "<风险描述>"}'
### 标记完成
成功:curl -X POST .../status -d '{"status": "review", "agent": "{agent_id}"}'
失败:curl -X POST .../status -d '{"status": "failed", "agent": "{agent_id}", "detail": "<原因>"}'
### 其他可用操作
读任务详情: GET http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}?expand=all
读所有任务: GET http://127.0.0.1:8083/api/projects/{pid}/tasks
和当前 _build_api_section() 的差异:
| 新增 | 当前没有的 |
|---|---|
| 写交接文档(handoff comment)curl | ❌ 当前完全没提 |
| 写评论/观察 curl | ❌ 当前没提 |
| 其他可用操作(读任务等) | ❌ 当前没提 |
五、handoff.schema.json 设计
{
"type": "object",
"required": ["completed", "artifacts"],
"properties": {
"completed": {
"type": "string",
"description": "完成了什么(必填)"
},
"artifacts": {
"type": "array",
"items": { "type": "string" },
"description": "产出物路径列表(必填)"
},
"remaining": {
"type": "string",
"description": "未完成事项(可选)"
},
"next_steps": {
"type": "string",
"description": "对接手者的建议(可选)"
},
"context": {
"type": "string",
"description": "交接上下文:关键决策、踩坑记录、给下一个Agent的建议。自由文本,≤500字(可选)"
}
}
}
对比原始设计:只新增了 context 字段,其他字段完全保持原设计。
六、改动清单(最终版)
| # | 变更 | 文件 | 改动量 | 优先级 |
|---|---|---|---|---|
| C1 | 新建 executor.md | prompt_templates/executor.md |
~50 行 | P1 |
| C2 | 新建 reviewer.md | prompt_templates/reviewer.md |
~40 行 | P1 |
| C3 | 增强 _build_api_section() |
src/daemon/spawner.py |
+15 行 | P1 |
| C4 | 新建 handoff.schema.json | schemas/handoff.schema.json |
~20 行 | P2 |
| C5 | 增强 _format_depends_on() |
src/daemon/bootstrap.py |
+20 行 | P2 |
| C6 | review 前检查 output 非空 | src/daemon/ticker.py |
+10 行 | P2 |
| C7 | 知识注入 + 查询日志 | src/daemon/bootstrap.py + spawner.py |
+50 行 | P3 |
| C8 | Mail 独立 | 新建 src/daemon/mail_handler.py |
~130 行 | P3 |
不改的
| 项 | 原因 |
|---|---|
| 流程步骤结构 | 必须保留,ticker 依赖 |
_build_api_section() 主体 |
保留,只增加 handoff/observation curl |
| VALID_TRANSITIONS | 数据库层已实现 |
| SPAWN_PROMPT_TEMPLATE | 保留为 fallback |
| scope_declaration | 等到 Scope Guard 实现再加(v2.10) |
| API 格式(HTTP curl) | 保持,不改 CLI |
七、验证计划
上线后跑 5 个测试 task:
| # | 场景 | 验证点 |
|---|---|---|
| 1 | 简单编码任务(张飞) | 是否按流程执行:标 working → 干活 → 写 output → 写 handoff → 标 review |
| 2 | 有前序依赖的任务 | 是否读了前序 handoff comment |
| 3 | 失败场景 | 是否标 failed + 写原因 |
| 4 | 发现风险场景 | 是否写了 observation |
| 5 | Mail 投递(inform) | 是否正常处理,不乱标状态 |