# 标准库 / 扩展库:代码即文档 当前可执行开发规范见[库开发指南](../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 | 初稿(随括号调用落地) |