Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

33 KiB
Executable File
Raw Permalink Blame History

我实际开发了一下,觉得借助外部框架反而会拖累marqdo的特性发挥,应该将marqdo的智能体框架优化一下,方便实际的开发工作。我觉得重点在于以下几个方面: 上下文操作,允许用户方便的进行用户输入和marqdo文件级、类级、函数级的提示词拼接和注入。 能够等待模型输入进行便捷的模型控制执行流 能够控制模型开启并发操作,进行多智能体并发执行 能够便捷的解析模型的输出,对于不是很稳定的模型也能实现交互 易于拓展

我认为这次应该对 Marqdo 的智能体框架进行一次面向文档原生执行的架构升级,而不是继续给 qdagent 增加包装层。

结合你此前对小模型、极短 SKILL 和递归调用的要求,我认为新的设计目标应该是:

Marqdo 文档负责描述任务,模型负责作出选择,Marqdo Runtime 负责控制执行。

模型不必理解整个智能体框架,只需要完成当前函数要求的一个小决策。

这与传统 Agent Framework 的区别在于:我们不应让模型不断生成复杂的工具调用协议,也不应要求它理解隐藏的框架状态机。它只需要返回简短结果,后续的判断、等待、路由、并发以及恢复都可以交给 Marqdo。

一、从现有代码看,真正缺少的是什么

我查看了目前 marqdo/main 的 ext/ai/agent.mq.md、ext/ai/llm.mq.md、lib/subtask.mq.md,以及相关设计文件。

Marqdo 并不是缺少智能体基础设施,而是已有能力尚未形成面向普通 Marqdo 作者的简洁统一接口。

目标能力 当前基础 需要补充
上下文操作 build_step_context、ContextPackV2、llm.prompt 文件/类/函数级的精确提取和组合
模型控制执行流 agent.step、model_turn、resume 简短模型结果驱动的条件分支、等待和恢复
多智能体并发 subtask.spawn、wait、run_many 模型任务级的派发、并发配额、结果汇合
不稳定输出解析 LLMResult、CALL:/DECISION: 解析 枚举选择、宽容解析、类型验证和有限修复
易于扩展 .mq.md 函数、插件、MCP、SKILL 编译 一套简单、稳定的开发者门面

尤其值得注意的是,当前 ext/ai/agent.mq.md 已经增长为约 256 KB 的大型文件,包含大量内部编排函数。这不意味着它一定会被完整送入模型,但说明开发接口和内部机制已经有明显的分离价值。

我建议此次重构的原则是:

不新增第二种编程语言,不重写 Agent Runtime,不破坏现有 SKILL。只给 Marqdo 增加几个真正必要、可以自然组合的智能体操作。

二、我建议提供的五项原生能力

1. 上下文:让函数所在的文档自动成为提示词

这是我认为最有 Marqdo 特色、也最应该优先实现的部分。

当前已有 source_brief 和 skill_brief,但开发者仍需要理解智能体的上下文组装机制。我希望把它进一步转化为编译器可寻址的上下文投影。

当前用户输入

始终保留本轮最新消息

文件级

全局职责

类级

当前领域

函数级

当前动作

ContextPack

按需拼接、去重、裁剪,然后交给模型

建议默认只注入当前函数和必要的祖先说明,不注入全部兄弟函数。

范围 读取内容 典型用途
file 文件级说明、约束与能力概述 根 SKILL
class 当前 # 类的说明和继承的约束 子领域
function 当前 ## 函数的说明与契约 单次模型决策
full 指定范围的完整源码 显式请求深入理解

这里必须使用 Marqdo 的 AST、模块身份和函数作用域来提取内容,不能简单用正则截取标题。

进一步建议增加一个可直接调用的 ai.context,支持 scope="function" 等选择,并允许 user= 提供显式输入。普通交互可以从当前调用会话获取最新用户消息;独立的 marqdo call 则能够明确传入该消息,便于复现和单元测试。

一个重要细节:文档片段是提示上下文,不代表执行这些片段。 import 也不应默认把依赖模块的完整内容注入模型。

2. 等待模型:让模型返回值直接控制 Marqdo 分支

现阶段 Marqdo 已经支持条件分支,真正需要的是一个足够简单、能够阻塞等待模型结果的函数。

