Files
marqdo/doc/library-development.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

275 lines
18 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
markup: occlusion
title: Marqdo 编程规范:源码即手册,手册即 SKILL,函数即工具
description: 标准库与拓展库的叙述式开发规范,包含可以直接调用的真实示例。
import:
文件: lib/文件.mq.md
---
库开发指南:让说明、调用和实现长在同一份源码里。
本文件供人和 AI 编写 Marqdo 程序、标准库、拓展库以及可执行 SKILL 时直接阅读。目标是把库文件交给一个没有读过
完整语法手册的模型,它仍能判断何时使用、提供哪些输入、如何调用、如何消费结果,
以及遇到失败时怎么办。完成这些任务所需的信息必须在库文件中,不依赖聊天历史、
隐藏提示词、另一份签名清单或模型猜测。修改实现所需的最少标记也在本文就地示范。
这份指南本身可以执行。下方三个函数分别演示句中计算、结构化数据和可恢复文件读取;
它们返回真实结果,不返回“已遵守规范”之类的固定通过标志。直接使用的命令为:
```sh
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 收拢接口与开发路线;
叶子只有一个文件时直接使用该文件,不为空目录层级继续增加入口。
中文镜像遵守已有命名约定,并说明其与英文模块的对应关系。
下面只是目录组织示意,不是已经存在、可以直接调用的拓展包:
```text
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 正文”,而不是“执行操作”
或原样复述宿主函数名。简单算术、取元、库调用和宿主调用都可以按需要使用这种写法。
下方函数会在叙述中执行赋值,赋值右侧用遮蔽表达式写出动作和实现。返回也可以直接
包住一个有说明的表达式;以下围栏只是排版示例,不会在阅读本指南时执行文件操作:
```markdown
读取阶段先**正文 = [读取授权范围内的 UTF-8 文本](文件.读文本(路径=`路径`))**,得到后续使用的内容。
读取完成后,我们返回*正文*,供调用方继续处理。
```
如果不需要中间命名,也可以用下面的直接返回替代上面整个过程。二者是两种写法,
不是连续执行的两个读取步骤;不要为了叙述或展示再调用一次有副作用的能力。
```markdown
读取阶段直接返回*[读取授权范围内的 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。
检查叙述比例是可读性门槛,不是功能正确性的证明,更不能代替业务与失败场景。
本文件可用以下命令检查。第二条是仓库内的可执行指南验收,覆盖叙述内赋值、
默认参数、结构化返回以及可恢复读取;修改库时还应运行该库本身相关的回归。
```sh
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
```
现有能力可直接参考 [文件库](../lib/文件.mq.md)、[表库](../lib/表.mq.md)、
[量子工程入口](../ext/quantum/index.mq.md)和[网页工程入口](../ext/web/index.mq.md)。
需要了解解析与语义的边界时再阅读[文档原生开发指导](design/document-native-development-guide.md)。
以下是真实可调用的单文件示例,也是前面三个命令的实现。
## 计算金额
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 单价 | 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。
失败记录只说明这次操作没有成功;它不会捕获任意语言错误,也不会替调用者授予权限。