请你重新阅读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这样会比较统一。