例如拟增加:

ai.choose(options=...)

模型只需要从提供的选项中选择一个,Marqdo 负责等待结果、解析结果、验证选项,然后把结果交给原有分支语句。

在此基础上保留:

接口(拟议) 职责
ai.ask 等待模型生成文本或指定类型的结果
ai.choose 等待模型从给定选项中选择
ai.start 发起非阻塞模型任务
ai.wait 等待任务完成并获取结果

ask 和 choose 默认是同步的。只有真正需要同时处理多个任务时,作者才使用 start 和 wait。

这意味着控制流无需新增 if AI、await AI 等语言关键字,也不必为了执行一步模型决策创建完整的工作簿。

对于需要用户回答的场景,还应区分 waiting_model 和 waiting_user。后者必须能持久化当前执行位置,并由会话输入恢复,不能在函数内部长期阻塞一个模型或 HTTP 请求。

3. 并发:直接并发执行 .mq.md,而不是另造 Agent 类型

当前 lib/subtask 的实现已经相当接近目标。

它支持创建子任务、等待、轮询,以及 run_many 的受限并发执行。因此不需要再做一套独立的 Multi-Agent Framework。

我建议新增薄封装:

ai.parallel(tasks=..., limit=2)

其中每个任务都引用一个实际存在的 .mq.md 文件、可调用函数和输入。

父 Marqdo 函数

子 SKILL A

资料检索

子 SKILL B

方案评估

子 SKILL C

风险分析

结果汇合

父函数获取三个独立返回值

每个子任务是独立的执行上下文,不继承父模型完整历史,只接收明确传入的任务、允许使用的能力与必要文档。

还需要统一限制并发数、模型请求配额、超时与取消。尤其在单张 GPU 上运行多个小模型任务时,任务并发不意味着推理一定能并行;Runtime 应允许共享模型服务进行排队,而不是为每个子智能体重复加载模型权重。

4. 输出解析:优先理解短文本,不强迫小模型生成复杂 JSON

这项能力对小模型尤其重要。

例如,模型本来只需要回答 chat,但实际可能生成以下任意一种结果:

chat

chat

我选择 chat

chat

选择:chat,因为用户希望对话

chat

```text
chat
```

chat

这些结果都可以被确定性地规范化为相同选项;无需再调用一个模型来解释前一个模型。

我建议采用递进式解析:

层级 行为
精确 完整匹配合法选项
规范化 处理空白、代码围栏、常见选择前缀
受限提取 从明确的选择字段中提取唯一合法选项
有界修复 无法确定时,只让模型重新输出选项标识
失败返回 仍不确定、多个选项冲突时返回 invalid

不能为了追求成功率而随意猜测。 模型同时提到 chat 和 office,不意味着可以选择其中第一个。工具执行、文件写入等高风险动作更不能依赖模糊匹配。

可以支持模型服务的 constrained decoding,但不应强制所有小模型使用复杂 JSON Schema。2026 年针对小模型的结构化输出研究也指出,格式合法性提高不一定意味着语义决策更正确。

image

ijcai.org+1

5. 扩展:把能力沉到 Marqdo 库,而不是产品框架

建议新增的接口仍保持 Marqdo 的现有组织习惯:

ext/ai/
  index.mq.md       # 简短导航
  flow.mq.md        # 模型控制流
  context.mq.md     # 文档上下文
  parse.mq.md       # 模型结果解析
  parallel.mq.md    # 智能体并发
  agent.mq.md       # 现有高级编排,保留兼容
  llm.mq.md         # 现有模型抽象

这些是拟议的新文件划分,不代表当前仓库已经实现。

每份 .mq.md 自身仍是一份可以阅读的 SKILL,公开 ## 函数即工具,不需要再维护独立的 Tool Schema。真正需要操作系统、异步调度或模型推理后端的部分,复用 Rust Runtime 与现有插件。

特别是 flow.mq.md,我建议它成为日常智能体开发的极薄门面,而不是把现有大型 agent.mq.md 再复制一遍。

三、理想中的开发体验:两个函数就能完成根 SKILL

这是最重要的验收标准:经过框架升级,原先的 qdagent 根入口不应该变复杂,反而应该更短。

