Macro SDK 文档流水线:用 TypeDoc 从源码注释生成可校验、可部署的 SDK 参考文档

原创2026-10-31 09:06:041,847 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

Macro SDK 文档流水线:用 TypeDoc 从源码注释生成可校验、可部署的 SDK 参考文档

本文以仓库中 packages/sdk-docs/README.md 为主体,详解 Macro 公开 SDK 的文档生产机制:如何通过 TypeDoc 与 typedoc-plugin-markdown 从 SDK 源码的注释与类型声明中生成规范的 Markdown/HTML 参考文档,如何用 SHA-256 指纹校验防止“陈旧文档”混入 CI,以及最终如何以 Cloudflare Worker 静态资产的方式把文档站点发布到 sdk.macro.com。读完本文,你可以理解 Macro SDK 文档从源码注释到线上站点的完整链路,并掌握 bun run generate、bun run check:generated、bun run docs:deploy 等命令的适用场景与底层实现。

文档生产的核心原则:源码注释是唯一事实来源

sdk-docs 包确立的第一原则是:公开 SDK 的源码及其注释是唯一事实来源(source of truth)。文档站不是独立维护的一篇篇手写页面,而是由 TypeDoc 从 SDK 的 TypeScript 声明构建出单一反射模型(reflection model),再由 typedoc-plugin-markdown 从同一反射模型渲染出:

  • 一个规范的 Markdown 文档层次结构(checked in 到 reference/ 目录);
  • 一套 HTML 参考站点(构建产物,不入库)。

两种格式共享同一份链接模型,因此文档中的 API 请求/响应类型引用(例如方法签名里链接到 types.gen.ts 中的 wire 类型)在 HTML 和 Markdown 中都有效。渲染规则还包括:

  • 排除 private、protected 与 internal 成员,只保留公开契约;
  • 对象别名(object alias)声明会展开出具体字段,同时保留链接类型与属性描述;
  • 测试文件被排除在参考文档之外。

站点的落地页则是手写的 SDK guide:一段快速上手、一份用平实英文写的实体目录(entity directory),以及指向生成参考文档的链接。TypeDoc 会在 HTML 和 Markdown 两种输出中解析这些链接。维护分工因此很清晰:介绍性文字改 pages/home.md,API 文档改 SDK 源码注释(位于 packages/sdk)。

文档站入口:手写 guide 页与实体目录

pages/home.md 是站点首页的原始文稿,它同时也是生成后参考文档的 README.md(由 TypeDoc 的 readme 选项注入)。其核心内容构成读者进入 SDK 参考的主路径:

Quick start:安装 @macro-inc/sdk,在 Macro 的 Settings → API Keys 创建 API key,然后在环境变量中设置 MACRO_API_KEY,最小示例如下:

import { Macro } from '@macro-inc/sdk';

const macro = new Macro({});

// Find a document and read its text. Stop after the first match.
for await (const document of macro.documents.search('weekly update')) {
  console.log(await document.name());
  console.log(await document.content());
  break;
}

Find the right entity:把 SDK 的命名空间组织成实体目录,按“内容与工作 / 通信 / 人员与组织 / AI 与集成 / 自动化与资源管理”五组列出入口,例如:

入口 含义
macro.documents 工作区中的文档与文件,含内容、评论、共享与历史
macro.databases 表格化的结构化数据,含类型化句柄、SQL 查询、版本守护的原子写入与视图
macro.email 已连接邮箱、线程、邮件、草稿、附件与标签
macro.channels 共享会话,含消息、回复、线程与帖子
macro.crm 公司与联系人记录,含备注与关系
macro.agentSessions Agent 会话及其配置、消息、排队动作与执行状态
macro.events 应用可通过流式或 webhook 接收器订阅的实时实体事件

guide 中每个条目都写成 TypeDoc 链接语法 {@link src/entities/documents/namespace!DocumentNamespace | macro.documents},生成 Markdown 后会被解析为真实相对路径。可以对照 reference/README.md 中解析后的效果,例如 macro.documents 变成了指向 src/entities/documents/namespace/classes/DocumentNamespace.md 的链接——这正是 README 所说“TypeDoc 为 HTML 与 Markdown 两种输出解析链接”的直接体现。

guide 还解释了实体句柄(entity handles)的语义:macro.documents.byId(id) 只创建句柄而不发起请求;读取字段用 await document.name()、await document.content();相关对象(如 await document.owner() 返回的用户)本身也是句柄;列表与搜索返回异步迭代器,边迭代边拉页,独立读取可用 Promise.all 并发。这些约定是理解所有生成参考页的前提。

