Files
marqdo/doc/next/010.md
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

21 KiB
Executable File
Raw Permalink Blame History

请你重新阅读marqdo的官方库,掌握marqdo的最新进度。在我对marqdo项目的仔细审视之下我发现有一点没有闭环,我终于找到了,考虑现在智能体开发最常用的SKILL,这是一个markdown文件写明了智能体该干什么,我想要更推荐一步,因为marqdo使用markdown语法,支持叙述和代码相互混合,这就使得marqdo满足这样一个条件,当分章节的SKILL撰写下来,只要经过调整就能成为一份marqdo代码其中包含若干函数,我打算开发新的CLI命令marqdo > 函数名 函数参数或者marqdo call 函数名 函数参数 此时SKILL的不同章节就变成了不同的函数,智能体就真正的成为了将知识复现的作用,这让代码即文档、文档即知识,知识即可执行推进了一步变成了知识即工具,真正发挥了marqdo的优势,同样这样的执行还以为着智能体能够自行改进SKILL并接受确定的问题后修改而不会出错,这让自我进化的智能体成为了具备理论支撑和清晰边界的可能

Marqdo 从“可执行知识”走向“知识即工具”:最新仓库审查与架构建议

我认为你这次找到了 Marqdo 一个非常重要、而且比单纯增加 marqdo call 命令更深层的突破口。

你实际上提出了一个新的统一关系:

SKILL 是人和 AI 都能阅读的操作知识;Marqdo 可以让其中具有确定性执行语义的章节,直接成为可调用的工具。

这样,Agent 的职责就有机会从“阅读说明、理解步骤、临时生成实现”,转向“定位已有能力、填入参数、执行和验证结果”。

这与 Marqdo 原来的三句话是连续的,不需要推翻原来的定位:

代码即文档 → 文档即知识库 → 知识即可执行 → 知识即可作为工具使用。

不过我建议把“知识即工具”视为可执行知识的对外使用形态,而不是再创造一套与语言、知识库平行的 Skill 运行系统。

一、重新检查仓库后的最新情况

本次核对的是 cflmy/marqdo 的 main 分支,HEAD 为 4018e992,Cargo.toml 版本为 2.1.5。最近的 v2.1.5 版本记录日期是 2026 年 10 月 27 日。

与我们之前讨论 v2.0.0 时相比,项目已经完成了不少与你的构想直接相关的基础建设。

相关能力 最新仓库证据 判断
跨文档确定性函数绑定 BoundCall、SymbolId,Tree/Bytecode 双后端测试 已有核心基础
已编译知识的执行复用 MLSP artifact.bind、artifact.execute、artifact.reuse_execute 已有子集
Agent 复用已有函数 agent_eng_bind_execute、发布门禁 已有子集
指定函数执行 marqdo run --call-lib-path、JSON 参数、隔离 worker 已有底层入口
智能体工具规范 ToolSpecV1、效应分类、权限检查与恢复设计 已有框架基础
章节式 SKILL 自动成为 CLI 工具 目前没有独立的 marqdo call 或 Skill 编译命令 待开发
SKILL 自修改、自动测试和受控发布 已有局部修改、验证与沙盒组件 尚未形成完整闭环

因此,现在不是重新开发一个 Skill 执行器,而是将已存在的 Marqdo 函数、知识制品、工具协议和 Agent 机制统一起来。

还有一个与你的新构想直接相关的问题值得先修复:

最新官方 skills/marqdo/SKILL.md 的核心语法说明,与仓库中的现行解析器、v0.3 语法规范和可执行测试存在冲突。

目前解析器与测试使用的是:

  • **…**:代码、赋值、调用等语句;
  • *…*:返回值。

但官方 Skill 顶部却把两者反过来描述。这不是小的文档笔误:如果 Agent 按照错误规则自我修改 Skill,就可能产生与实际运行时不一致的程序。

