Files
marqdo/doc/design/lib-code-as-docs.md
T
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

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 | 初稿(随括号调用落地) |