From e891f721078650acb121daa86565031dbcf70a3c Mon Sep 17 00:00:00 2001 From: cfdaily Date: Wed, 27 May 2026 23:00:34 +0800 Subject: [PATCH] auto-sync: 2026-05-27 23:00:34 --- docs/design/v2.8-executor-prompt-design.md | 252 +++++++++++++++++++-- 1 file changed, 227 insertions(+), 25 deletions(-) diff --git a/docs/design/v2.8-executor-prompt-design.md b/docs/design/v2.8-executor-prompt-design.md index e469cbe..30ae66a 100644 --- a/docs/design/v2.8-executor-prompt-design.md +++ b/docs/design/v2.8-executor-prompt-design.md @@ -7,17 +7,17 @@ --- -## 一、设计原则（讨论确认） +## 一、设计原则(讨论确认) -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 范围 +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 范围 --- @@ -52,19 +52,19 @@ | 层 | 谁生成 | 怎么注入到 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` | +| 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() @@ -82,7 +82,7 @@ ticker.py _dispatch_pending() │ └── L3: _format_skills() │ ├── _build_api_section(project_id, task_id, agent_id) - │ └── 具体 curl 命令（动态参数） + │ └── 具体 curl 命令(动态参数) │ └── 返回完整 message 文本 │ @@ -284,12 +284,214 @@ curl -X POST http://127.0.0.1:8083/api/projects/{pid}/tasks/{tid}/comments \ ## 七、验证计划 -上线后跑 5 个测试 task: +上线后跑 5 个测试 task： | # | 场景 | 验证点 | |---|------|--------| -| 1 | 简单编码任务(张飞) | 是否按流程执行:标 working → 干活 → 写 output → 写 handoff → 标 review | +| 1 | 简单编码任务（张飞） | 是否按流程执行：标 working → 干活 → 写 output → 写 handoff → 标 review | | 2 | 有前序依赖的任务 | 是否读了前序 handoff comment | | 3 | 失败场景 | 是否标 failed + 写原因 | | 4 | 发现风险场景 | 是否写了 observation | -| 5 | Mail 投递(inform) | 是否正常处理,不乱标状态 | +| 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。 + +```markdown +# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +# 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|VeighNa (vnpy)]] — Python开源量化交易框架，MIT许可，v4.0新增vnpy.alpha多因子模块 ( #vnpy #quant ) +- [[projects/vectorbt/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 同样能看到。