下面展示我希望实现的最终作者体验。注意,这是拟议的新接口示例,当前 Marqdo 2.7.1 还不能直接运行这些新函数。


---
markup: occlusion
title: 求道智能体入口
import:
  ai: ext/ai/flow.mq.md
---

# main

你是求道智能体。

每次收到非空用户输入,先提供简短选项,
等待用户确认,再进入对应的 SKILL。
这里只负责意图确认和路由,不执行具体任务。

## 分解意图

根据`用户输入`生成两个简短方向,
每个方向说明好处和代价。

**选项 = [让模型生成意图选项](ai.ask(input=`用户输入`, output="options", count=2))**

**确认 = [展示选项并等待用户回复](ai.input(options=`选项`))**

返回*确认*。

## 路由函数

根据确认后的`用户意图`选择下一层 SKILL。

**目标 = [让模型选择已有的技能](ai.choose(input=`用户意图`, options=["chat", "office"]))**

返回*[进入对应的 SKILL](ai.enter(skill=`目标`))*。

这份入口只保留两个业务函数。运行时自动提供函数级上下文,模型不需要认识 ai.input 的暂停实现,也不需要理解 ai.enter 的模块加载机制。

其中 ai.input 应该由 Marqdo Runtime 原生支持持久化暂停:展示选项后释放执行资源,收到用户回复时从原执行位置恢复。qdagent 只需要实现用户消息和选项卡的传输、展示。

ai.enter 只能接受已登记的 SKILL 标识,运行时解析为实际文档,并校验权限与函数入口。不能直接执行模型任意返回的文件路径。

这样,真正复杂的东西存在于 Marqdo Runtime,而不是每份 SKILL 的正文中。

四、开发顺序:先做最小闭环,再扩展并发

我建议按下面的依赖顺序推进,避免一开始就大规模重构 agent.mq.md。

P0 — 文档上下文与模型选择

在 src/frontend 的 AST/符号定位基础上,建立文档作用域提取;给 ext/ai 增加 context、ask、choose 的轻量接口。

验收:一个函数能够使用自己的说明与用户输入,完成一次模型选择,不依赖 agent.plan。

P1 — 用户等待与跨 SKILL 续执行

在现有 Runtime checkpoint、会话和事件基础上增加可持久化的 input、enter。恢复时检查文档版本、用户回复和调用权限。

验收:qdagent 从意图选择卡暂停,用户回复后继续进入聊天 SKILL;服务中断后也可以安全恢复。

P2 — 并发模型与多智能体

将 subtask.run_many 包装为可接收模型与 SKILL 任务的 ai.parallel,加入每个子任务独立上下文、模型选择、取消、超时和结果汇合。

验收:三个独立 SKILL 可以同时运行,父函数获得全部成功或失败结果,且不会重复提交有副作用的操作。

P3 — 小模型可靠性与开发工具

整合输出解析、自动修复和轻量上下文预算;增加实际调用测试、trace 与 marqdo view 中的模型决策展示。

验收:测试格式正确率、真实意图命中率、工具执行正确率和 Token 消耗,而不是只检查输出是否符合 JSON 格式。

这里还有一个建议:先挑选约 100~200 条实际意图、路由、人格切换、函数调用用例,使用目标 1B 小模型测试,再与当前的 agent.step 方式比较。重点测量每次决策输入 Token、输出 Token、有效选择率、修复轮数和最终任务成功率。并发部分还要独立测量吞吐量、等待时延和取消后的资源回收。

五、这次升级最关键的架构决定

我不建议立即修改 Marqdo 的 19 个核心语法构造。现有的 #、##、###、GFM 表格、描述链接、返回值和条件分支,已经足够表达智能体编排。

真正值得修改的是 Marqdo 的执行能力与开发体验:

层次 应承担的职责
Marqdo Language 函数、参数、分支、文档作用域
Marqdo AI Extension 上下文、模型推理、选择、解析
Marqdo Runtime 任务等待、恢复、并发、权限
.mq.md SKILL 当前任务的自然语言规则与少量可执行操作
qdagent 人格、交互界面、模型配置、用户数据

这也直接呼应了 Marqdo 仓库中 doc/next/012.md 提出的构想:code as document, document as skill, skill is tools。

