企业官网建设流程全解析

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

【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra

Mastra 是一个用 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 文档共用的底线。

在它之后，还有一组页面专属指南：

写作顺序固定：先按 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 条细则，可归纳为"避免什么"和"坚持什么"两组。

必须避免的写法

必须坚持的写法

• 句子与段落长度交错变化，避免"主题句 + 三个支撑点 + 结论"的八股公式
• 连续段落或句子不要以同一个词开头
• 去掉结论式收尾：页面完成使命就结束
• 直接陈述观点，不绕弯、不铺垫修辞
• 需要时用you称呼读者；用You can...表示许可或可选操作；You should...只用于描述预期结果
• 用现在时写给读者
• 标题与标题层级使用 sentence case（仅首字母大写）
• 常见短语使用缩写形式，如 don't、doesn't、can't、isn't
• 使用包容、性别中立、以人为主的措辞（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作为 title，description 写"读者将理解或完成什么"，然后 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 title="src/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 作为链接格式化
• 代码块使用正确的语法高亮
• 终端命令用bash
• npm 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 URL：

pnpm 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。

按变更类型选择最小验证集

不同性质的变更对应不同的最低检查项：

docs/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）：

选 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.md）：

<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, }, ], }, ], }, ]} />

写前自检清单

综合 STYLEGUIDE 与配套指南，一篇合格 Mastra 文档的最终检查项可以浓缩为：

1. 事实：每个技术论断都有实现、公共类型、包导出或测试依据；导入路径、选项名、默认值、返回值、环境变量与版本要求均已确认。
2. 归属：页面放在了正确的 content family；没有与既有页面重复，重叠内容已合并或重定向。
3. 结构：围绕读者的问题或任务组织；任务导向页面先给结果再给动作；结尾不加祝贺语。
4. 文风：无 AI 味词汇、无填充语、无 em dash；用you称呼读者、以 Mastra 指代产品；sentence case 标题；主动语态。
5. 链接：全部为根相对路径；链接到规范路由而非重定向源；链接文本有描述性。
6. 代码：示例完整、包含 imports 与文件路径、使用受支持的包版本；代码块带title；npm 命令块加npm2yarn。
7. 验证：按变更类型运行最小检查集（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/scripts（move-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