Mastra 文档写作风格指南：编写准确、易读、可检索的开发者文档

Mastra 是一个面向 AI 应用与 Agent 的现代 TypeScript 框架，其官方文档库沉淀了一整套完整的写作规范。本文以仓库中 docs/styleguides/STYLEGUIDE.md 为骨架，系统讲解这套文档写作风格指南：从核心写作规则、事实准确性要求，到任务导向的指令结构、代码示例与无障碍规范，并延伸到页面类型、信息架构、文档组件、Mermaid 图表与验证工具链等配套指南。读完本文，你将掌握为 Mastra 编写符合项目标准、易于人类阅读且能被搜索引擎、Agent 与 LLM 正确提取的开发者文档的完整方法。

风格指南的定位与使用顺序

Mastra 的文档写作规范由一组相互配合的指南文件组成，全部位于 docs/styleguides/。STYLEGUIDE.md 是所有文档写作的默认写作指南，使用规则是：先阅读这份文件，再阅读页面类型对应的特定指南。

配套指南的分工如下：

指南文件	适用范围
STYLEGUIDE.md	所有 Mastra 文档的默认写作规范
DOC.md	docs/src/content/en/docs 下的产品文档
REFERENCE.md	docs/src/content/en/reference 下的 API、配置、CLI、类型参考页
GUIDE_INTEGRATION.md	docs/src/content/en/integrations 下的集成页
COMPONENTS.md	文档中可复用的共享组件
DIAGRAM.md	文档中的 Mermaid 图表
INFORMATION_ARCHITECTURE.md	内容的规范归属与路由命名
AUTHORING_WORKFLOW.md	文档编辑、评审、移动、删除与验证工作流

核心规则

风格指南在开头就确立了六条贯穿全文的核心规则：

• 写得清晰直接（write clearly and directly）；
• 优先使用短句、短段落、简单词汇和低行话（low jargon）；
• 用有用的标题、列表、表格、图表或示例打破密集的文本；
• 为那些可能时间紧张、以非母语阅读、或对生态体系陌生的读者写作；
• 围绕读者的问题或任务组织页面结构，而不是套用强制模板；
• 与相邻页面已经确立的术语和有用惯例保持一致。

这些规则决定了一个基本原则：页面结构服从读者的任务，而不是服从某种固定模板。指南中反复出现的一句话是"Do not force a heading solely to satisfy a template"——不要仅仅为了满足模板而强行添加标题。

准确性：以源码与测试为证据边界

STYLEGUIDE.md 将"准确性"列为独立的章节，因为文档的技术声明必须可以追溯到实现。其要求是：

• 对照实现验证技术声明：以源码实现、公开类型、包导出和测试为准，而不是以旧文档为准；
• 把现有文档当作上下文，而非当前行为的证明：文档可能过时，行为是否如此必须回到源码确认；
• 尽可能实际运行可执行的示例：能跑通的示例才算数；
• 包含当前 API 所需的配置：不要照抄旧示例的形状而不检查源码；
• 确认导入路径、选项名、默认值、返回值、环境变量和版本要求：这些细节是读者复制代码后能否运行的关键。

这条规则与仓库本身的工程实践一致：Mastra 的每个包都有完整的测试（例如 packages/core 下的数千个 TypeScript 文件与快照测试），文档中的任何行为声明都应当能在这些测试或公开类型中找到对应证据。从源码结构看，文档团队正是通过"实现、类型、导出、测试"四重证据链来保证文档不脱离实际代码。

范围：只写集成所需

在内容范围上，指南要求：

• 文档的主题是"如何将某种技术与 Mastra 一起使用"；
• 对第三方技术的解释只到 Mastra 集成所需的程度，不要写成第三方产品的教程；
• 需要背景知识或产品特定细节时，链接到外部文档；
• 需要穷尽的 API 细节时，链接到参考页而不是在指南中重复它。

这意味着每个页面都应保持自包含（self-contained）且聚焦，既不越界替第三方产品写文档，也不把参考页该干的事塞进概念页。

写作风格：一套可执行的清单

