- 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。
70 lines
3.4 KiB
Markdown
Executable File
70 lines
3.4 KiB
Markdown
Executable File
# 标准库 / 扩展库:代码即文档
|
|
|
|
当前可执行开发规范见[库开发指南](../library-development.mq.md),其中的真实函数示范叙述内赋值、遮蔽调用、表格数据与返回。本页保留设计背景与历史波次。
|
|
|
|
| | |
|
|
|---|---|
|
|
| 状态 | **Active** |
|
|
| 日期 | 2026-09-14 |
|
|
| 相关 | [code-as-docs-gaps.md](code-as-docs-gaps.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [stdlib.md](stdlib.md) · [marqdo-dev skill](../../.cursor/skills/marqdo-dev/SKILL.md) · [roadmap](../roadmap/lib-ext-code-as-docs.md) |
|
|
|
|
---
|
|
|
|
## 1. 目标
|
|
|
|
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库用充分且具体的叙述解释短实现;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
|
|
|
## 2. 单文件标准库模板
|
|
|
|
标准库通常是一个 `lib/*.mq.md` 文件,源码自身承担使用手册、开发说明与 SKILL。
|
|
直接阅读、导入或调用此文件,不增加强制 `index.mq.md` 或平行模块手册。
|
|
多文件拓展库才用 `index.mq.md` 组织模块与开发路线。
|
|
|
|
每个函数依次提供:标题、参数表(名称、类型、默认值、含义)、返回契约、效应说明、
|
|
叙述形参、用途与真实调用例子、简短实现。无参数函数直接放返回表。
|
|
参数和返回契约位于第一条执行语句之前;标准库不再保留旧 `+` 形参清单。
|
|
|
|
叙述形参使用正文中的反引号名称,默认值紧跟等号;表格说明与实际默认值必须一致。
|
|
例如正文写「输入路径 `path`」,调用时即可提供 path。含标点的文本默认值使用完整引号。
|
|
不透明类型保留渐进式 any,并说明其产生途径和限制。
|
|
|
|
## 3. 可读性与调用规范
|
|
|
|
每个函数单元的叙述比例必须超过 50%,同时说明真实用途和边界;不能靠重复套话凑比例。
|
|
参数和返回契约表属于文档面,绑定的数据表仍须表达真实数据。
|
|
|
|
宿主等不透明调用用遮蔽语法表达动作:`[]` 写做什么,`()` 写实际执行代码。
|
|
返回和赋值仍遵循原有标记;标签不执行,也不替代失败处理。
|
|
|
|
```markdown
|
|
## read_text
|
|
|
|
| 参数 | 类型 | 默认 | 说明 |
|
|
|---|---|---|---|
|
|
| path | text | 必填 | 授权根目录内的文件路径 |
|
|
|
|
| 返回 | 类型 | 说明 |
|
|
|---|---|---|
|
|
| result | text | UTF-8 文本;无效编码或读取失败产生诊断 |
|
|
|
|
输入路径 `path`。此操作读取整个文件;大文件应改用分块读取。
|
|
文件根目录由调用方授权,不能通过传入路径绕过权限。
|
|
|
|
读取完成后,我们返回*[读取授权范围内的 UTF-8 文本](> host_read_text path=`path`)*,供调用方继续处理。
|
|
```
|
|
|
|
集合读取使用 access(collection, key),不使用旧链接取元;循环使用显式遍历。
|
|
用 GFM 表和具名助手表达结构化数据,避免 json.set/json.append 链。
|
|
说明中的调用示例放在未绑定代码围栏内,不能让示例意外成为函数执行步骤。
|
|
中英文源码保持语义、默认值与行为一致;检查叙述比例、契约并执行真实示例。
|
|
|
|
## 4. 波次
|
|
|
|
见 [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md):先稳定调用表面,再 M1 试点 table/text/json,其后批次 lib → ext。
|
|
|
|
## 5. 修订历史
|
|
|
|
| 日期 | 说明 |
|
|
|------|------|
|
|
| 2026-09-14 | 初稿(随括号调用落地) |
|