ask-the-docs

询问文档应用资料管理员

apps/docs 知识参考——架构、构建流水线、联合文档、已知脆弱点——以及代码库推崇的功能设计原则：编写新代码前先理解并复用现有代码，并践行极简编码，以缩小影响范围。

两项用途：

1. 查找已有文档中关于文档应用的内容——架构、权衡、注意事项、过往决策——而不是从头阅读代码重新推导。
2. 在打开 PR 前应用代码复用／极简原则，提前避免审查反馈。及早发现“下一轮再修”的评论。

何时调用

• 用户询问 apps/docs 的架构、约定或行为（“Markdown 流水线如何工作？”、“列表数据文件放在哪里？”、“为什么 Troubleshooting 有一个 .mjs utils 文件？”）。
• 用户询问 LLM／Agent 如何使用文档（llms.txt、Markdown 内容协商、searchDocs、批量导出、Agent 入门指南、人类与 Agent 及爬虫的区别、快速入门中的 AI 提示词块）。
• 即将编写 apps/docs/ 下涉及以下内容的代码：MDX 组件、internals/markdown-schema/、generate-guides-markdown.ts、内容数据模块、lint 流水线、遥测事件、面向贡献者的代码片段、联合路由、参考文档代码生成，或 Management API／OpenAPI 参考页面。
• 审查文档应用 PR，并希望根据已记录的原则进行检查。

**不适用于：**常规 Supabase 文档_内容_问题（请使用 work-linear-issue、audit-quickstarts 等），或 apps/docs/ 之外的应用级工作。

使用图表作答

架构和流水线问题通常用图表比文字说明更清晰。回答以下问题时，默认附上 Mermaid 图表：

• MDX 运行时与 Markdown 导出流水线的分工。
• 构建流程（Turbo → pnpm prebuild／build／postbuild → Vercel）。
• LLM／Agent 使用入口（llms.txt、内容协商、批量导出）。
• 联合文档获取流程。
• CI／PR 流程。
• 组件／数据注册表之间的关系。
• Management API OpenAPI → 代码生成 → 参考页面流程。

Mermaid 代码围栏（`` ```mermaid `````) 可在 GitHub 和大多数 Markdown 预览器中原生呈现。若干参考文件已内嵌 Mermaid 图表；请复用或调整这些图表，而不是重新推导。

图表应简洁且聚焦单一主题。如果图表需要超过十二个节点，请拆分。

参考文件

reference/ 下存放着简短、聚焦的文档。请阅读与当前任务相关的文档——它们会在需要背景信息时相互引用。

文件	内容
reference/adding-features.md	向 apps/docs 添加功能的最佳实践指南。先盘点现有代码，选择满足需求的最小方案，并复用现有流水线。
reference/docs-app-direction.md	重构愿景和工作规范——新工作应遵循的方向。
reference/known-issues.md	持续更新的故障、不稳定或正在变更的系统清单。依赖任何内容前请先查看（联邦文档、搜索、Sentry、参考页面架构）。
reference/app-map.md	架构速览——目录、双流水线（MDX 运行时 + markdown 导出）模型、标题／排版规范、遥测、lint 条目。
reference/build-pipeline.md	构建 apps/docs 的 Turborepo + pnpm 生命周期步骤——代码生成、预构建、后构建、Vercel 部署。包含 Mermaid 图表。
reference/llm-agent-surface.md	受众路由、llms.txt、内容协商、批量导出。
reference/llm-agent-parity.md	HTML↔markdown 保真度（例如 AI 提示词）、搜索注意事项、Agent 入门指南、尚在变更的配置。
reference/federated-docs.md	文档如何在构建时从外部仓库拉取 markdown。包括路由、pageMap、remark/rehype 插件、链接转换和已知故障模式。
reference/ci-and-lint.md	每个 PR 上运行的 GitHub Actions——Docs Tests、类型检查、prettier、Vercel 预览门禁。创建新检查前应先了解可添加检查的位置。
reference/management-api-reference.md	Management API OpenAPI → 参考文档生成，包括作用域 PAT 权限表；以及为何不应改用 Scalar/Redoc。
reference/graphql-endpoint.md	apps/docs/resources/ 下的 /api/graphql 端点——各查询的文件夹布局、rootSchema.ts、连接／字段工具，以及添加新的顶层查询的步骤。
reference/search-embeddings.md	searchDocs 背后的 scripts/search/ 嵌入流水线——内容来源、处理流程、变更检测，以及 page / page_section 表。
reference/gotchas.md	需要注意的具体陷阱。每项一行。

如何在聊天期间使用

1. 先阅读 adding-features.md 和 app-map.md，如果问题涉及设计选择或不熟悉的代码路径。文件刻意保持精简——请都读一遍，不要只浏览。
2. 提出建议前先核实。 参考内容可能落后于当前代码。采取行动前，请对照实际文件（apps/docs/...）确认有关文件路径、函数名称或行为的记忆是否准确。
3. 引用原则，而不只是规则。“根据 adding-features.md § ‘Reuse pipelines, don't fork them’，这里会通过现有的 markdown-schema 处理程序进行路由，而不是引入一条旁路。”
4. 解释架构、流程或关系时，优先使用 Mermaid——参见使用图表作答。

更新 librarian

此技能位于 supabase/supabase 中的 .agents/skills/ask-the-docs/。 当 apps/docs 中的内容发生变化，导致参考文件不再准确，或在 PR 审查中总结出普遍适用的经验时，请像提交其他仓库内变更一样，向此仓库发起拉取请求，更新相关文件。

每个规范文件应控制在约 250 行以内；变得臃肿前就拆分。 只记录未来的贡献者会受益的信息——如果通过快速浏览当前代码就能轻易看出某个事实，就不要把它写下来。

相关技能

• pm-the-docs — 处理受众、阶段和跨领域范围问题（即“Write the docs”检查清单中的 Frame 阶段，该阶段也反映在 pm-the-docs 的参考文件中）。跨仓库的产品查询（universe）由该技能负责，而非此技能。
• test-the-docs — 在 Docker 隔离的本地技术栈中执行文档代码片段；生成验证报告。
• work-linear-issue — 实施已分配的 DOCS-* 工单。
• review-the-docs — 使用针对不同类型的验证方式审查待处理的文档 PR。
• audit-content-listings — 批量将概览页面转换为内容列表。
• create-pull-request — 发起或更新文档 PR。