Supabase 文档应用的内容类型门控：Guide、Troubleshooting、Reference 与 Federated 的边界与处理流程

本文围绕 Supabase 仓库中 write-the-docs 技能的内容类型门控（content-type gate）展开：它规定了在动笔写任何文档之前，必须先将需求对照 apps/docs 文档应用真实存在的四类内容进行分类。读完本文，你将掌握 Supabase 文档应用各内容类型的存放位置与生成方式、识别"看似写文档、实为改 spec"的 Reference 类需求的判断与交接流程，以及需求跨类型时的拆分策略，并能在 apps/docs/spec/ 的 Makefile 流水线中找到每一类声明的源码级印证。

门控的定位：起草前的强制分类步骤

内容类型门控是 write-the-docs 技能 Phase 1.5 的组成部分。该技能整体分为 Gather（收集 Linear 工单、PRD、代码、作者补充材料四类输入）→ Content-type gate（分类）→ Draft（起草）→ Review checklist → Handoff 五个阶段，完整定义见 .agents/skills/write-the-docs/SKILL.md。门控的核心要求只有一句话：

在起草任何东西之前，先对照 apps/docs 真实的内容类型对请求进行分类。

分类的事实来源（source of truth）是 ask-the-docs 技能的 app-map.md 中的 "Content types" 表。content-type-gate.md 自身还特别提示：如果这份 note 与线下的 app-map 出现不一致，以 app-map 为准。这一设计反映了 docs-app-direction.md 中的一条工作规范——架构知识应当复用既有地图，而不是在各技能里重复推导。

四类内容的权威对照表

apps/docs 文档应用（Next.js 15 App Router 站点，basePath 为 /docs）的每种内容在磁盘上都有明确的归属。下表完整继承自门控文档，并与 app-map 交叉核对：

类型	位置	是否由 write-the-docs 手工撰写？
Guide / tutorial（指南/教程）	content/guides/	是——手写 MDX，目标导向（goal-oriented）。这是默认情形。
Troubleshooting（故障排查）	content/troubleshooting/	是，但部分条目从 GitHub issues 同步——先检查，再假设需要新建页面。
Reference（参考手册）	由 spec/（OpenAPI、SDK YAML、CLI 配置）生成 → features/docs/generated/**	否。 Reference 页面不走标准 MDX 路径，原因见 docs-app-direction.md，OpenAPI 专属的 spec → codegen → reference 页面流程见 management-api-reference.md。
Federated（联邦内容）	外部仓库，构建时拉取	否——超出该技能范围，机制见 ask-the-docs 的 federated-docs.md。

这四类内容在当前仓库中都有真实落点，可以直接验证：

• apps/docs/content/guides/ 下按领域组织手写 MDX，如 ai/、auth/、database/、self-hosting/ 等目录及各级 *.mdx 索引页；
• apps/docs/content/troubleshooting/ 下是带 hash 后缀的排查文章（如 auth-error-401-invalid-claim-missing-sub--AFwMR.mdx），并包含 _template.mdx 模板，印证了"部分条目从 GitHub issues 同步"的说法；
• apps/docs/spec/ 下存放生成参考文档的原始规格文件（详见下文）；
• 联邦内容在 app-map 中被描述为"构建时通过 GitHub App 从外部仓库拉取"。

app-map 还给出了一个对理解门控很重要的补充：Guide 页面除了 MDX 运行时渲染之外，还有一条 markdown 导出流水线（internals/generate-guides-markdown.ts 遍历 content/guides/**/*.mdx 生成 public/markdown/guides/），两条流水线共享同一数据注册表。也就是说，"手写 MDX"这个类型在 Supabase 的语境里还额外承担了对齐 LLM/Agent 可消费导出的约束。

识别 Reference 型需求的常见陷阱

门控文档点出了一个高频陷阱：工单写着"为新的 X 配置项写文档"或"为新 API 端点添加文档"，听起来是普通的文档撰写需求，实际上是一次 spec 变更。此时正确的处理流程是三步：

1. 不要手写 MDX 参考页——它会与下一次 generate-reference-markdown.ts 运行产生的内容发生偏离，或被其静默覆盖。
2. 定位正确的 spec 来源——apps/docs/spec/ 下按接口面（surface）分为 OpenAPI、SDKSpec、ConfigSpec、CLISpec 几类。
3. 在交接说明中明确写出：真正的修复是 spec/codegen 变更，而不是由 write-the-docs 技能发起的 docs PR，并指向 ask-the-docs 的 spec 编辑工作流。

apps/docs/spec/ 目录本身就是第 2 步的实物证据。目录中包含：

• OpenAPI 规格：api_v1_openapi.json、api_v2_openapi.json、auth_v1_openapi.json、storage_v0_openapi.json、functions_v0_openapi.json、analytics_v0_openapi.json；
• CLI/ConfigSpec：cli_v1_commands.yaml、cli_v1_config.yaml、functions_v0_config.yaml、storage_v0_config.yaml、realtime_v0_config.yaml 等；
• SDK 规格（SDKSpec）：supabase_js_v1.yml、supabase_js_v2.yml、supabase_kt_v1.yml … supabase_kt_v3.yml、supabase_dart_v1/v2.yml、supabase_swift_v1/v2.yml、supabase_py_v2.yml、supabase_csharp_v0/v1.yml 等各语言客户端的 YAML 规格。

apps/docs/spec/README.md 说明了用途："这些 spec 文件用于生成参考文档"，并给出最小操作流程：make init 安装依赖，然后执行 make 即完成"下载并转换 spec 为文档"。