这个真实存在的不一致,恰好证明了你所说的闭环为什么重要——SKILL 不能仅靠自然语言说明自己的正确性,它需要由语言编译器和实际测试提供独立验证。

二、你真正提出的是一种新的 Skill 体系

我建议把它暂时命名为 Executable Skill(可执行技能)。

它不应被理解为“给 Markdown Skill 增加一点代码”,而应当满足一个更严格的定义:

Executable Skill 是一份以 Markdown 为人类可读接口、以 Marqdo 函数为确定性执行单元、以编译后的语义制品为工具身份、能够由 Agent 发现、调用、验证和改进的技能文档。

传统 Skill 与你的目标之间,存在一个非常重要的区别。

维度 普通 Markdown Skill Marqdo Executable Skill
技能说明 自然语言 自然语言
操作步骤 Agent 阅读后自行实施 可以绑定已有 Marqdo 函数
函数接口 通常需要额外编写工具代码 从 .mq.md 的函数和契约生成
执行 依赖 Agent 选择工具、生成代码或操作软件 对已实现的步骤直接执行
输出验证 往往需要单独建立 可连接编译器、契约和测试
改进 编辑说明或脚本 编辑同源的知识与实现,验证后发布
可追踪性 主要依赖工具日志 可关联 SymbolId、源码、版本和执行结果

但不是每个 Skill 章节都应该自动变成可执行函数。

比如“适用场景”“注意事项”“禁止操作”是知识或约束;“检查订单”“生成报价”“汇总报告”才可能成为可调用能力。编译器应区分文档章节与可执行章节,不能把所有二级标题不加判断地暴露成工具。

这实际上使 Agent 的结构发生变化

SKILL.md

目标 · 流程 · 函数 · 契约 · 示例 · 约束

Marqdo Skill Compiler

章节解析 · 符号绑定 · 类型检查 · 效应分析

Knowledge View

Agent 阅读技能与限制

Tool Registry

Agent 调用已编译函数

Agent:选择、组合、执行、观察与改进

由语言运行时执行确定性部分,由模型处理非确定性判断

特别值得注意的是:这不仅是执行接口的统一,还是知识交付接口的统一。

同一份 Skill 能够投影成可读说明、CLI 函数、Agent Tool Schema、MCP 工具描述,以及知识库中的能力节点。实现这些投影的系统仍是同一个 Marqdo 编译器。

三、CLI 应采用 marqdo call,不要采用 marqdo >

你提出了两个命令形式:

marqdo > 函数名 函数参数
marqdo call 函数名 函数参数

我明确建议采用第二种。

原因是 > 在 Bash、PowerShell、CMD 等 Shell 中已经具有输出重定向语义。marqdo > xxx 会被 Shell 先行解释,无法可靠地作为传递给 Marqdo 的函数调用语法。

推荐设计为:

# 按函数名调用
marqdo call "订单计算.商品小计" \
  --skill ./skills/order-calculator \
  --arg 单价=30 \
  --arg 数量=2

# 结构化调用,供 Agent 使用
marqdo call "订单计算.商品小计" \
  --skill ./skills/order-calculator \
  --args-json inputs.json \
  --output json \
  --policy pure

上述是建议新增的 CLI 接口,不是 v2.1.5 已支持的命令。

我还建议在 CLI 层保留一个便利别名:marqdo skill call。它与 marqdo call 进入同一个 dispatcher,不应分别实现两套调用逻辑。

最小必要的 CLI 能力

命令 作用
marqdo skill inspect PATH 解析 Skill 文档、章节、可调用函数和依赖
marqdo skill list PATH 列出对 Agent 暴露的工具
marqdo skill check PATH 检查语法、绑定、签名、效应和工具导出规则
marqdo call TARGET 调用指定 Marqdo 函数并返回结果
marqdo skill test PATH 执行 Skill 的测试与契约检查
marqdo skill export PATH 生成通用工具描述或 MCP 暴露接口
marqdo skill trial PATH 对修改后的候选版本进行隔离验证
marqdo skill promote PATH 在门禁通过后发布新版本
marqdo skill rollback PATH 恢复到指定已接受版本

