Macro SDK 文档流水线实战:用 TypeDoc 从 SDK 源码生成受检入仓的 Markdown 与 HTML 参考

原创2026-10-30 23:51:242,167 阅读
文章标签:企业应用协同办公后端前端即时通讯AI Agent人工智能CRM桌面应用MCP Clients

Macro SDK 文档流水线实战:用 TypeDoc 从 SDK 源码生成受检入仓的 Markdown 与 HTML 参考

Macro 仓库中的 packages/sdk-docs 承担着一件容易被低估但极其关键的工作:把 packages/sdk 的类型声明与注释,稳定地转换成可评审、可预览、可部署的公开 SDK 参考文档。本文以该包内的开发指南 packages/sdk-docs/AGENTS.md 为主线,结合 packages/sdk-docs/src/render.ts、packages/sdk-docs/scripts/generate.ts、测试与 Cloudflare Worker 配置,完整拆解这套「源码即文档」的生成、校验、预览与发布链路,读完后你可以独立地在本仓库中重建整条文档流水线,并避免文档过期、产物被误覆盖等常见事故。

一、包的定位:公开 SDK 参考与静态文档 Worker

根据 packages/sdk-docs/AGENTS.md,这个包的职责边界非常明确:

  • 拥有公开 SDK 参考文档(reference/)以及静态文档 Worker(Cloudflare Workers 静态资源站点)。
  • 不拥有 SDK 行为本身:SDK 的行为与源码注释属于 packages/sdk(指南里写作 ../sdk)。
  • 允许下游消费规范化的 Markdown,但 Deno bundle、工具目录(tool catalog)与后端产物必须留在各自的构建包中,不在此处生成。

这条边界决定了整套设计的两个核心特征:其一,文档的所有内容都来自 SDK 源码,本包只负责“渲染与发布”;其二,本包对外暴露的是一个可复用的渲染函数,而不是一份手工维护的文档站点。

从 packages/sdk-docs/package.json 可以看到它的技术选型:

依赖 版本 作用
typedoc 0.28.20 从 TypeScript 声明中构建 reflection 模型,负责签名、可见性与继承成员
typedoc-plugin-markdown 4.14.0 把 reflection 渲染成 Markdown(同时支持 HTML 主题输出)
wrangler 4.110.0 本地预览与部署静态文档 Worker
vitest 5.0.1 运行引用一致性与内容契约测试
typescript ^5.9.3 类型检查

同时它只导出一个子路径 ./render,指向 packages/sdk-docs/src/render.ts,这使得其他构建包可以直接 import { renderSdkDocs } from '@macro-inc/sdk-docs/render' 复用同一套渲染逻辑。

二、渲染流水线:renderSdkDocs 做了什么

packages/sdk-docs/src/render.ts 中的 renderSdkDocs(root, output) 是整个包的心脏。它分四步完成一次完整渲染。

1. 解析插件自身的 TypeDoc 实例(peer 解析)

代码开头的注释点明了最隐蔽的一个坑:

// The workspace also uses an older TypeDoc. Load the plugin's peer instance so
// its reflection instanceof checks see the same constructors.
const plugin = createRequire(import.meta.url).resolve(
  'typedoc-plugin-markdown'
);
const { Application } = (await import(
  createRequire(plugin).resolve('typedoc')
)) as typeof TypeDoc;

因为 monorepo 里还存在其他版本的 TypeDoc,如果直接 import 'typedoc',插件内部基于 instanceof 的 reflection 判定会拿到不同构造器,从而产生看似莫名其妙的渲染错误。这里通过 createRequire 从 typedoc-plugin-markdown 的解析上下文里反向解析 typedoc,保证插件与运行时是同一个 TypeDoc 实例。这也是 AGENTS.md 中“TypeDoc and its Markdown plugin must use the same TypeDoc runtime instance”的直接实现。

2. 计算入口点(entry points)

入口点由 Glob 扫描加固定文件列表组成:

