- 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。
18 KiB
Executable File
markup, title, description, import
| markup | title | description | import | ||
|---|---|---|---|---|---|
| occlusion | Marqdo 编程规范:源码即手册,手册即 SKILL,函数即工具 | 标准库与拓展库的叙述式开发规范,包含可以直接调用的真实示例。 |
|
库开发指南:让说明、调用和实现长在同一份源码里。
本文件供人和 AI 编写 Marqdo 程序、标准库、拓展库以及可执行 SKILL 时直接阅读。目标是把库文件交给一个没有读过 完整语法手册的模型,它仍能判断何时使用、提供哪些输入、如何调用、如何消费结果, 以及遇到失败时怎么办。完成这些任务所需的信息必须在库文件中,不依赖聊天历史、 隐藏提示词、另一份签名清单或模型猜测。修改实现所需的最少标记也在本文就地示范。
这份指南本身可以执行。下方三个函数分别演示句中计算、结构化数据和可恢复文件读取; 它们返回真实结果,不返回“已遵守规范”之类的固定通过标志。直接使用的命令为:
marqdo call doc/library-development.mq.md 计算金额 单价=12 数量=3 --json
marqdo call doc/library-development.mq.md 形成订单摘要 '商品="笔记本"' 单价=12 数量=3 --json
marqdo call doc/library-development.mq.md 尝试读取正文 '路径="doc/library-development.mq.md"' --effects fs.read --fs-root . --json
第一条返回 36,第二条返回商品为笔记本、数量为 3、金额为 36 的记录。 第三条返回包含本文源码的成功结果记录。需要读写权限的工具必须给出授权命令及路径基准; 纯计算不要求插件、网络或文件授权。读到一个工具时,读者应该能直接复制其真实命令。
一、先确定文件承担的任务。
标准库通常是一份 lib/名称.mq.md:这个单文件本身就是手册和 SKILL,直接导入或调用。 不要为了文档另造一个 index、目录包装函数或同名模块手册。文件开头写清用途、适用范围、 输入来源、权限、运行环境、共享数据形态和一个真实工作流;每个函数再就地说明自己的契约。
拓展库需要多个文件时,以 index.mq.md 为入口组织工程。入口要说明先读什么、任务在哪个 模块、依赖怎样安装或准备、有哪些可运行流程,以及新能力应该加在哪里。 子目录有独立职责和多个文件时,也用自己的 index.mq.md 收拢接口与开发路线; 叶子只有一个文件时直接使用该文件,不为空目录层级继续增加入口。 中文镜像遵守已有命名约定,并说明其与英文模块的对应关系。
下面只是目录组织示意,不是已经存在、可以直接调用的拓展包:
ext/sample/
index.mq.md 任务导航、安装和权限、主流程、公开门面、开发路线
core.mq.md 单一职责的纯计算;本文件自身就是手册
parse/
index.mq.md 解析任务入口,组合本目录的格式能力
markdown.mq.md Markdown 叶子能力,保留可独立调用的契约
csv.mq.md CSV 叶子能力
examples/
workflow.mq.md 使用公开 API 的完整业务流程
tests/
acceptance.mq.md 工程自有的可执行验收场景
入口沿用公开能力进行组合,避免复制一份底层实现。索引中的路径和命令必须可用, 还要说明输入与产物怎样跨步骤传递,而不只是列文件名。工具 schema、签名和效应由现有 编译器、call、catalog、MLSP 从源码投影,不另建一套由作者同步维护的工具协议。 本指南也无需安装为另一套 SKILL 包;开发者或 AI 读这份源码即可使用其中的规范与示例。
二、标题下面立即交代参数与返回。
普通网页正文、内容叶子与静态文档可以继续使用内容标题;它们没有调用契约,不能为了 满足函数格式而插入虚假的参数或返回值表。需要执行任务的 SKILL 应把操作写入 mq.md, SKILL.md 只保留发现入口、适用范围和必要约束,避免两份独立维护的长命令清单。
每个真正可调用的函数使用函数标题。紧接标题先写参数表,再写返回表;没有参数时直接 放返回表。表格必须位于第一条执行语句之前。正文中的普通小节使用说明段和分隔线, 不要把“安装说明”“注意事项”等叙述标题误做成空函数。
参数表逐项写名称、类型、默认值和含义。含义应包含输入来源、数据形态、单位、索引基数、 是否允许为空及必要限制,而非“运行时参数”或把参数名复述一次。返回表写实际值的类型、 字段和含义,指出是新集合、文件路径、句柄、普通值还是可恢复结果,并说明失败出口。 正文进一步解释这些约束的原因与处理方式,不能把关键边界埋到另一个文件才找得到。
新库用正文中的叙述形参,不保留旧的加号形参清单。参数表提供类型契约和说明, 不是另一套参数声明器:名称、顺序和默认值要与正文和实际实现一致。 有默认值的形参在正文首次声明时紧跟等号,文本默认值加完整引号;无默认值的输入 必须由调用方提供。下面的真实函数展示完整排版,不需要先学另一份模板语法。
三、先把函数写成能读懂的文章,再让必要部分执行。
每个函数单元的叙述比例超过 50%,整份文件也保持说明充分。目的、适用条件、步骤之间 的因果、数据含义、返回去向和失败处理都属于有用叙述。不要用重复套话、巨型契约表、 无关背景或在文件头堆文章来掩盖某个函数仍然难读。短实现也需要说明为什么这样做。
检查按每个真实函数单元分别计算,契约表与说明文字属于叙述;绑定的数据表与代码围栏 属于实现。句中粗体、返回表达式和遮蔽圆括号中的代码仍计入代码,方括号中的动作说明 计入叙述。因此把整段代码搬进一句话,并不会把它全部变成说明文字。比例只是最低门槛, 还应逐段检查输入来源、分支理由、失败出口与可执行示例。
尽量让语句成为句子的组成部分。粗体标记执行赋值、调用或表达式;单斜体标记返回。 例如,下方计算金额函数在解释金额来源的句子中完成赋值,在交代用途的句子中返回结果。 先读句子能够理解意图,展开其中的精确表达式又能看清实际执行的代码。
使用当前已支持的句中返回写法:完成上述操作后,我们返回*结果*,供调用方继续使用。
其中“返回”直接引出单斜体。不要把粗体当作返回,也不要假定任意句中出现的单斜体强调
都会结束函数。返回立即结束当前函数;同一句后面的文字只能解释,不能安排后续执行动作。
讲解标记本身或展示尚不执行的示例时,使用行内代码或未绑定的代码围栏,避免意外执行。
确实需要单独成块的表格、分支和循环可以保留结构化排版。减少孤立代码的目的在于 保留可读因果,而不是把长循环硬塞到一句话里。每个结构块前说明判断或遍历的目的, 块内使用清楚的变量名与动作标签,块后说明产物;不要让读者靠追踪临时变量猜流程。
四、用遮蔽语法把意图和精确实现放在同一处。
方括号写“要做什么”,圆括号写实际代码。标签应解释领域动作、输入与结果之间的关系, 例如“按单价和购买数量计算金额”“在授权根目录读取 UTF-8 正文”,而不是“执行操作” 或原样复述宿主函数名。简单算术、取元、库调用和宿主调用都可以按需要使用这种写法。
下方函数会在叙述中执行赋值,赋值右侧用遮蔽表达式写出动作和实现。返回也可以直接 包住一个有说明的表达式;以下围栏只是排版示例,不会在阅读本指南时执行文件操作:
读取阶段先**正文 = [读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))**,得到后续使用的内容。
读取完成后,我们返回*正文*,供调用方继续处理。
如果不需要中间命名,也可以用下面的直接返回替代上面整个过程。二者是两种写法, 不是连续执行的两个读取步骤;不要为了叙述或展示再调用一次有副作用的能力。
读取阶段直接返回*[读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))*,把内容交给调用方。
执行位置很重要:普通正文中的链接样式是叙述引用或导航,单靠写出一个动作标签不会 自动执行它。需要执行的表达式应放在赋值、语句、返回等明确的执行位置; 不要用一个没有实现的空圆括号假装功能已完成。标签不参与参数求值,也不能证明实现 符合描述;修改标签或实现后仍要检查二者是否一致,并执行相关场景。
五、用表格表达结构,用模块表达职责。
静态记录、行列表、配置、命令和视图结构优先写成 GFM 表格。一列表达列表, 一行多列表达记录;多行多列默认是列式数据,要表达行记录列表时把首列写成 @。 调用产生的值先计算并命名,再在单元格中引用,不能假定表格里任意一段函数文本会执行。 普通值用列表和记录传递;读取集合使用 access,不能把描述标签误当作集合键。
命令参数也作为数据写入表格:"-p"、"--offline" 等文本必须带引号;
裸写 -p 会被当成表达式而不是命令选项。已计算的路径使用反引号引用变量,
不要再拼接整段 shell 源码。需要同时被 call 与 View 使用的过程用普通函数标题,
例如 ## main;# main 是对象入口,不能假定两者具有相同的调用语义。
整数除法会保留整数语义;计算平均值优先使用统计库的 mean,或明确采用浮点输入,
并在非整除样例中验证结果,避免演示数据恰好整除掩盖精度问题。
不可变更新要保存返回的新值。少量动态键用表库的具名助手;解析与序列化才使用 JSON。 不要用长串 json.set/json.append 来拼原本一张表就能读懂的数据,也不要为每个数字或 单个字段创建层层转发的空壳函数。只有当一段逻辑需要解释、复用或独立验证时才提取职责。
网页工程从最小布局拆分开始:首页拆为导航、主体、底部,底部再拆为品牌和链接双栏, 链接栏还可拆成文档与社区。一直拆到叶子内部能够用简单 Markdown 表达内容; 父模块负责导入、组合与布局,叶子负责内容。使用现有 web 的文档、组件与 View 表能力, 让结构与内容保持统一语言,避免大段原生 HTML/CSS、转义字符串和手写业务 JavaScript。
通用组合优先写在 mq 源码里。仅在 OS、算法或原生 ABI 边界加入小型宿主原语, 声明实际效应与资源限制;拓展库通过公开标准库或插件接口使用能力,不直接调用 host_*。 中英文镜像保持契约、默认值与行为一致。不要把未来规划写成当前已经可用的接口。
六、把运行边界和工程验收写在开发者找得到的位置。
实际开发也使用这些能力:读取、搜索、撰写和原子修订通过固有文件库完成;JSON、表格、 散列和网络读取优先组合标准库。不要为已有能力再生成 Python 或 shell 程序。缺少能力时, 把可复用的边界补成拓展插件,或者通过明确参数数组外联已有工具;决策、条件和重试仍在 mq.md 中表达。开发与发版入口分别位于 skills/marqdo-dev 和 skills/marqdo-release,操作用 marqdo call 执行。大段源码通过 --args-json 文件或标准输入传输,保留换行、引号和字面数据。 外部自动化可以加 --require-ok,让失败 Result 产生非零退出码,避免继续执行依赖步骤。
有副作用的能力写明授权、根目录、平台、超时、资源上限以及重试与清理责任。 返回可恢复结果时先检查其中的 ok,再读取 value 或 error;CLI 外层的 ok 只说明调用 是否完成,不替代函数结果、HTTP 状态或子进程退出码的判断。未知副作用不能声称为纯函数。 文件原子替换不等于多文件事务;条件写入也不等于无竞争的内核 CAS。
文件类示例使用明确的临时根目录,说明产物是否保留、失败是否留下临时文件、由谁清理。 需要插件、外部服务或凭据时写明前提,验收优先使用本地可控替身,不把线上写入作为 阅读文档的隐含步骤。维护原有库时保留既有调用语义,必要变更要说明迁移路径。
交付时至少检查四件事:首次读源码能否完成一次真实调用;契约和正文是否一致; 叙述是否超过半数且解释了真实行为;正常、边界、错误场景是否返回预期结果。 修改源码中的示例时同步执行它们;公共调用面需要兼顾 Tree 和 Bytecode。 检查叙述比例是可读性门槛,不是功能正确性的证明,更不能代替业务与失败场景。
本文件可用以下命令检查。第二条是仓库内的可执行指南验收,覆盖叙述内赋值、 默认参数、结构化返回以及可恢复读取;修改库时还应运行该库本身相关的回归。
marqdo call skills/marqdo-dev/index.mq.md check 'path="doc/library-development.mq.md"' --require-ok --effects plugin --fs-root . --json
marqdo call skills/marqdo-dev/index.mq.md test 'targets=["stdlib_tasks"]' 'filter="library_development_guide_examples_match_their_contracts"' --require-ok --effects plugin --fs-root . --json
现有能力可直接参考 文件库、表库、 量子工程入口和网页工程入口。 需要了解解析与语义的边界时再阅读文档原生开发指导。 以下是真实可调用的单文件示例,也是前面三个命令的实现。
计算金额
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 单价 | number | 必填 | 单件商品的金额;币种由调用方保持一致 |
| 数量 | number | 1 | 参与乘法的购买数量;调用方按业务规则校验其范围 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 结果 | number | 单价乘以数量的金额,不含税费、折扣或币种转换 |
输入单价为单价,购买数量数量=1,没有指定数量时按一件计算。
本示例只演示透明的乘法组合,不暗示商品有效、允许负数交易或具有货币精度保证;
需要货币精度时由领域库采用整数最小货币单位,并补充其单位和范围约束。
为得到这笔购买的基础金额,我们先结果 = [按单价和购买数量计算金额](单价 * 数量), 后续说明仍留在同一段落,使读者无需从一条孤立赋值反推它的业务目的。
完成上述计算后,我们返回结果,调用方可以继续计算税费、折扣或生成订单摘要。
形成订单摘要
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 商品 | text | 必填 | 调用方提供的商品显示名称;此函数不查商品库 |
| 单价 | number | 必填 | 与数量相乘的单件金额,币种与调用方约定 |
| 数量 | number | 1 | 购买数量,默认一件;业务校验由调用方完成 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 摘要 | map | 商品、数量、金额三个字段组成的新记录 |
本函数接收商品名商品、单件金额单价以及购买数量数量=1,
只生成供下一步展示或保存的数据,不会下单、扣款、写文件或访问外部服务。
因此调用者可以在纯计算权限下验证完整的数据组合过程。
我们复用同一文件的计算能力,先金额 = [计算本次购买的基础金额](计算金额(单价=单价, 数量=数量)),
避免在订单摘要中再维护一份乘法规则。接着将需要交给调用方的字段直接列成记录,
让阅读者能逐项看到商品名称、数量和金额从哪里来,而无需解码字典构造链。
摘要 =
| 商品 | 数量 | 金额 |
|---|---|---|
商品 |
数量 |
金额 |
表格中的反引号引用已经得到的值,未增加一层隐式求值。字段准备好后,我们返回摘要, 调用方可以把它交给其他库继续展示或序列化;本函数不会修改传入的值。
尝试读取正文
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | text | 必填 | 授权文件根目录内的 UTF-8 文件路径;不是相对本指南的导航链接 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 读取结果 | map | ok/value/error 记录;成功的 value 是正文,失败的 error 含 code/message/operation |
输入文件路径由调用者提供,执行时需要 fs.read,路径以 --fs-root 为基准;
省略根目录时采用被调用文件的目录。本函数复用文件库的有界读取,不能绕过根目录、
编码检查或资源上限。此例不执行读到的代码,也不从正文推断额外的文件访问权限。
为了让一次读取失败仍能作为数据交给下一步,我们先读取结果 = 在授权范围读取 UTF-8 正文并保留失败信息, 由公开文件库统一处理已定义的可恢复失败,而不是在此复制宿主 IO 或假造成功文本。
读取结束后,我们返回读取结果,调用者先检查记录中的 ok,再使用 value 或 error。 失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。