渲染管线:renderSdkDocs 与 TypeDoc 选项逐项解析

文档生成的实现集中在 src/render.ts,它导出唯一的公开入口 renderSdkDocs(root, output)。整个管线的关键点逐项对照源码说明:

1. 入口点选择(entryPoints)。生成范围覆盖:

  • packages/sdk/src/entities/**/*.ts(所有实体命名空间);
  • packages/sdk/generated/*/types.gen.ts(openapi-ts 生成的 wire 类型);
  • 以及一组核心模块:src/macro.ts、src/config.ts、src/mentions.ts、src/events/receiver.ts、src/utils/lazy.ts、src/utils/pagination.ts、src/utils/unwrap.ts。

随后用 !/\.(test|spec)\.ts$/ 和 /__tests__/ 过滤掉测试文件,与 TypeDoc 的 exclude 选项(**/*.test.ts、**/*.spec.ts、**/__tests__/**)双重保险,保证“测试文件不进入参考文档”。

2. 可见性与链接控制。excludePrivate、excludeProtected、excludeInternal 均开启,excludeExternals 排除外部库类型,disableSources 关闭源码折叠展示,gitRevision: 'main' 固定链接基准,includeVersion: false 隐藏版本徽标。

3. 双输出路由。outputs 同时声明 markdown 与 html 两个输出:Markdown 使用 router: 'member'(按成员组织目录),HTML 覆盖为 router: 'kind'(按类型组织,例如 classes/src_entities_workspace_namespace.WorkspaceNamespace.html)。两种路由的差异由 render.test.ts 中的断言同时覆盖。

4. 展开对象别名。expandObjects: true 使得对象别名声明展示具体字段而不是 = object,同时保留链接类型与属性描述。reference.test.ts 用生成物验证了这一点,例如 AgentSessionChangesPatchResponse 页必须以 > patch: string 形式的字段行开头,且包含“The git-style unified diff of the current changeset.”描述,而不允许出现 = object`` 的折叠形式。

5. 参数表格化。parametersFormat、interfacePropertiesFormat、classPropertiesFormat、typeAliasPropertiesFormat、typeDeclarationFormat 全部设为 table,让签名、参数与属性都以表格呈现,适合 LLM 与搜索引擎解析。

6. 同实例约束。文件头部注释说明了 src/render.ts 中最微妙的一处实现:工作区中还存在旧版 TypeDoc,而插件内部对反射对象做 instanceof 检查,因此 renderSdkDocs 通过 createRequire 先解析 typedoc-plugin-markdown,再解析插件自身的 peer 依赖 typedoc,保证插件与 TypeDoc 运行时是同一实例。AGENTS.md 也把“TypeDoc 与 Markdown 插件必须使用同一 TypeDoc 运行时实例、依赖变更后必须实测生成”列为 gotcha。

7. 输出目录卫生。cleanOutputDir: true 之外,代码在 app.convert() 成功后显式 rm 旧输出目录再 generateOutputs,并在 app.logger.hasErrors() 时直接抛错——注释指出这是为了“调用方永远不要消费上一次失败渲染残留的陈旧文件”。

reference/ 入库与陈旧文档检测

生成的 Markdown 参考文档以 reference/ 目录 checked in,这样任何 SDK 变更带来的文档变化都包含在 PR 里、可被 code review 审查;生成页面在 PR 中默认折叠(collapsed)。工作流是:编辑 SDK 源码注释或声明 → 运行 bun run generate → 提交重新生成的 reference。

三种运行模式由 scripts/generate.ts 区分,对应 package.json 中的脚本:

命令 脚本 行为
bun run generate bun scripts/generate.ts 渲染新输出,然后删除并复制 reference/(只有此模式重写入库文档)
bun run check:generated bun scripts/generate.ts --check 把新的 Markdown/HTML 渲染进被忽略的 dist/docs/,然后逐路径、逐字节比对 reference/;发现变更、新增或删除的页面即失败,不重写 reference
bun run build bun scripts/generate.ts --build 只产出被忽略的构建资产,不触碰 reference/
bun run test bun run check:generated && vitest run 先做陈旧检测,再跑公开契约测试,因此 CI 能捕获陈旧文档

陈旧检测的核心是 verifyReference(reference, generated):对两个目录分别计算指纹(fingerprint)——按排序后的相对路径与文件内容依次喂入 SHA-256,任何路径或字节的差异(页面内容变化、新增页面、删除页面)都会导致指纹不一致并抛出 SDK reference is stale; run bun run generate and commit packages/sdk-docs/reference.。指纹为空目录时直接报错,防止“空 reference”混过检查。

reference.test.ts 用临时目录构造了三种失败场景来锁定这一契约:内容变更(old signature vs new signature)抛错且不覆盖 reference;补齐一致后通过;生成侧多出 New.md、或 reference 侧多出 Removed.md 都抛错。这正是“changed / added / removed 三类漂移都能被发现,且检测过程绝不写回 reference”的行为保证。

测试侧还有一组针对生成物内容本身的契约测试(render.test.ts):首页 HTML 必须包含 Build with Macro、Quick start、Find the right entity 等章节标题,且不得残留未解析的 {@link;classes/*.html 链接不少于 24 个且全部可解析;reference/ 递归扫描不得出现任何 .test/.spec 路径;WorkspaceNamespace 页必须保留 page()、list() 方法与 WorkspacePageOptions 链接,同时不得泄漏私有实现细节(如 property-client)。这些断言使“文档与公开 API 契约同步”成为可执行的回归测试,而非口头约定。

本地验证与发布链路

README 给出的本地命令序列是:

bun run generate
bun run check:generated
bun run type-check
bun run test
bun run docs:dev

其中 bun run type-check 运行 tsc --noEmit(tsconfig.json 开启 strict 与 noUncheckedIndexedAccess);bun run test 由 vitest.config.ts 只拾取 src/**/*.test.ts。

