Mastra 文档写作指南页面类型、结构规范与仓库源码验证【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 开源仓库TypeScript AI 应用框架的官方文档不仅服务于人类读者还要面向搜索引擎、Agent 与 LLM 生成可检索、可引用的llms.txt输出。本篇技术指南基于 docs/styleguides/DOC.md 这一页面风格指南系统讲解 Mastra 文档的四种页面类型、五种页面结构范式、推荐用 MDX 组件与 llms-txt 抽取控制并结合仓库内 docs/styleguides/STYLEGUIDE.md、docs/styleguides/COMPONENTS.md、docs/styleguides/REFERENCE.md 等配套规范及源码插件验证。读完你将掌握如何为 Mastra 各类功能页选择正确的文档形态、如何组织 MDX frontmatter 与章节骨架、如何通过CardGrid/IntegrationGrid/PropertiesTable等共享组件和data-llms-ignore控制 llms-txt 抽取以及如何用仓库内置脚本完成文档的移动、删除、重定向与质量校验。页面类型先选对文档形态再谈内容组织docs/styleguides/DOC.md指出绝大多数文档页可以归入以下四种模式之一。它们是编排模式authoring patterns不是强制模板一页可以组合多种模式只要结果保持连贯页面类型适用场景核心任务Overview概览页agents、memory、authentication、deployment、storage 等类别落地页界定类别包含与排除的内容解释主要选择引导读者选择起点链接最实用的聚焦页与参考材料Focused concept聚焦概念页单一能力、行为或心智模型的连贯讲解说明概念是什么、为何重要、何时使用展示用法覆盖行为、约束与权衡Setup or configuration安装配置页启用并配置 Mastra 自有功能从受支持的配置方式开始说明默认值与持久化边界区分本地开发假设与生产要求Task-oriented任务导向页创建、配置、运行或排查 Mastra 自有能力从已知起点带读者到达可验证的结果遵循STYLEGUIDE.md的任务序列Overview 概览页的推荐结构概览页不应该变成所有子页面的复制品。如果侧边栏或聚焦索引已经提供了穷尽式导航概览页无需逐个链接每个子页面。DOC.md给出了概览页的推荐骨架docs/src/content/en/docs 下的类别落地页即按此模式组织--- title: $CATEGORY description: What the category helps readers understand or accomplish. packages: - mastra/core --- # $CATEGORY State what the category does and the main decision the page helps readers make. ## Choose an approach Explain the important options with a table, list, cards, or integration grid. ## Quickstart Include this only when a short working example clarifies the category. ## Category-wide topic Add sections for behavior shared across the category. ## Next steps Add selected follow-up links when they improve navigation.概览页可用的结构要素包括能力清单、决策表、用于精选目的地的CardGrid、用于提供商选择的IntegrationGrid、架构图或架构说明、快速开始、以及类别级的短章节。标题直接使用已确立的类别名不必为了满足某个公式而添加后缀。Focused concept 聚焦概念页的推荐结构当读者需要单个连贯解释或能力时使用聚焦页。即使页面超过三个 H2 章节也要把相关章节放在一起只有当各章节拥有独立的受众、任务或规范归属时才拆分。推荐骨架如下docs/styleguides/DOC.md--- title: $FEATURE | $CATEGORY description: What the reader will understand or accomplish. packages: - mastra/core --- # $FEATURE Define the feature and its role in Mastra. ## When to use $FEATURE Add this section only when readers need help choosing it. ## Configure $FEATURE Introduce the example and show the supported setup. typescript titlesrc/mastra/path.ts // Complete code for the documented behavior ## Behavior or constraint Explain the important runtime behavior, decision, or limitation. ## Related Add selected links when they help readers continue.标题常用$FEATURE | $CATEGORY模式但应遵循该栏目既有的标题惯例H1 直接命名主题对象。Conceptual 概念页与任务导向页概念页可以比较模式、解释架构或建立术语不必提供 quickstart。组织原则是围绕读者的问题与决策组织内容用示例澄清概念而非把页面硬变成教程直接陈述权衡读者需要对比选项时使用表格先解释模型再链接实现页与参考页。任务导向页的主要目的是创建、配置、运行或排查 Mastra 自有能力。STYLEGUIDE.md中规定先陈述预期结果再给第一个动作把前置条件放在首个需要它的动作附近按依赖顺序呈现必需动作先达到可用结果再引入可选分支或高级配置最后给出可验证结果的命令、URL、界面动作或预期输出。Quickstart最短可行路径Quickstart 是一类短小的任务导向页面或章节聚焦于到达可用结果的最快受支持路径优先采用仓库默认值而不是解释每一个选择说明生成的命令或文件会创建什么概念解释保持简短并链接到更深入的文档。写作风格与准确性规则STYLEGUIDE.md 是 Mastra 文档的默认写作指南要求在所有文档编辑、审查、移动、删除和新页面工作中应用。其核心规则包括清晰直接短句、短段落、简单词、低行话用标题、列表、表格、图示或示例打破密集文本。面向读者为可能赶时间、非母语读者或生态新手写作围绕读者的问题或任务组织页面而非强制模板。准确性对照实现、公开类型、包导出与测试验证技术声明把既有文档当作上下文而非行为仍然有效的证据确认导入路径、选项名、默认值、返回值、环境变量与版本要求。风格自然变化句式和段落长度避免 delve、leverage、comprehensive、robust 等 AI 写作指纹词用you称呼读者以Mastra而非we/us/our指代产品现在时标题与各级标题使用句首大写sentence case。语言细节用Ensure而非make sure缩略词首次出现时写全称再加括号缩写避免用Lets...、Next, we will...用You can...表示许可或可选用You should...仅在描述预期结果时使用。链接规范首次提及 API 或概念时链接到权威页面使用根相对内部链接链接到最终权威路由而非重定向源使用描述性链接文本使其在路由移动后仍然自然可读。UI 术语界面中的 UI 标签、标题、章节名与产品名用加粗用select或open而非click界面表面如对话框用open而非appears。代码示例规则引入代码时先用一句话说明其用途在读者需要的节点给出完整代码读者需要创建或替换文件时包含导入与文件路径代码块只解释非显而易见的部分页面内示例保持一致使用真实名称与受支持的包版本避免仅复述下一行的注释。代码块使用bash高亮终端命令为 npm install、npx、npm run 命令块添加npm2yarn元数据在文件路径重要时给代码块添加title。页面级组件CardGrid、IntegrationGrid、Steps、PropertiesTableCOMPONENTS.md 规定使用共享组件编码既定的文档或抽取模式。在引入新标记前先检查docs/CONTRIBUTING.md与既有用法。CardGrid与CardGridItem用于一组精选目的地其标签、描述与顺序属于当前页面import { CardGrid, CardGridItem } from site/src/components/cards/card-grid; CardGrid columns{3} CardGridItem titleAgents descriptionCreate model-powered agents. href/docs/agents/overview / /CardGrid不要手工重建卡片边框、链接或栅格布局共享组件提供一致的视觉行为并为 llms-txt 抽取提供 card-grid 数据槽位。IntegrationGrid当条目来自 docs/src/content/en/integrations/sidebars.js 时使用import { IntegrationGrid } from site/src/components/integrations/grid; IntegrationGrid sectionFrameworks allowlist{[frameworks/next-js, frameworks/astro]} /可用控制项包括section集成侧边栏类别、allowlist按请求顺序包含的条目、blocklist排除的条目、additionalItems没有独立集成页的侧边栏形态条目、columns三列或四列布局。集成侧边栏是标签、路由、排序与图标的唯一事实来源不要把该元数据复制进 MDX。Steps与StepItem当读者必须按顺序完成动作且每个动作需要大量散文、代码或提示时使用Steps短步骤用 Markdown 有序列表。不要仅仅为了让不相关的章节显得像流程而使用Steps。Tabs与TabItem用于互斥的备选方案如包管理器、运行时、框架或后端选择。共享设置放在 tabs 之外。不要把顺序指令藏在 tabs 里当读者需要同时对比两个示例时不要创建 tabs。PropertiesTable用于结构化的 API 参数、属性、配置与嵌套类型遵循当前参考页支持的形状。嵌套参数组将parameters放在带type的条目内PropertiesTable content{[ { name: options, type: RunOptions, description: Options for the run., properties: [ { type: RunOptions, parameters: [ { name: timeout, type: number, description: Timeout in milliseconds., isOptional: true, }, ], }, ], }, ]} /CopyPrompt与InjectCopyPrompt用于提供可被 AI 编码工具遵循的自包含提示提示应点名预期结果、相关文件与约束不能替代可读的人类指令。Inject用于简短、必要的指令专门帮助 AI Agent 应用周围的文档页面本体对人类读者保持完整。Admonitions提示块提示块用于值得视觉区隔的信息note范围、兼容性或支撑性上下文、warning可能的失败模式、安全顾虑或破坏性后果、danger严重且即时的风险、beta明确以 Beta 呈现的功能。不要把常规指令放进提示块beta提示块仅用于以 Beta 呈现的功能。llms-txt 抽取控制让文档同时服务 Agent 与 LLMMastra 文档系统内置了面向 LLM 的抽取管线其实现位于 docs/src/plugins/docusaurus-plugin-llms-txt插件入口 index.ts。该插件生成根级llms.txt与每个页面独立的 llms.txt 文件output-generator.ts 中的generateRootLlmsTxt从各侧边栏文件解析条目按类别生成 Markdown 列表写入根llms.txtwriteLlmsTxt负责写出每个独立文件。根文件前缀块将 Mastra 描述为 a framework for building AI-powered applications and agents with a modern TypeScript stack并声明其下是所有可用文档页的列表。COMPONENTS.md为 LLM 抽取定义了以下控制规则在不应出现在抽取文档中的渲染控件或界面文本上添加data-llms-ignore扩展 llms-txt 插件识别的卡片标记时保留data-slotcard-grid、data-slotcard与data-slotcard-title在准确表达内容时优先使用语义化 HTML包括ul与li修改感知抽取的标记后测试生成的章节。配套的remark-model-tokens插件docs/src/plugins/remark-model-tokens在构建期替换文档代码块与行内代码中的模型占位 token。模型常量定义在 models.ts__GATEWAY_*token 使用provider/model格式用于 Mastra 模型路由如__GATEWAY_OPENAI_MODEL__替换为openai/gpt-5.6-sol、__GATEWAY_ANTHROPIC_MODEL_SONNET__替换为anthropic/claude-sonnet-4-6、__GATEWAY_GOOGLE_MODEL__替换为google/gemini-2.5-pro__AI_SDK_*token 使用裸模型名用于直接 AI SDK 用法如__AI_SDK_OPENAI_MODEL_BASE__替换为gpt-5。新模型世代发布时只需更新该文件中的值所有文档引用自动同步。仓库内置测试覆盖了抽取行为见 content-extractor.test.ts 与 head-link.test.ts。参考页与图表的专门规范Reference 参考页规范REFERENCE.md 适用于 docs/src/content/en/reference 下的 API、配置、CLI、类型与查找类页面目标是让精确行为与配置易于查找完整记录公共契约。参考页类型包括类或工厂、独立函数或方法、选项或配置对象、返回值/事件/流/结果类型、CLI 命令、包或子系统概览、迁移参考。标题常见模式为Reference: $NAME | $CATEGORYfrontmatter 结构--- title: Reference: $NAME | $CATEGORY description: API reference for $NAME and its supported configuration. packages: - mastra/core --- # $NAME规则要点开头简述 API 的用途与使用时机当参数表、属性表或配置表用PropertiesTable呈现结构化条目每项包含name、type、description源码支持时补充 optional、default 与嵌套字段方法签名用反引号包裹的标题如methodName(value, options?)对每个方法或函数记录用途、参数、返回值、抛出的错误或重要失败行为、副作用/生命周期/持久化行为与示例返回值不明显时写Returns: $TYPECLI 参考包含语法、参数与选项、默认值、必需的构建或初始化状态、环境变量、重要副作用与常见调用示例事件/流/结果对象文档记录对象形态、判别字段、各变体出现时机、顺序或生命周期保证、完成与错误行为。只记录公开导出与受支持的契约。Diagram 图表规范DIAGRAM.md 规定文档中的图表均为 Mermaid写在mermaid代码围栏中通过 docs/src/theme/Mermaid 渲染。形状选择按顺序匹配节点是运行起点或终点用圆形(( start ))等待人工操作用manual-input形状读写存储数据用cyl形状条件分支用菱形{approved?}其余工作单元用 stadium([step1])。边用实线--表示工作流自行推进虚线-.-表示工作流外部事件人工回复、事件到达、定时器触发必须先发生用引发转换的 API 名suspend、resume、out标注边。颜色只用三个语义类accent运行成功完成、pending阻塞等待外部、danger停止、拒绝或失败通过类名而非颜色应用。主路径按源码顺序先声明使用flowchart LR只有八节点图在手机上溢出时才切换TB超过八个节点则拆分图或改为散文。标签小写API 大写除外超过 16 字符用br/换行每个图都带accTitle与accDescr以服务屏幕阅读器。禁止使用十六进制颜色、style、classDef、linkStyle与var(--token)因为它们无法同时适配明暗主题或会被 Mermaid 解析器拒绝。内容归属Information Architecture 决策框架INFORMATION_ARCHITECTURE.md 规定在写作前先选择内容的权威归属canonical home。四个内容族面来源用途/docsdocs/src/content/en/docsMastra 概念、能力、安装、决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查找材料/modelsdocs/src/content/en/models生成的模型与提供商信息勿手工编辑归属判定当 Mastra 拥有概念或读者决策时用/docs如 agents、workflows、memory、storage、Studio、authentication、deployment 概念页面主要解释 Mastra 如何与外部产品或生态协作时用/integrations如框架、数据库、可观测性导出器、渠道、浏览器提供商、认证提供商、部署平台读者需要精确签名、选项、返回值、事件、命令或类型细节时用/reference。页面结构不决定内容族任务导向页既可以位于/docs也可以位于/integrations取决于归属。新建页面前的流程在所有内容族中搜索该概念及其旧名确定移动后应保持权威的页面受众与意图匹配时把缺失信息补充到该页面合并或重定向重叠页面而非保留平行解释为穷尽式 API 细节链接参考材料。不要因为侧边栏有另一个看似合理的类别就创建第二个页面一个页面可以从多处链接。导航与路由规则docs/src/content/en/docs/sidebars.js 拥有主文档导航集成与参考侧边栏各自管理其类别。路由命名使用小写、描述性段对类别落地页优先用overview.mdx一个主题保留一个权威路由并重定向历史路由避免链式重定向重定向目标必须是最终权威页面合并聚焦页时保留有用的章节锚点。文件名以_开头的文件是 partials 或支持文件不是公开路由候选。写作工作流与仓库脚本验证AUTHORING_WORKFLOW.md 定义了文档编辑、审查、移动、删除与新页面的完整工作流每一步都有可运行的仓库脚本支持。移动页面从docs/运行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脚本支持可编辑的/docs、/integrations与/reference路由会更新受支持的侧边栏 ID、入站 Markdown 与 MDX 链接及重定向。移动后检查每个改动链接的锚文本是否自然、JSXhref与link目标、目标路由是否匹配预期内容族、是否残留旧作者链接然后重新生成重定向并做生产构建。删除或合并页面pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement --dry-run pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement替换目标可以是受支持的内部路由或 HTTPS URL。脚本会更新入站链接、侧边栏、重定向并在适用时清理空的父类别。删除后确认关键信息已并入替换页面、检查改写后的链接文本与锚点、若删除子页面导致空类别被移除则恢复侧边栏项再重新生成重定向并构建。维护重定向vercel.redirects.json是作者维护的事实来源vercel.json是生成的产物。修改作者维护的重定向后运行pnpm generate-vercel-redirects生成器会拒绝重复源、拒绝重定向链、为符合条件的/llms.txt创建配套重定向、从生成的 llms-txt 目标中移除片段。永远不要直接编辑生成的vercel.json。验证命令从docs/运行最窄的覆盖改动检查pnpm format:mdx:check pnpm format:check pnpm lint:remark pnpm lint:vale:ai pnpm validate pnpm test pnpm build各脚本定义在 docs/package.jsonvalidate并行执行 frontmatter、参考侧边栏排序、侧边栏文档与侧边栏新标签校验validate:frontmatter、validate:reference-sidebar、validate:sidebar-docs、validate:sidebar-new-tagslint:remark用 remark 检查 docs 内容lint:vale:ai用 Vale 运行 AI 写作风格检查--minAlertLevelerror --outputlinetest运行 Vitestbuild执行 Docusaurus 生产构建。不同改动类型对应不同最低检查组合纯散文 MDX 用 MDX 格式化、Remark、Valefrontmatter 用格式化与pnpm validate侧边栏在路由或导航变化时用格式化、validate 与构建移动或删除用聚焦脚本测试、重定向、校验与构建重定向用重定向生成器测试、生成、校验与构建MDX 组件或 llms-txt 处理器用聚焦 Vitest 测试、格式化、校验与构建主题或导航行为用聚焦单元测试或 Playwright 测试与构建。生产构建是路由解析、MDX 编译与生成的 llms-txt 输出的最终证明。交付前检查运行git diff --check确认只改动了预期文件检查是否残留旧路由名、临时文本、调试输出与生成产物将最终页面与任务和源码发现对比把无关的失败单独陈述而不是削弱或跳过检查。配套风格指南文件一览Mastra 文档体系由一组风格指南协同构成写作前按需查阅docs/styleguides/DOC.md页面类型与结构骨架本文主体docs/styleguides/STYLEGUIDE.md默认写作风格、语言、链接、代码示例与格式规则docs/styleguides/COMPONENTS.md共享 MDX 组件与 llms-txt 抽取控制docs/styleguides/REFERENCE.md参考页API、CLI、类型规范docs/styleguides/DIAGRAM.mdMermaid 图表形状、边、颜色与无障碍规范docs/styleguides/INFORMATION_ARCHITECTURE.md内容归属、侧边栏与路由命名docs/styleguides/AUTHORING_WORKFLOW.md文档移动、删除、重定向与验证工作流。这套规范保证所有页面遵循同一套结构决策概览页引导决策、聚焦页讲解单一能力、配置页从受支持设置开始、任务页到达可验证结果同时通过共享组件与抽取控制让同一份内容同时服务于网页读者与llms.txt消费端搜索引擎、Agent 与 LLM这正是 Mastra 文档在现代 AI 检索时代保持可发现性的关键工程实践。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考