Mastra 文档写作风格指南编写准确、易读、可检索的开发者文档【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是一个面向 AI 应用与 Agent 的现代 TypeScript 框架其官方文档库沉淀了一整套完整的写作规范。本文以仓库中 docs/styleguides/STYLEGUIDE.md 为骨架系统讲解这套文档写作风格指南从核心写作规则、事实准确性要求到任务导向的指令结构、代码示例与无障碍规范并延伸到页面类型、信息架构、文档组件、Mermaid 图表与验证工具链等配套指南。读完本文你将掌握为 Mastra 编写符合项目标准、易于人类阅读且能被搜索引擎、Agent 与 LLM 正确提取的开发者文档的完整方法。风格指南的定位与使用顺序Mastra 的文档写作规范由一组相互配合的指南文件组成全部位于 docs/styleguides/。STYLEGUIDE.md 是所有文档写作的默认写作指南使用规则是先阅读这份文件再阅读页面类型对应的特定指南。配套指南的分工如下指南文件适用范围STYLEGUIDE.md所有 Mastra 文档的默认写作规范DOC.mddocs/src/content/en/docs下的产品文档REFERENCE.mddocs/src/content/en/reference下的 API、配置、CLI、类型参考页GUIDE_INTEGRATION.mddocs/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。删除填充语如 Its important to note值得注意的是和 in order to为了。标点用逗号或句号代替 em dash长破折号。优先简单词用use而不是utilize用help而不是facilitate。语气中性、事实化不要搞笑、异想天开、谄媚或讲故事式叙述。代词规则需要时用you称呼读者指代产品时用Mastra绝不用we、us、our、ours不要使用I。时态与大小写用现在时标题使用 sentence case只有首字母和专有名词大写。收缩形式常用短语使用收缩形式如dont、doesnt、cant、isnt。删减弱词移除弱副词、weasel words含糊其辞的词、陈词滥调和冗长短语。句首限制不要以So、There is、There are开头句子。包容性措辞使用包容、性别中立、person-first人优先的措辞。缩写首次使用时写全称然后在括号中给出缩写。标题动名词当更清晰的动词短语可用时避免在标题中使用动名词。语态优先使用主动语态和祈使句指令。禁止的说法不要写Lets...或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在第一个动作之前陈述预期结果把前提条件放在第一个需要它的动作附近按依赖顺序呈现必需动作在引入可选分支或高级配置之前先达到一个可工作的结果包含一个命令、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源目录用途/docsdocs/src/content/en/docsMastra 概念、能力、设置、决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查找材料/modelsdocs/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-slotcard-grid、data-slotcard、data-slotcard-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: $TYPECLI 参考页需包含语法、参数与选项、默认值、必需的构建或初始化状态、环境变量、重要副作用和常见调用示例事件、流与结果对象要记录对象形状、判别字段、各变体发生时机、顺序或生命周期保证、完成与错误行为。GUIDE_INTEGRATION.md 适用于集成页目标是从所需起点把读者带到可用结果。常见标题模式是$PRODUCT | $SIDEBAR_CATEGORYH1 用产品或集成名。集成页没有统一的强制章节顺序功能导向的结构用于相互独立的能力任务序列用于动作依赖前置设置的情况。不同集成类别有各自的常规覆盖范围例如框架类通常覆盖创建/打开项目、初始化 Mastra、连接路由与代码、运行验证、框架特定的部署或运行时约束渠道类覆盖服务与凭证前提、提供商注册、传输/Webhook/轮询设置、存储或记忆需求、消息处理与平台限制、具体的收发测试方式数据库与存储类覆盖 Mastra 接口、包安装与客户端初始化、注册、连接/模式/索引要求、持久化与部署约束。部署集成页还要覆盖运行时、持久化、网络、安全与可观测性约束并要求在公开 Mastra 端点或 Studio 前启用认证、在警示框中说明禁用签名验证等风险、通过端点、健康检查或仪表盘验证部署结果。图表规范Mermaid 的形状语义DIAGRAM.md 规定文档图表一律使用 Mermaid通过 docs/src/theme/Mermaid 渲染。其核心思想是形状承载语义即使在灰度打印或色盲读者眼中也成立因此不同职责的节点绝不共用形状节点开始或结束一次运行 → 圆形(( start ))等待人工输入 →id{ shape: manual-input, label: ... }读写存储数据 →id{ shape: cyl, label: ... }条件分支 → 菱形{approved?}其余是工作单元 → 圆角矩形([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.tspnpm 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目标、确认目的地路由符合内容归属、确认没有遗留旧链接然后重新生成重定向并运行生产构建。删除或合并页面使用 scripts/delete-doc.tspnpm 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 工具。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考