From fbece725e1fb0636f5e068fac343d25caf9962bb Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 7 Aug 2026 13:47:34 +0800 Subject: [PATCH] Enable default writeback on agent step and lock the plan design. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document multi-step workbooks in ext-agent-plan, and make step/单步 persist ok/error slots unless writeback is turned off. Co-authored-by: Cursor --- .cursor/skills/marqdo/SKILL.md | 2 +- doc/README.md | 1 + doc/design/ext-agent-plan.md | 309 +++++++++++++++++++++++++++++++++ doc/design/ext-agent.md | 96 ++++------ doc/design/ext-llm.md | 2 +- doc/design/stdlib-writeback.md | 2 + ext/ai/agent.mq.md | 15 +- ext/ai/智能体.mq.md | 15 +- tests/ext/agent-run-live.mq.md | 21 ++- 9 files changed, 383 insertions(+), 80 deletions(-) create mode 100644 doc/design/ext-agent-plan.md diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index a8b9a75..91cbfda 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -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`/`非`. diff --git a/doc/README.md b/doc/README.md index 1f3c8a1..91d679d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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/ 金样例目录布局** | diff --git a/doc/design/ext-agent-plan.md b/doc/design/ext-agent-plan.md new file mode 100644 index 0000000..7df5c0e --- /dev/null +++ b/doc/design/ext-agent-plan.md @@ -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. **允许工作簿在「跑 → 看结果 → 改代码 / 改写回 → 再跑」中演化**——既更新可执行语句,也更新 ``。 +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 换成固化调用、修分支 | +| **写回注释更新** | `` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 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 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。** diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md index 82e0c4c..b52aa34 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -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` / `写回` → ``。 -### 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)。 diff --git a/doc/design/ext-llm.md b/doc/design/ext-llm.md index 01e09d0..a8c1435 100644 --- a/doc/design/ext-llm.md +++ b/doc/design/ext-llm.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. diff --git a/doc/design/stdlib-writeback.md b/doc/design/stdlib-writeback.md index 3507300..9ef9042 100644 --- a/doc/design/stdlib-writeback.md +++ b/doc/design/stdlib-writeback.md @@ -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)。 diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index 3133424..c9f17e8 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -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 diff --git a/ext/ai/智能体.mq.md b/ext/ai/智能体.mq.md index 811db97..3f6793d 100644 --- a/ext/ai/智能体.mq.md +++ b/ext/ai/智能体.mq.md @@ -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`** ## 多步 diff --git a/tests/ext/agent-run-live.mq.md b/tests/ext/agent-run-live.mq.md index 8cb826f..6ecfafb 100644 --- a/tests/ext/agent-run-live.mq.md +++ b/tests/ext/agent-run-live.mq.md @@ -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 +*`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` *