- 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。
21 KiB
Executable File
请你重新阅读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 宿主报错。
这与此前我们讨论的通用语言能力重构是直接关联的。
自我进化的边界必须比普通代码修改更严格
我建议把以下约束固定下来:
- 修改不能自动扩大权限。 原 Skill 只有纯计算权限,新版本不能因为 Agent 自己添加网络或文件操作就获得这些权限。
- 候选版不能直接覆盖运行中的正式版本。 需要隔离工作区、原子发布和固定引用版本。
- 必须证明目标问题被修复。 不允许通过删除测试、放宽断言或隐藏失败来宣称成功。
- 测试通过不是绝对正确的证明。 未覆盖的业务情况、外部事实和依赖服务仍可能出错。
- 高风险修改需要更严格的发布决策。 尤其是支付、外部写入、删除、凭证和安全策略变更,不能由被修改的 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这样会比较统一。