风格指南的"Writing style"章节是全文最长的部分，它给出的不是抽象建议，而是一组几乎可以直接对照检查的规则：

• 自然变化散文：混合句子与段落的长度；避免"主题句 + 三个支撑点 + 结论"的公式化结构；不要让连续段落或连续句子以同一个词开头。
• 不要写结论包装：页面完成它的职责就结束，不需要"综上所述"式的收尾。
• 直陈观点：不要含糊其辞，不要修辞性的铺垫。
• 避免 AI 词汇指纹：明确列出了一批应避免的词：delve、tapestry、multifaceted、leverage、foster、underscores、comprehensive、robust。
• 删除填充语：如 "It's important to note"（值得注意的是）和 "in order to"（为了）。
• 标点：用逗号或句号代替 em dash（长破折号）。
• 优先简单词：用 use 而不是 utilize，用 help 而不是 facilitate。
• 语气中性、事实化：不要搞笑、异想天开、谄媚或讲故事式叙述。
• 代词规则：需要时用 you 称呼读者；指代产品时用 Mastra，绝不用 we、us、our、ours；不要使用 I。
• 时态与大小写：用现在时；标题使用 sentence case（只有首字母和专有名词大写）。
• 收缩形式：常用短语使用收缩形式，如 don't、doesn't、can't、isn't。
• 删减弱词：移除弱副词、weasel words（含糊其辞的词）、陈词滥调和冗长短语。
• 句首限制：不要以 So、There is、There are 开头句子。
• 包容性措辞：使用包容、性别中立、person-first（人优先）的措辞。
• 缩写：首次使用时写全称，然后在括号中给出缩写。
• 标题动名词：当更清晰的动词短语可用时，避免在标题中使用动名词。
• 语态：优先使用主动语态和祈使句指令。
• 禁止的说法：不要写 Let's... 或 Next, we will...。
• You should... 的边界：除非在描述预期结果，否则避免使用 You should...；用 You can... 表示许可或可选选择。
• 顺序原则：当顺序重要时，先说位置、后说动作（lead with the location and end with the action）。
• 区分必需与可选：将必需动作与示例中带个人偏好的选择分开陈述。
• 用词规范：用 Ensure，不用 make sure；少用感叹号。
• 版本标签：不要用 "Alpha" 标记早期功能，需要标签时用 "Beta"。

开头与结尾

• 开头：说明主题做什么、读者能完成什么、或这个页面帮助读者做出的决定；开头保持简短，但当页面需要交代范围或前提时，可以超过两句话；不要每页都以 "In this guide" 或其他固定公式开头。
• 结尾：只有当链接确实能帮助读者继续深入时才添加 Next steps、Related 等收尾章节；不要添加祝贺文本。

任务导向的指令结构

对于以"创建、配置、运行、排错"为目的的页面，指南规定了任务序列（task sequence）：

1. 在第一个动作之前陈述预期结果；
2. 把前提条件放在第一个需要它的动作附近；
3. 按依赖顺序呈现必需动作；
4. 在引入可选分支或高级配置之前，先达到一个可工作的结果；
5. 包含一个命令、URL、界面动作或预期输出来验证结果。

这一结构确保读者沿着一条"能跑通"的主路径前进，可选内容永远不阻塞主路径。

链接与引用

• 首次提及某个 API 或概念、且存在规范页面时，就链接它；
• 只有在读者可能从该章节直接进入页面时，才在新的标题下再次链接同一目标；
• 不要在一个章节内反复重复同一个引用链接；
• 使用 root-relative（相对仓库根目录）的内部链接；
• 链接到最终的规范路由，而不是重定向源；
• 使用描述性链接文本，即使路由日后变更，文本读起来依然自然。

UI 术语

• 界面中出现的 UI 标签、标题、节名和产品名使用加粗；
• 用 select 或 open，不要用 click；
• 除非为了清晰必须说明，否则不要包含 button 一词；
• 对于对话框等界面元素，用 open，不要用 appears。

代码示例规范

