Mastra 文档信息架构内容家族、侧边栏与路由命名的完整治理指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/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 ArchitectureIA极易出现同一概念多处重复解释、相似页面分散在多个分类、历史路由无人维护等问题。仓库中的 INFORMATION_ARCHITECTURE.md 正是为回答“在写任何内容之前先决定它的规范归属canonical home”这一问题而存在。它不规定某个页面怎么写而是规定每个页面应该放在哪个内容家族、谁是权威页面、导航如何组织、路由如何命名是贡献者写文档前的“前置决策文件”。二、四大内容家族Content Families路由表面与源目录信息架构的核心是四个“内容家族”每个家族对应一个对外路由表面URL 前缀和一个仓库内的源目录。其对应关系如下表面Surface源目录Source用途Purpose/docsdocs/src/content/en/docsMastra 的概念、能力、配置、决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查阅类材料/modelsdocs/src/content/en/models生成的模型与提供商信息禁止手动编辑这四个源目录在仓库中真实存在可以直接在 docs/src/content/en 下逐一核对。需要特别强调的是最后一行/models下的内容是程序生成的模型与提供商信息贡献者不应手工修改该目录相应地它的导航也由独立的 docs/src/content/en/models/sidebars.js 管理内容约 1087 行覆盖 embeddings、环境变量、Gateways 等自动生成的类别。原文档还明确指出一条容易被忽略的规则路由工具可能仍然“认识”旧的内容家族以便维持历史重定向但这并不等于旧家族是新增页面的正确去向。兼容性只是存量迁移的缓冲不是新内容的放置依据。三、选择页面所有者四种归属的判定标准当你要新增一个页面时第一步不是打开编辑器而是先回答“这个页面归哪个家族管”。原文档给出了四条判定准则3.1 归/docsMastra 拥有这个概念或读者的决策当“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写新页面前的四步流程在新增任何页面之前必须执行“权威所有权”检查防止内容碎片化。原文档给出了五步操作搜索全部内容家族查找该概念及其历史曾用名former names确认变更后应保持权威canonical的那个页面当受众与意图匹配时把缺失信息补充到该权威页面上对重叠页面进行合并或重定向而不是留下两套平行解释对于详尽的 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 categoriesdocs/src/content/en/integrations/sidebars.js拥有集成分类的类别、标签、排序、链接与图标元数据docs/src/content/en/reference/sidebars.js拥有参考文档的导航与排序期望此外独立的 sidebar 导出如 platform sidebar可以代表一个不同的导航表面但不会因此创建新的路由家族。5.1sidebar-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 层面的最终体现原文档给出五条规范使用小写、描述性的路由段lowercase, descriptive route segments优先使用稳定的产品概念而非临时的功能标签temporary feature labels或侧边栏分组名当多个同级页面共享同一命名空间时用overview.mdx作为分类落地页category landing page一个主题只保留一条规范路由历史路由用重定向指过来避免链式重定向chained destinations——重定向目标必须是最终的规范页面当把分散的小页面合并进更大的页面时保留有用的章节锚点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 contentbefore writing it”——信息架构决策必须前置因为它会向下游的每一个消费者人类、搜索引擎、Agent、LLM扩散影响。八、实操速查写一个 Mastra 文档页面前的自检清单综合全文可将原文档的治理规则压缩为一份可执行的自检清单定位在 docs/src/content/en/docs、integrations、reference 四个家族中搜索该概念及其曾用名确认是否已有权威页面归属按“Mastra 拥有概念 →/docs解释与外部产品协作 →/integrations精确 API 细节 →/reference”判定不因页面写法是教程式就改变归属合并与权威页面受众、意图一致时把新信息补充进去重叠内容做合并或重定向禁止双轨解释导航新增页面若需出现在侧边栏修改对应家族的sidebars.js不要为sidebar-group-name结构标签创建 URL_前缀文件不进路由命名小写描述性路由段同级共享命名空间时使用overview.mdx落地页一个主题一条规范路由重定向必须直达最终页面禁止链式重定向迁移历史路由依赖 docs/scripts/generate-vercel-redirects.mjs 生成重定向合并页面时保留有用锚点验证运行仓库中的 validate-sidebar-docs.ts、validate-reference-sidebar-sort.ts 等脚本确保侧边栏引用与排序符合预期。遵循这套信息架构Mastra 文档才能长期维持“每个概念只有一个权威页面、每个路由都指向规范内容、每个侧边栏都有明确归属”的状态——这正是支撑大规模开发者文档持续演进并同时服务好人类读者与 AI 消费者的底层骨架。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考