不过不建议一次性实现这九项命令。最小可用产品只需要 inspect、call、check、test 四项,版本发布与改进机制可以随后补齐。

最重要的技术决策是:

marqdo call 必须调用现有编译器绑定的函数,不得重新用字符串搜索源码、猜测章节位置再执行。

当前 src/mlsp.rs 已有 artifact.bind 与 artifact.execute,能够检查制品指纹、依赖闭包、来源摘要和效应策略。新的 CLI 应复用相同的应用服务和语义校验,而不是通过进程内调用 MLSP JSON 接口制造另一层重复协议。

还有一个现有实现细节:marqdo run --call-lib-path 已支持隔离 worker 通过 JSON 参数调用函数,但当前 src/lib.rs 的这个入口只在树遍历分支中处理,Bytecode 分支仍按普通程序入口执行。新的公开 call 命令需要补齐这一差异,或者明确在第一版只支持 Tree backend,不能静默忽略所选后端。

四、完整示例:让一份 Skill 同时成为文档、知识和工具

我建议第一版尽量保持作者体验简单:人只维护一份 Markdown 源文件,编译器自动生成工具描述、函数索引和知识制品。

例如,我们建立一个订单计算 Skill。

下面是目标设计示例。其中 runtime 和 tools 是我建议为 Skill 编译增加的元数据约定,目前不能将这份 SKILL.md 直接交给 v2.1.5 的 CLI,期待自动注册工具。


---
name: order-calculator
description: 订单价格计算,包括商品小计和含税金额
runtime: marqdo
tools:
  - 订单计算.商品小计
  - 订单计算.含税金额
---

# 订单计算

这份技能用于计算订单金额。

所有金额使用同一货币单位。税率使用小数表示,
例如 0.10 表示 10%。

## 商品小计

给定商品单价`单价`和购买数量`数量`,
计算未税商品小计。

*[商品小计](单价 * 数量)*

## 含税金额

给定商品单价`单价`、购买数量`数量`
和适用税率`税率`,计算含税金额。

**小计 = [计算商品小计](订单计算.商品小计(单价=单价, 数量=数量))**

*[最终含税金额](小计 * (1 + 税率))*

这里的计算是演示规则。正式业务技能还需要校验数量范围、金额精度、货币单位、税率适用条件与舍入规则;这些不能由函数名字自动推断为正确。

这份 Skill 会产生三种投影

给人阅读: 它是一份正常的 Markdown 文档。读者能理解每个步骤的目的,以及所需输入和返回值。

给 Marqdo 编译器: 两个 ## 单元构成可解析的函数;第二个函数可以确定性地调用第一个函数;符号索引能够记录它们的依赖关系。

给 Agent 使用: 编译器输出两个工具的结构化描述。Agent 不需要重新生成乘法计算程序,只需选择工具并提供参数。

例如,编译后的工具描述可以是:

{
  "id": "order-calculator::订单计算.商品小计",
  "description": "计算未税商品小计",
  "input_schema": {
    "type": "object",
    "properties": {
      "单价": {"type": "number"},
      "数量": {"type": "number"}
    },
    "required": ["单价", "数量"]
  },
  "output_schema": {
    "type": "number"
  },
  "effect": "pure"
}

但这个 Schema 必须由明确的类型契约和编译器检查生成。若源文件没有足够的类型信息,应标记为未知或要求补全,不能因为变量参加了乘法就无条件断言它一定是 number。

需要强调:不是 ## 标题自动等于一个公开工具。 ## 让章节具备 Marqdo 函数的结构,tools 则声明哪些函数允许对外暴露。这样才能避免“安全说明”一类章节被意外注册成工具,也避免内部辅助函数被 Agent 随意调用。

