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

249 lines
8.3 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。