跳至主要內容

扩展包文档交付清单

mumu2026/7/20大约 5 分钟扩展包文档模板CIReference

扩展包文档交付清单

新增包不能只增加一页安装说明。以下清单用于保证首次使用、日常查阅、排障、维护和历史版本都有稳定入口。

页面集合

页面必须回答
快速入门安装哪个精确版本、最低环境、怎样完成固定自检和第一个业务闭环
说明书首页公共边界、导入方式、能力索引、状态模型、Reference 入口
能力页每个函数、类或重载族的参数、单位、默认值、结果、错误和示例
排障入口安装、配置、输入、环境与依赖失败怎样分层定位
安全/数据边界哪些输入敏感、数据来源多久更新、哪些结论不能保证
latest Reference当前主线源码生成的逐成员签名
版本 Reference与每个已发布制品版本对应的不可变快照

页面元数据模板

---
title: 页面标题
description: 一句话说明页面解决的问题，避免重复站点名称。
icon: code
order: 1
category:
  - 扩展包名称
tag:
  - 可检索关键词
---

每个页面正文只保留一个 H1。标题应描述用户任务，description 用于搜索摘要和 SEO，tag 使用用户可能搜索的包名、能力或协议词。

API 条目模板

每个公共函数、类、构造器或重载族至少说明：

  1. 完整公开签名和精确 Reference 链接。
  2. 适用场景与不适用场景。
  3. 参数名称、类型、必填性、默认值、单位和编码。
  4. 返回值及结果对象字段。
  5. 非法输入、业务失败、异常和资源关闭行为。
  6. 是否有状态、是否线程安全、能否复用、是否需要 reset 或 close。
  7. 安全、数据时效、平台和跨语言差异。
  8. 带中文注释、断言和预期结果的可执行代码。

同语义重载可以使用矩阵，但每个公开签名都必须出现在矩阵中。

导航与链接

  • 快速入门进入 /guide/ 侧栏。
  • 手写说明书进入 /api/<package-id>/ 独立侧栏。
  • 首页只展示已发布 catalog 条目。
  • 算法或能力总览链接到说明书具体页面，不只链接 latest。
  • 包 README 只保留摘要、最小示例和官网入口，不复制整套说明书。
  • 所有站内 Markdown 链接和原生 HTML href 都必须能够解析。

可执行示例

发布与历史版本

发布前同步更新制品版本、catalog/packages.json、变更记录、包 README 和站点入口。生成器应把当前签名写入 latest，并把与 tag 对应的内容保存到 /api/<package-id>/versions/<version>/。

不得用新版本覆盖历史目录；不得把 latest 链接描述成线上制品的固定 Reference。

本地验收

扩展应提供自己的定向测试命令，并最终执行：

npm run docs:verify

全量门禁应检查 catalog、说明书覆盖、页面元数据、导航、站内链接、锚点、可执行示例、latest 与版本 Reference。详细部署流程见文档构建与部署。