为什么采用显式的 runtime: marqdo?

因为普通 Skill 的 Markdown 本来就可能包含 **加粗内容**、编号列表、代码块和二级标题。这些在现有 Marqdo 中可能具有执行语义。

如果直接把所有 SKILL.md 当成 .mq.md 执行,很可能发生严重的语义误读。

所以我建议:

  • 未明确声明 Marqdo 运行时的 SKILL.md,仍然是普通 Markdown 文档。
  • 明确声明 runtime: marqdo 的 Skill 才进入 Marqdo 编译流程。
  • 内嵌示例代码块不应因展示而执行。
  • 编辑器应对具有执行意义的 Markdown 标记提供可视化提示。
  • 导出的工具必须经过独立检查和授权。

未来还可以支持从已有普通 Skill 中自动提取候选函数,但那应当是生成可审阅的转换补丁,而不是默认把自然语言步骤当成已经实现的代码。

五、这次最有价值的部分:自我改进的 Skill

你提出的第二层意义,我认为甚至比 marqdo call 更值得研究。

传统 Agent 修改一个 Skill 时,常见问题是:它修改了一段说明或脚本,却无法可靠判断其他步骤是否受到影响。

Marqdo 已经具备一些适合解决这个问题的基础,例如 SymbolId、依赖闭包、artifact.patch、artifact.verify 和知识影响分析。

但是,不能由此推出“智能体修改 Skill 就不会出错”。

更精确的目标是:智能体可以提出改进,系统能够判定一组明确、可测试的性质是否被保持,并且只有通过门禁的版本才有资格替换原有 Skill。

我建议采用以下演化协议:

已发布 Skill v1

现有稳定版本与完整依赖

1. 发现确定的问题

失败测试、诊断、复现步骤或用户提出的明确修改要求

2. AI 生成局部修改候选

只修改获准的章节或函数,记录版本与修改意图

3. 编译与静态验证

语法、符号、参数、返回类型、效应、依赖关系

4. 隔离测试与回归验证

目标问题修复、历史行为保持、异常输入、性能与权限边界

5. 发布门禁

仅当策略允许且必要验证通过时晋升新版本;否则保留旧版本

Skill v2 · 已接受版本

可追溯、可回滚、后续调用绑定到明确版本

举一个真正的自我改进案例

原 Skill 中存在:

## 商品小计

商品单价`单价`,购买数量`数量`。

*[小计](单价 * 数量)*

现在发现一个确定的问题:输入 数量=-1 时,函数返回负数,但业务要求数量必须大于零。

Agent 不应该只是把说明修改成“数量必须大于零”。这不会改变执行行为。

它应当在候选版本中增加可执行的校验逻辑,并补充至少三个测试:

测试 输入 期望
正常订单 单价 30,数量 2 返回 60
非法数量 单价 30,数量 -1 返回结构化参数错误
边界数量 单价 30,数量 0 根据业务契约决定接受或拒绝

如果 Marqdo 尚不具备合适的语言级错误返回或异常处理方式,这个案例还会暴露一个语言能力缺口:需要一种由 Marqdo 程序自身构造、传递和处理错误的机制,而不是只能依赖 Rust 宿主报错。

这与此前我们讨论的通用语言能力重构是直接关联的。

自我进化的边界必须比普通代码修改更严格

我建议把以下约束固定下来:

  1. 修改不能自动扩大权限。 原 Skill 只有纯计算权限,新版本不能因为 Agent 自己添加网络或文件操作就获得这些权限。
  2. 候选版不能直接覆盖运行中的正式版本。 需要隔离工作区、原子发布和固定引用版本。
  3. 必须证明目标问题被修复。 不允许通过删除测试、放宽断言或隐藏失败来宣称成功。
  4. 测试通过不是绝对正确的证明。 未覆盖的业务情况、外部事实和依赖服务仍可能出错。
  5. 高风险修改需要更严格的发布决策。 尤其是支付、外部写入、删除、凭证和安全策略变更,不能由被修改的 Skill 自己批准。