我的核心建议是将此次升级首先锁定在 “函数级上下文投影 + 等待模型选择 + 原生用户暂停恢复” 这个最小闭环。

只要这三个能力完成,qdagent 的根 SKILL 就能够独立驱动一次真实的意图确认和递归路由。后续聊天、Office、代码开发、科研等 SKILL 都可以基于同样的简单函数组合构建。

这次改进的价值不在于 Marqdo 能支持多少种 Agent,而在于让一个很小的模型,只阅读几十行文档、输出几个字,就能够可靠地控制一个复杂的可执行系统。

一个智能体框架很重要的一点是错误处理和恢复上面展示的内容看上去确实不错但是错误处理和恢复这些写的不够好,我希望达成的目标是减少错误,这依靠框架本身,但是一旦出现无法避免的错误,请你给出框架应该怎么应对这些问题

我认为,Marqdo 的智能体框架应该把错误预防与自动恢复提升为 Runtime 的原生能力,而不是依靠每份 SKILL 自己编写重试逻辑,更不能依靠大模型不断阅读错误日志、重新思考和重新执行。

对于你希望使用的 1B 左右小模型,这一点尤其重要。

我建议确立一个核心原则:

能由编译器和运行时避免的错误,不交给模型;能由确定性程序恢复的错误,不重新调用模型;只有必须重新作出语义判断时,才让模型介入。

而且恢复必须满足三个条件:

  • 不重复做:已经成功的步骤不得因为后续失败而无故重新执行。
  • 不丢失结果:即使最终任务失败,也保留已经完成的工作与验证证据。
  • 不假装成功:无法确定执行结果时,明确标记为未知,而不是猜测成功或失败。

一、Marqdo 现有基础与真正的问题

我重新检查了 ext/ai/agent.mq.md。当前代码已经具备相当一部分可靠性基础:

现有能力 当前作用 仍需加强
error_make 构造结构化错误 统一所有 AI 调用与 SKILL 的错误出口
error_decide_retry 有界重试判断 自动选择具体恢复策略
resume_save/load 保存、恢复检查点 与函数执行位置、用户等待和子任务统一
effects_prepare/transition 记录副作用执行状态 在所有可能写入的操作前强制应用
effects_reconcile 对账不确定的执行结果 自动检测、恢复和阻断不安全的重复执行
subtask.spawn/wait/run_many 子任务和并发 失败隔离、部分成功与子任务恢复

此外,源码已经提供 checkpoint_v2 选项,但 resume_save 的默认值还是 False。而 run_tool 在缺失原生 Agent 插件时存在能力较弱的兼容执行路径。

这些说明 Marqdo 不需要再造一个恢复框架,但需要把分散的能力统一为可靠的默认执行语义,特别是消除容易绕过严格校验的路径。

我建议的总体执行模型

Marqdo SKILL 函数调用

执行前预检

类型 · 上下文 · 权限 · 预算 · 依赖版本

受控执行

模型调用 / 普通函数 / 子 SKILL / 并发

结果验证

格式、类型、业务条件、执行证据

成功提交

记录结果并继续

恢复控制器

分类、恢复或安全中止

这里的“恢复控制器”应是 Rust Runtime 的确定性机制,不是另一个依赖 LLM 的智能体。

它可以在必要时请求模型作出局部判断,但错误处理本身不能依赖模型是否足够聪明。

二、先预防:让错误尽可能无法进入执行阶段

对于 Marqdo,我建议设置四道防线,但全部由框架自动完成,不要求 SKILL 作者编写额外逻辑。

防线 框架自动完成 可以阻止的问题
编译前 检查函数签名、依赖、参数、类型 调用不存在的函数、参数错误
推理前 检查上下文范围、模型能力、Token 预算 上下文溢出、错误模型配置
执行前 校验模型输出、工具权限、资源版本 幻觉工具、非法路径、过期文件
提交前 验证返回值、操作结果和执行证据 错误结果被当作成功、重复写入

这里有两个关键设计。

首先,模型只产生候选值,不直接决定程序是否成功。例如要求模型选择 chat 或 office,框架在验证之后才允许结果进入路由函数。模型说“已执行成功”,也不能代替真实的执行回执。

