Mastra 文档信息架构：内容家族、侧边栏与路由命名的完整治理指南

本文以 Mastra 官方仓库中的 INFORMATION_ARCHITECTURE.md 为骨架，结合 docs 目录 下的真实内容组织、四个 sidebars.js 与 llms-txt 生成插件源码，系统讲解 Mastra 文档体系“内容放哪里、归属谁、如何导航、如何命名路由”的完整规则。读完本文，你将掌握为 Mastra 文档新增页面时判断归属的四步决策法、四类内容家族的边界与判定标准、侧边栏与路由的治理约束，以及这套信息架构如何直接决定 Agent / LLM 检索文档的效果。

一、为什么 Mastra 需要一套显式的文档信息架构

Mastra 是一个现代 TypeScript 的 AI 应用与 Agent 框架，其文档仓库规模庞大：仅 docs/src/content 下的英文内容就分为四个顶层目录，覆盖概念、集成、API 参考与模型四大类，合计数百个 .mdx 页面。面对如此体量的内容，如果没有一套统一的信息架构（Information Architecture，IA），极易出现同一概念多处重复解释、相似页面分散在多个分类、历史路由无人维护等问题。

仓库中的 INFORMATION_ARCHITECTURE.md 正是为回答“在写任何内容之前，先决定它的规范归属（canonical home）”这一问题而存在。它不规定某个页面怎么写，而是规定每个页面应该放在哪个内容家族、谁是权威页面、导航如何组织、路由如何命名，是贡献者写文档前的“前置决策文件”。

二、四大内容家族（Content Families）：路由表面与源目录

信息架构的核心是四个“内容家族”，每个家族对应一个对外路由表面（URL 前缀）和一个仓库内的源目录。其对应关系如下：

表面（Surface）	源目录（Source）	用途（Purpose）
/docs	docs/src/content/en/docs	Mastra 的概念、能力、配置、决策与聚焦用法
/integrations	docs/src/content/en/integrations	外部产品、提供商、框架、渠道与部署目标
/reference	docs/src/content/en/reference	API、配置、CLI、类型与查阅类材料
/models	docs/src/content/en/models	生成的模型与提供商信息，禁止手动编辑

这四个源目录在仓库中真实存在，可以直接在 docs/src/content/en 下逐一核对。需要特别强调的是最后一行：/models 下的内容是程序生成的模型与提供商信息，贡献者不应手工修改该目录；相应地，它的导航也由独立的 docs/src/content/en/models/sidebars.js 管理（内容约 1087 行，覆盖 embeddings、环境变量、Gateways 等自动生成的类别）。

原文档还明确指出一条容易被忽略的规则：路由工具可能仍然“认识”旧的内容家族（以便维持历史重定向），但这并不等于旧家族是新增页面的正确去向。兼容性只是存量迁移的缓冲，不是新内容的放置依据。

三、选择页面所有者：四种归属的判定标准

当你要新增一个页面时，第一步不是打开编辑器，而是先回答“这个页面归哪个家族管”。原文档给出了四条判定准则：

3.1 归 /docs：Mastra 拥有这个概念或读者的决策

当“Mastra 自己拥有这个概念”，或“页面主要影响读者的决策”时，放在 /docs。原文档给出的典型例子包括：agents、workflows、memory、storage、Studio、authentication、deployment 等概念。从仓库目录结构看，这些内容恰好一一对应 docs/src/content/en/docs 下的 agents/、workflows/、memory/、storage.mdx、studio/、auth/、deployment/ 等子目录。

3.2 归 /integrations：页面主要解释 Mastra 如何与外部生态协作

当页面“主要解释 Mastra 如何与某个外部产品/生态系统协同工作”时，归 /integrations。典型例子包括：框架（framework）、数据库（database）、可观测性导出器（observability exporter）、渠道（channel）、浏览器提供商（browser provider）、认证提供商（authentication provider）、部署平台（deployment platform）。仓库中 docs/src/content/en/integrations 下的真实子目录完全印证了这一点：auth/（auth0、better-auth、clerk、firebase、google、okta、supabase、workos）、browsers/（agent-browser、browser-viewer、firecrawl、stagehand）、channels/（discord、github、imessage、slack 等）……

3.3 归 /reference：读者需要精确签名、选项与类型

