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

8.3 KiB
Executable File
Raw Permalink Blame History

SKILL的名称应该是.mq.md有一点必须提及,SKILL其实命名不一定必须得是SKILL,平常的一个marqdo文件也可以是一份skill这里的设计太复杂了没有抽离出来核心本质,你看对于一个平常的marqdo文件,完全也可以和SKILL一样,这都是没有区别的,所谓的知识即工具作为高度抽象本质就是带参数调用函数,所以你的inspect等等命令其实完全可以对传统的marqdo也生效而不是非要绑定SKILL对吧,而且这样处理还有好处是方面智能体做单元测试,单个函数是否可以带参数直接运行,换句话说,你仔细思考就会发现这些好处是marqdo的设计哲学在增加一点点call自然派生的优势,所以不需要繁复的设计

你说得对。这次我认为你抓住了真正的核心,而且我的上一版设计确实把一个本来很自然的语言能力复杂化了。

Marqdo 根本不需要引入一种叫作 Executable Skill 的新概念,也不需要专门建立 Skill 编译器。

因为在 Marqdo 的设计哲学下:

一个 .mq.md 文件本身就是文档、知识与程序。只要允许从外部直接调用其中的函数,它自然也就能够成为 Skill。

这不是为 Skill 开发一套新系统,而是为 Marqdo 补齐一个非常基础的语言使用入口。

一、真正缺少的只有一件事:函数级执行入口

Marqdo 当前已经支持函数定义、参数、返回值、模块引用,以及确定性符号绑定。

但是日常使用时,我们往往仍然站在“运行整个文件”的角度:

marqdo run example.mq.md

你现在提出的是:

marqdo call example.mq.md 函数名 参数

这实际上意味着:

Marqdo 的最小可执行单位,从文件进一步扩展为文件中的任意可调用函数。

而这一点会自然派生大量优势。

普通 .mq.md 文件

自然语言叙述 + 函数 + 参数 + 返回值

marqdo call

指定函数 + 绑定参数 + 直接执行

知识复用

调用已存在的实现

Agent Skill

直接暴露函数为工具

单元测试

逐个函数验证结果

自我改进

修改函数并重新测试

这里不存在四套实现,只有一个底层能力的四种使用方式。

二、一个普通的 Marqdo 文件就足够了

比如,文件 calculator.mq.md:

# 计算器

这是一个普通的 Marqdo 文档。

其中包含一些可以复用的数学计算知识。

## 加法

计算两个数字`a`和`b`的和。

*[计算结果](a + b)*

## 乘法

计算两个数字`a`和`b`的积。

*[计算结果](a * b)*

它既是可阅读的文档,也包含两个函数。

现在只需要支持:

marqdo call calculator.mq.md 计算器.加法 a=2 b=3

返回:

5

再比如:

marqdo call calculator.mq.md 计算器.乘法 a=4 b=6

返回:

24

以上 marqdo call 是拟新增的命令形式;函数示例遵循当前 *…* 返回、[]() 遮蔽的语义。

这时候,一个 Agent 只要能够读取这个 .mq.md 文档,就可以理解函数的用途;只要能够调用 Marqdo CLI,就能执行其中的能力。

它根本不需要关心这个文件是不是 Skill,也不需要一份特殊的 SKILL.md。

如果 Agent 把它当成 Skill 阅读和使用,它就是 Skill;如果开发者把它当成程序库调用,它就是程序库;如果研究者把它作为知识库中的一部分,它就是可执行知识。

文件的身份没有变化,变化的是使用方式。

三、这项能力会自然解决三个问题

1. 让知识成为工具

传统 Skill:

Agent 阅读操作说明,决定如何完成任务。

Marqdo:

Agent 阅读函数说明,找到适合的函数,传入参数,直接执行。

这就将原来的:

知识 → Agent 理解 → 重新实现 → 执行

缩短为:

知识 → 函数定位 → 参数调用 → 执行