const sdk = join(root, 'packages/sdk');
const entryPoints = [
  ...new Bun.Glob('src/entities/**/*.ts').scanSync(sdk),
  ...new Bun.Glob('generated/*/types.gen.ts').scanSync(sdk),
  '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',
]
  .filter(
    (file) =>
      !/\.(test|spec)\.ts$/.test(file) && !file.includes('/__tests__/')
  )
  .sort()
  .map((file) => join(sdk, file));

含义很清晰:

  • src/entities/**/*.ts:所有实体(文档、邮件、频道、任务、CRM……)的命名空间与句柄。
  • generated/*/types.gen.ts:由 OpenAPI 生成的线上请求/响应类型,这些类型在文档里保留为可点击的链接,读者据此能查到真实 wire 结构。
  • 少量顶层模块:主客户端 src/macro.ts、配置 src/config.ts、mention 辅助 src/mentions.ts、事件接收 src/events/receiver.ts 以及三个工具模块(lazy / pagination / unwrap)。
  • 过滤掉 *.test.ts、*.spec.ts 与 __tests__/ 目录,最后 sort() 保证扫描顺序稳定——这对“字节级比对”的校验至关重要。

3. 选项:一次转换,两种产物

选项对象(satisfies TypeDoc.TypeDocOptions & Partial<PluginOptions>)是理解输出结构的钥匙:

选项 值 效果
basePath packages/sdk 产物路径按 SDK 目录相对化
tsconfig packages/sdk/tsconfig.json 用 SDK 自己的编译配置解析类型
name Macro SDK 站点/项目名
readme packages/sdk-docs/pages/home.md 首页取自手工撰写的指南
exclude **/*.test.ts、**/*.spec.ts、**/__tests__/** 测试不进入参考
excludePrivate / excludeProtected / excludeInternal true 私有、受保护、内部成员不出现在公开文档
excludeExternals true 排除外部依赖符号
disableSources true 不渲染源码位置信息
router member Markdown 用成员级路由
expandObjects true 对象别名展开成具体字段
parametersFormat / interfacePropertiesFormat / classPropertiesFormat / typeAliasPropertiesFormat / typeDeclarationFormat table 用表格呈现参数与属性
outputs markdown + html 同一 reflection 同时产出两套格式

其中两个 outputs 条目值得强调:

outputs: [
  { name: 'markdown', path: join(output, 'markdown') },
  { name: 'html', path: join(output, 'html'), options: { router: 'kind' } },
],

Markdown 采用 router: 'member'(每个成员一页),适合在 PR 中逐页 diff;HTML 采用 router: 'kind'(按 kind 聚合页面),适合浏览器浏览。tests/render.test.ts 断言的 HTML 文件名 html/classes/src_entities_workspace_namespace.WorkspaceNamespace.html 正是 router: 'kind' 的产物形态。

4. 失败即中止,绝不留下陈旧产物

const app = await Application.bootstrapWithPlugins(options);
const project = await app.convert();
if (!project) throw new Error('TypeDoc could not convert the public SDK.');
// TypeDoc only warns when it cannot clear old output. Fail here so callers
// never consume stale files left behind by a failed render.
await rm(output, { recursive: true, force: true });
await app.generateOutputs(project);
if (app.logger.hasErrors()) throw new Error('TypeDoc generation failed.');

三个失败点:无法转换、无法清理旧输出、生成过程中 logger 报错。这样调用方(CI、Wrangler 构建)永远不会拿到半成品或上一次的文件。

三、generate.ts 的三种运行模式

packages/sdk-docs/scripts/generate.ts 在渲染之上叠加了“参考目录治理”逻辑。它定义了三个路径常量:

const root = fileURLToPath(new URL('../../../', import.meta.url));
const output = join(root, 'packages/sdk-docs/dist/docs');
const reference = join(root, 'packages/sdk-docs/reference');

即构建产物写入 packages/sdk-docs/dist/docs(被忽略),而受版本控制的参考位于 packages/sdk-docs/reference。主流程按命令行参数分流:

调用方式 行为 是否改写 reference/
bun run generate(无参数) 先渲染,再 rm 旧参考并 cp 新 Markdown 覆盖 是
bun run check:generated(--check) 渲染到 dist/docs 后调用 verifyReference 否
bun run build(--build) 只渲染,不做任何比对或复制 否

指纹校验的实现

fingerprint() 把目录下所有文件按相对路径排序,逐个把「路径 + \0 + 内容 + \0」喂给 SHA-256:

async function fingerprint(directory: string) {
  const hash = createHash('sha256');
  const files = (
    await readdir(directory, { recursive: true, withFileTypes: true })
  )
    .filter((entry) => entry.isFile())
    .map((entry) => relative(directory, join(entry.parentPath, entry.name)))
    .sort();
  if (!files.length)
    throw new Error('SDK reference is empty; run bun run generate.');
  for (const file of files) {
    hash.update(file).update('\0');
    hash.update(await readFile(join(directory, file))).update('\0');
  }
  return hash.digest('hex');
}

注意 if (!files.length) 这一句:空参考目录会直接报错并提示先运行 bun run generate,避免了“空目录等于空文档”的静默通过。而路径参与哈希,意味着新增、删除、重命名页面都会改变指纹,不只是内容修改。

verifyReference(reference, generated) 被显式导出,正是为了让测试复用:

/** Compare every Markdown path and byte without modifying the checked-in reference. */
export async function verifyReference(reference: string, generated: string) {
  if ((await fingerprint(reference)) !== (await fingerprint(generated))) {
    throw new Error(
      'SDK reference is stale; run bun run generate and commit packages/sdk-docs/reference.'
    );
  }
}