其次,要把模型的不确定性限制在最小的函数范围内。一次 ai.choose 只需要理解当前函数及两个选项,不应该携带整个 qdagent 的执行历史。上下文不够时读取相关内容,而不是无条件扩充系统提示词。

这种设计降低的是错误发生概率,不保证模型的语义判断必然正确。语义正确性仍需要任务相关的验证或用户确认。

三、错误发生后,框架必须先分类,再采取不同动作

我不建议把所有错误交给一个通用 retry()。

因为“模型选项格式错误”和“文件写入后进程崩溃”,虽然都叫失败,但适合的处理方式完全不同。

下面是我建议的默认恢复策略。

错误情况 框架应该怎么做 是否重新调用模型
模型输出格式不正确 规范化、匹配合法值,必要时要求重新输出 最多一次
模型选择不在选项内 拒绝非法值,重新请求明确选择 必要时一次
上下文超过限制 删除冗余、提取相关函数、重新计算预算 通常不需要
模型请求超时、429 检查超时与限流,退避后重试 可以
模型返回错误事实 通过验证器识别问题,提供局部修正依据 可能需要
Marqdo 函数参数错误 根据已知契约检查并修正可确定的问题 通常不需要
SKILL 文件或函数不存在 重新解析注册目录;不存在则终止 不应盲目重试
权限不足、凭证失效 保存现场,要求用户或管理员处理 不需要
文件版本冲突 重新读取最新版本,重新计算变更 可能需要
子智能体执行失败 保留其他成功结果,仅处理失败子任务 视情况
写入结果不确定 查询外部结果和效应账本,不得直接重做 不应重新决策
运行时崩溃 恢复检查点,检查未完成操作后继续 通常不需要

默认恢复应该有预算,例如传输请求总共最多三次尝试、输出修复一次、代码局部修复一至两次。这些属于初始策略参数,不应该变成语言硬编码的限制。

同时必须识别重复失败循环:如果同一个输入、同一个错误、同一个版本连续失败两次,且没有新证据,自动终止该恢复路径,避免小模型陷入无限生成。

恢复策略应当分层

L0 · Runtime 自行修复

无需 LLM

清理格式、重新获取连接、读取检查点、重建缓存、解析已知选项

L1 · 确定性替代路径

已注册的备用工具、已有知识命中、只读降级、可验证的本地计算

L2 · 小模型局部修复

只给模型失败字段、允许选项和必要证据,不再发送全部上下文

L3 · 安全停止与交接

保存成功进度,报告错误、未决操作和能够安全继续的入口

L0 到 L2 只在恢复动作被验证为安全、且仍有预算时继续;不可逆写入、权限拒绝等错误可能直接进入 L3。不能把这套层级理解为所有错误都要逐层尝试。

这是最适合小模型的重要改进之一:大部分错误不应该消耗额外的推理 Token。

四、真正困难的部分:如何做到失败后继续,而不是重新运行

这是我认为整个框架最值得投入研发资源的部分。

假设一份 Marqdo 文档依次完成:

读取用户输入

已完成

分析与确认意图

已完成

进入 Office SKILL

已完成

生成演示文稿

执行中断

交付结果

尚未执行

此时的正确恢复方式,不是重新运行 # main,更不是重新询问用户意图。

而是从“生成演示文稿”的可恢复边界继续执行,并复用之前的意图确认结果。

关键机制:函数级 Checkpoint + 执行日志

现有 CheckpointV2 已经提供良好的基础,但建议将它从 Agent 的可选机制进一步发展为支持暂停的 Marqdo 执行会话的默认机制。

每个可恢复边界记录这些信息:

信息 作用
run_id / step_id 明确是哪次执行、哪一步
文档与函数 digest 确保恢复的还是原始逻辑
参数、局部变量或结果引用 保留后续执行需要的数据
已完成步骤记录 跳过已经成功的操作
当前等待原因 等用户、等模型、等子任务或需要对账
副作用账本位置 判断写入是否发生
权限、资源版本和剩余预算 防止旧状态绕过新限制

在实现上,我倾向优先采用语句/函数边界的持久化续体(continuation),而不是一开始就尝试保存任意 Rust 调用栈。

