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