报错文案本身就给出了修复动作:运行生成命令,并把 packages/sdk-docs/reference 一并提交。

四、命令与校验矩阵

packages/sdk-docs/README.md 与 package.json 给出一致的命令集合。在 packages/sdk-docs 目录下执行:

bun run generate        # 重新生成并覆盖 reference/
bun run check:generated # 只校验,不改写 reference/
bun run type-check      # tsc --noEmit
bun run test            # 先 check:generated,再跑 vitest
bun run docs:dev        # wrangler dev 本地预览 HTML

各命令的职责对应关系如下:

命令 实际执行 校验强度
type-check tsc --noEmit --project tsconfig.json 渲染代码本身类型正确
check:generated bun scripts/generate.ts --check 参考与源码逐字节一致
test bun run check:generated && vitest run 一致性 + 内容契约
build bun scripts/generate.ts --build 仅产出 dist/docs
docs:dev wrangler dev 浏览器人工验证
docs:deploy wrangler deploy 发布到 Cloudflare

test 脚本的顺序是刻意设计的:先比对再跑契约测试。README 对此的表述是“bun run test performs this check before testing public contracts, so CI catches stale documentation”——如果参考过期,会在最早的环节失败,而不是等到部署。

五、人工撰写与自动生成的接缝:pages/home.md

自动生成的参考只解决“API 长什么样”,不解决“我该从哪开始”。因此首页是手工撰写的 packages/sdk-docs/pages/home.md,通过 readme 选项注入 TypeDoc。

这份指南的结构值得借鉴:

  1. Quick start:npm install @macro-inc/sdk,在 Settings → API Keys 创建密钥,设置环境变量 MACRO_API_KEY,然后用 new Macro({}) 加异步迭代搜索文档。
  2. Find the right entity:按「内容与工作」「沟通」「人与组织」「AI 与集成」「自动化与资源管理」分组,用表格把 macro.documents、macro.email、macro.ai 等入口与语义一一对应。
  3. How to use entity handles:解释 macro.documents.byId(id) 只创建句柄不取数据,await document.name() 才发请求;支持 Promise.all 并行读取,列表/搜索返回异步迭代器、可 break 提前终止。
  4. Read the API reference:指向 packages/sdk-docs/reference/README.md。