但模型仍然需要负责判断应该调用哪个函数、传入哪些参数。确定性的是被调用函数的语言语义,而不是整个 Agent 决策过程。

2. 让单元测试成为语言的天然能力

我非常赞同你提到的单元测试价值。

有了 marqdo call,可以直接测试:

marqdo call calculator.mq.md 计算器.加法 a=2 b=3
# 期望 5

marqdo call calculator.mq.md 计算器.加法 a=-2 b=3
# 期望 1

marqdo call calculator.mq.md 计算器.乘法 a=0 b=100
# 期望 0

不必为了测试一个函数,再创建一个 # main,再编写调用、打印和结果检查的包装程序。

未来即使增加 marqdo test,底层仍然可以复用同一个函数调用接口。

3. 让 Agent 可以针对知识进行局部改进

这是你提出的最有意义的延伸。

假设一个 Agent 发现 计算器.乘法 对某类输入存在错误。

它可以:

  1. 阅读相应函数及其上下文。
  2. 修改这个 .mq.md 文件中的函数实现。
  3. 直接用 marqdo call 传入错误输入验证。
  4. 再运行该函数的历史测试。
  5. 如果检查通过,就提交候选修改;否则保留原有实现。

这使得 Agent 的改进对象不再仅仅是自然语言提示词,而是有明确输入、输出和可执行语义的知识单元。

当然,测试不能证明函数在所有输入上都正确;正式发布和权限控制仍需要遵循已有的项目验证机制。但不需要为此创造一套 Skill 专属的演化协议。

四、真正的 CLI 设计可以非常简单

我建议第一阶段只做一个命令:

marqdo call <文件> <函数> [具名参数...]

比如:

marqdo call book.mq.md 订单.计算总价 单价=30 数量=2

它只需要完成五件事:

步骤 职责
1 加载指定 .mq.md 文件及其导入
2 解析并唯一定位目标函数
3 根据现有函数签名绑定、校验参数
4 使用现有运行时执行该函数
5 返回函数结果和结构化错误

额外提供一个 --json 输出选项就足够方便 Agent 调用。

如果未来需要 marqdo inspect,它也应该针对任何 .mq.md 文件,列出其中函数、参数和文档描述,而非限定 Skill。

此外,当前仓库已经有 --call-lib-path 和 artifact.execute 的相关基础,因此实现时应尽量复用现有函数定位与执行机制,而不是重复开发解释器。

唯一值得坚持的边界是:外部调用仍必须经过现有权限检查,不能因为新增了 call 就默认允许 Agent 对任意函数执行文件删除、网络写入等操作。

五、我认为你的设计哲学现在更加清晰了

你原来的理念:

代码即文档,文档即知识库,知识即可执行。

实际上已经足够完整。

“知识即工具”不是额外的设计理念,而是“知识即可执行”在函数级调用能力成熟后自然出现的结果。

进一步看,这件事还有一个很漂亮的对称性:

参与者 对同一个 .mq.md 的使用方式
人类 阅读文档、理解知识
编译器 解析并验证函数
开发者 调用函数、组合程序
Agent 发现知识、调用工具
测试系统 输入参数、检查结果
维护者或 Agent 修改实现、验证改进

这些角色并没有要求作者维护六份不同的东西。

同一份文件,同一套语义,同一个函数调用接口。

这也恰恰是我认为 Marqdo 相比传统“Markdown 文档 + 外部工具”组合最值得证明的优势:知识描述与执行实现共址,而且能够直接由语言工具链消费,避免维护重复的工具包装和操作说明。

所以,我现在的建议与上一轮不同:

不要开发 Executable Skill 系统。不要设计 Skill 专属语法。不要引入新的 Skill 注册、编译和执行机制。

先完成 marqdo call,使普通 .mq.md 中的可调用函数都能被精确定位、传参执行,并用现有语义系统验证。

这是一个相对很小的接口变化,却可能自然打通 Marqdo 的编程、知识复用、Agent 工具调用和函数级测试四个场景。

我认为这才是你所说的:让 Marqdo 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。