Files
marqdo/doc/library-development.mq.md
T

18 KiB
Raw Blame History

markup, title, description, import
markup title description import
occlusion Marqdo 编程规范:源码即手册,手册即 SKILL,函数即工具 标准库与拓展库的叙述式开发规范,包含可以直接调用的真实示例。
文件
lib/文件.mq.md

库开发指南:让说明、调用和实现长在同一份源码里。

本文件供人和 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。 失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。