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>
374 lines
21 KiB
Markdown
374 lines
21 KiB
Markdown
请你重新阅读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](https://github.com/cflmy/marqdo?utm_source=chatgpt.com) 的 `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](https://github.com/cflmy/marqdo/blob/main/src/mlsp.rs?utm_source=chatgpt.com) 已有 `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这样会比较统一。 |