# 智能体多步(`## 多步` / `## plan`) | | | |---|---| | 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** | | 日期 | 2026-08-11 | | 父文档 | [ext-agent.md](ext-agent.md) | | 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) · [调研:主流框架与 Marqdo](../research/agent-frameworks-and-marqdo.md) | --- ## 1. 动机 单步(`## 单步` / `## step`)适合原子任务。复杂目标需要: 1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。 2. **用子任务真正跑这份工作簿**,与主推理隔离。 3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。 4. **允许工作簿演化**——代码与 `` 均可更新,但**禁止**以整文件 LLM 重写作为修订主路径。 5. 子智能体只做不确定的 `单步`;能写成代码的就不要再问模型。 本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](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. 调用流水线(锁定) ```text 父:`助手`.多步 目标=… ▼ ① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…) ▼ ② 创建(或打开)工作簿 .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](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`;**禁止**长独白): ```text CALL: 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 推荐:多个子智能体 面对多种情形时,**多个 `# 智能体`(或一个类型多次构造)** 优于单一巨型提示: ```markdown --- 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 换成固化调用、修分支 | | **写回注释更新** | `` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 writeback 实现约定) | 工作簿是活文档:子任务跑完后磁盘上的 `.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](okf.md)):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 `marqdo catalog` | | 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** | --- ## 12. 实现路线(D2) | 项 | 内容 | |----|------| | D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** | | D2b | 工作簿模板 + 创建路径 + 父 llm 继承;`inspect_workbook` 观察面 | **done** | | D2c | `plan`:生成 → `spawn path` → wait → **观察** → 返回;`confirm` | **done** | | D2d | 二次规划 + **精确补丁**循环(`max_rounds`);禁止整文件重写 | **done**(主路径) | | D2e | 多子智能体模板与固化提示 | **done**(`skeleton=dual` + Solidify 段 + 父规划优先级) | | D2f | 离线骨架金样例 + 可选 live 多步 | **done**(decision 离线 + `agent-plan-live`) | --- ## 13. 决议摘要 1. **`多步` 自动创建(或续跑)工作簿 `.mq.md`**,内容为任务的详细可执行步骤。 2. **子文件大模型配置与父一致**(共享 env / 等价句柄;v1 无静默换模)。 3. **经 `lib/subtask` 启动该文件**;可多轮执行。 4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。 5. **工作簿持续更新**:代码 + `marqdo-out`。 6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。 7. **父具备源码、Skill、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。 --- ## 14. 一句话 **多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**