Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the old one-liner form, and migrate lib/ext/examples/tests/docs accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
15 KiB
智能体多步(## 多步 / ## plan)
| 状态 | Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档 |
| 日期 | 2026-08-11 |
| 父文档 | ext-agent.md |
| 相关 | ext-agent-parent.md(父 Plan-and-Move 行动面) · stdlib-writeback.md · stdlib-subtask.md · module-namespace.md · ai-skill.md · objects.md · 调研:主流框架与 Marqdo |
1. 动机
单步(## 单步 / ## step)适合原子任务。复杂目标需要:
- 把分解与执行过程落成一份可运行的
.mq.md(工作簿),而不是藏在进程内的任务图。 - 用子任务真正跑这份工作簿,与主推理隔离。
- 父智能体作为「智能体开发大师」:结构化读取执行结果与写回,再二次规划;用精确补丁改工作簿代码,并把确定步骤固化为普通 Marqdo
##。 - 允许工作簿演化——代码与
<!-- marqdo-out … -->均可更新,但禁止以整文件 LLM 重写作为修订主路径。 - 子智能体只做不确定的
单步;能写成代码的就不要再问模型。
本文锁定 ## 多步 / ## plan 的语义。总览与分层见 ext-agent.md;实现以 D2 为准。
2. 一句话
多步 = 父智能体(开发大师)生成并演进一份子 Marqdo 程序:经 lib/subtask 运行它,结构化观察写回与源码,再二次规划并精确打补丁;子 # 智能体 只跑 单步,确定步骤固化为代码。
3. 角色与产物
| 角色 | 职责 |
|---|---|
| 父智能体 | 持有目标;创建 / 改写工作簿;spawn path= 运行工作簿;读执行结果与写回块;决定改代码还是改提示;汇总并写回父文档 |
工作簿 .mq.md |
任务实现的详细步骤文档兼程序:导入、工具、一个或多个子智能体、可固化的普通函数与 # main 编排 |
| 子智能体 | 工作簿内的 # 智能体 / # agent;走 单步(默认);工具表白名单可收窄 |
| 子任务通道 | lib/subtask:spawn path=<工作簿> → wait;与工具 spawn fn= 同一套能力 |
| 产物 | 说明 |
|---|---|
| 工作簿路径 | 默认目录 .marqdo/agent-runs/(可参数覆盖);文件名含时间 / 短 id |
| 父侧返回值 | 结构化 map:status、goal、workbook(路径)、result(子 # main 返回值优先)、summary / error;可选 observation |
| 写回 | 工作簿内各 单步 默认落盘;父 多步 调用行亦可汇总写回 |
4. 调用流水线(锁定)
父:`助手`.多步 目标=…
▼
① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…)
▼
② 创建(或打开)工作簿 .mq.md
- frontmatter:导入 ext/ai/llm|agent、json、writeback、subtask…
- **大模型配置与父智能体一致**(见 §5)
- 正文:总目标叙述 + 子智能体骨架 / 或父模型生成的首版步骤
▼
③ 父模型「分解」(非 OKF 命中路径必跑):`phase=decompose`,尚未 spawn;可 `DECISION: RUN` / `CONTINUE`+补丁 / 固化后 `DONE`
▼
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
▼
⑤ wait → 收集 `{code, value}`(`# main` 返回)+ 工作簿内写回块;TTY 默认静默
▼
⑥ 父智能体 **结构化观察**(工作簿最新源码 + 写回槽 + 退出码 + `value`)
- 充分 → 汇总,写回父文档,返回
- 不足 / 失败 → **二次规划** → 对工作簿打**精确补丁**(禁止整文件重写)→ 回到 ④
▼
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
要点:
- 创建文件发生在
多步内,不是调用方手写脚手架(调用方可传已有工作簿=路径以续跑)。 - 执行工作簿 = 子任务跑整文件(入口
# main),不是父进程内嵌解释子 AST。 - 父是智能体开发大师:读真实执行结果再规划;修订靠精确补丁与代码固化,不靠整文件重生。
- 修订循环属于父智能体职责:同一
多步调用内可多轮「观察 → 规划 → 补丁 → 再 spawn」。
4.1 观察面与补丁(锁定)
父每次二次规划前必须拿到观察 map(inspect_workbook / await_workbook)。磁盘可持全文;注入父 LLM 的默认观察为有界紧凑面(摘录 + I/O 尾部)。完整语义与 READ: / CALL: 行动面见 ext-agent-parent.md。
| 字段 | 含义 |
|---|---|
path |
工作簿路径 |
source |
最新全文(磁盘);prompt 默认用 source_excerpt |
exit_code |
上一轮子任务退出码 |
value |
子 # main 返回值(经 await_workbook / wait.value) |
stdout / stderr |
子任务捕获(quiet 仅静音 TTY,不丢弃数据) |
slots |
命名写回列表(key + body) |
last_ok / last_error |
便捷字段 |
二次规划输出协议(机器可解析;禁止只输出整份 .mq.md;禁止长独白):
CALL:<parent-tool>
READ:source|stderr|stdout|slots
DECISION: DONE
SUMMARY: <一行>
DECISION: RUN
DECISION: CONTINUE
PATCH:
<<<
FIND
<确切旧片段>
===
REPLACE
<新片段>
>>>
解析优先级:CALL → READ → DECISION。应用器对文件做精确 FIND→REPLACE;找不到则报错。DONE 时运行时 agent_workbook_solidify 固化答案(不必靠长 REPLACE 粘贴子散文)。
4.2 多轮哲学:仅子智能体接力(模式 C)
复杂 / 多轮目标 = 多份可执行 .mq.md 接力,经 OKF 索引与复用;父 plan 聚合各子 wait.value 为 result。
| 做 | 不做 |
|---|---|
每主题 / 子目标一份工作簿(resources/ / explore/) |
单文件无限追加「对话日志」 |
| OKF task/skill 做索引与命中 | 单文件状态机表冒充流程 UI |
# main 返回答案;quiet 只管 TTY |
依赖子 print 把答案刷到父终端 |
5. 大模型配置与父保持一致
工作簿内构造子智能体时:
| 从父继承 | 说明 |
|---|---|
model / 大模型 句柄字段 |
api_key、base_url、model、suffix、bearer 及拼装前缀等与父相同 |
| 默认站立提示基调 | 可追加「只负责本工作簿内子任务」等收窄句;不得更换供应商端点 |
实现约定(D2):
- 父把当前 llm 句柄 序列化进工作簿(例如构造段直接写
> llm.llm前先load_env,或写入由父生成的配置表 / 环境约定)。 - 优先:工作簿与父共享同一套
OPENAI_*/.env加载路径,子文件内> llm.load_env+> llm.llm(或中文面),避免把密钥明文写进工作簿。 - 若父句柄来自非默认 env,父须在生成工作簿时写出等价构造(仍禁止把密钥写进 git 跟踪路径;工作簿目录应默认被 ignore)。
禁止:子工作簿默默改用另一 base_url / 另一模型名,除非调用方显式参数允许覆盖(v1 不提供覆盖;一律继承)。
6. 工作簿内容形态
6.1 推荐:多个子智能体
面对多种情形时,多个 # 智能体(或一个类型多次构造) 优于单一巨型提示:
---
title: agent-run-…
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
writeback: lib/writeback.mq.md
subtask: lib/subtask.mq.md
---
# 总目标
(父写入的目标叙述)
## 工具甲
…
# main
> llm.load_env path=…
*`模型` = > llm.llm *
*`调研` = > agent.agent model=`模型` tools=`表甲` standing=… *
*`撰写` = > agent.agent model=`模型` tools=`表乙` standing=… *
*`a` = > `调研`.step task=… *
*`b` = > `撰写`.step task=… *
6.2 也可:一个智能体多次单步
适合线性流水线;每次 step 仍默认写回,便于中断续跑。
6.3 固化为代码(强烈推荐)
一旦某步输入输出稳定(例如「取今日日期」「解析固定 JSON」),父智能体应把该步 改写成普通 ## 函数 + 直接调用,不再经子智能体推理:
| 不确定 | 已确定 |
|---|---|
> `子`.step task=… |
*`x` = > 本地函数 … |
| 宽工具表 + 长 standing | 窄函数、表驱动、分支 1. / 2. |
多步的价值之一就是把「试出来的正确步骤」沉淀成工作簿里的代码,而不仅是 chat 痕迹。
6.4 持续更新的两类内容
| 更新 | 含义 |
|---|---|
| 代码更新 | 增删 ##、改 # main 编排、改工具表、把 step 换成固化调用、修分支 |
| 写回注释更新 | `<!-- marqdo-out ok |
工作簿是活文档:子任务跑完后磁盘上的 .mq.md 应比创建时更「像最终报告」。
7. 单步自动写回(服务多步)
7.1 决议
| 默认 | 单步 / step 自动写回 本步结果(命名槽) |
| 开关 | 参数 写回 / writeback(布尔,默认 真 / True) |
| 槽 | 成功 → key=ok;失败 → key=error;正文为结构化 map 的 JSON(或与现 live 样例一致的 stringify) |
| 锚点 | 本步调用行(与现 writeback.record 锚点规则一致) |
这样:
- 父 / 工作簿不必靠提示词强迫模型「请记得写回」。
- 编排方仍可
写回=假拿到纯 map,自行writeback.record(测试、嵌套去重时有用)。
7.2 与父写回的分工
| 层级 | 写什么 |
|---|---|
子 step(默认开) |
该步 decision / tool / result 或 error |
父 plan |
工作簿路径、轮次、汇总摘要;可选把关键子 ok 块索引写在父调用行下 |
推荐:载荷以子 # main 返回值(wait.value → plan.result)为准;写回作审计与 step 缓存。避免只靠 stdout(默认静默会丢弃)。
7.3 返回值
step 仍返回结构化 map(与现 D1 一致)。自动写回是附加副作用,不取代返回值。
8. 父智能体上下文(每次修订 / 汇总前)
父在多步循环中每次「想下一步」时,注入不得弱于单步,且额外包含工作簿:
| 片段 | 来源 |
|---|---|
| 站立提示 | 父构造 |
| 总目标 | 多步 实参 |
| 父文件源码 | agent_module_source |
| 调用位置 | agent_call_site |
| Marqdo Skill | agent_marqdo_skill |
| 工作簿全文 / 写回 / 子返回 | inspect_workbook(源码 + slots + 退出码 + value) |
| 子任务退出码 | subtask.wait |
| 对话 / 历史 | 父 session;真相以写回为准 |
父模型输出必须是 DONE / CONTINUE+精确补丁 协议(见 §4.1),禁止整文件重写。
9. 公开 API(D2 契约)
9.1 ## 多步 / ## plan
| 参数 | 中 / 英 | 默认 | 说明 |
|---|---|---|---|
| 目标 | 目标 / goal |
必填 | 复杂任务描述 |
| 工作簿目录 | 工作簿目录 / workbook_dir |
.marqdo/agent-runs |
新建文件所在目录 |
| 工作簿 | 工作簿 / workbook |
空 | 若给路径则续跑 / 修订该文件,跳过空白创建 |
| 最大深度 | 最大深度 / max_depth |
2 |
工作簿内再调 多步 的嵌套上限;叶强制单步 |
| 最大轮次 | 最大轮次 / max_rounds |
实现选定(如 4) |
父「改文件 → 再执行」循环上限 |
| 确认分解 | 确认分解 / confirm |
假 |
真 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
| 写回 | 写回 / writeback |
真 |
父侧汇总写回 |
| 骨架 | 骨架 / skeleton |
single |
single 单 worker;dual 为 research→writer 两子智能体 |
返回 map(字段名英文字段,中文面可读同一结构):
| 字段 | 含义 |
|---|---|
status |
ok / error / pending(待确认) |
goal |
回显目标 |
workbook |
工作簿路径 |
rounds |
实际执行轮次 |
summary |
成功时的汇总 |
error |
失败信息 |
9.2 ## 单步 / ## step(修订)
在 D1 参数上增加:
| 参数 | 默认 | 说明 |
|---|---|---|
写回 / writeback |
真 |
是否自动 record 到 ok/error 槽 |
9.3 内部辅助(非稳定对外)
工作簿模板渲染、从父句柄生成子文件 frontmatter、解析子写回摘要等——可随实现调整。
10. 安全与边界
| 风险 | 对策 |
|---|---|
| 无限修订 / 嵌套 | 最大轮次、最大深度;叶任务禁止再 plan |
| 工作簿写爆仓库 | 默认目录 .marqdo/agent-runs/ + gitignore;禁止默认写到 lib/ / ext/ |
| 密钥进工作簿 | 继承 env / load_dotenv,不写明文 key |
| 子文件乱改父仓 | 子任务 cwd / fs_root 落到工作簿目录;工具表白名单 |
| 写回空行膨胀 | 替换跨度含 --> 行尾换行(已实现) |
| 并发写同一工作簿 | writeback 全局锁;同一 plan 内串行 spawn 为 v1 默认 |
11. 与旧 §3.2 叙述的差异(显式)
| 旧粗述 | 本文锁定 |
|---|---|
| 分解表 + 每行一个子智能体实例 | 整文件工作簿可含多智能体与固化代码;表只是可选骨架 |
| 子任务默认单步,写回在流水线步骤里点到为止 | 单步默认自动写回;父负责修订循环与汇总 |
| 缓存命中略写 | 以 OKF 任务知识包为准(okf.md §7):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 marqdo catalog |
| 父上下文未强调工作簿全文 | 父每次修订前必须能读最新工作簿 + 写回 |
12. 实现路线(D2)
| 项 | 内容 |
|---|---|
| D2a | step 增加 writeback=(默认真);金样例改默认行为并保留 writeback=False 测例 |
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承;inspect_workbook 观察面 |
| D2c | plan:生成 → spawn path → wait → 观察 → 返回;confirm |
| D2d | 二次规划 + 精确补丁循环(max_rounds);禁止整文件重写 |
| D2e | 多子智能体模板与固化提示 |
| D2f | 离线骨架金样例 + 可选 live 多步 |
13. 决议摘要
多步自动创建(或续跑)工作簿.mq.md,内容为任务的详细可执行步骤。- 子文件大模型配置与父一致(共享 env / 等价句柄;v1 无静默换模)。
- 经
lib/subtask启动该文件;可多轮执行。 - 工作簿内推荐多个智能体;也允许单智能体多
step;确定步骤固化为代码。 - 工作簿持续更新:代码 +
marqdo-out。 单步默认自动写回(写回=可关);父维护汇总写回。- 父具备源码、Skill、位置、历史与工作簿观察面,二次规划后以精确补丁修改再执行(禁止整文件重写主路径)。
14. 一句话
多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。