当读者需要确切的签名（exact signatures）、选项（options）、返回值（return values）、事件（events）、命令（commands）或类型细节（type details）时，归 /reference。原文档特别强调：reference 页面应当链接到 docs 页面获取概念解释，而不是在 reference 中重复长篇概念叙述。仓库中 docs/src/content/en/reference/sidebars.js 的内容印证了这一原则——它按 AcpAgent、AgentController Class、Agent Class、.generate()、createSkill() 等实体组织，是典型的“查阅式”导航。

3.4 归 /models：生成数据，不讨论归属

/models 不参与“归属决策”——因为它的内容是自动生成的，不存在人为放置的问题。

3.5 关键澄清：页面结构 ≠ 内容家族

原文档强调了一个非常容易踩的坑：“页面结构不决定它的内容家族”（Page structure does not determine its content family）。一个以任务为导向（task-oriented）的页面，既可能放在 /docs 也可能放在 /integrations，取决于它由谁“拥有”——如果任务围绕 Mastra 自身能力（如“如何用 Mastra 构建一个 Agent”），即使写法很“教程化”，也应归 /docs；如果任务围绕外部产品（如“如何把 Mastra 接入 Slack”），即使写法也很“教程化”，也应归 /integrations。

四、权威所有权（Canonical Ownership）：写新页面前的四步流程

在新增任何页面之前，必须执行“权威所有权”检查，防止内容碎片化。原文档给出了五步操作：

1. 搜索全部内容家族，查找该概念及其历史曾用名（former names）；
2. 确认变更后应保持权威（canonical）的那个页面；
3. 当受众与意图匹配时，把缺失信息补充到该权威页面上；
4. 对重叠页面进行合并或重定向，而不是留下两套平行解释；
5. 对于详尽的 API 细节，链接到 reference 材料。

并给出了一条硬性约束：不要仅仅因为侧边栏里“另一个分类看起来也放得下”，就新建第二个页面——同一个页面完全可以从多个位置被链接到（One page can be linked from several places）。

这条规则的深层动机是避免“并行解释”（parallel explanations）：同一概念在两处各写一半、措辞不一致，最终既伤害读者，也伤害检索这些文档的 Agent——它们无法判断哪一份是权威来源。

五、侧边栏与导航：四个 sidebars.js 的职责边界

导航不是随意的。原文档明确了每个侧边栏文件的“所有权”：

• docs/src/content/en/docs/sidebars.js：拥有主文档导航与上下文分类（main docs navigation and contextual categories）；
• docs/src/content/en/integrations/sidebars.js：拥有集成分类的类别、标签、排序、链接与图标元数据；
• docs/src/content/en/reference/sidebars.js：拥有参考文档的导航与排序期望；
• 此外，独立的 sidebar 导出（如 platform sidebar）可以代表一个不同的导航表面，但不会因此创建新的路由家族。

5.1 sidebar-group-name：结构标签不是路由

原文档特别澄清了一个易混淆点：标记为 sidebar-group-name 的标签是结构性导航标签，不能从中推导 URL 或内容归属。在 docs/src/content/en/docs/sidebars.js 中可以找到真实证据——例如 Build 分类就带有 className: 'sidebar-group-name' 属性，而它只是把 Agents、Workflows 等子分类聚合在一起的视觉分组，并不对应任何实际的 /build/... 路由。

5.2 _ 前缀：部分文件不是公开路由

文件名以 _ 开头的文件是 partials 或支持文件（partials or support files），不是公开路由候选。这一约定在 docs 目录中同样有据可查：例如 docs/src/content/en/docs/getting-started/_partial-agent-quickstart.mdx 与 _partial-quickstart-prompt.mdx，它们是被其他页面引用的片段，若被当成独立路由发布会产生无意义且不完整的页面。

六、路由命名：稳定、小写、单一规范

路由命名规则是信息架构落到 URL 层面的最终体现，原文档给出五条规范：

1. 使用小写、描述性的路由段（lowercase, descriptive route segments）；
2. 优先使用稳定的产品概念，而非临时的功能标签（temporary feature labels）或侧边栏分组名；
3. 当多个同级页面共享同一命名空间时，用 overview.mdx 作为分类落地页（category landing page）；
4. 一个主题只保留一条规范路由，历史路由用重定向指过来；
5. 避免链式重定向（chained destinations）——重定向目标必须是最终的规范页面；
6. 当把分散的小页面合并进更大的页面时，保留有用的章节锚点（section anchors）。

