- 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。
20 KiB
Executable File
Official agent development framework (ext/ai/agent)
| Status | Accepted · redesign(取代「thin TOOL: loop」方案) |
| Date | 2026-08-07 |
| Related | ext-llm.md · ext-cli.md · ext-abi.md · ext-agent-plan.md(多步锁定设计) · ext-agent-parent.md(父 Plan-and-Move) · okf.md(OKF / 任务知识包) · engineering-knowledge.md(EKC / EFI preflight) · 调研:主流框架与 Marqdo 优势 · 缺口:A0–A4 之后 · module-namespace.md · objects.md · stdlib-writeback.md · stdlib-subtask.md · markdown-mapping.md |
0. 为什么要改掉旧方案
旧版把智能体做成「黑盒对话循环」:隐藏提示拼装、TOOL:<name> 协议、host 历史袋、一次(或几次)模型往返。这是对 LangChain 类框架的平移,背离了 Marqdo 的初衷。
Marqdo 的宪法是 代码即文档、文档即知识库:
| 旧方案的问题 | Marqdo 应有的形态 |
|---|---|
| 提示词藏在框架字符串里,与编排源码分离 | 提示、工具、任务、结果都在 .mq.md 里,人与模型同读同写 |
| 执行过程是不透明的 chat transcript | 思考与行动写回文档;view / debug 可跟可审 |
| 复杂任务与简单任务同一套循环 | 单步与**多步(工作簿)**两级模型 |
| 成功经验留在进程内存 | 自写回做成果缓存与失败知识;同类任务可复用 |
本文件锁定新方向。仓库里现有的 ext/ai/agent.mq.md / 智能体.mq.md(TOOL: 薄循环)视为 待替换实现,以本文为准。
1. 我们在建什么
一个 文档驱动的智能体开发框架:编排本身就是可读的 .mq.md;模型吃的是这份文档与调用位置;写回让思考过程可控、可调试、可沉淀。
不是 外挂任务队列、不是 官方捆绑领域工具、不是 第二套聊天栈(模型 I/O 仍用 ext/ai/llm)。
| 在范围内 | 在范围外(应用 / runbook) |
|---|---|
# 智能体 / # agent 构造 |
领域工具:## 查天气、## 分配任务 … |
## 单步 / ## step |
业务表格、队列、工单流程 |
## 多步 / ## plan(生成并驱动工作簿) |
具体分解策略模板库(可放用户仓) |
| 上下文:源码、调用位置、工作簿路径、Skill | 第二套 HTTP / 聊天协议 |
与 lib/writeback、lib/subtask(工具执行通道)、lib/plugin + ABI v2 plugins/agent 协作 |
把领域技能塞进官方 ext/ai/;在 ext 内直调 host_* |
2. 核心理念:编排可读,过程可写回
-
提示词与代码不分离
站立提示、工具表、任务叙述都写在.mq.md里。框架把当前模块源码与调用位置交给模型,而不是另起一套 system prompt 黑盒。 -
把 Marqdo 源码交给智能体
每次推理可注入:入口 / 工作簿.mq.md全文(或相关切片)、host_call_site(路径、函数、行)、skills/marqdo(写 / 读.mq.md的语法纪律)。模型输出应优先是 可解释的决策 与 对文档的结构化改动意图,而不是私有 JSON 协议。 -
自写回 = 思考轨迹 + 成果缓存
成功或失败都写回文档(见 stdlib-writeback.md)。成功块可被后续同类任务命中,避免重复失败;失败块成为可读的「避坑记录」。marqdo view在语句下展示 output-card,调试面可对齐同一份真相。 -
相对其他框架的优势
无需外挂向量库 / 状态机才能「记住」某次子任务已成功:记忆就是仓库里的 Markdown。审计、合规、复盘 =git log+ 打开工作簿。
3. 两级执行模型
3.1 模式 A — 单步(原子任务)
| 输入 | 小任务描述 + 必要上下文(工具表、站立提示、源码切片) |
| 过程 | 一次(或有限次)推理;可选调用 runbook 内 的工具函数;结果写回 |
| 输出 | 原子结果(文本 / 表 / 句柄字段) |
| 适用 | 问答、单一工具、确定性一步 |
公开方法(中 / 英):## 单步 / ## step。
示意(语法外形;实现以落地代码为准):
---
导入:
智能体: ext/ai/智能体.mq.md
大模型: ext/ai/大模型.mq.md
自写回: lib/自写回.mq.md
时间: lib/时间.mq.md
---
## 获取时间
*`u` = > 时间.此刻秒 *
**> 时间.格式化 秒=`u` 格式=%Y-%m-%d**
# main
*`模型` = > 大模型.大模型 *
`工具表` =
| 工具 |
|------|
| 获取时间 |
*`助手` = > 智能体 大模型=`模型` 工具=`工具表` 站立提示=你是可调试的 Marqdo 助手。 *
*`结果` = > `助手`.单步 任务=今天日期是什么?请在需要时调用工具。 *
> 打印 内容=`结果`
单步约定:
- 模型看到的上下文 包含本文件源码与调用位置,因此「有哪些
##工具」对模型是可见的;行动约定写在提示里(人可读),例如单独一行CALL:<工具名>/调用:<工具名>,最终答案则直接正文回复。 - 工具仍是 runbook 里的
##函数(v1 以零参为主;可经args=扩展)。 - 调用工具走
lib/subtask:白名单校验通过后spawn fn=<名>(中文面启动 函数=)→wait/等待,而不是进程内直接call_fn。这样工具与主推理隔离在子任务语义下,并可与并行、超时、探测同一套主机能力对齐。 - 结束后用自写回记录:任务摘要、选用工具、结果或错误。
3.2 模式 B — 多步 / 复杂执行(工作簿)
完整锁定设计见 ext-agent-plan.md。以下为摘要。
| 输入 | 复杂目标 |
| 过程 | 父智能体创建(或续跑)工作簿 →(非命中)父先分解 → lib/subtask spawn 跑子文件 → 观察写回 → 父修订补丁后再执行(有轮次上限) |
| 输出 | 汇总 map(含 result)+ 磁盘上的工作簿(代码与 marqdo-out 均可演化) |
| 适用 | 需分解、多情形、可固化步骤、可复用子成果的任务 |
公开方法:## 多步 / ## plan。
流水线要点:
- 创建工作簿 — 默认
.marqdo/agent-runs/;内容为任务的详细可执行步骤(导入、工具、# main、子智能体)。 - 模型配置继承父智能体 — 共享 env / 等价 llm 句柄;v1 不静默换模。
- 子任务执行整文件 — 不是父进程内嵌解释。
- 工作簿内推荐多个
# 智能体;也允许一个智能体多次单步;已确定步骤应固化为返回答案的普通代码(多轮 = 多文件接力 + OKF,见 ext-agent-plan.md §4.2)。 - 持续更新 — 代码修订 + 写回注释刷新(替换不累积空行)。
单步默认自动写回(写回=/writeback=可关),父侧再汇总写回。- 父上下文 — 与单步同级的源码 / Skill / 调用位置 / 历史,外加工作簿全文与子写回。
示意:
*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 *
> 打印 内容=`报告`
工作簿概念形状与修订循环细节 → ext-agent-plan.md。
4. 分层与仓库布局
ext/
ai/
llm.mq.md / 大模型.mq.md # 模型 I/O
agent.mq.md / 智能体.mq.md # 本框架(按本文重写)
| 层 | 职责 |
|---|---|
| 应用 runbook | 领域 ## 工具、任务表、是否人工确认分解 |
ext/ai/agent |
单步 / 多步、工作簿生成、子智能体编排、写回约定 |
ext/ai/llm |
补全 / 聊天 |
lib/writeback |
持久化输出块 |
lib/subtask |
工具调用与(多步时)子智能体并行的执行通道;见 stdlib-subtask.md |
安装:ext-cli.md — marqdo ext add agent / add llm(.mq.md + native/libagent.so)。导入:导入 智能体:ext/ai/智能体.mq.md。
原生插件(ABI v2):ext/ai/agent 经 lib/plugin 加载;优先 > plugin.native_path name=agent,否则按序查找:
MARQDO_AGENT_PLUGIN(显式.so/.dylib路径)CARGO_TARGET_DIR/{debug,release}/libagent.so(或.dylib)- cwd
target/{debug,release}/ - 可执行文件旁
libagent.*或target/debug/ MARQDO_EXT/native/libagent.*(marqdo ext add agent安装)
本地开发须先 cargo build -p marqdo_plugin_agent(或 ext add agent / 设 MARQDO_AGENT_PLUGIN)。详见 ext-cli.md · ext-abi.md。
分层纪律(硬规则,勿破):
ext/**/*.mq.md禁止出现任何host_*/host_调用。- Agent 专属能力(含 OKF agent-kb:
agent_goal_sig/agent_kb_lookup/agent_kb_promote/ …;以及 EKC:agent_eng_preflight/agent_eng_reuse/agent_eng_record)只进plugins/agent注册名,由ext/ai/agent在plugin.load后调用。 - 禁止向
src/host/(HostFn表)添加 agent / OKF / EKC 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。 - Engineering preflight:
agent.preflight/plan … eng_preflight=True在 agent-kb 之前解析 REUSE/ADAPT/CREATE(见 engineering-knowledge.md)。缺.marqdo知识图时返回missing_knowledge并放行,以兼容纯任务包测试。 - 进程退出用
sys.exit/系统.退出,不用裸exit。
官方 ext/ai/ 用 lib/* 包装或插件注册名;见 module-namespace.md §8 · ext-abi.md。
5. 公开 API(目标契约)
| 中文 | 英文 | 角色 |
|---|---|---|
# 智能体 |
# agent |
构造:大模型/model,工具/tools,可选 站立提示/standing |
## 运行 |
## run |
v2 主入口:Adaptive route → execute → record episode → maybe_learn(技能 + 策略) |
## 单步 |
## step |
原子执行;注入源码 + 位置;可选工具;返回结构化 map;默认自动写回(写回= / writeback= 可关) |
## 多步 |
## plan |
建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 ext-agent-plan.md) |
## 解析 |
## resolve |
技能解析:exact → alias → canonical → near |
## 路由 |
## route |
P4 Adaptive Routing:marqdo | small-llm | llm | auto(jev 为 small-llm 兼容别名) |
## 应用路由 |
## route_apply |
将小模型/大模型路由回复(SKILL:<slug> / EXPLORE)落到 kb 技能 |
## 编译策略 |
## compile_policy |
Policy Compilation → policies/router.mq.md |
## 记录情景 |
## record_episode |
每次执行沉淀为 .mq.md episode(.marqdo/agent-memory/) |
## 尝试学习 |
## maybe_learn |
情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
## 编译 |
## compile |
候选技能 → 版本化 skills/<slug>/vN.mq.md + 可选 OKF promote |
## 指标 |
## metrics |
Reasoning amortization(avg_llm_calls / compiled_runs) |
## 分解 |
## decompose |
(可公开或内部)目标 → 子任务表 |
## 清空历史 |
## clear_history |
若仍保留会话式辅助状态则清空;不以隐藏 chat 袋为真相源——真相在文档写回 |
Skill Compilation(v2):Agent 的记忆不是向量袋,而是可执行 .mq.md。路径:episodes/ → experiences/ → candidates/ → skills/vN.mq.md → OKF agent-kb(llm_free)。编译技能正文为合法 Marqdo(**result = …** + 斜体返回);金样 tests/ext/agent-zero-llm.mq.md 验收 policy+skill 全路径 execution.llm_calls=0。plan 对已存在的 resources/<slug>.mq.md 不覆盖(agent-plan-preserve)。
LLM 成本:model_turn 走 model.ask / stream+collect,把 LLMResult.tokens 写入 episode / execution。
Adaptive Routing(P4):Router 是抽象能力,backend = marqdo(已编译 policies/router.mq.md)/ small-llm(router_model 任意 llm 句柄)/ llm / auto 级联。jev 仅为 small-llm 兼容别名,不进入框架专属设计。热路径在 plugins/agent(route.rs);禁止向 src/host/ 加领域原语。设计:doc/next/003.md · doc/next/004.md。
构造参数(v1):
| 参数 | 说明 |
|---|---|
大模型 / model |
ext/ai/llm 句柄 |
工具 / tools |
工具名表(单列文本,或多列且含 工具/tools/name) |
站立提示 / standing |
写在文档里的常驻说明(可空) |
## 单步 参数:任务 / task;可选 写回 / writeback(默认真)、深度、是否强制不用缓存等。
## 多步 参数:目标 / goal;可选 工作簿目录、工作簿(续跑路径)、最大深度、最大轮次、确认分解 —— 详见 ext-agent-plan.md §9。
模块内辅助函数(组装上下文、解析模型回复、匹配写回缓存)不是稳定对外契约,可随实现调整。
6. 工具表与子任务调用
工具 不是 框架内置能力。在 runbook 定义 ##,再用表登记名称:
`工具表` =
| 工具 |
|------|
| 获取时间 |
| 读取摘要 |
- 单列表 → 名称列表。
- 多列表 → 从列
工具/tools/name取名。 - 名称须对应当前模块(或导入可见)的
##。 - 不要 用
parse text=["fn"]列工具(未加引号的标识符会被当成调用)。
6.1 调用路径(锁定)
模型回复含 CALL:<名> / 调用:<名>
▼
host_tool_allowed(工具表白名单)
▼
lib/subtask:spawn fn=<名> → wait
▼
工具返回值写回上下文 / 自写回
| 英文面 | > spawn fn=名 → `> wait id=`… |
| 中文面 | > 启动 函数=名 → `> 等待 id=`… |
| 可选 | args= / 参数= 传给带形参的工具;多工具并行时多次 spawn 再 wait_all / 等待全部 |
非目标: 以裸 call_fn 作为框架默认工具通道(应用仍可直接 call_fn,但官方智能体走子任务库)。
领域逻辑永远留在应用文件,不进官方 ext/ai/。
7. 上下文注入(每次单步 / 子步)
必须可注入(实现可切片,但不得默默丢掉「代码即文档」):
| 片段 | 来源 |
|---|---|
| 站立提示 | 构造参数 / 文档正文 |
| 任务 / 目标 | 方法实参 |
| 工具表(人可读) | 构造参数 |
当前 .mq.md 源码 |
插件 agent_module_source(经 ABI v2 host_query) |
| 调用位置 | 插件 agent_call_site |
| Marqdo skill | 插件 agent_marqdo_skill |
| Marqdo Skill | skills/marqdo/(MARQDO_SKILL 可覆盖) |
| 相关写回块 | lib/writeback 的 get / list |
禁止:把整份 Skill + 全文源码藏进不可审查的二进制提示且不在文档中留迹。框架拼装的提示应能在调试时落盘或写回(至少摘要)。
8. 自写回与缓存语义
依赖 stdlib-writeback.md:record / 写回 → <!-- marqdo-out … -->。
8.1 单步返回值与默认写回
单步 / step 返回结构化 map,并在 写回 / writeback 默认真 时自动 record 到命名槽(成功 ok / 失败 error)。关闭写回则行为与早期「纯返回值」一致,由编排方自行 writeback.record。
| 字段 | 何时 | 含义 |
|---|---|---|
status |
总是 | ok / error |
task |
总是 | 本步任务 |
decision |
总是 | 模型首轮输出(含 CALL 行等) |
tool / tool_result |
成功且调了工具 | 工具名与子任务返回 |
result |
成功 | 最终答复 |
error |
失败 | 错误信息 |
*`out` = > `助手`.step task=… *
*`回复` = > json.get value=`out` key=result *
# 默认已写回;若 writeback=False 则需自行 record:
# > writeback.record value=`body` key=ok
命名槽 ok / error 互不覆盖;锚点为调用行。多步工作簿内依赖此默认写回,避免靠提示词强制落盘 —— 见 ext-agent-plan.md §7。
命中规则(后续缓存):读 key=ok 且非占位时可复用。失败知识读 key=error。
用户可 clear key=ok / clear key=error 强制重跑。
复杂执行中,子结果写回优先落在 工作簿 文件;父 多步 维护汇总写回。
8.2 Live 金样例
tests/ext/agent-run-live.mq.md:agent.step(默认写回 ok/error)+ 子任务工具。凭证:tests/ext/.env;> llm.load_env path=.env 相对源文件目录。需已构建 agent 原生库(见 §4)。
9. 安全与边界
| 风险 | 对策 |
|---|---|
| 无限多步递归 | 最大深度(默认小,如 2);叶任务强制单步 |
| 工具越权 | 仅工具表白名单;子智能体可传更窄的表 |
| 工作簿爆炸 | 统一目录、命名含时间 / id;可选总超时 |
| 缓存过期 | 签名 + 时间戳;手动清块 |
| 模型乱改仓库 | 写回 API 约束写入形态;多步生成文件限于工作簿目录 |
10. 相对旧 API 的迁移
| 旧(废弃方向) | 新 |
|---|---|
唯一的 ## 执行 / ## run + 隐藏 TOOL: 循环 |
## 单步 / ## 多步 |
| host 历史袋为真相 | 文档写回 + 工作簿为真相;历史袋至多辅助 |
| 提示全在框架字符串 | 站立提示与任务在 .mq.md;源码注入 |
tests/ext/agent-smoke 测 TOOL 上下文拼接 |
重写为单步离线 / 写回 / 工作簿骨架测试 |
兼容:可短期保留 ## 执行 作为 ## 单步 的别名,但文档与金样例迁到新名后删除别名。
11. 实现路线(文档锁定后)
| 阶段 | 内容 | 状态 |
|---|---|---|
| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | 本文件 |
| D1 | 重写 ext/ai/agent.mq.md / 智能体.mq.md:单步 + 源码/位置注入 + 子任务调工具 + 结构化返回值;运行时经 ABI v2 agent 插件(禁 ext 直调 host) |
done |
| D2 | 多步:按 ext-agent-plan.md(观察→精确补丁;禁止整文件重写);D2a–D2f 主路径已落地 |
done |
| D3 | 金样例:离线单步 / 写回;live 单步(tests/ext/agent-run-live.mq.md);多步骨架(可不打网) |
live done |
| D4 | view / debug 对工作簿与写回块的导航体验 |
done(workbook 链到 /file?path=;写回槽 ok/error/trace 徽章 + #wb-{line};plan 结果卡) |
| O2 | OKF 任务知识包:plan reuse/promote(okf.md §7) |
done |
非目标
- 在官方
ext/ai/捆绑领域工具或工单技能 - 在
ext/根目录摊平.mq.md - 平行再造一套 LLM HTTP 栈
- 以不可读的私有二进制协议作为编排主界面
12. 一句话
智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。
单步解决原子问题(默认写回);多步让父智能体编写并修订子 Marqdo 工作簿、经子任务执行、把确定步骤固化为代码——详见 ext-agent-plan.md。
流式:## step / ## plan 支持 stream=True / echo=True(SSE 增量;返回 map 不变;plan 另附 events,可选 trace 写回)。非命中时先流式父分解再 spawn 子任务。见 agent-streaming.md。