• 在展示代码前，先用一句简短的话说明其目的；
• 把完整代码放在读者需要的那个位置；
• 当读者需要创建或替换文件时，包含导入语句和文件路径；
• 代码块之后只解释不明显的部分；
• 保持页面内示例的一致性，除非正在演示的正是这种变化本身；
• 使用现实的命名和受支持的包版本；
• 避免只复述下一行代码含义的注释。

标题、列表、示例与无障碍

标题：页面标题是 H1，新章节从 H2 开始；标题保持简短、有描述性，描述读者将理解、配置或完成的事情；标题不以标点结尾；当标题文本本身就是代码时使用代码格式；函数名用反引号包裹。

列表：顺序无关时用无序列表，动作必须按顺序发生时用有序列表；长而多段落的列表项应改写成标题或 Steps；标签与描述之间用冒号而非 em dash；列表项中冒号后的第一个单词大写；完整句子的列表项以句号结尾，片段的列表项不加句号；只有在没有更强的排序依据时才按字母排序。

示例措辞：句中给出一个示例用 for example；括号内给出部分列表用 e.g.；完整列表不要用 e.g.。

无障碍（Accessibility）：不假设读者熟练；避免用 just、easy、simple、hard、beginner、senior 这类评判难度或技能水平的词；首次出现行话时给出定义或链接到可信的解释；使用有意义的链接文本，装饰性图片使用空的 alt 文本。

代码格式

• 代码、命令、文件名、环境变量和字面 URL 使用等宽字体；
• 行内展示 URL 时格式化为链接；
• 代码块使用正确的语法高亮；
• 终端命令使用 bash；
• 对 npm install、npx、npm run 命令块添加 npm2yarn 元数据，便于读者切换包管理器；
• 当文件路径重要时，为代码块添加 title；
• 只有当行高亮能引导读者关注相关改动时才使用它。

页面类型：按读者任务选择结构

在 STYLEGUIDE.md 之上，DOC.md 进一步定义了产品文档（位于 docs/src/content/en/docs）的四种页面模式：

• Overview（概览页）：定义某个类别（如 agents、memory、authentication、deployment、storage）包含什么、不包含什么，解释主要选择，帮助读者决定从哪里开始，并链接到最有用的聚焦页面和参考材料；适合的结构包括能力列表、决策表、CardGrid、IntegrationGrid、架构图、快速上手等。注意不要把概览页写成所有子页面的复制品。
• Focused concept（聚焦概念页）：解释一个连贯的能力、行为或心智模型；说明概念是什么、为什么重要、何时使用，必要时展示用法，并覆盖相关行为、约束与权衡。
• Setup or configuration（设置与配置页）：从受支持的配置方式开始，解释会影响行为的默认值与持久化边界，并区分本地开发假设与生产环境要求。
• Task-oriented（任务导向页）：从已知起点把读者带到可验证的结果；快速上手（Quickstart）是其中一种以最快受支持路径到达可用结果的形式，应优先采用仓库默认配置，并说明生成的命令或文件会创建什么。

DOC.md 同时强调：这些是写作模式而非强制模板，只要结果仍然连贯，一个页面可以组合多种模式。

信息架构：内容的规范归属

INFORMATION_ARCHITECTURE.md 规定了四种内容家族（content families）及其源目录：

表面（Surface）	源目录	用途
/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；主要讲解 Mastra 如何与外部产品或生态协作归 /integrations；读者需要精确签名、选项、返回值、事件、命令或类型细节归 /reference。页面结构（如任务导向）不决定归属，位置取决于所有权。

写新页面前应遵循的规范归属流程是：搜索所有内容家族中的概念及其旧名称 → 找出应保持规范（canonical）的页面 → 当受众与意图匹配时把缺失信息补到该页 → 合并或重定向重叠页面，而不是保留平行解释 → 把穷尽的 API 细节链接到参考材料。不要因为侧边栏有另一个看似合理的分类就创建第二个页面。

侧边栏方面，docs/src/content/en/docs/sidebars.js 拥有主文档导航与上下文分类，集成与参考侧边栏分别拥有各自的分类、排序与图标元数据；以 _ 开头的文件是部分内容或支持文件，不是公开路由候选。

共享组件：CardGrid 到 llms-txt 控件