这三条规则的仓库证据非常充分：

• overview.mdx 约定：在 docs/src/content/en/docs/agents/overview.mdx、workflows/、auth/overview.mdx、memory/、observability/overview.mdx、server/overview.mdx、deployment/ 等处均可看到该文件；同时 docs/src/content/en/docs/sidebars.js 中 Agents 分类就是通过 link: { type: 'doc', id: 'agents/overview' } 把分类与落地页绑定的；
• 重定向机制：仓库中 docs/scripts/generate-vercel-redirects.mjs 与 docs/vercel.redirects.json 的存在，说明路由迁移是通过脚本生成重定向表来维持存量链接的——这正是“历史路由用重定向指向规范路由”的工程实现；
• 路由命名测试：仓库还提供了 validate-reference-sidebar-sort.ts 等校验脚本，用于保证 reference 侧边栏排序符合预期，说明排序与命名规范是被自动化测试守护的，而非仅靠人工自觉。

七、信息架构的下游影响：llms-txt 与嵌入式文档输出

原文档在结尾点出了一个容易被忽视但极其重要的关联：“路由（Routes）、组件（Components）、frontmatter 和页面结构，可能会影响生成的 llms-txt 与嵌入式文档输出”。

这意味着信息架构决策的受众不只是人类读者，还有 AI。仓库中的 docusaurus-plugin-llms-txt 插件是这条结论的直接证据：

• 插件为每个文档页面生成独立的 llms.txt 文件（见 index.ts 中“Generates individual llms.txt files for each documentation page, converting rendered HTML to clean markdown for LLM consumption”的注释）；
• 通过 generateManifest / writeManifest 生成 llms-manifest.json，把包与文档建立映射；
• 还会生成根级 llms.txt，作为所有可用页面的索引入口。

当信息架构混乱（例如同一概念存在两套并行页面、路由频繁变更、overview.mdx 缺失）时，这套自动生成机制产出的内容索引质量会直接下降——Agent 可能检索到过期路由或非规范页面。因此，“规范归属 + 单一规范路由 + 稳定命名”不仅是人类导航体验的问题，也是文档对 LLM 可发现性（discoverability）与可引用性（citatability）的基础设施。这也解释了为什么原文档开篇要求“Use this file to choose the canonical home for content before writing it”——信息架构决策必须前置，因为它会向下游的每一个消费者（人类、搜索引擎、Agent、LLM）扩散影响。

八、实操速查：写一个 Mastra 文档页面前的自检清单

综合全文，可将原文档的治理规则压缩为一份可执行的自检清单：

1. 定位：在 docs/src/content/en/docs、integrations、reference 四个家族中搜索该概念及其曾用名，确认是否已有权威页面；
2. 归属：按“Mastra 拥有概念 → /docs；解释与外部产品协作 → /integrations；精确 API 细节 → /reference”判定，不因页面写法是教程式就改变归属；
3. 合并：与权威页面受众、意图一致时，把新信息补充进去；重叠内容做合并或重定向，禁止双轨解释；
4. 导航：新增页面若需出现在侧边栏，修改对应家族的 sidebars.js；不要为 sidebar-group-name 结构标签创建 URL，_ 前缀文件不进路由；
5. 命名：小写描述性路由段；同级共享命名空间时使用 overview.mdx 落地页；一个主题一条规范路由，重定向必须直达最终页面，禁止链式重定向；
6. 迁移：历史路由依赖 docs/scripts/generate-vercel-redirects.mjs 生成重定向，合并页面时保留有用锚点；
7. 验证：运行仓库中的 validate-sidebar-docs.ts、validate-reference-sidebar-sort.ts 等脚本，确保侧边栏引用与排序符合预期。

遵循这套信息架构，Mastra 文档才能长期维持“每个概念只有一个权威页面、每个路由都指向规范内容、每个侧边栏都有明确归属”的状态——这正是支撑大规模开发者文档持续演进，并同时服务好人类读者与 AI 消费者的底层骨架。