Files
marqdo/doc/design/ext-agent-plan.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

15 KiB
Executable File
Raw Blame History

智能体多步(## 多步 / ## 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)适合原子任务。复杂目标需要:

  1. 把分解与执行过程落成一份可运行的 .mq.md(工作簿),而不是藏在进程内的任务图。
  2. 用子任务真正跑这份工作簿,与主推理隔离。
  3. 父智能体作为「智能体开发大师」:结构化读取执行结果与写回,再二次规划;用精确补丁改工作簿代码,并把确定步骤固化为普通 Marqdo ##。
  4. 允许工作簿演化——代码与 <!-- marqdo-out … --> 均可更新,但禁止以整文件 LLM 重写作为修订主路径。
  5. 子智能体只做不确定的 单步;能写成代码的就不要再问模型。

本文锁定 ## 多步 / ## 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):

  1. 父把当前 llm 句柄 序列化进工作簿(例如构造段直接写 > llm.llm 前先 load_env,或写入由父生成的配置表 / 环境约定)。
  2. 优先:工作簿与父共享同一套 OPENAI_* / .env 加载路径,子文件内 > llm.load_env + > llm.llm(或中文面),避免把密钥明文写进工作簿。
  3. 若父句柄来自非默认 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. 决议摘要

  1. 多步 自动创建(或续跑)工作簿 .mq.md,内容为任务的详细可执行步骤。
  2. 子文件大模型配置与父一致(共享 env / 等价句柄;v1 无静默换模)。
  3. 经 lib/subtask 启动该文件;可多轮执行。
  4. 工作簿内推荐多个智能体;也允许单智能体多 step;确定步骤固化为代码。
  5. 工作簿持续更新:代码 + marqdo-out。
  6. 单步 默认自动写回(写回= 可关);父维护汇总写回。
  7. 父具备源码、Skill、位置、历史与工作簿观察面,二次规划后以精确补丁修改再执行(禁止整文件重写主路径)。

14. 一句话

多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。