sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c9680cfa94de29517e822203e2a94e05f074f94
sanguo_moziplus_v2/docs/design/archive-2.0/v2.8-executor-prompt-design.md
T
cfdaily f613895360 auto-sync: 2026-05-28 08:45:47
2026-05-28 08:45:47 +08:00

22 KiB
Raw Blame History

v2.8 executor.md 设计方案(最终版)

日期: 2026-05-27 作者: 庞统 状态: 待用户确认 依赖: v2.8-direction-notes.md, architecture-v2.6.md

一、设计原则(讨论确认)

  1. 流程步骤必须保留 - 标 working → 感知上下文 → 自主执行 → 写 output → 写 handoff → 标 review,顺序不能乱(ticker 超时会误判)
  2. 步骤 2 面向 v3.0"感知上下文" - Agent 不只是理解自己的任务,而是感知黑板全局、其他 Agent 的状态
  3. 步骤 3 面向 v3.0"自主协作" - 不只是执行任务,而是主动发起协作、发现风险、建议重新分配
  4. 执行内容自主 - 步骤3"自主执行"完全由 Agent 自己决定方法/工具/顺序
  5. scope_declaration 暂不加 - 等 Scope Guard 实现时再加(v2.10)
  6. API 命令由 _build_api_section() 动态生成 - executor.md 里不写具体 curl 命令
  7. handoff 用 JSON + 自由文本 - handoff.schema.json 的结构化字段 + context 自由文本
  8. 保留 _build_api_section() - 之前说删是错的
  9. 面向 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. 步骤 1 必须在开始干活前完成(否则超时判定假死)
  2. 产出(output)是必须的 - 不写产出 = 任务没完成
  3. 交接文档(handoff)是必须的 - 不写 = 下一个 Agent 丢失上下文
  4. 失败要说清楚 - failed 时必须写原因
  5. 安全红线 - 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认
  6. 风险要及时报 - 发现潜在问题写 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） 是否正常处理，不乱标状态

八、完整 Sample：张飞收到"实现双均线策略"任务

以下是张飞（zhangfei-dev）被 spawn 后在 session 中实际看到的完整 prompt。

注意：L1 层（SOUL.md / IDENTITY.md / MEMORY.md / USER.md）由 OpenClaw Gateway 自动加载，不在 message 中。这里展示的是 message 内容，即 L2a ~ API section。

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# L2a: 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. 步骤 1 必须在开始干活前完成（否则超时判定假死）
  2. 产出（output）是必须的 — 不写产出 = 任务没完成
  3. 交接文档（handoff）是必须的 — 不写 = 下一个 Agent 丢失上下文
  4. 失败要说清楚 — failed 时必须写原因
  5. 安全红线 — 涉及数据删除、实盘交易、生产环境变更 → 标 waiting_human 等人确认
  6. 风险要及时报 — 发现潜在问题写 observation，不要等问题爆发

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

L2b: 项目背景（BootstrapBuilder 自动拼装）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

项目背景

项目: sanguo_quant_live 描述: 量化实战项目 团队: pangtong-fujunshi, simayi-challenger, jiangwei-infra, guanyu-dev, zhangfei-dev, zhaoyun-data

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

L2c: 任务上下文（BootstrapBuilder 自动拼装）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

任务上下文

任务ID: sanguo-quant-live-20260527-0001 标题: 实现双均线策略 描述: 基于SMA(5,20)的分钟线动量策略，使用vnpy框架实现，包含止损逻辑 类型: coding 必须完成: {"truths": ["策略代码通过单元测试", "回测结果包含收益曲线"], "artifacts": ["sanguo-quant-live-20260527-0001/strategy.py", "sanguo-quant-live-20260527-0001/backtest_report.pdf"], "constraints": ["使用vnpy框架", "不超过500行"]} 风险级别: standard

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

L2d: 前序信息（BootstrapBuilder，已增强读 handoff）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

前序产出

  • [sanguo-quant-live-20260527-0000] 分钟线数据已下载，数据路径: /Volumes/stock/min_data/IF888.csv

前序交接文档（handoff）

[赵云 zhaoyun-data] completed: IF888 2024-01~2025-05 分钟线数据已下载，含成交量 artifacts: ["/Volumes/stock/min_data/IF888.csv"] context: 2024-08有3天数据缺失，已用前值填充。分钟线收盘价在9:30-9:35有异常跳变， 建议策略编码时过滤掉开盘前5分钟的K线

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

L2e: Guardrail 规则（仅执行者）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Guardrail 规则

  • 涉及实盘交易操作 → 必须标 waiting_human 等待确认
  • 涉及数据删除 → 必须标 waiting_human 等待确认
  • 产出文件不超过 500 行代码
  • 必须使用 vnpy 框架

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

L2g: 经验注入

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

相关经验

  • [coding] vnpy CtaTemplate 的 on_bar/on_tick 不要做重计算，用 array_manager 缓存
  • [coding] 双均线策略注意均线计算起始点，前N根K线信号无效

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

L3b: 知识注入（wiki summary，v2.9 新增）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

相关知识（来自 LLM Wiki）

  • projects/vnpy/vnpy — Python开源量化交易框架，MIT许可，v4.0新增vnpy.alpha多因子模块 ( #vnpy #quant )
  • projects/vectorbt/vectorbt — 向量化回测引擎，pandas/NumPy+Numba加速，极速参数优化 ( #quant #backtesting #vectorized #numba )

（如需详细信息，用 exec rg 读取完整页面）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

_build_api_section()（代码动态生成）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

操作命令

标记开始

curl -X POST http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001/status
-H 'Content-Type: application/json'
-d '{"status": "working", "agent": "zhangfei-dev"}'

写入产出

curl -X POST http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001/outputs
-H 'Content-Type: application/json'
-d '{"agent": "zhangfei-dev", "type": "<类型>", "title": "<标题>", "content": "<内容>", "summary": "<摘要>"}' type: code / document / data / config / other

写交接文档

curl -X POST http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001/comments
-H 'Content-Type: application/json'
-d '{"author": "zhangfei-dev", "comment_type": "handoff", "body": ""}'

写评论/观察

curl -X POST http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001/comments
-H 'Content-Type: application/json'
-d '{"author": "zhangfei-dev", "comment_type": "observation", "body": "<风险描述>"}'

标记完成

成功：curl -X POST http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001/status
-H 'Content-Type: application/json'
-d '{"status": "review", "agent": "zhangfei-dev"}' 失败：curl -X POST http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001/status
-H 'Content-Type: application/json'
-d '{"status": "failed", "agent": "zhangfei-dev", "detail": "<原因>"}'

其他可用操作

读任务详情: GET http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks/sanguo-quant-live-20260527-0001?expand=all 读所有任务: GET http://127.0.0.1:8083/api/projects/sanguo-quant-live/tasks


**张飞实际体验**：他在 session 中看到以上全部内容作为一个完整的用户消息。上面用 `━━━` 分隔的每一块，对应代码中 BootstrapBuilder 的一个 `_format_*` 方法或 `_build_api_section()` 的输出。L1 层（SOUL.md 等）由 OpenClaw Gateway 自动注入，不在 message 中但 Agent 同样能看到。
Reference in New Issue View Git Blame Copy Permalink