源码印证：spec 到参考页的生成流水线

管理 API 参考页的完整生成链路在 management-api-reference.md 中有精确描述，且与 apps/docs/spec/Makefile 的实际内容一一对应：

1. 下载——make download.api.v1 从线上接口拉取 OpenAPI 到 api_v1_openapi.json / api_v2_openapi.json。Makefile 中的实现即：

   download.api.v1:
   	curl -sS https://api.supabase.com/api/v1-json > $(REPO_DIR)/api_v1_openapi.json
   	curl -sS https://api.supabase.com/api/v2-json > $(REPO_DIR)/api_v2_openapi.json
   

   同类目标还包括 download.mcp-tools-permissions（MCP 工具权限）、download.storage.v1、download.tsdoc.v2（TypeDoc JSON）等。

2. Bundle——make dereference.api.v1 调用 Redocly CLI（@redocly/cli）执行 bundle，输出 transforms/*_deparsed.json。Makefile 中有一条值得注意的注释：Management API 刻意不带 --dereferenced 参数，因为 api_v2_openapi.json 中存在循环引用（APIErrorObject.issues -> APIErrorObject），Redocly 无法将其压平为 JSON；$ref 留到 codegen 阶段用一个带循环保护的解析器手动解决。这正是"Reference 不能走标准 MDX 路径"的底层原因之一：规格文件本身的特性决定了它必须走一条专门的、对循环引用安全的生成管线。

3. 导航分节——sections/generateMgmtApiSections.cts 遍历 operations/tags 生成 common-api-sections.json（该文件确实存在于 apps/docs/spec/ 下）。

4. Codegen——codegen:references:legacy（对应 features/docs/Reference.generated.script.ts）合并 v1+v2、解析引用，写出 features/docs/generated/ 下的 api.latest.endpointsById.json、sections.json、flat.json、bySlug.json。

5. 运行时渲染——/reference/api/[operation] 路由经 ApiReferencePage → SectionSwitch → ApiEndpointSection，是自定义 React 组件而非 MDX，一个端点一个页面。

6. Agent 导出——generate-reference-markdown.ts 把同一份数据导出为 public/markdown/reference/api.md，供 Agent/LLM 消费。

这也解释了门控文档第 1 步的警告从何而来：参考页的运行时数据来自 codegen 产物，markdown 导出来自 generate-reference-markdown.ts 的同一数据源。手写一份 MDX 参考页既不在渲染链路中，也可能与下一次生成结果冲突——它"看起来完成了，但并不是真正的修复"。

为什么 Reference 不走标准 MDX 路径

docs-app-direction.md 说明了文档应用的长期方向："one-to-one markdown fidelity"——渲染出的指南页面与面向 LLM 的 markdown 导出必须语义一致。而 management-api-reference.md 进一步解释了参考页坚持自定义 React 渲染（而非接入第三方 OpenAPI 查看器）的理由：

• 双流水线共享同一数据形状——HTML 渲染、markdown 导出、GraphQL 搜索共用同一个 IApiEndPoint/generated-JSON 形状，引入第三方 viewer 会把这个形状分叉；
• 自定义扩展字段（x-oauth-scope、x-allowed-plans、x-fga-permissions）需要一等公民式的渲染支持；
• 模块化页面——API 页面已从单体页面拆分为每个端点一页，嵌入全量 spec 查看器会逆转这一方向；
• 表面积控制——文档应用的方向是减少表面积，不新增并行渲染器。

因此，"为参考页提需求"的正确出口永远是 spec 侧（apps/docs/spec/）与 codegen 侧（apps/docs/generator/、apps/docs/features/docs/Reference.generated.script.ts），而不是内容目录。

真正模糊时的拆分策略

门控文档最后覆盖了跨类型场景：某些功能同时属于两类，例如一个新 API 端点（Reference 型）同时需要一个展示如何用它的任务导向指南（Guide 型）。规则很直接：

• Reference 部分：按上文流程标记并交接给 spec/codegen 管线，不要在 write-the-docs 中起草；
• Guide 部分：只在此技能中起草 Guide 型内容，放置于 apps/docs/content/guides/ 下对应的领域目录，遵循 apps/docs 的 MDX 约定与 CONTRIBUTING.md、WORD_LIST.md 的写作规范（术语与声音规则同样服务于门控的"手写类"内容）。

SKILL.md 中 Phase 1.5 还有一条兜底原则：拿不准时向 ask-the-docs 求证，而不是靠对应用架构的外部印象猜——因为内容类型分类是"如果从外部知识判断，最可能出错的那一个决定"。

实践要点小结

1. 动笔前先对照 app-map 的 Content types 表分类，四选一：Guide（content/guides/，手写 MDX）、Troubleshooting（content/troubleshooting/，部分由 GitHub issues 同步）、Reference（spec/ 生成，禁止手写）、Federated（外部仓库，超出范围）。
2. 听到"为新端点/新配置项/新 SDK 方法写文档"时，先验证它是否属于 Reference 型；是则指向 apps/docs/spec/ 与 codegen 管线，避免产出会被 generate-reference-markdown.ts 覆盖的 MDX 幻象页面。
3. 跨类型需求按"Reference 走 spec、Guide 走 MDX"拆分交付，交接说明中显式写明这一点。
4. 所有分类争议以 apps/docs 的实时目录结构与 app-map 为准，可用 apps/docs/spec/Makefile 中的 download/transform/generate 目标作为 spec 流水线的可执行事实来源。