如果当前解释器无法序列化整个运行帧,可以先从已提交的步骤边界恢复,再通过执行日志复用此前的结果。这要求可重放部分具有确定性,所有外部效应都由账本管理。

特别注意:ai.input 等待用户时,应提交暂停状态、释放执行资源。用户恢复时必须匹配原来的 run_id、输入请求 ID 和文档版本,不能把回复当作新的根任务重复执行。

类似的恢复问题在其他框架中也存在。例如 LangGraph 的部分中断机制会在恢复时重新执行节点,所以特别要求中断前的副作用具备幂等性。Marqdo 可以争取在语句/函数粒度提供更直观的恢复语义。

image

GitHub+1

五、最不能出错的地方:副作用执行后崩溃

考虑这样一个场景:

智能体调用“发送邮件”,邮件已经成功发出,但进程在收到确认结果之前崩溃。

如果框架简单重试,就可能把同一封邮件发送两次。

这个问题无法只靠模型解决。

我建议将 Marqdo 已有的 EffectLedger 变成所有带副作用工具的强制执行路径:

prepared · 记录执行意图与幂等标识

started · 开始真实操作

committed

有成功回执,允许复用结果

unknown

先对账,不自动重做

其处理应当遵循:

状态 恢复行为
prepared 尚未开始真实效应且有可信证据时,可以开始
started 如果执行中断,先调查,不能推断未生效
committed 直接复用已保存的成功结果
failed_no_effect 确认无效应后,才根据策略决定重试
unknown 查询外部资源、回执、版本;无法确认就阻断
reconciled_* 使用对账后的事实决定是否继续

对接外部工具时,应提供可选的 reconcile 查询能力。外部系统支持幂等键就使用稳定幂等键,不支持则尽可能使用状态查询与版本校验。

对于已执行的动作,如果存在业务上明确、安全的逆操作,可以进行补偿;但不能把补偿等同于数据库事务回滚。

这一点与 Temporal 的可靠任务设计原则一致:外部操作可能在完成后、记录结果前失去连接,所以必须单独处理幂等性和不确定状态。

image

GitHub+1

Marqdo 不能承诺所有外部操作都严格只执行一次;它应承诺绝不在结果未知时盲目重试不可逆操作。

六、多智能体错误:允许局部失败,不让整个任务雪崩

将来支持 ai.parallel 后,可能出现三个子智能体同时工作,其中一个失败。

我建议父智能体按照任务依赖与结果完整性决定下一步,而不是默认重新启动全部子任务。

子任务状态 父级处理
成功 缓存结果和验证状态
暂时性错误 仅安全重试该子任务
无法恢复 标记失败并保留错误证据
需要用户输入 保存该分支的等待状态
已取消 不再自动重启
写入状态未知 阻断依赖这一写入的后续动作

例如三个子 SKILL 分别负责资料检索、方案分析和风险评估。当资料检索失败时,已经完成的风险评估不应该无条件被抛弃。

如果任务要求三份结果必须齐全,父函数进入 partial 或 blocked;如果允许部分交付,则可以返回两份成功结果,但必须标注缺失项。

并发管理还要处理取消传播:父级取消时停止新任务,通知运行中的子任务,并等待它们清理;已经发生的外部副作用不能假定被撤销。

七、让恢复不破坏极短 SKILL 范式

你的根 SKILL 仍然只应有两个函数。

例如未来可以继续这样编写(下面的 ai.choose 是拟议接口):


## 路由函数

根据`用户意图`选择下一层 SKILL。

**目标 = [选择合适的技能](ai.choose(input=`用户意图`, options=["chat", "office"]))**

返回*目标*。

注意,这段函数完全没有重试逻辑、异常捕获或状态维护。

模型正常时,ai.choose 返回一个短字符串;框架校验成功后,路由函数 正常返回。

模型异常时,由 Runtime 根据错误类别处理。必要时暂停整个可恢复执行会话。对调用方暴露统一的执行结果,而不是要求模型理解复杂的恢复协议。

建议的结果结构可以简化为:


{
  "status": "waiting_input",
  "value": null,
  "error": {
    "code": "model.invalid_choice",
    "stage": "路由函数"
  },
  "resume_id": "run-42",
  "recovery": "ask_user"
}

