The same page is the document, the knowledge and the program. marqdo call runs that function with arguments, so reuse, tools and tests do not need a second skill system. Co-authored-by: Cursor <cursoragent@cursor.com>
249 lines
8.3 KiB
Markdown
249 lines
8.3 KiB
Markdown
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 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。 |