最新仓库的 artifact.patch 已经提供基于摘要的修改和有限回滚,但它还不是完整的候选版本事务与测试后晋升系统。现有 HostCaps 的默认值也允许文件写入、执行、网络和插件,因此新 call 的安全默认值应当收紧,不能简单继承普通本地运行的全部宿主权限。

这就是“有界自我进化”的含义:不保证 Agent 永不犯错,而是让它能够在可验证、可回滚、可限制权限的范围内持续改进。

六、我建议如何安排开发

阶段 目标 关键验收
S0 · Skill 语义一致性 修复官方 Skill 与解析器的标记冲突,建立 Skill 语法同步测试 Skill 记载的每条核心语法都有可运行金样例
S1 · 函数调用 CLI marqdo call 调用已绑定的普通函数、类函数和跨文档函数 JSON 参数正确绑定;错误路径和双后端行为明确
S2 · Skill 编译 对显式启用的 SKILL.md 解析章节和可执行函数 自动产生 SymbolId、签名、依赖、导出清单
S3 · 知识即工具 将公开函数编译为 ToolSpec,并接入现有 Agent dispatcher Agent 不重新生成实现即可调用并取得结果
S4 · Skill 测试 增加 skill check/test、负例、效应门禁和回归测试 未通过验证的 Skill 不得自动发布
S5 · Skill 演化 实现候选修改、隔离验证、影响分析、版本晋升与回滚 修改失败不影响已发布版本,权限不能自行扩大

这里还需要一项对你的研究目标尤其重要的对照实验。

让相同模型分别使用普通 Markdown Skill、Markdown Skill 加外部脚本工具、以及 Marqdo Executable Skill 完成相同的一组任务。分别测量正确率、模型需要重新生成的代码量、工具调用参数错误、修改后的回归失败率、token 消耗和完成时间。

只有与“Markdown + 现有工具调用”进行公平对照,才能证明 Marqdo 的优势来自文档、程序与知识的统一,而不只是因为它额外提供了一个执行器。

七、我对这项构想的最终评价

我认为这次构想具有三个非常值得肯定的性质。

第一,它有明确的语言基础。#、##、自然语言叙述、函数参数、[]()、契约表和跨文档符号绑定并不是为了 Skill 重新创造的。Skill 可以成为现有语言的一种应用形态。

第二,它有真实的工程基础。当前 Marqdo 已经具备部分确定性绑定、制品验证、Agent 复用与隔离运行能力。你需要做的是将这些能力收敛到统一的公开接口,而不是重新实现一套 Agent 框架。

第三,它能够引出一个更有研究价值的问题:自然语言描述的操作知识,如何逐步转化为可调用、可检查、可维护,并可由 Agent 在受限条件下自行改进的程序制品?

但是,“SKILL 章节即函数”本身还不足以证明新的编程范式。Markdown 章节映射函数,与文学编程、文档驱动工作流及现有工具包装有明显的共同点。

更有价值的是把三个原本需要单独维护的对象——Skill 说明、函数实现、Agent Tool Schema——统一为一个可编译的源事实,并展示这种统一确实降低了错误、维护成本和重复生成成本。

我建议为 Marqdo 保留原来的核心理念,并将这一阶段的技术方向明确为:

知识即工具(Knowledge as Tool):将可执行知识直接编译为 Agent 能够发现、调用和验证的工具,并允许智能体在明确的语义、测试和权限边界内持续改进这些知识。

这可能是 Marqdo 从“AI 可以使用的编程语言”,进一步走向“AI 能够使用并维护的可执行知识体系”的关键一步。

备注,这里实际上有一点叙述错误,marqdo支持mq.md文件,所以最好针对SKILL也是SKILL.mq.md这样会比较统一。