Macro SDK 文档流水线实战:用 TypeDoc 从 SDK 源码生成受检入仓的 Markdown 与 HTML 参考
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。
这份指南的结构值得借鉴:
- Quick start:
npm install @macro-inc/sdk,在 Settings → API Keys 创建密钥,设置环境变量MACRO_API_KEY,然后用new Macro({})加异步迭代搜索文档。 - Find the right entity:按「内容与工作」「沟通」「人与组织」「AI 与集成」「自动化与资源管理」分组,用表格把
macro.documents、macro.email、macro.ai等入口与语义一一对应。 - How to use entity handles:解释
macro.documents.byId(id)只创建句柄不取数据,await document.name()才发请求;支持Promise.all并行读取,列表/搜索返回异步迭代器、可break提前终止。 - 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} 的区别是本质性的:前者生成后入仓,后者被忽略。因此正确的工作流是:
- 修改
packages/sdk的源码或注释; - 在
packages/sdk-docs运行bun run generate; - 把
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);
需要注意两点约束:
renderSdkDocs的root参数用于定位packages/sdk与packages/sdk-docs/pages/home.md,因此它假设你身处本仓库的目录布局中,而不是任意独立项目。- 该函数不做“参考目录比对”,也不做“覆盖
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 的公开文档。