Mastra 文档信息架构指南内容族、页面归属与路由命名规范【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文是 Mastra 文档体系的信息架构Information Architecture设计指南用于在撰写或迁移任何文档页面之前为内容选定唯一的权威归属位置。文章围绕四大内容族Content Families、页面归属判定、权威页合并、侧边栏导航与路由命名五条主线展开并结合 docs 与 docs/scripts 中的真实配置和工具链帮助贡献者在写新页面时一步到位、避免内容重复与路由碎片化。内容族Content Families为内容选择唯一的家Mastra 文档站点将全部内容划分为四个顶层 Surface每个 Surface 对应一个独立的源目录Source与用途Purpose。在动笔之前先回答这段内容属于哪个 Surface是整份信息架构的第一原则。Surface源目录用途/docsdocs/src/content/en/docsMastra 的概念、能力、安装配置、设计决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查询类资料/modelsdocs/src/content/en/models自动生成的模型与提供商信息禁止手工编辑从仓库当前结构看四个 Surface 均已落地为真实目录docs/src/content/en/docs、docs/src/content/en/integrations含auth/、databases/、browsers/、channels/、deploy/、frameworks/、observability/等子目录、docs/src/content/en/reference含agents/、memory/、workflows/、storage/、cli/等子目录以及docs/src/content/en/models。需要注意两点旧路由族不等于新路由族路由工具Route tooling可能为了维持重定向redirects而认识更早期的内容族但这种兼容性并不意味着旧路由族是新增页面的正确归宿。/models是机器生成的该 Surface 由构建流程自动生成模型与提供商信息人工内容不应写入其中。选择页面归属判断谁拥有这个概念判定页面归属的核心标准是ownership所有权而不是页面形态是教程、概念还是任务向页面。归属/docsMastra 自己拥有这个概念当 Mastra 拥有该概念本身、或读者的决策取决于 Mastra 的能力时页面应放在/docs。典型例子包括Agents智能体Workflows工作流Memory记忆Storage存储StudioAuthentication认证Deployment 概念部署概念本身归属/integrations页面主要解释如何与外部生态协作当页面重点讲解 Mastra 如何与某个外部产品或生态协同工作时放在/integrations。典型例子包括Frameworks框架Databases数据库Observability exporters可观测性导出器Channels渠道Browser providers浏览器提供商Authentication providers认证提供商Deployment platforms部署平台这与仓库目录一一对应docs/src/content/en/integrations下恰好有frameworks/、databases/、observability/、channels/、browsers/、auth/、deploy/等子目录。归属/reference读者需要精确的签名与参数当读者需要精确的签名signatures、选项options、返回值return values、事件events、命令commands或类型细节type details时页面应放在/reference并链接到/docs的概念页获取解释而不是在 reference 中重复概念讲解。这与 reference 侧边栏 的组织方式一致例如Agents分类下按Agent Class、.generate()、.getMemory()、.getTools()等 API 条目逐一列出。页面结构不决定归属Page structure does not determine its content family——一个任务导向task-oriented的页面既可以放在/docs也可以放在/integrations位置取决于所有权而不是页面形式。权威归属Canonical Ownership新增页面前的五步检查在添加任何页面之前按以下顺序执行全量搜索在所有内容族中搜索该概念及其曾用名former names避免平行页面。确定权威页识别本次变更后应保持权威地位canonical的那一页。补充而非新建当受众与意图匹配时把缺失信息补充到该权威页上。合并或重定向对重叠页面做整合或重定向而不是留下两套平行解释。链接到 reference对穷举式的 API 细节链接到参考资料而非重复罗列。同时强调一条反直觉但重要的原则不要仅仅因为侧边栏里存在另一个看似合理的分类就创建第二个页面。一个页面可以从多处被链接。换言之侧边栏分类是入口不是所有权同一页面被多个分类引用是完全正常的设计。侧边栏与导航谁拥有什么Mastra 的文档导航由各 Surface 下的sidebars.js独立管理docs/src/content/en/docs/sidebars.js —— 掌控主文档导航与上下文分类contextual categories。docs/src/content/en/integrations/sidebars.js—— 掌控集成分类的标签、顺序、链接与图标元数据。docs/src/content/en/reference/sidebars.js—— 掌控参考导航与排序预期。从源码可以确认 docs 侧边栏 中Build这样的顶层分类带有className: sidebar-group-name标记。对于这类标签需要遵守两条规则sidebar-group-name标记的标签是结构性导航标签不要从中推导 URL 或内容所有权。文件名以_开头的文件是 partials 或支持文件不是公开路由候选。此外仓库还允许存在独立的侧边栏导出如平台侧边栏 platform sidebar它可以代表一个独立的导航表面但不会因此创建新的路由族。路由命名Route Naming稳定、小写、单一权威路由命名遵循以下约定使用小写、描述性的路由段如/docs/agents/tools、/docs/agents/structured-output见 docs 侧边栏。优先使用稳定的产品概念而不是临时的功能标签或侧边栏分组名。当多个同级页面共享同一命名空间时使用overview.mdx作为分类落地页——仓库中大量页面遵循此约定例如 docs/agents/overview.mdx、docs/auth/overview.mdx、docs/deployment/overview.mdx 等。一个主题只保留一个权威路由历史路由一律重定向到它。避免链式跳转chained destinations重定向的最终目标必须是最终权威页不允许 A→B→C 的接力。当把聚焦页合并进更大的页面时保留有用的段落锚点section anchors避免外部链接失效。信息架构与生成式输出的联动路由、组件、frontmatter 与页面结构会影响生成的llms-txt与嵌入式文档embedded documentation输出。这意味着信息架构的决策不仅是人读的导航问题还会影响 Agent 与 LLM 抓取文档站点时的可达性与内容质量——保持单一权威路由、避免重定向链、保持结构稳定是保证机器可读输出的前提。仓库在docs/scripts/下提供了与之配套的校验工具链进一步落实上述规范sidebar-doc-ids.ts与sidebar-doc-ids.test.ts校验侧边栏 doc id 与真实页面一致。validate-sidebar-docs.ts校验侧边栏文档引用合法性。validate-reference-sidebar-sort.ts校验 reference 侧边栏的排序预期。generate-vercel-redirects.mjs从 docs/vercel.redirects.json 生成重定向配置并拒绝重复 source 与重定向链。附迁移与维护时的配套工作流信息架构不是一次性设计而是伴随页面移动与删除持续演进。当需要变更路由时仓库提供了专用脚本详见 docs/styleguides/AUTHORING_WORKFLOW.md# 从 docs/ 目录执行移动页面先 dry-run 预览 pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route --dry-run pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route # 删除或合并页面 pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement --dry-run pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacementmove-doc.ts支持可编辑的/docs、/integrations、/reference路由并同步更新受支持的侧边栏 id、入站 Markdown/MDX 链接与重定向。迁移完成后务必确认改写的链接使用了自然锚文本、JSXhref/link目标无误、目标路由属于正确的内容族、且没有遗留旧的创作链接。小结Mastra 文档信息架构可以浓缩为四个关键词四大内容族/docs概念与用法、/integrations外部生态协作、/reference精确 API 细节、/models机器生成。所有权优先用谁拥有这个概念决定归属而不是页面形态或侧边栏位置。单一权威一个主题一个权威页重叠内容合并或重定向不做平行页面。稳定路由小写、描述性、稳定的路由段overview.mdx做分类落地页重定向直达最终权威页并借助docs/scripts/下的校验工具持续维护。无论是撰写新页面、迁移旧路由还是整合重复内容先对照本指南完成内容族 → 所有权 → 权威页 → 侧边栏 → 路由命名五步决策即可保证 Mastra 文档体系长期清晰、可检索、可被 Agent 与 LLM 高效引用。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra 文档信息架构指南：内容族、页面归属与路由命名规范
Mastra 文档信息架构指南内容族、页面归属与路由命名规范【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文是 Mastra 文档体系的信息架构Information Architecture设计指南用于在撰写或迁移任何文档页面之前为内容选定唯一的权威归属位置。文章围绕四大内容族Content Families、页面归属判定、权威页合并、侧边栏导航与路由命名五条主线展开并结合 docs 与 docs/scripts 中的真实配置和工具链帮助贡献者在写新页面时一步到位、避免内容重复与路由碎片化。内容族Content Families为内容选择唯一的家Mastra 文档站点将全部内容划分为四个顶层 Surface每个 Surface 对应一个独立的源目录Source与用途Purpose。在动笔之前先回答这段内容属于哪个 Surface是整份信息架构的第一原则。Surface源目录用途/docsdocs/src/content/en/docsMastra 的概念、能力、安装配置、设计决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查询类资料/modelsdocs/src/content/en/models自动生成的模型与提供商信息禁止手工编辑从仓库当前结构看四个 Surface 均已落地为真实目录docs/src/content/en/docs、docs/src/content/en/integrations含auth/、databases/、browsers/、channels/、deploy/、frameworks/、observability/等子目录、docs/src/content/en/reference含agents/、memory/、workflows/、storage/、cli/等子目录以及docs/src/content/en/models。需要注意两点旧路由族不等于新路由族路由工具Route tooling可能为了维持重定向redirects而认识更早期的内容族但这种兼容性并不意味着旧路由族是新增页面的正确归宿。/models是机器生成的该 Surface 由构建流程自动生成模型与提供商信息人工内容不应写入其中。选择页面归属判断谁拥有这个概念判定页面归属的核心标准是ownership所有权而不是页面形态是教程、概念还是任务向页面。归属/docsMastra 自己拥有这个概念当 Mastra 拥有该概念本身、或读者的决策取决于 Mastra 的能力时页面应放在/docs。典型例子包括Agents智能体Workflows工作流Memory记忆Storage存储StudioAuthentication认证Deployment 概念部署概念本身归属/integrations页面主要解释如何与外部生态协作当页面重点讲解 Mastra 如何与某个外部产品或生态协同工作时放在/integrations。典型例子包括Frameworks框架Databases数据库Observability exporters可观测性导出器Channels渠道Browser providers浏览器提供商Authentication providers认证提供商Deployment platforms部署平台这与仓库目录一一对应docs/src/content/en/integrations下恰好有frameworks/、databases/、observability/、channels/、browsers/、auth/、deploy/等子目录。归属/reference读者需要精确的签名与参数当读者需要精确的签名signatures、选项options、返回值return values、事件events、命令commands或类型细节type details时页面应放在/reference并链接到/docs的概念页获取解释而不是在 reference 中重复概念讲解。这与 reference 侧边栏 的组织方式一致例如Agents分类下按Agent Class、.generate()、.getMemory()、.getTools()等 API 条目逐一列出。页面结构不决定归属Page structure does not determine its content family——一个任务导向task-oriented的页面既可以放在/docs也可以放在/integrations位置取决于所有权而不是页面形式。权威归属Canonical Ownership新增页面前的五步检查在添加任何页面之前按以下顺序执行全量搜索在所有内容族中搜索该概念及其曾用名former names避免平行页面。确定权威页识别本次变更后应保持权威地位canonical的那一页。补充而非新建当受众与意图匹配时把缺失信息补充到该权威页上。合并或重定向对重叠页面做整合或重定向而不是留下两套平行解释。链接到 reference对穷举式的 API 细节链接到参考资料而非重复罗列。同时强调一条反直觉但重要的原则不要仅仅因为侧边栏里存在另一个看似合理的分类就创建第二个页面。一个页面可以从多处被链接。换言之侧边栏分类是入口不是所有权同一页面被多个分类引用是完全正常的设计。侧边栏与导航谁拥有什么Mastra 的文档导航由各 Surface 下的sidebars.js独立管理docs/src/content/en/docs/sidebars.js —— 掌控主文档导航与上下文分类contextual categories。docs/src/content/en/integrations/sidebars.js—— 掌控集成分类的标签、顺序、链接与图标元数据。docs/src/content/en/reference/sidebars.js—— 掌控参考导航与排序预期。从源码可以确认 docs 侧边栏 中Build这样的顶层分类带有className: sidebar-group-name标记。对于这类标签需要遵守两条规则sidebar-group-name标记的标签是结构性导航标签不要从中推导 URL 或内容所有权。文件名以_开头的文件是 partials 或支持文件不是公开路由候选。此外仓库还允许存在独立的侧边栏导出如平台侧边栏 platform sidebar它可以代表一个独立的导航表面但不会因此创建新的路由族。路由命名Route Naming稳定、小写、单一权威路由命名遵循以下约定使用小写、描述性的路由段如/docs/agents/tools、/docs/agents/structured-output见 docs 侧边栏。优先使用稳定的产品概念而不是临时的功能标签或侧边栏分组名。当多个同级页面共享同一命名空间时使用overview.mdx作为分类落地页——仓库中大量页面遵循此约定例如 docs/agents/overview.mdx、docs/auth/overview.mdx、docs/deployment/overview.mdx 等。一个主题只保留一个权威路由历史路由一律重定向到它。避免链式跳转chained destinations重定向的最终目标必须是最终权威页不允许 A→B→C 的接力。当把聚焦页合并进更大的页面时保留有用的段落锚点section anchors避免外部链接失效。信息架构与生成式输出的联动路由、组件、frontmatter 与页面结构会影响生成的llms-txt与嵌入式文档embedded documentation输出。这意味着信息架构的决策不仅是人读的导航问题还会影响 Agent 与 LLM 抓取文档站点时的可达性与内容质量——保持单一权威路由、避免重定向链、保持结构稳定是保证机器可读输出的前提。仓库在docs/scripts/下提供了与之配套的校验工具链进一步落实上述规范sidebar-doc-ids.ts与sidebar-doc-ids.test.ts校验侧边栏 doc id 与真实页面一致。validate-sidebar-docs.ts校验侧边栏文档引用合法性。validate-reference-sidebar-sort.ts校验 reference 侧边栏的排序预期。generate-vercel-redirects.mjs从 docs/vercel.redirects.json 生成重定向配置并拒绝重复 source 与重定向链。附迁移与维护时的配套工作流信息架构不是一次性设计而是伴随页面移动与删除持续演进。当需要变更路由时仓库提供了专用脚本详见 docs/styleguides/AUTHORING_WORKFLOW.md# 从 docs/ 目录执行移动页面先 dry-run 预览 pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route --dry-run pnpm tsx scripts/move-doc.ts /docs/old-route /docs/new-route # 删除或合并页面 pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement --dry-run pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacementmove-doc.ts支持可编辑的/docs、/integrations、/reference路由并同步更新受支持的侧边栏 id、入站 Markdown/MDX 链接与重定向。迁移完成后务必确认改写的链接使用了自然锚文本、JSXhref/link目标无误、目标路由属于正确的内容族、且没有遗留旧的创作链接。小结Mastra 文档信息架构可以浓缩为四个关键词四大内容族/docs概念与用法、/integrations外部生态协作、/reference精确 API 细节、/models机器生成。所有权优先用谁拥有这个概念决定归属而不是页面形态或侧边栏位置。单一权威一个主题一个权威页重叠内容合并或重定向不做平行页面。稳定路由小写、描述性、稳定的路由段overview.mdx做分类落地页重定向直达最终权威页并借助docs/scripts/下的校验工具持续维护。无论是撰写新页面、迁移旧路由还是整合重复内容先对照本指南完成内容族 → 所有权 → 权威页 → 侧边栏 → 路由命名五步决策即可保证 Mastra 文档体系长期清晰、可检索、可被 Agent 与 LLM 高效引用。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考