COMPONENTS.md 规定了文档中可复用的共享组件（位于 docs/src/components），使用它们可以保证视觉一致性和 llms-txt 提取的正确性：

• CardGrid / CardGridItem：用于当前页面精心挑选的目的地集合，不要手写卡片边框、链接或网格布局；
• IntegrationGrid：当条目来自集成侧边栏时使用，支持 section、allowlist、blocklist、additionalItems、columns 等控制项，标签、路由、排序和图标以集成侧边栏为唯一事实来源，不要在 MDX 中复制这些元数据；
• Steps / StepItem：仅当读者必须按顺序完成动作、且每个动作需要较多正文、代码或警示时使用；短步骤用 Markdown 有序列表即可；
• Tabs / TabItem：用于互斥的替代选择（如包管理器、运行时、框架），共享设置放在标签之外，不要把顺序指令藏在标签里；
• PropertiesTable：用于结构化的 API 参数、属性、配置与嵌套类型，嵌套参数组通过 parameters 字段放在带 type 的条目内；
• CopyPrompt：当页面提供一段可让 AI 编码工具跟随的自包含提示词时使用，提示应指明预期结果、相关文件和约束，但不得替代可读的人类指令；
• Inject：用于简短、必要的指令，专门帮助 AI Agent 应用周边文档，普通页面内容对人类读者保持完整。

llms-txt 控件方面：给渲染控件或界面文本添加 data-llms-ignore，使其不出现在提取出的文档中；扩展卡片标记时保留 data-slot="card-grid"、data-slot="card"、data-slot="card-title"；优先使用语义化 HTML（如 ul、li）；修改提取感知标记后要测试生成的章节。

**Admonitions（警示框）**只有四种语义：note（范围、兼容性或支撑上下文）、warning（可能的失败模式、安全问题或破坏性后果）、danger（严重且迫在眉睫的风险）、beta（明确标记为 Beta 的功能）。日常指令不要放进警示框。

参考页与集成页的专门规范

REFERENCE.md 适用于 docs/src/content/en/reference 下的 API、配置、CLI、类型与查找页，目标是让精确行为和配置容易找到、完整记录公开契约。其要点包括：按主题选择结构（类或工厂、独立函数或方法、选项或配置对象、返回值/事件/流/结果类型、CLI 命令、包或子系统概览、迁移参考）；标题模式为 Reference: $NAME | $CATEGORY；开头用一两句说明 API 做什么、何时使用，需要时用最小用法示例帮助读者定位；参数用 PropertiesTable 呈现；方法签名用反引号标题（如 ### `methodName(value, options?)` ）；不明显的返回类型要声明 Returns: $TYPE；CLI 参考页需包含语法、参数与选项、默认值、必需的构建或初始化状态、环境变量、重要副作用和常见调用示例；事件、流与结果对象要记录对象形状、判别字段、各变体发生时机、顺序或生命周期保证、完成与错误行为。

GUIDE_INTEGRATION.md 适用于集成页，目标是从所需起点把读者带到可用结果。常见标题模式是 $PRODUCT | $SIDEBAR_CATEGORY，H1 用产品或集成名。集成页没有统一的强制章节顺序：功能导向的结构用于相互独立的能力，任务序列用于动作依赖前置设置的情况。不同集成类别有各自的常规覆盖范围，例如框架类通常覆盖创建/打开项目、初始化 Mastra、连接路由与代码、运行验证、框架特定的部署或运行时约束；渠道类覆盖服务与凭证前提、提供商注册、传输/Webhook/轮询设置、存储或记忆需求、消息处理与平台限制、具体的收发测试方式；数据库与存储类覆盖 Mastra 接口、包安装与客户端初始化、注册、连接/模式/索引要求、持久化与部署约束。部署集成页还要覆盖运行时、持久化、网络、安全与可观测性约束，并要求在公开 Mastra 端点或 Studio 前启用认证、在警示框中说明禁用签名验证等风险、通过端点、健康检查或仪表盘验证部署结果。

图表规范：Mermaid 的形状语义

DIAGRAM.md 规定文档图表一律使用 Mermaid，通过 docs/src/theme/Mermaid 渲染。其核心思想是形状承载语义，即使在灰度打印或色盲读者眼中也成立，因此不同职责的节点绝不共用形状：

