Enable default writeback on agent step and lock the plan design.
Document multi-step workbooks in ext-agent-plan, and make step/单步 persist ok/error slots unless writeback is turned off. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
1f23e2ed93
commit
fbece725e1
9 files changed
+383
-80
No files matched your search
@@ -131,7 +131,7 @@ title: example
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** / **multi-step workbook** + writeback ([ext-agent.md](../../doc/design/ext-agent.md)).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
|
||||
@@ -35,6 +35,7 @@
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
|
||||
@@ -0,0 +1,309 @@
|
||||
# 智能体多步(`## 多步` / `## plan`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;D2a(`step` 默认写回)已落地;其余 D2 待实现** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 父文档 | [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [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) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
单步(`## 单步` / `## step`)适合原子任务。复杂目标需要:
|
||||
|
||||
1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。
|
||||
2. **用子任务真正跑这份工作簿**,与主推理隔离。
|
||||
3. **允许工作簿在「跑 → 看结果 → 改代码 / 改写回 → 再跑」中演化**——既更新可执行语句,也更新 `<!-- marqdo-out … -->`。
|
||||
4. **父智能体持有与单步同等级的上下文**(源码、Skill、调用位置、历史),并能创建 / 修改 / 再执行工作簿。
|
||||
5. **能固化的步骤尽量固化为 Marqdo 代码**;仅不确定分支继续交给子智能体。
|
||||
|
||||
本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](ext-agent.md);实现以 D2 为准。
|
||||
|
||||
---
|
||||
|
||||
## 2. 一句话
|
||||
|
||||
**多步 = 父智能体生成(并持续修订)一份子 runbook `.mq.md`,用与父相同的大模型配置,经 `lib/subtask` 启动该文件;子文件内推荐多个 `# 智能体`(或一个智能体多次单步);结果靠单步默认写回 + 父侧汇总写回沉淀;确定步骤优先写成普通 Marqdo 代码。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 角色与产物
|
||||
|
||||
| 角色 | 职责 |
|
||||
|------|------|
|
||||
| **父智能体** | 持有目标;创建 / 改写工作簿;`spawn path=` 运行工作簿;读执行结果与写回块;决定改代码还是改提示;汇总并写回父文档 |
|
||||
| **工作簿 `.mq.md`** | 任务实现的**详细步骤文档兼程序**:导入、工具、一个或多个子智能体、可固化的普通函数与 `# main` 编排 |
|
||||
| **子智能体** | 工作簿内的 `# 智能体` / `# agent`;走 `单步`(默认);工具表白名单可收窄 |
|
||||
| **子任务通道** | `lib/subtask`:`spawn path=<工作簿>` → `wait`;与工具 `spawn fn=` 同一套能力 |
|
||||
|
||||
| 产物 | 说明 |
|
||||
|------|------|
|
||||
| 工作簿路径 | 默认目录 `.marqdo/agent-runs/`(可参数覆盖);文件名含时间 / 短 id |
|
||||
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`summary` / `error`;可选引用子写回摘要 |
|
||||
| 写回 | 工作簿内各 `单步` 默认落盘;父 `多步` 调用行亦可汇总写回 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 调用流水线(锁定)
|
||||
|
||||
```text
|
||||
父:`助手`.多步 目标=…
|
||||
▼
|
||||
① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…)
|
||||
▼
|
||||
② 创建(或打开)工作簿 .mq.md
|
||||
- frontmatter:导入 ext/ai/llm|agent、json、writeback、subtask…
|
||||
- **大模型配置与父智能体一致**(见 §5)
|
||||
- 正文:总目标叙述 + 子智能体骨架 / 或父模型生成的首版步骤
|
||||
▼
|
||||
③ (可选)父模型「分解」:改写工作簿为更细的步骤 / 多智能体
|
||||
▼
|
||||
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
|
||||
▼
|
||||
⑤ wait → 收集退出码、stdout、工作簿内写回块
|
||||
▼
|
||||
⑥ 父智能体阅读结果(源码最新版 + 写回 + 子输出)
|
||||
- 成功且充分 → 汇总,写回父文档,返回
|
||||
- 不足 / 失败 → **修改工作簿**(代码与/或 marqdo-out)→ 回到 ④
|
||||
▼
|
||||
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- **创建文件发生在 `多步` 内**,不是调用方手写脚手架(调用方可传已有 `工作簿=` 路径以续跑)。
|
||||
- **执行工作簿 = 子任务跑整文件**(入口 `# main`),不是父进程内嵌解释子 AST。
|
||||
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「改文件 → 再 spawn」。
|
||||
|
||||
---
|
||||
|
||||
## 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-…
|
||||
> ext/ai/llm.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> 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 块索引写在父调用行下 |
|
||||
|
||||
**推荐**:子结果以工作簿内写回为真相;父维护「总状态」写回,避免只靠 stdout。
|
||||
|
||||
### 7.3 返回值
|
||||
|
||||
`step` 仍返回结构化 map(与现 D1 一致)。自动写回是**附加副作用**,不取代返回值。
|
||||
|
||||
---
|
||||
|
||||
## 8. 父智能体上下文(每次修订 / 汇总前)
|
||||
|
||||
父在多步循环中每次「想下一步」时,注入不得弱于单步,且额外包含工作簿:
|
||||
|
||||
| 片段 | 来源 |
|
||||
|------|------|
|
||||
| 站立提示 | 父构造 |
|
||||
| 总目标 | `多步` 实参 |
|
||||
| **父文件源码** | `agent_module_source` |
|
||||
| **调用位置** | `agent_call_site` |
|
||||
| **Marqdo Skill** | `agent_marqdo_skill` |
|
||||
| **工作簿路径与全文**(或增量 diff) | 磁盘读回 |
|
||||
| **工作簿内写回块** | `writeback.list` / 扫描 `marqdo-out` |
|
||||
| **子任务 stdout / 退出码** | `subtask.wait` 结果 |
|
||||
| **对话 / 历史**(若有) | 父 session;真相仍以文档写回为准,历史仅辅助 |
|
||||
|
||||
父模型输出应优先是:
|
||||
|
||||
1. **对工作簿的具体修改意图**(增删改哪些段落 / 固化哪一步);或
|
||||
2. **判定完成**并给出汇总文案;或
|
||||
3. **请求再跑一轮**(无改或小改后 spawn)。
|
||||
|
||||
禁止把「只能改内存状态、不落盘」当作多步的主路径。
|
||||
|
||||
---
|
||||
|
||||
## 9. 公开 API(D2 契约)
|
||||
|
||||
### 9.1 `## 多步` / `## plan`
|
||||
|
||||
| 参数 | 中 / 英 | 默认 | 说明 |
|
||||
|------|---------|------|------|
|
||||
| 目标 | `目标` / `goal` | 必填 | 复杂任务描述 |
|
||||
| 工作簿目录 | `工作簿目录` / `workbook_dir` | `.marqdo/agent-runs` | 新建文件所在目录 |
|
||||
| 工作簿 | `工作簿` / `workbook` | 空 | 若给路径则**续跑 / 修订**该文件,跳过空白创建 |
|
||||
| 最大深度 | `最大深度` / `max_depth` | `2` | 工作簿内再调 `多步` 的嵌套上限;叶强制单步 |
|
||||
| 最大轮次 | `最大轮次` / `max_rounds` | 实现选定(如 `4`) | 父「改文件 → 再执行」循环上限 |
|
||||
| 确认分解 | `确认分解` / `confirm` | `假` | `真` 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
|
||||
|
||||
返回 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 叙述的差异(显式)
|
||||
|
||||
| 旧粗述 | 本文锁定 |
|
||||
|--------|----------|
|
||||
| 分解表 + 每行一个子智能体实例 | **整文件工作簿**可含多智能体与固化代码;表只是可选骨架 |
|
||||
| 子任务默认单步,写回在流水线步骤里点到为止 | **单步默认自动写回**;父负责修订循环与汇总 |
|
||||
| 缓存命中略写 | 仍有效:读工作簿 `ok` 槽,签名命中可跳过模型(D2 可后置) |
|
||||
| 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** |
|
||||
|
||||
---
|
||||
|
||||
## 12. 实现路线(D2)
|
||||
|
||||
| 项 | 内容 |
|
||||
|----|------|
|
||||
| D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** |
|
||||
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承约定 |
|
||||
| D2c | `plan`:生成 → `spawn path` → wait → 读写回;无修订循环的最小闭环 |
|
||||
| D2d | 父修订循环(改文件再执行)+ `max_rounds` |
|
||||
| D2e | 多子智能体模板与「固化为代码」提示写入 Skill / standing 片段 |
|
||||
| D2f | 离线骨架金样例 + 可选 live 多步 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 决议摘要
|
||||
|
||||
1. **`多步` 自动创建(或续跑)工作簿 `.mq.md`**,内容为任务的详细可执行步骤。
|
||||
2. **子文件大模型配置与父一致**(共享 env / 等价句柄;v1 无静默换模)。
|
||||
3. **经 `lib/subtask` 启动该文件**;可多轮执行。
|
||||
4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。
|
||||
5. **工作簿持续更新**:代码 + `marqdo-out`。
|
||||
6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。
|
||||
7. **父具备源码、Skill、位置、历史与工作簿全文**,并能按结果修改后再执行。
|
||||
|
||||
---
|
||||
|
||||
## 14. 一句话
|
||||
|
||||
**多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
|
||||
+31
-65
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
@@ -106,64 +106,35 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
### 3.2 模式 B — 多步 / 复杂执行(工作簿)
|
||||
|
||||
> **完整锁定设计**见 [**ext-agent-plan.md**](ext-agent-plan.md)。以下为摘要。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **输入** | 复杂目标 |
|
||||
| **过程** | 见下方流水线 |
|
||||
| **输出** | 汇总结果 + **一份新的 `.mq.md` 工作簿**(完整执行报告) |
|
||||
| **适用** | 需分解、多工具、可复用子成果的任务 |
|
||||
| **过程** | 父智能体**创建(或续跑)一份工作簿 `.mq.md`** → 子文件大模型配置与父一致 → **`lib/subtask` `spawn path=`** 运行该文件 → 读结果与写回 → **改代码 / 改写回后再执行**(有轮次上限) |
|
||||
| **输出** | 汇总 map + 磁盘上的工作簿(代码与 `marqdo-out` 均可演化) |
|
||||
| **适用** | 需分解、多情形、可固化步骤、可复用子成果的任务 |
|
||||
|
||||
公开方法:`## 多步` / `## plan`(名称可双语并列;中文面以「多步」为准)。
|
||||
公开方法:`## 多步` / `## plan`。
|
||||
|
||||
流水线:
|
||||
流水线要点:
|
||||
|
||||
1. **创建工作簿** — 在约定目录(默认 `.marqdo/agent-runs/` 或参数指定)生成新的 `.mq.md`:总目标叙述、元信息、子任务表骨架。
|
||||
2. **分解** — 主智能体(或 `## 分解`)把目标写成子任务表(可要求人工确认后再跑)。
|
||||
3. **子智能体** — 每个子任务实例化一个小的 `# 智能体`(可收窄工具集与站立提示)。
|
||||
4. **执行子任务** — 子智能体走 **单步**(默认);仅当子任务仍过复杂且未触达深度上限时,才允许嵌套多步。
|
||||
5. **写回** — 成功或失败都写回该子任务区块(含输入签名、时间戳、结果 / 错误)。
|
||||
6. **汇总** — 主智能体收集子结果,写回工作簿末尾,返回汇总。
|
||||
1. **创建工作簿** — 默认 `.marqdo/agent-runs/`;内容为任务的详细可执行步骤(导入、工具、`# main`、子智能体)。
|
||||
2. **模型配置继承父智能体** — 共享 env / 等价 llm 句柄;v1 不静默换模。
|
||||
3. **子任务执行整文件** — 不是父进程内嵌解释。
|
||||
4. **工作簿内推荐多个 `# 智能体`**;也允许一个智能体多次 `单步`;**已确定步骤应固化为普通 `##` 代码**。
|
||||
5. **持续更新** — 代码修订 + 写回注释刷新(替换不累积空行)。
|
||||
6. **`单步` 默认自动写回**(`写回=` / `writeback=` 可关),父侧再汇总写回。
|
||||
7. **父上下文** — 与单步同级的源码 / Skill / 调用位置 / 历史,外加工作簿全文与子写回。
|
||||
|
||||
**缓存命中**:再次遇到签名相同的子任务时,先 `get` / 扫描工作簿中的写回块;命中且策略允许则 **不再调用模型或工具**。
|
||||
|
||||
示意(文档级外形):
|
||||
示意:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 *
|
||||
*`编排` = > 智能体 大模型=`模型` 工具=`工具表` *
|
||||
|
||||
*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 工作簿目录=.marqdo/agent-runs *
|
||||
*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 *
|
||||
> 打印 内容=`报告`
|
||||
```
|
||||
|
||||
生成的工作簿(概念形状,非最终模板):
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
goal: 调研并汇总…
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
(叙述)
|
||||
|
||||
`子任务` =
|
||||
| 标识 | 描述 | 状态 |
|
||||
|------|------|------|
|
||||
| t1 | … | pending |
|
||||
|
||||
# main
|
||||
|
||||
*`子1` = > 智能体 大模型=`模型` 工具=`窄工具表` 站立提示=只做 t1 *
|
||||
*`r1` = > `子1`.单步 任务=… *
|
||||
> 写回 值=`r1`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
工作簿概念形状与修订循环细节 → [ext-agent-plan.md](ext-agent-plan.md)。
|
||||
## 4. 分层与仓库布局
|
||||
|
||||
```text
|
||||
@@ -202,8 +173,8 @@ ext/
|
||||
| 中文 | 英文 | 角色 |
|
||||
|------|------|------|
|
||||
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
|
||||
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;**返回结构化 map**(不内置写回) |
|
||||
| `## 多步` | `## plan` | 建工作簿 → 分解 → 子智能体 → 写回 → 汇总 |
|
||||
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
|
||||
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
|
||||
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
|
||||
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
|
||||
|
||||
@@ -215,8 +186,8 @@ ext/
|
||||
| `工具` / `tools` | 工具名表(单列文本,或多列且含 `工具`/`tools`/`name`) |
|
||||
| `站立提示` / `standing` | 写在文档里的常驻说明(可空) |
|
||||
|
||||
`## 单步` 参数:`任务` / `task`;可选深度、是否强制不用缓存等。
|
||||
`## 多步` 参数:`目标` / `goal`;可选 `工作簿目录`、`最大深度`、`是否确认分解`。
|
||||
`## 单步` 参数:`任务` / `task`;可选 `写回` / `writeback`(默认真)、深度、是否强制不用缓存等。
|
||||
`## 多步` 参数:`目标` / `goal`;可选 `工作簿目录`、`工作簿`(续跑路径)、`最大深度`、`最大轮次`、`确认分解` —— 详见 [ext-agent-plan.md §9](ext-agent-plan.md)。
|
||||
|
||||
模块内辅助函数(组装上下文、解析模型回复、匹配写回缓存)**不是**稳定对外契约,可随实现调整。
|
||||
|
||||
@@ -286,9 +257,9 @@ lib/subtask:spawn fn=<名> → wait
|
||||
|
||||
依赖 [stdlib-writeback.md](stdlib-writeback.md):`record` / `写回` → `<!-- marqdo-out … -->`。
|
||||
|
||||
### 8.1 单步返回值(不内置写回)
|
||||
### 8.1 单步返回值与默认写回
|
||||
|
||||
`单步` / `step` **不再自动写盘**。它返回一张结构化 map,由编排方决定是否、如何写回:
|
||||
`单步` / `step` 返回结构化 map,并在 **`写回` / `writeback` 默认真** 时自动 `record` 到命名槽(成功 `ok` / 失败 `error`)。关闭写回则行为与早期「纯返回值」一致,由编排方自行 `writeback.record`。
|
||||
|
||||
| 字段 | 何时 | 含义 |
|
||||
|------|------|------|
|
||||
@@ -302,25 +273,20 @@ lib/subtask:spawn fn=<名> → wait
|
||||
```markdown
|
||||
*`out` = > `助手`.step task=… *
|
||||
*`回复` = > json.get value=`out` key=result *
|
||||
*`status` = > json.get value=`out` key=status *
|
||||
*`body` = > json.stringify value=`out` *
|
||||
1. `status` == ok
|
||||
> writeback.record value=`body` key=ok
|
||||
2. *
|
||||
> writeback.record value=`body` key=error
|
||||
# 默认已写回;若 writeback=False 则需自行 record:
|
||||
# > writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
命名槽 `ok` / `error` 仍建议互不覆盖;锚点由调用方的 `写回`/`record` 决定。
|
||||
命名槽 `ok` / `error` 互不覆盖;锚点为调用行。多步工作簿内依赖此默认写回,避免靠提示词强制落盘 —— 见 [ext-agent-plan.md §7](ext-agent-plan.md)。
|
||||
|
||||
**命中规则(后续缓存)**:读 `key=ok` 且非占位时可复用。失败知识读 `key=error`。
|
||||
用户可 `clear key=ok` / `clear key=error` 强制重跑。
|
||||
|
||||
复杂执行中,写回优先落在 **工作簿** 文件。
|
||||
复杂执行中,子结果写回优先落在 **工作簿** 文件;父 `多步` 维护汇总写回。
|
||||
|
||||
### 8.2 Live 金样例
|
||||
|
||||
[`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md):`agent.step` + 子任务工具 + `writeback.record`(`key=ok` / `error`)。凭证:`tests/ext/.env`;`> llm.load_env path=.env` 相对**源文件目录**(`marqdo run` 将 cwd 设为该文件所在目录)。需已构建 agent 原生库(见 §4)。
|
||||
|
||||
[`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md):`agent.step`(**默认写回** `ok`/`error`)+ 子任务工具。凭证:`tests/ext/.env`;`> llm.load_env path=.env` 相对**源文件目录**。需已构建 agent 原生库(见 §4)。
|
||||
---
|
||||
|
||||
## 9. 安全与边界
|
||||
@@ -354,7 +320,7 @@ lib/subtask:spawn fn=<名> → wait
|
||||
|------|------|------|
|
||||
| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | **本文件** |
|
||||
| D1 | 重写 `ext/ai/agent.mq.md` / `智能体.mq.md`:`单步` + 源码/位置注入 + **子任务调工具** + **结构化返回值**;运行时经 **ABI v2 agent 插件**(禁 ext 直调 host) | **done** |
|
||||
| D2 | `多步`:工作簿模板、分解、子智能体(亦可 `spawn`)、缓存命中 | TODO |
|
||||
| D2 | `多步`:按 [ext-agent-plan.md](ext-agent-plan.md)(工作簿创建、`spawn path`、修订循环);**D2a `step` 默认写回已落地** | D2a done;其余 TODO |
|
||||
| D3 | 金样例:离线单步 / 写回;**live 单步**(`tests/ext/agent-run-live.mq.md`);多步骨架(可不打网) | **live done** |
|
||||
| D4 | `view` / `debug` 对工作簿与写回块的导航体验 | TODO |
|
||||
|
||||
@@ -370,4 +336,4 @@ lib/subtask:spawn fn=<名> → wait
|
||||
## 12. 一句话
|
||||
|
||||
**智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。**
|
||||
单步解决原子问题;多步生成工作簿、拆分子智能体、用自写回记住成功与失败——这才是 Marqdo 相对其它智能体框架的优越性所在。
|
||||
单步解决原子问题(默认写回);多步让父智能体编写并修订子 Marqdo 工作簿、经子任务执行、把确定步骤固化为代码——详见 [ext-agent-plan.md](ext-agent-plan.md)。
|
||||
@@ -18,7 +18,7 @@
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) (**document-driven agent** — step / multi-step workbook + writeback; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
|
||||
@@ -55,3 +55,5 @@ pending
|
||||
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
|
||||
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`);智能体侧经 `lib/subtask` 异步调用写回,避免阻塞推理主路径。
|
||||
|
||||
**与 `ext/ai/agent`:** `## step` / `## 单步` 在 D2 起 **默认自动** `record` 到 `ok`/`error` 槽(参数 `writeback=` / `写回=` 可关)。多步工作簿依赖此默认,见 [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md)。
|
||||
+14
-1
@@ -4,6 +4,7 @@ description: Document-driven agent — step / plan; tools via lib/subtask; runti
|
||||
> ext/ai/llm.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> lib/subtask.mq.md
|
||||
> lib/plugin.mq.md
|
||||
---
|
||||
@@ -127,8 +128,9 @@ Clear the plugin session bag for this agent id.
|
||||
|
||||
## step
|
||||
+ `task`
|
||||
+ `writeback`=True
|
||||
|
||||
One atomic turn: context → LLM → optional tool via subtask. Returns a **map** (`status`, `task`, `decision`, and on success `result` plus optional `tool` / `tool_result`; on failure `error`). Does **not** write back — call `lib/writeback` yourself if you want persistence.
|
||||
One atomic turn: context → LLM → optional tool via subtask. Returns a **map** (`status`, `task`, `decision`, and on success `result` plus optional `tool` / `tool_result`; on failure `error`). By default (`writeback=True`) persists that map under named slots `ok` / `error` at the call site; pass `writeback=False` to skip.
|
||||
|
||||
*`ctx` = > build_step_context agent=`self` task=`task` *
|
||||
*`id` = > json.get value=`self` key=id *
|
||||
@@ -175,6 +177,17 @@ One atomic turn: context → LLM → optional tool via subtask. Returns a **map*
|
||||
*`as_turn` = > json.parse text={"role":"assistant"} *
|
||||
*`as_turn` = > json.set map=`as_turn` key=content value=`reply` *
|
||||
> agent_history_append id=`id` item=`as_turn`
|
||||
|
||||
1. `writeback`
|
||||
*`body` = > json.stringify value=`out` *
|
||||
*`st` = > json.get value=`out` key=status *
|
||||
1. `st` == ok
|
||||
> writeback.record value=`body` key=ok
|
||||
2. *
|
||||
> writeback.record value=`body` key=error
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`out`**
|
||||
|
||||
## plan
|
||||
|
||||
+14
-1
@@ -4,6 +4,7 @@ description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务
|
||||
> ext/ai/大模型.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/系统.mq.md
|
||||
> lib/自写回.mq.md
|
||||
> lib/子任务.mq.md
|
||||
> lib/插件.mq.md
|
||||
---
|
||||
@@ -127,8 +128,9 @@ description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务
|
||||
|
||||
## 单步
|
||||
+ `任务`
|
||||
+ `写回`=真
|
||||
|
||||
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 **map**(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。**不**自动写回——需要持久化时自行调用 `lib/自写回`。
|
||||
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 **map**(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
|
||||
|
||||
*`ctx` = > 构建单步上下文 智能体=`自` 任务=`任务` *
|
||||
*`id` = > json.get value=`自` key=id *
|
||||
@@ -175,6 +177,17 @@ description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务
|
||||
*`as_turn` = > json.parse text={"role":"assistant"} *
|
||||
*`as_turn` = > json.set map=`as_turn` key=content value=`reply` *
|
||||
> agent_history_append id=`id` item=`as_turn`
|
||||
|
||||
1. `写回`
|
||||
*`body` = > json.stringify value=`out` *
|
||||
*`st` = > json.get value=`out` key=status *
|
||||
1. `st` == ok
|
||||
> 自写回.写回 值=`body` 键=ok
|
||||
2. *
|
||||
> 自写回.写回 值=`body` 键=error
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`out`**
|
||||
|
||||
## 多步
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: ext/agent step (DeepSeek)
|
||||
description: Real agent.step with tool via lib/subtask. Credentials from tests/ext/.env.
|
||||
description: Real agent.step with tool via lib/subtask; default writeback to ok/error slots.
|
||||
> lib/time.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> lib/json.mq.md
|
||||
@@ -28,21 +28,20 @@ description: Real agent.step with tool via lib/subtask. Credentials from tests/e
|
||||
*`助手` = > agent.agent model=`模型` tools=`工具表` standing=You are a Marqdo agent. When you need the current date, reply with exactly one line CALL:获取时间 and nothing else. *
|
||||
|
||||
*`out` = > `助手`.step task=请调用获取时间工具,然后用一句话告诉用户今天的日期。 *
|
||||
|
||||
*`status` = > json.get value=`out` key=status *
|
||||
*`回复` = > json.get value=`out` key=result *
|
||||
*`body` = > json.stringify value=`out` *
|
||||
|
||||
> print text=`回复`
|
||||
|
||||
1. `status` == ok
|
||||
> writeback.record value=`body` key=ok
|
||||
<!-- marqdo-out ok
|
||||
{"decision":"CALL:获取时间","result":"今天是2026年8月7日。","status":"ok","task":"请调用获取时间工具,然后用一句话告诉用户今天的日期。","tool":"获取时间","tool_result":"\"2026-08-07\""}
|
||||
-->
|
||||
|
||||
*`status` = > json.get value=`out` key=status *
|
||||
*`回复` = > json.get value=`out` key=result *
|
||||
|
||||
> print text=`回复`
|
||||
|
||||
*`cached` = > writeback.get key=ok *
|
||||
1. `cached`
|
||||
> print text=writeback-ok
|
||||
2. *
|
||||
> writeback.record value=`body` key=error
|
||||
> print text=writeback-missing
|
||||
|
||||
*`id` = > json.get value=`助手` key=id *
|
||||
*`历史` = > agent_history_get id=`id` *
|
||||
|
||||
Reference in new issue
Block a user