这是运行时的结果信封,不是让小模型生成的 JSON。正常成功时作者仍然得到原本的 Marqdo 返回值。

状态建议至少区分 succeeded、partial、waiting_input、blocked、uncertain、failed 和 cancelled。

这里 uncertain 特别重要:它表示外部执行结果尚未确认,不能简单归类为失败。

如果错误被框架自动恢复,SKILL 不需要知道细节。只有恢复耗尽、需要外部输入,或者作者显式要求检查错误时,才将结构化诊断提供给上层。

同时保留原始错误、每次尝试、模型用量和恢复动作的执行记录,供 marqdo view 和 debug 检查。

八、具体应该修改哪些代码

我建议在现有能力上进行增量重构。

优先级 修改位置 主要工作
P0 plugins/agent/src/error.rs 建立统一错误分类、恢复动作和策略预算
P0 plugins/agent/src/tools.rs 强制校验和授权,不允许插件缺失时静默降低安全保证
P0 ext/ai/llm.mq.md 统一模型超时、格式错误与结果验证出口
P1 plugins/agent/src/resume.rs 让 CheckpointV2 成为可恢复会话默认格式
P1 src/runtime/ 实现等待输入、步骤恢复、取消与恢复调度
P1 plugins/agent/src/effects.rs 将效应账本强制接入受控写工具
P2 lib/subtask.mq.md 增强子任务部分成功、取消和结果恢复
P2 ext/ai/flow.mq.md(新) 提供简洁的 ask/choose/input/enter/parallel 门面

我特别建议先检查 error.rs 中当前根据错误代码字符串推断类别的路径。作为兼容机制可以保留,但核心调用应该直接从 LLM Adapter、工具执行器、解释器获得结构化错误码,而不是靠字符串包含 timeout、connect 等词来识别。

另外,生产模式下不能让缺失原生 Agent 插件的情况退化成一个不具备同等效应和权限保证的执行路径。只读实验可以降级,涉及写入的生产调用必须显式拒绝。

最重要的验收测试

可靠性验收清单

0/8 已确认

模型输出错误

只在允许范围内修复,不路由到错误 SKILL

429 / 网络中断

有界退避,正确计算模型调用和成本

意图确认后崩溃

恢复后不再次询问同一轮意图

外部写入后崩溃

不重复执行,先查询真实效应

三个子智能体中一个失败

保留另外两个成功结果

SKILL 源码被修改

检测版本变化,不静默恢复旧步骤

权限被撤销

立即阻断,不利用旧检查点继续

恢复失败或预算耗尽

返回部分结果和可操作的失败信息

重置检查

这些测试应使用确定性假模型、假工具和故障注入完成,不能只依赖线上模型的偶然成功。特别要测试进程在每一个关键提交点前后崩溃的情况。

九、最终我希望 Marqdo 达到的标准

我认为这次优化的成功,不应该用“重试后最终完成的任务数量”来单独衡量。

还应该关注首次执行成功率、自动恢复成功率、恢复额外 Token、重复副作用次数、恢复时延和人工介入率。

其中最重要的是:

可自动避免的错误越来越少发生;发生错误时只重做必要的部分;无法安全恢复时保留全部可用成果,并明确告诉用户原因。

更进一步,我认为 Marqdo 可以把经过验证的失败恢复方案沉淀成可执行知识。比如某个 SKILL 遇到特定格式错误后成功使用了一个确定性修复函数,系统可以将这一规则作为候选知识,在验证和批准后复用。下次遇到相同情况,甚至不需要再次调用模型。

这将形成一个很有价值的闭环:

执行 → 错误 → 恢复 → 验证 → 知识沉淀 → 下次预防。

它与传统框架只强调容错重试的方向相比,更符合 Marqdo 的核心理念:文档不仅描述智能体该怎么做,还能逐渐沉淀成经过验证、可直接执行的处理能力。

我建议把这次框架升级的第一阶段明确收敛为 “统一错误信封 + 自动恢复策略 + CheckpointV2 默认化 + 安全副作用账本”。这四项比立即增加更多模型控制函数更优先,因为它们决定了后续所有简短 SKILL 能否真正可靠地运行。