源文件里的链接使用 TypeDoc 的 {@link} 语法,例如 {@link src/config!MacroOpts | client options};生成的 packages/sdk-docs/reference/README.md 中已变成普通的相对 Markdown 链接 <a href="https://link.gitcode.com/i/b974f20296c4aa6df84b2687cf7e2f96" target="_blank">client options</a>。这说明 TypeDoc 会为 HTML 与 Markdown 两种格式分别解析 {@link}——这也是为什么 render.test.ts 会断言首页 HTML 中不残留 {@link 字面量。

一个实操建议:首页只写导览性文字,API 细节写进 SDK 源码注释。README 的原话是“Edit that guide for introductory prose and SDK source comments for API documentation”。

六、测试:把“文档不腐烂”变成可执行断言

两个测试文件分别守护不同维度。

reference.test.ts:陈旧检测的行为契约

packages/sdk-docs/src/reference.test.ts 在临时目录里构造 reference/ 与 generated/,覆盖三种偏差:

  • 内容变更:Document.md 从 old signature 变成 new signature → 抛 reference is stale,且断言 reference 中的文件未被改写(old signature 仍在)。
  • 新增页面:generated/New.md 出现 → 仍然 stale。
  • 删除页面:reference/Removed.md 残留 → 仍然 stale。

这个测试实际锁定了两条重要性质:比对是双向的(不只看改了什么,也看多了/少了什么),且校验过程是只读的。

render.test.ts:公开内容契约

packages/sdk-docs/src/render.test.ts 直接读 dist/docs 与 reference/ 的产物,验证:

  • 首页 HTML 含 Build with Macro、Quick start、Find the right entity、Connected mailboxes,且不含 {@link。
  • 首页至少链接到 24 个 classes/*.html,并且这些 HTML 文件真实存在且包含 <html——链接不能指向 404。
  • reference/ 中不存在任何 .test / .spec 路径。
  • WorkspaceNamespace 的 Markdown 包含 page()、list()、WorkspacePageOptions,但不包含内部实现痕迹(如 property-client、/home/)。
  • wire 类型(如 generated/storage/types.gen/type-aliases/ApiEntityFilterAst.md)在 Markdown 中保留。
  • Document.md 包含 content();AiNamespace.md 包含 structuredCompletion 与 decide。
  • 对象别名展开:AgentSessionChangesPatchResponse.md 必须出现 > ... patch: string 这类具体字段行,不能退化成 `= `object,同时保留原始字段描述 The git-style unified diff of the current changeset.。
  • 跨链接类型保留:StructuredCompletionRequest.md 中出现指向 DynamicSchema.md 的链接,并含 ## Properties。

其中“对象别名展开”那条最能解释一个配置的价值:如果关掉 expandObjects,读者只能看到 object,无法知道真实字段;测试用 expect(patch).not.toContain('= object') 把它钉死。

七、六个必须知道的坑

packages/sdk-docs/AGENTS.md 的 Gotchas 部分是整篇文档中最具操作价值的内容,逐条展开如下:

1. reference/ 是生成物,但要提交;不要手改

reference/ 与 dist/docs/{markdown,html} 的区别是本质性的:前者生成后入仓,后者被忽略。因此正确的工作流是:

  1. 修改 packages/sdk 的源码或注释;
  2. 在 packages/sdk-docs 运行 bun run generate;
  3. 把 reference/ 的变更与源码一起提交,让文档评审进入 PR。

生成页永远不要手改,改了下一次 generate 也会被覆盖。

2. 保留指向生成 API 类型的链接

指南要求“retain links to generated API request/response types”。这正是 entryPoints 里显式包含 generated/*/types.gen.ts 的原因:方法签名中的请求/响应类型必须是可点击的,读者才能看到真实 wire 字段。

3. CI 里绝不能先生成再检查

“Never regenerate the reference before checking it in CI, because that hides stale documentation.” 如果 CI 先跑 generate 再跑比对,参考永远等于新生成的,陈旧文档会被自动“洗白”。所以 CI 只跑 check:generated(经由 test),失败就必须由开发者提交更新后的参考。

4. Wrangler 使用 build-only 模式

预览与部署都不应该改写 reference/。这由 wrangler.jsonc 的构建命令保证:"command": "bun run build",而 build 对应 scripts/generate.ts --build,只产出 dist/docs。于是本地 docs:dev 和线上 docs:deploy 都不会污染受版本控制的目录。

5. TypeDoc 与 Markdown 插件必须同实例

如前文所述,render.ts 用 createRequire(plugin).resolve('typedoc') 保证 peer 解析。指南补充了一个动作要求:依赖变更后要真正跑一次生成,因为版本漂移只会在实际渲染时暴露。

6. 用 TypeDoc 的 reflection 与 Markdown 插件,不要自造声明解析器

“Use TypeDoc's reflection and Markdown plugin for signatures and visibility; do not add a separate TypeScript declaration parser.” 自行解析 .d.ts 会漏掉可见性、继承成员、泛型与链接解析,属于重复造轮子且必然与 TypeDoc 输出不一致。同理,expandObjects 必须保持开启,以保证对象别名声明展示具体字段。

另外附带一条事实:packages/sdk-docs/CLAUDE.md 是指向本指南的符号链接(CLAUDE.md -> AGENTS.md),所以不存在两份需要同步的说明。

八、本地预览与 Cloudflare 部署

wrangler.jsonc 的静态资源站点

packages/sdk-docs/wrangler.jsonc 把这个包定义为一个纯静态 Worker:

{
  "name": "macro-sdk-docs",
  "compatibility_date": "2026-07-15",
  "workers_dev": true,
  "routes": [{ "pattern": "sdk.macro.com", "custom_domain": true }],
  "build": {
    "command": "bun run build",
    "watch_dir": ["./src", "./scripts", "./pages", "../sdk/src", "../sdk/generated"]
  },
  "assets": {
    "directory": "./dist/docs/html",
    "html_handling": "auto-trailing-slash",
    "not_found_handling": "404-page"
  }
}

要点:

  • 没有 request handler:assets.directory 指向 ./dist/docs/html,请求由静态资源层处理,不涉及数据库、凭据或模型调用(README 亦如此说明)。
  • watch_dir 覆盖上游:../sdk/src 与 ../sdk/generated 被纳入监听,SDK 改动会触发本地重建。
  • 路由:sdk.macro.com 作为 Worker 自定义域名;README 说明生产地址即该域名,且 Worker 同时保留账号下的 workers.dev 地址。首次成功部署后域名才生效。
  • html_handling: auto-trailing-slash:适配 TypeDoc HTML 的目录式链接;not_found_handling: 404-page 提供 404 页行为。

部署命令与 CI 限制

bun run docs:dev     # wrangler dev,本地浏览器验证
bun run docs:deploy  # wrangler deploy,发布到已配置的 Cloudflare 账号

.github/workflows/deploy_sdk_docs.yml 定义了 Deploy SDK Docs 工作流(该文件由仓库根目录的 cargo x workflows 生成,源码在 tooling/xtask/crates/xtask_workflows/src/workflows/deploy_sdk_docs.rs,因此不应手工编辑)。关键信息:

  • 触发:push 到 main,且路径命中 .github/workflows/deploy_sdk_docs.yml、packages/sdk/**、packages/sdk-docs/**、bun.lock、package.json;另外支持 workflow_dispatch。
  • 主分支限制:job 上有 if: ${{ github.ref == 'refs/heads/main' }},手动部署同样只能针对 main。
  • 步骤顺序:checkout(clean: 'false'、persist-credentials: 'false')→ Setup Bun → Setup Node 22 → bun install --frozen-lockfile → bun run type-check && bun run test(工作目录 packages/sdk-docs) → bun run docs:deploy(注入 CLOUDFLARE_API_TOKEN 与 CLOUDFLARE_ACCOUNT_ID)。
  • 并发:group: ${{ github.workflow }} 且 cancel-in-progress: false,部署串行执行,避免并发覆盖。

同时在 .github/workflows/web-app-check-main.yml 中,packages/sdk-docs/** 被列入路径过滤(约第 48 行),并在约第 226–231 行的步骤里先安装 packages/sdk 依赖,再以 packages/sdk-docs 为工作目录执行 bun run type-check && bun run test。也就是说,PR 阶段就会拦截陈旧文档,部署工作流只是最后一道发布动作。

九、给下游构建包的复用方式

如果其他构建包需要同一份规范化 Markdown(例如打包出另一套文档站点或做内容索引),不必复制脚本,直接使用导出:

import { renderSdkDocs } from '@macro-inc/sdk-docs/render';
import { fileURLToPath } from 'node:url';

const root = fileURLToPath(new URL('../../../', import.meta.url));
await renderSdkDocs(root, new URL('./dist/docs', import.meta.url).pathname);

需要注意两点约束:

  1. renderSdkDocs 的 root 参数用于定位 packages/sdk 与 packages/sdk-docs/pages/home.md,因此它假设你身处本仓库的目录布局中,而不是任意独立项目。
  2. 该函数不做“参考目录比对”,也不做“覆盖 reference/”——这些都属于 scripts/generate.ts 的职责。下游若要做一致性校验,应自行引入 verifyReference 或直接复用 bun run check:generated。

此外,packages/sdk-docs/AGENTS.md 明确本包不生成 Deno bundle 与后端产物。若你的下游需要这些,应该在各自的构建包里完成,保持本包“只拥有公开参考与静态 Worker”的清晰边界。

十、日常改文档的标准操作序列

把前文散落的规则收束成一条可执行路径:

# 1) 修改 SDK 源码或注释(不是修改 generated 的 reference)
#    packages/sdk/src/entities/... 、packages/sdk/generated/... 的注释

# 2) 重新生成参考
cd packages/sdk-docs && bun run generate

# 3) 类型检查与本地预览
bun run type-check
bun run docs:dev

# 4) 只读校验,模拟 CI
bun run check:generated

# 5) 提交 SDK 源码 + packages/sdk-docs/reference 的变更

如果 check:generated 报出 SDK reference is stale; run bun run generate and commit packages/sdk-docs/reference.,说明你改了 SDK 但忘了生成(或者生成后忘了随源码一起提交);如果报出 SDK reference is empty; run bun run generate.,说明 reference/ 目录为空或未检出——这两种错误的修复动作都在报错文案里写明了。

一个团队级约定同样值得沿用:生成页面在 PR 中默认折叠(README 中“Generated pages are collapsed by default in pull requests”),这样评审者先看到源码差异,需要时再展开生成的 Markdown——既保证可评审性,又不让数百个生成文件淹没讨论。

小结

packages/sdk-docs 的价值不在于“能生成文档”,而在于用工程手段把文档漂移变成可失败的构建:packages/sdk-docs/src/render.ts 用同一 reflection 模型同时产出 Markdown 与 HTML,并通过 peer 解析保证插件与 TypeDoc 同实例;packages/sdk-docs/scripts/generate.ts 用全路径 SHA-256 指纹把“参考是否过期”变成确定性判定;generate / check:generated / build 三种模式的分离让本地改稿、CI 校验与 Wrangler 构建互不污染;测试与 GitHub Actions 把这条规则落实到每一次 main 分支的提交与每一次 PR。理解了这些约束,你就能在不破坏既有约定的前提下安全地扩展 Macro SDK 的公开文档。

登录后查看全文
macro