Mastra 文档风格指南（STYLEGUIDE）：为开源 AI 框架编写高质量技术文档的规范与实践

Mastra 文档风格指南STYLEGUIDE为开源 AI 框架编写高质量技术文档的规范与实践【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是一个用 TypeScript 构建 AI 应用与 Agent 的开源框架其文档体系由一套完整、可执行的写作规范支撑。本文基于 Mastra 仓库中的文档风格指南STYLEGUIDE整理而成系统讲解 Mastra 文档的写作原则、准确性要求、文风规则、代码示例规范以及配套的校验脚本、Vale 规则集和发布工作流。读完本文你将掌握为 Mastra 撰写新页面、修改旧页面或评审他人文档时的完整检查清单也能把其中大部分规范迁移到自己的项目文档建设中。风格指南在仓库中有两份同源副本一份是 Claude 技能包内的写作参考 .claude/skills/mastra-docs/references/STYLEGUIDE.md另一份是文档站正式使用的 docs/styleguides/STYLEGUIDE.md二者内容一致。按 docs/AGENTS.md 的约定任何文档编辑都应先读 STYLEGUIDE再读页面专属指南DOC.md、GUIDE_INTEGRATION.md、REFERENCE.md。这份风格指南的定位先全局规范再页面专属STYLEGUIDE 是全仓库文档写作的默认基线覆盖写作、准确性、链接、代码与可访问性五个维度。它不针对某个页面类型而是规定所有 Mastra 文档共用的底线。在它之后还有一组页面专属指南指南文件适用范围DOC.md/docs下的产品文档概念、能力、配置、任务GUIDE_INTEGRATION.md/integrations下的外部产品与集成页面REFERENCE.md/reference下的 API、配置、CLI、类型参考页COMPONENTS.md共享 MDX 组件与 llms-txt 标记规范DIAGRAM.mdMermaid 图的形状、配色、布局、标签与可访问性AUTHORING_WORKFLOW.md编辑、移动、删除、重定向与验证的操作流程INFORMATION_ARCHITECTURE.md内容归属content family、侧边栏与路由命名写作顺序固定先按 STYLEGUIDE 把事实核对清楚、把句子写平实再按页面类型指南DOC / GUIDE_INTEGRATION / REFERENCE决定页面骨架最后按 AUTHORING_WORKFLOW 运行校验。这套全局规范 → 页面模式 → 自动化验证的三层结构是 Mastra 文档工程化的核心思路。核心规则为匆忙的读者写作STYLEGUIDE 开篇给出的 6 条核心规则定义了整个文档体系的价值取向写得清楚、直接Write clearly and directly偏好短句、短段落、简单词、低行话用有意义的标题、列表、表格、图示或示例打破密集文本面向可能赶时间、可能以非母语阅读、可能刚接触生态的读者写作围绕读者的问题或任务组织页面而不是套用强制模板与相邻页面的既有术语和通用惯例保持一致最后一条匹配相邻页面术语在仓库里被具体化为两件事模型名称和 ID 必须取自 docs/src/plugins/remark-model-tokens/models.ts 生成的 token 列表见 docs/AGENTS.md集成页面标签、路由与图标元数据则统一由 docs/src/content/en/integrations/sidebars.js 维护文档正文不得自行复制这套元数据见 COMPONENTS.md 的IntegrationGrid说明。准确性以源码、公共类型、导出和测试为准准确性是 Mastra 文档的第一优先级。风格指南给出的检查要求是技术论断必须对照实现、公共类型、包导出和测试验证把既有文档当作上下文而不是行为仍然如此的证据尽量实际运行可执行的示例必须包含当前 API 所需的配置不要不查源码就照抄旧示例的形状确认导入路径、选项名、默认值、返回值、环境变量和版本要求这条规则在仓库中层层落地。写作前 docs/AGENTS.md 要求先读相邻页面、相关侧边栏、源码或测试AUTHORING_WORKFLOW.md 要求在子系统变化较快时检查近期历史而参考页reference的每个参数、默认值、返回类型都要有源码依据无法从仓库确认的内容不允许写进文档。从代码层面看Mastra 的文档规范本身就带着自动化验证的基因docs/scripts目录下有一批校验脚本例如 validate-frontmatter.ts 校验 frontmatter 格式、validate-sidebar-docs.ts 校验侧边栏与文档页的对应关系、validate-sidebar-new-tags.ts 校验侧边栏新标签、validate-reference-sidebar-sort.ts 校验参考页排序、sidebar-doc-ids.ts 生成并校验文档 ID 一致性。这些脚本与各自的测试位于 docs/scripts/tests共同保证文档声明与仓库现实不脱节。写作范围只讲 Mastra 集成所需记录如何在 Mastra 中使用某种技术对第三方技术的解释只到 Mastra 集成所需为止背景知识或产品细节链接到外部文档详尽的 API 细节链接到参考页不在正文重复换句话说一篇关于如何在 Mastra 中使用某数据库的页面重点是该数据库的 Mastra 存储实现、连接参数与行为差异而不是重写该数据库的官方手册。这决定了信息架构上的分工概念与决策放/docs外部产品集成放/integrations精确签名与选项放/reference。文风平实、直接、中性的技术写作文风部分是 STYLEGUIDE 篇幅最大的一节约 30 条细则可归纳为避免什么和坚持什么两组。必须避免的写法类别规则AI 味词汇不使用 delve、tapestry、multifaceted、leverage、foster、underscores、comprehensive、robust 等词填充语删除 Its important to note、in order to 这类废话破折号用逗号或句号代替 em dash——花哨动词用 use 而非 utilize用 help 而非 facilitate语气中性、事实性口吻不搞笑、不奇想、不谄媚、不讲故事固定套路不用 So、There is、There are 开头不写 Lets...、Next, we will...人称产品一律称Mastra不写 we、us、our、ours不写I弱词删掉弱副词、weasel words、陈词滥调、冗长表达情绪词少用感叹号不用 Alpha 标记早期功能确需标记时用 Beta必须坚持的写法句子与段落长度交错变化避免主题句 三个支撑点 结论的八股公式连续段落或句子不要以同一个词开头去掉结论式收尾页面完成使命就结束直接陈述观点不绕弯、不铺垫修辞需要时用you称呼读者用You can...表示许可或可选操作You should...只用于描述预期结果用现在时写给读者标题与标题层级使用 sentence case仅首字母大写常见短语使用缩写形式如 dont、doesnt、cant、isnt使用包容、性别中立、以人为主的措辞person-first首次出现缩写时先写全称再在括号中给出缩写标题优先用动词短语而非动名词gerund优先主动语态和祈使句指令顺序重要时先给位置再给动作把必需动作与示例中的个性化选择分开用Ensure不用make sure有意思的是风格指南把Avoid AI vocabulary fingerprints列为显式规则说明这份规范本身就针对 LLM 生成内容做了防御设计。这与仓库中 docs/styles 下的 Vale 规则集一脉相承ai-tells/目录包含 132 个检测 AI 写作痕迹的 YAML 规则write-good/收录 10 个通用写作建议规则Mastra/则是 Mastra 专属的术语与风格规则signs-of-ai-writing/进一步补充 8 个 AI 写作特征检测。这些规则通过pnpm lint:vale:ai在 CI 中执行。开头与结尾直奔主题不要仪式感开头说明这个主题做什么、读者能完成什么、页面帮读者做什么决定开头保持简短当页面需要交代范围或前置条件时可以超过两句话不要每页都用 In this guide 或某个固定公式开头只在链接确实有助于读者继续时才加Next steps、Related之类的结尾小节不添加祝贺语congratulations text结合 DOC.md 给出的页面骨架一个聚焦概念页focused concept page的标准写法是frontmatter 用$FEATURE | $CATEGORY作为 titledescription 写读者将理解或完成什么然后 H1 直接点名主题正文先定义该特性及其在 Mastra 中的角色再讲何时使用、如何配置、有何行为约束。--- 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. ## Behavior or constraint Explain the important runtime behavior, decision, or limitation. ## Related Add selected links when they help readers continue.注意packages字段声明页面涉及的包如mastra/core这是 Docusaurus 文档元数据的一部分会影响到参考链接与生成产物。任务导向指令先给结果再给动作对于如何做某事类型的页面STYLEGUIDE 规定了任务序列task sequence在第一个动作之前说明预期结果把前置条件放在靠近第一个需要它的动作处必需动作按依赖顺序排列先达到一个可工作的结果再引入可选分支或高级配置给出一个命令、URL、界面操作或预期输出来验证结果这与 DOC.md 中的 Quickstart 建议一致优先采用仓库默认值而不是解释每一个选择明确说明生成的命令或文件创建了什么概念性解释保持简短并链接到更深的文档。Steps组件见 COMPONENTS.md专门用于必须按顺序完成且每个动作需要大量文字、代码或提示的场景短步骤直接用 Markdown 有序列表即可不要把无关小节硬套成步骤样式。链接与引用根相对路径与规范路由首次提到某个 API 或概念且存在规范页面时就链接它只有当读者可能从该小节直接进入时才在新标题下再次链接同一小节内不要反复贴同一个参考链接使用根相对路径root-relative internal links链接到最终规范路由而不是重定向源使用描述性链接文本即使路由移动后读起来仍然自然根相对路径意味着文档内部链接一律从仓库根目录开始如docs/styleguides/REFERENCE.md而不是相对于当前文档的../局部路径这保证了路由迁移后链接依然可解析。路由本身的治理规则见 INFORMATION_ARCHITECTURE.md使用小写、描述性的路由段优先用稳定的产品概念而非临时的功能标签或侧边栏分组名分类落地页用overview.mdx一个主题只保留一条规范路由历史路由重定向到它重定向目标必须是最终规范页禁止链式跳转合并页面时保留有用的锚点。路由、组件、frontmatter 与页面结构都可能影响生成的 llms-txt 与嵌入式文档输出这也是 Mastra 强调链接规范的深层原因。UI 术语界面文案的固定用法界面中出现的 UI 标签、标题、区块名、产品名一律加粗用select或open不用click除非为清晰所必需否则不写button这个词对对话框等界面元素用open不用appears这套术语让 Mastra 文档中的界面操作描述保持统一也便于非英语母语读者和翻译工具准确理解。代码示例完整、真实、可运行代码示例是 Mastra 文档的实操核心STYLEGUIDE 的要求是用一句简短说明引出代码的目的在读者需要的位置给出完整代码当读者要新建或替换文件时包含 imports 和文件路径代码块之后只解释不明显的部分同一页面内示例保持一致除非页面本身在演示某种变更使用真实的名字和受支持的包版本避免只复述下一行的注释代码块要给出文件路径标题。例如 DOC.md 中的写法typescript titlesrc/mastra/path.ts // Complete code for the documented behavior 在 REFERENCE.md 中参考页开头通常放一个最小可用示例帮助读者定位但如果示例在签名之外不增加任何信息就不要强行放示例。配置参数与选项的完整条目使用PropertiesTable组件呈现详见下文组件一节每个条目包含name、type、description支持 optional、default 与嵌套字段。标题、列表与示例用词标题页面标题是 H1新章节从 H2 开始标题保持简短、有描述性标题描述读者将理解、配置或完成什么标题不以标点结尾标题文本是正文中的代码时使用代码格式函数名用反引号包裹不要为了凑模板而强加标题列表顺序无关用无序列表动作必须按序发生时用有序列表长的、多段落的列表项改用标题或Steps标签与描述之间用冒号而不是 em dash列表项冒号后的第一个单词大写完整句子的列表项以句号结尾片段式列表项不以句号结尾没有更强的排序理由时才按字母序排列示例用词句中举一个例子用for example括号内列举部分项用e.g.完整列举不能用e.g.可访问性不假设读者水平不假设读者熟练Do not assume reader proficiency避免用just、easy、simple、hard、beginner、senior这类评价难度或技能水平的词术语首次出现时给出定义或链接到可信解释使用有意义的链接文本装饰性图片用空 alt 文本可访问性规则与 llms-txt 的输出质量直接相关文档不仅要给人读还要被搜索引擎、Agent 和 LLM 解析仓库中docs/scripts下就有 llms-txt 相关的生成与校验逻辑见 AUTHORING_WORKFLOW.md 关于generated llms-txt output的说明。有意义的链接文本和描述性标题正是机器可检索性的基础。代码格式统一排版约定代码、命令、文件名、环境变量和字面 URL 使用等宽字体monospace行内展示的 URL 作为链接格式化代码块使用正确的语法高亮终端命令用bashnpm install、npx、npm run 命令块添加npm2yarn元数据Docusaurus 的 npm/yarn/pnpm 切换能力文件路径重要时给代码块加title只有需要引导注意力时才使用行高亮配套工具链从风格规范到落地检查规范要落地离不开工具链。Mastra 文档仓库围绕 AUTHORING_WORKFLOW.md 建立了一套完整的编辑与验证流程分为六个阶段准备变更、移动页面、删除或合并页面、维护重定向、验证变更、审查最终 diff。移动与删除页面仓库脚本页面移动使用 move-doc.ts支持/docs、/integrations、/reference三类可编辑路由会自动更新侧边栏 ID、入站 Markdown/MDX 链接和重定向。先在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删除或合并页面使用 delete-doc.ts替代目标可以是受支持的内部路由或 HTTPS URLpnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement --dry-run pnpm tsx scripts/delete-doc.ts /docs/old-page /docs/replacement重定向治理docs/vercel.redirects.json是人工维护的权威来源docs/vercel.json是生成产物。修改重定向后运行pnpm generate-vercel-redirects生成器会拒绝重复的 source、拒绝重定向链、为符合条件的路由创建/llms.txt配套重定向并从生成的 llms-txt 目标中移除 fragment。绝不直接编辑生成的docs/vercel.json。按变更类型选择最小验证集不同性质的变更对应不同的最低检查项变更类型最低检查项纯文案 MDX聚焦的 MDX 格式、Remark、ValeFrontmatter格式检查与pnpm validate侧边栏格式、pnpm validate路由或导航变化时加 build移动或删除聚焦的脚本测试、重定向、校验与 build重定向重定向生成器测试、生成、校验与 buildMDX 组件或 llms-txt 处理器聚焦的 Vitest 测试、格式、校验与 build主题或导航行为聚焦的单元测试或 Playwright 测试与 builddocs/scripts/__tests__下对应的测试包括 move-doc.test.ts、delete-doc.test.ts、generate-vercel-redirects.test.ts、sidebar-doc-ids.test.ts 等保证这些运维脚本本身行为稳定。常用检查命令在docs/目录下执行的通用命令pnpm format:mdx:check pnpm format:check pnpm lint:remark pnpm lint:vale:ai pnpm validate pnpm test pnpm build其中pnpm lint:vale:ai调用 Vale此处仅指仓库内 docs/styles 下的规则集配置检测 AI 写作痕迹与风格违规pnpm validate聚合前文提到的 frontmatter、侧边栏、文档 ID 等校验脚本生产构建是路由解析、MDX 编译与 llms-txt 生成的最终证明。按 AUTHORING_WORKFLOW.md 的收尾要求提交前还应运行git diff --check、确认只改动预期文件、排查过期的路由名、临时文本、调试输出与生成产物。内容家族与页面类型先选对位置再动笔在动笔之前INFORMATION_ARCHITECTURE.md 要求先决定内容的归属家庭content family页面面源码位置用途/docsdocs/src/content/en/docsMastra 的概念、能力、配置、决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查询材料/modelsdocs/src/content/en/models生成的模型与提供商信息禁止手动编辑选 owner 的判据是谁拥有这个概念或读者的决策Mastra 自有的概念agents、workflows、memory、storage、Studio、认证、部署放/docs主要讲 Mastra 如何与外部产品协作的放/integrations读者需要精确签名、选项、返回值、事件、命令或类型细节的放/reference参考页只做查找概念解释链接回/docs。页面结构不决定归属——一个任务导向的页面既可以放/docs也可以放/integrations取决于内容归属。侧边栏由 docs/src/content/en/docs/sidebars.js、docs/src/content/en/integrations/sidebars.js、docs/src/content/en/reference/sidebars.js 分别维护sidebar-group-name标记只是导航结构标签不能据此推导 URL 或内容归属文件名以_开头的是 partials 或支持文件不是公开路由候选。四种页面类型DOC.md 把/docs下的页面归纳为四种模式是作者模式而非强制模板Overview概览定义某个分类如 agents、memory、authentication、deployment、storage的包含与排除范围解释主要选择帮助读者决定从哪里开始链接最有用的聚焦页和参考材料并给出分类级的前置条件与一条简短可用路径。常用结构包括能力清单、决策表、CardGrid精选目的地、IntegrationGrid提供商选择、架构图与快速上手。Focused concept聚焦概念解释一个连贯的能力、行为或心智模型说明概念是什么、为什么重要、何时使用、约束与权衡并链接精确的 API 参考页。Setup or configuration安装配置从受支持的配置讲起说明默认值与持久化边界区分本地开发假设与生产环境要求。Task-oriented任务导向以创建、配置、运行或排查某个 Mastra 能力为主要目的套用 STYLEGUIDE 的任务序列只使用任务需要的章节。参考页的专属规范REFERENCE.md 规定参考页按主题选择结构类或工厂、独立函数或方法、选项或配置对象、返回值/事件/流/结果类型、CLI 命令、包或子系统概览、迁移参考。常见标题模式是Reference: $NAME | $CATEGORY。方法用反引号签名作标题如### \methodName(value, options?)每个方法说明用途、参数、返回值返回类型不明显时写Returns: $TYPE、抛出的错误、副作用或生命周期行为。CLI 参考页要包含语法、参数与选项、默认值、所需构建或初始化状态、环境变量、重要副作用和常见调用示例。事件、流与结果对象要说明对象形状、区分字段、各变体的触发时机、顺序或生命周期保证、完成与错误行为。参考页只记录公共导出与受支持的契约迁移与兼容性说明放在受影响 API 附近。共享 MDX 组件COMPONENTS.md 规定了一套共享组件既保证视觉一致也为 llms-txt 提取提供结构化数据槽位CardGrid/CardGridItem精选目的地卡片不要手工复刻卡片边框、链接或网格布局IntegrationGrid条目来自集成侧边栏支持section、allowlist、blocklist、additionalItems、columns控制项Steps/StepItem必须按序完成且每个动作需要大量说明的步骤Tabs/TabItem互斥的替代方案如包管理器、运行时、框架、后端选择共享设置放在标签外PropertiesTable结构化的 API 参数、属性、配置与嵌套类型嵌套参数的写法示例来自 COMPONENTS.mdPropertiesTable content{[ { name: options, type: RunOptions, description: Options for the run., properties: [ { type: RunOptions, parameters: [ { name: timeout, type: number, description: Timeout in milliseconds., isOptional: true, }, ], }, ], }, ]} /写前自检清单综合 STYLEGUIDE 与配套指南一篇合格 Mastra 文档的最终检查项可以浓缩为事实每个技术论断都有实现、公共类型、包导出或测试依据导入路径、选项名、默认值、返回值、环境变量与版本要求均已确认。归属页面放在了正确的 content family没有与既有页面重复重叠内容已合并或重定向。结构围绕读者的问题或任务组织任务导向页面先给结果再给动作结尾不加祝贺语。文风无 AI 味词汇、无填充语、无 em dash用you称呼读者、以 Mastra 指代产品sentence case 标题主动语态。链接全部为根相对路径链接到规范路由而非重定向源链接文本有描述性。代码示例完整、包含 imports 与文件路径、使用受支持的包版本代码块带titlenpm 命令块加npm2yarn。验证按变更类型运行最小检查集format、Remark、Vale、validate、test、build生产构建通过。继续深入阅读完整风格规范docs/styleguides/STYLEGUIDE.md、.claude/skills/mastra-docs/references/STYLEGUIDE.md页面类型与骨架docs/styleguides/DOC.md、docs/styleguides/REFERENCE.md、docs/styleguides/GUIDE_INTEGRATION.md内容归属与路由docs/styleguides/INFORMATION_ARCHITECTURE.md组件与图示docs/styleguides/COMPONENTS.md、docs/styleguides/DIAGRAM.md操作与验证流程docs/styleguides/AUTHORING_WORKFLOW.md、docs/CONTRIBUTING.md校验脚本与测试docs/scriptsmove-doc、delete-doc、generate-vercel-redirects、validate-frontmatter、validate-sidebar-docs 等及其__tests__【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考