发布链路是一个无请求处理器的纯静态 Worker,由 wrangler.jsonc 定义:

  • Worker 名 macro-sdk-docs,compatibility_date: 2026-07-15;
  • routes 将 sdk.macro.com 配置为 custom domain,同时保留账号的 workers.dev 地址;
  • build.command 为 bun run build(即只产构建资产的 build-only 模式,预览与部署都不会改写 checked-in 的 reference/),watch_dir 同时监听本包与 ../sdk/src、../sdk/generated,使 SDK 源码变化也能触发重建;
  • assets.directory 指向 ./dist/docs/html,html_handling: auto-trailing-slash,not_found_handling: 404-page。

部署到配置的 Cloudflare 账号即 bun run docs:deploy(wrangler deploy)。生产地址 https://sdk.macro.com 通过 Worker custom domain 生效,首次成功部署后 hostname 上线。仓库中对应的自动化工作流是 .github/workflows/deploy_sdk_docs.yml(该文件头部注明由 cargo x workflows 从 xtask 源 再生,不应手改):它在 main 分支上、当 packages/sdk/**、packages/sdk-docs/**、bun.lock 或根 package.json 变化时触发,步骤依次为 checkout → 安装依赖 → bun run type-check && bun run test(即先跑陈旧检测与契约测试)→ 携带 CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID 执行 bun run docs:deploy;workflow_dispatch 手动触发同样被 if: github.ref == 'refs/heads/main' 限制在 main。

程序化复用:renderSdkDocs 导出面

除站点形态外,该包还通过 package.json 的 exports["./render"] 暴露 renderSdkDocs(指向 src/render.ts),其他构建包可以 import { renderSdkDocs } from '@macro-inc/sdk-docs/render' 直接消费同一份规范 Markdown,而不必各自解析 SDK 声明。边界同样在 AGENTS.md 中写明:本包只负责公开 SDK 参考与静态文档 worker,不产出 Deno bundle 或后端工件——消费者可以把规范 Markdown 打包进自己的构建,但 Deno bundle、工具目录与后端产物应留在各自的构建包里。

小结:一条“文档即代码”的闭环

把上述环节串起来,packages/sdk-docs 实现的是一条职责分明的文档闭环:

  1. 写作面:API 文档写在 packages/sdk 的源码注释与声明中,介绍性内容写在 pages/home.md;
  2. 生成面:src/render.ts 用固定 TypeDoc 配置把源码反射成 Markdown + HTML 双输出,展开对象别名、表格化参数、排除一切非公开与测试成员;
  3. 校验面:scripts/generate.ts 的 --check 模式用 SHA-256 指纹对 reference/ 做逐字节比对,bun run test 将其前置,CI(部署工作流)在发布前强制执行,使“文档落后于代码”成为可拦截的构建失败;
  4. 发布面:wrangler 以 build-only 模式构建、静态 Worker 托管,仅 main 分支可发布到 sdk.macro.com。

这套机制对任何以 TypeScript 声明为契约的 SDK 都有借鉴意义:文档不需要独立仓库,陈旧检测不需要人肉 review diff,且同一份渲染管线可以同时服务于人类阅读的 HTML 站点与 LLM/搜索引擎消费的规范 Markdown。

登录后查看全文
macro