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>
358 lines
15 KiB
Markdown
358 lines
15 KiB
Markdown
# 智能体多步(`## 多步` / `## 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. **允许工作簿演化**——代码与 `<!-- marqdo-out … -->` 均可更新,但**禁止**以整文件 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:<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 推荐:多个子智能体
|
||
|
||
面对多种情形时,**多个 `# 智能体`(或一个类型多次构造)** 优于单一巨型提示:
|
||
|
||
```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 换成固化调用、修分支 |
|
||
| **写回注释更新** | `<!-- marqdo-out ok|error -->` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 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 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
|