1. 节点开始或结束一次运行 → 圆形 (( start ))；
2. 等待人工输入 → id@{ shape: manual-input, label: "..." }；
3. 读写存储数据 → id@{ shape: cyl, label: "..." }；
4. 条件分支 → 菱形 {approved?}；
5. 其余是工作单元 → 圆角矩形 ([step1])。

边（edge）分两种：实线 --> 表示工作流自行推进；虚线 -.-> 表示工作流外部先要发生的事情（人工回复、事件到达、定时器触发）。边的标签用引起转换的 API 名（如 suspend、resume、out），而不是对其的描述，这样读者对照代码时能找到同一个词。

颜色只用于结果，使用三个语义类名而不用具体颜色：accent（运行成功完成）、pending（阻塞、等待外部事物）、danger（停止、拒绝或失败）。图中严禁使用十六进制颜色、style、classDef、linkStyle 以及 var(--token)，否则会破坏浅色/深色主题或导致渲染失败。布局上：优先声明主路径（第一条链会成为主轴）、使用 flowchart LR、节点上限为 8 个、超过 16 字符的标签用 <br/> 换行。每个图都必须同时提供 accTitle 和 accDescr，替代图片的 alt 文本，屏幕阅读器用户才能获取信息。

编辑、移动、删除与验证工作流

AUTHORING_WORKFLOW.md 把文档变更固化成一条可执行的工作流，并提供了仓库脚本支持：

准备变更：应用 STYLEGUIDE 检查源码准确性与写作；用 INFORMATION_ARCHITECTURE.md 找到规范归属与重叠页面；阅读页面、相邻页面和相关侧边栏；检查快速变化的子系统近期历史。

移动页面：在 docs/ 下运行 scripts/move-doc.ts：

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 入链和重定向。移动后要检查每个改动的链接锚文本、JSX href 与 link 目标、确认目的地路由符合内容归属、确认没有遗留旧链接，然后重新生成重定向并运行生产构建。

删除或合并页面：使用 scripts/delete-doc.ts：

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；脚本会更新入链、侧边栏、重定向和空的父级分类。删除后要确认关键信息已并入替换页、检查改写后的链接文本与锚点、必要时恢复被误删的侧边栏条目。

维护重定向：docs/vercel.redirects.json 是人工维护的事实来源，docs/vercel.json 是生成产物，由 scripts/generate-vercel-redirects.mjs 生成：

pnpm generate-vercel-redirects

生成器会拒绝重复的 source、拒绝重定向链、为符合条件的路由创建 /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

变更类型与最低检查的对应关系是：纯散文 MDX 只需格式化、Remark 与 Vale 检查；frontmatter 需格式化与 pnpm validate；侧边栏改动需格式化、validate 与构建；移动或删除需脚本测试、重定向、验证与构建；重定向需生成器测试、生成、验证与构建；MDX 组件或 llms-txt 处理器需聚焦的 Vitest 测试、格式化、验证与构建；主题或导航行为需聚焦的单元测试或 Playwright 测试与构建。生产构建是路由解析、MDX 编译和 llms-txt 生成的最终证明。

终审差异：交接前运行 git diff --check，确认只改动预期文件，检查是否有过时路由名、临时文本、调试输出和生成产物，并把页面与任务和源码发现做对比。

如何应用这套规范

在 Mastra 仓库中实际写作时，推荐的路径是：先通读 STYLEGUIDE.md 掌握全局规则，再根据页面归属选择 DOC.md、REFERENCE.md 或 GUIDE_INTEGRATION.md 作为页面级指导；写代码示例与结构时对照 COMPONENTS.md；画流程时对照 DIAGRAM.md；动路由与文件时走 AUTHORING_WORKFLOW.md 的脚本流程并以生产构建收尾。这套规范的价值在于：它把"写文档"从自由创作变成可检查、可验证的工程活动，同时通过 llms-txt 控件、可访问性要求与准确的源码证据，让文档同时服务于人类读者、搜索引擎与 AI 工具。