Mastra 文档工程化指南从写作规范到自动化验证的完整文档编写工作流【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是面向 AI 应用与 Agent 的现代 TypeScript 框架其开源仓库将文档本身也视为一套可工程化的系统从写作风格、信息架构、页面结构到 Mermaid 图表、共享 MDX 组件、重定向与构建验证全部沉淀为位于 .claude/skills/mastra-docs 的规范文件与可执行脚本。本文以该技能包为骨架逐层拆解这套规范体系并给出对应的仓库实现证据帮助你理解如何在本仓库中编写、组织、迁移并验证高质量文档也能作为其他项目建立文档工程实践的参考模板。文档技能包的整体架构SKILL.md 是整个文档体系的入口它定义了这套技能的使用场景创建、编辑、移动、删除或审查 Mastra 文档、侧边栏、重定向与文档组件时都应遵循它。SKILL.md 本身很短核心价值在于它建立了一个按需取用的引用索引STYLEGUIDE.md全局写作、准确性、链接、代码与可访问性规则INFORMATION_ARCHITECTURE.md内容家族、规范所有权、侧边栏与路由按页面类型选择指南DOC.md 适用于/docs下的页面GUIDE_INTEGRATION.md 适用于/integrations下的页面REFERENCE.md 适用于/reference下的页面COMPONENTS.md共享 MDX 组件与 llms-txt 标记DIAGRAM.mdMermaid 图表的形状、颜色、布局、标签与可访问性约定AUTHORING_WORKFLOW.md编辑、移动、删除、重定向与验证流程。值得注意的是SKILL.md 明确指出页面模式是指导而非固定模板Treat page patterns as guidance rather than fixed templates并强调优先遵循当前分区中最具体的AGENTS.md。这意味着一套规范体系要能落地靠的不是把模板机械套用而是让规范与真实分区docs、integrations、reference一一对应。当需要把已有的示意图替换为 Mermaid 时SKILL.md 还指向独立的docs-diagrams技能体现了技能包之间的职责拆分。全局写作规范准确、直接、为读者而写STYLEGUIDE.md 是默认写作基线在阅读任何页面级指南之前都应先读它。核心规则与准确性要求写作上要求清晰直接短句、短段落、简单词汇、低术语密度并用标题、列表、表格、图表或示例拆解密集文本结构上围绕读者的问题或任务组织页面而不是套固定模板。准确性是硬约束技术论断必须对照实现、公开类型、包导出与测试验证既有文档只是上下文不能当作行为仍然有效的证明能跑通的示例尽量实测必须包含当前 API 所需的配置不要照抄旧示例确认导入路径、选项名、默认值、返回值、环境变量与版本要求。例如文中要求确认包导出与测试在本仓库中docs 脚本确实有对应的测试支撑generate-vercel-redirects.test.ts 就是规范中用测试证明行为的直接体现。写作风格细则风格要求相当具体甚至给出了AI 写作指纹词清单要求避免delve、tapestry、multifaceted、leverage、foster、underscores、comprehensive、robust等词同时删除 Its important to note、in order to 之类的填充语。其他要点包括用逗号或句号不用破折号优先简单词use而非utilize保持中立、事实性语气不幽默、不煽情、不故事化每页自包含需要时用you称呼读者产品一律称Mastra不用we/us/our不用I用现在时与主动语态标题使用 sentence case常用缩写写作dont、cant删除弱副词、含糊措辞、陈词滥调不以So、There is、There are开头首次出现缩写时写全称再括注不用Lets...或Next, we will...用Ensure而非make sure极少使用感叹号不用 Alpha 标记早期功能需要标记时用 Beta。任务导向的写作顺序STYLEGUIDE 规定任务型页面的写作顺序先说明预期结果再给出第一步操作把前置条件放在首次需要它的动作附近按依赖顺序呈现必需动作先给出可运行的成果再引入可选分支或高级配置最后要包含能验证结果的命令、URL、界面动作或预期输出。这保证了每一篇任务型文档都有可验证的终点而不是讲完就结束。链接、UI 术语与代码示例链接方面要求API 或概念首次出现时若存在规范页面就链接它新标题下再次出现时只在读者可能从该节进入时再链一次同一节内不重复同一引用使用根相对内部链接链接到最终规范路由而非重定向源链接文字要可描述且路由迁移后仍自然可读。UI 术语方面界面标签、标题、区段名用加粗用select或open不用click除非必要否则不写buttonUI 界面用open而非appears。代码示例要求先一句话说明用途在读者需要的位置给出完整代码创建或替换文件时包含导入与文件路径只解释不显然的部分示例前后保持一致注释不要复述下一行。标题、列表与可访问性标题规范H1 是页面标题新章节从 H2 开始标题要短且描述读者将理解、配置或完成的内容标题不以标点结尾标题中的代码用等宽格式函数名用反引号包裹不为凑模板强加标题。列表规范顺序无关用无序列表必须按序执行用有序列表过长的多段落列表项改用标题或Steps标签与描述之间用冒号而非破折号完整句列表项以句号结尾。可访问性上避免just、easy、simple、hard、beginner、senior这类评判难度的词首次使用行话时定义或链接可信解释装饰性图片用空 alt 文本。代码格式则要求代码、命令、文件名、环境变量和字面 URL 用等宽格式代码块用正确的语法高亮终端命令用bash标记npm/npx/pnpm 命令块加npm2yarn元数据文件路径重要时给代码块加title。信息架构为内容找到唯一的家INFORMATION_ARCHITECTURE.md 解决内容应该放在哪里、由谁拥有的问题是避免文档重复和碎片化的关键。四个内容家族面源目录用途/docsdocs/src/content/en/docsMastra 概念、能力、配置、决策与聚焦用法/integrationsdocs/src/content/en/integrations外部产品、提供商、框架、渠道与部署目标/referencedocs/src/content/en/referenceAPI、配置、CLI、类型与查询材料/modelsdocs/src/content/en/models自动生成的模型与提供商信息禁止手工编辑信息架构文件特别提醒路由工具可能理解旧的内容家族以便维护重定向但这种兼容性并不代表旧路由家族是新增页面的正确归宿。选择页面归属判断归属遵循三个原则当 Mastra 拥有该概念或该决策属于读者时用/docs例如 Agent、工作流、记忆、存储、Studio、认证、部署概念当页面主要解释 Mastra 如何与外部产品或生态协作时用/integrations例如框架、数据库、可观测性导出器、渠道、浏览器提供商、认证提供商、部署平台当读者需要精确签名、选项、返回值、事件、命令或类型细节时用/reference。关键判定是页面结构不决定其内容家族一个任务导向页面既可以放在/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 或内容所有权以_开头的文件是片段或支持文件不是公开路由候选。路由命名要求使用小写、描述性的路由段优先稳定的产品概念而非临时功能标签或侧边栏组名同级页面共享命名空间时用overview.mdx作为分类落地页一个主题只保留一条规范路由并把历史路由重定向到它避免链式重定向重定向目标必须是最终规范页面合并聚焦页面到更大页面时保留有用的章节锚点。最后路由、组件、frontmatter 与页面结构会影响生成的 llms-txt 与嵌入文档输出这一点在 COMPONENTS.md 中会有更细的约定。三类页面指南docs、integrations 与 reference/docs 页面DOC.mdDOC.md 用于docs/src/content/en/docs下的产品文档定义了四类页面模式Overview概览定义分类、解释关键选择、路由读者到聚焦材料用于 Agent、记忆、认证、部署、存储等分类落地页。概览页应定义分类包含什么、不包含什么解释主要选择或子主题帮助读者决定从哪开始链接最有用的聚焦页面与参考材料包含分类级约束或前置条件并在需要时提供一条简短的可行路径。建议结构包括能力清单、决策表、CardGrid、IntegrationGrid、图表或架构说明、快速开始与简短分类区段。但要避免把概览写成所有子页的复制品Focused concept聚焦概念解释一个连贯的能力、行为或心智模型。应说明概念是什么、为何重要必要时解释何时使用概念涉及代码或配置时给出用法并覆盖相关行为、约束与权衡对详尽选项链接到精确的 API 参考页Setup or configuration配置帮助读者启用并配置 Mastra 自有功能。从受支持的配置开始解释影响行为的默认值与持久化边界区分本地开发假设与生产需求Task-oriented任务导向从已知起点带读者走向可验证结果。快速开始是其中最短的形式应优先仓库默认而非解释每个选择说明生成命令或文件创建了什么概念解释保持简短并链接到更深的文档。DOC.md 为每种模式给出了建议的 MDX 骨架例如聚焦概念页的 frontmatter 使用title: $FEATURE | $CATEGORY、description与packages字段正文建议形态是定义功能与作用 → 何时使用 → 配置示例带typescript titlesrc/mastra/path.ts的完整代码块→ 行为或约束 → Related。标题通常遵循$FEATURE | $CATEGORY模式H1 应直接命名主题。/integrations 页面GUIDE_INTEGRATION.mdGUIDE_INTEGRATION.md 用于所有docs/src/content/en/integrations下的页面目标是解释 Mastra 特有的集成路径从必需起点带读者到可用结果并覆盖该路径所需的提供商特定配置与行为。集成页面没有强制的小节顺序功能相互独立时用功能导向结构动作依赖前置配置时用 STYLEGUIDE 的任务序列。常见 frontmatter 模式是$PRODUCT | $SIDEBAR_CATEGORYH1 用产品或集成名标题不要加Using、Deploy Mastra to之类固定前缀。新增或重命名集成时更新docs/src/content/en/integrations/sidebars.js。指南还按类别给出了通常覆盖的内容清单框架类创建/打开项目、初始化 Mastra、连接路由与代码、运行验证、部署约束、渠道类服务与凭据前置、提供商注册、传输/webhook/轮询设置、存储或记忆要求、消息处理与平台限制、可验证的收发测试、数据库与存储提供商实现的 Mastra 接口、包安装与客户端初始化、注册、连接/模式/索引要求、持久化与部署约束、可观测性集成导出器或桥选择、凭据与环境变量、注册、支持的信号、缓冲/刷新/配额/无服务器行为、在目标产品中验证、认证提供商提供商侧应用设置、回调 URL 与凭据、注册、Studio 与 API 路由行为、会话/令牌约束、受保护路由验证等。部署集成/integrations/deploy有专门章节将可运行的 Mastra 应用部署到一个受支持目标覆盖运行、持久化、网络、安全与可观测性约束标题模式是$PLATFORM | Deploy。当 Mastra 提供mastra/deployer-*包时应覆盖包安装、在 Mastra 配置中注册、生成输出或构建行为、平台连接与部署、可选 deployer 覆盖与对应参考页当读者通过框架适配器或既有服务器部署时覆盖受支持的构建与启动命令、服务端适配器或框架要求、路由前缀与公开端点、环境变量、平台配置文件、进程与文件系统假设容器/基础设施部署则覆盖构建产物、容器命令与暴露端口、健康检查、持久存储与外部服务、入口与认证、扩展与进程角色约束、优雅关闭等。平台约束一节要求逐一说明无服务器进程终止、冷启动、临时文件系统等对 Mastra 行为的影响并陈述后果与必要动作。部署安全与验证要求公开暴露 Mastra 端点或 Studio 前必须先认证文档化秘密与令牌要求但不展示真实凭据禁用签名验证、公开回调或过宽 Studio 访问要放进警告通过端点、Studio 路由、工作流运行、健康检查、日志或平台仪表盘验证部署并说明预期结果。/reference 页面REFERENCE.mdREFERENCE.md 用于docs/src/content/en/reference下的 API、配置、CLI、类型与查询页面目标是让精确行为与配置易于查找并把公开契约完整记录到可实现的程度概念解释与任务指引链接到 docs 页面。参考页类型可选择类或工厂、独立函数或方法、选项或配置对象、返回值/事件/流/结果类型、CLI 命令、包或子系统概览、迁移参考。一个参考页可以记录一个原语或紧密相关的 API 面不要把读者查找时需要放在一起的信息拆散。常见 frontmatter 模式是Reference: $NAME | $CATEGORY函数在标题中带括号符合惯例时保留括号H1 直接使用类、命令、类型或子系统名只有最小包版本重要时才在 H1 后立即加**Added in:**。开头先写 API 的功能与使用时机在读者需要取舍时链接替代 API开头附近放最小可用示例帮助读者定位纯签名或查询页可以直接从参数、语法或命令用法开始。参数、属性与选项用PropertiesTable结构化呈现见 COMPONENTS.md每条含name、type、description源码支持时补充可选、默认与嵌套字段。方法与函数用反引号签名作标题记录用途、参数、返回值、抛出的错误与重要失败行为、副作用/生命周期/持久化行为与不易看懂的示例返回类型不明显时写Returns: $TYPE自定义返回对象用接口、表格或链接类型参考记录。CLI 参考需包含语法、参数与选项、默认值、所需构建或初始化状态、环境变量、重要副作用与常见调用短例任务走查保留在/docs或/integrations并链接过去。事件、流与结果对象要记录对象或事件形状、判别字段、各变体出现时机、排序或生命周期保证、完成与错误行为。大篇幅类参考可以交替使用用法与领域专属章节但标题要可预测且避免同一选项多处重复。参考页只记录公开导出与受支持契约迁移与兼容性说明紧贴受影响 API。共享 MDX 组件与 llms-txt 标记COMPONENTS.md 规定使用共享组件因为它们编码了既定的文档与提取模式。写文档前应检查docs/CONTRIBUTING.md与既有用法引入新标记前先确认没有现成方案。CardGrid/CardGridItem用于当前页面拥有标签、描述与顺序的精选目标集合从site/src/components/cards/card-grid导入columns可设列数。不要手写卡片边框、链接或栅格布局共享组件提供一致的视觉行为与 llms-txt 提取所需的 card-grid 数据槽IntegrationGrid条目来自docs/src/content/en/integrations/sidebars.js时使用从site/src/components/integrations/grid导入。可用控制包括section集成侧边栏分类、allowlist按请求顺序包含条目、blocklist排除条目、additionalItems没有独立集成页的侧边栏形条目与columns三或四列布局。集成侧边栏是标签、路由、排序与图标的唯一事实来源不要在 MDX 中复制这些元数据Steps/StepItem读者必须按序完成动作且每个动作需要大量散文、代码或提醒时使用简短步骤用 Markdown 有序列表即可不要仅仅为了让无关章节看起来像流程而使用StepsTabs/TabItem用于互斥的替代方案包管理器、运行时、框架、后端选择共享设置放在标签外不要把顺序指令藏进标签也不要创建读者需要同时比较两个示例的标签PropertiesTable用于结构化 API 参数、属性、配置与嵌套类型。嵌套参数组把parameters放进带type的条目内每个条目含name、type、description可选加isOptionalCopyPrompt页面提供可让 AI 编码工具遵循的自包含提示词时使用提示词应指明预期结果、相关文件与约束但不能替代可读的人类指令Inject用于简短、必要、专门帮助 AI Agent 应用周围文档的指令正常页面仍要为人类读者保持完整。llms-txt 控制是这套体系面向 LLM 时代的重要设计用data-llms-ignore标记不应出现在提取文档中的渲染控件或界面文本扩展被 llms-txt 插件识别的卡片标记时保留data-slotcard-grid、data-slotcard、data-slotcard-title能准确表达内容时优先语义 HTML如ul/li修改提取感知的标记后测试生成的分区。本仓库的 EditThisPage/index.tsx 等主题组件即属于此类需要与 llms-txt 输出保持一致的界面代码。Admonitions方面note用于范围、兼容性或支撑上下文warning用于可能的失败模式、安全问题或破坏性后果danger用于严重且紧急的风险beta仅用于明确以 Beta 呈现的功能。常规指令不要放进 admonitions。Mermaid 图表规范形状、颜色与可访问性DIAGRAM.md 规定文档中的图表一律用 Mermaid 编写在mermaid代码围栏中通过src/theme/Mermaid/渲染该主题提供颜色、字体与布局引擎图表内不得重复这些设置。选形状按顺序匹配第一个命中节点开始或结束一次运行 → 圆形(( start ))等待人工 →id{ shape: manual-input, label: ... }读写存储数据 →id{ shape: cyl, label: ... }按条件分支 → 菱形{approved?}其余为工作单元 → 圆角矩形([step1])。形状承载的意义要能在灰度打印和色盲读者面前存活两个职责不同的节点绝不共享同一形状。选边实线--表示工作流自行推进虚线-.-表示工作流之外必须先发生某事人工回复、事件到达、定时器触发。边用引发转换的 API 名标注suspend、resume、out而不是对它的描述让读者在图表与下方代码之间看到同一个词。用色只有三个语义类accent运行成功完成、pending阻塞等待外部、danger停止、拒绝或失败。节点通过class node name取类边通过以类名前缀的 id 取类。只给结果上色普通路径保持中性这样图表变大后彩色部分仍有含义。布局先按源码顺序声明主路径再声明分支ELK 会把读到的第一条链当作主干flowchart LR是默认方向仅当八个节点的图在手机上超宽时改用TB超过八个节点就拆分图表或改用散文。禁止在图表中设置layout:或look:站点全局使用 ELK。标签小写API 大写处除外超过 16 字符用br/换行因为 Mermaid 按标签缩放节点单个长标签会让节点压倒其余部分。可访问性每个图表都要带accTitle与accDescr代替图片原本应有的 alt 文本。禁止事项十六进制颜色、style、classDef、linkStyle无法跟随明暗主题任何位置的var(--token)Mermaid 解析器会拒绝(-导致页面渲染失败重复上文已经说过的图表。当节点位置本身承载意义而自动布局会破坏它或主题是截图时保留图片而不是改用 Mermaid。文档维护工作流移动、删除、重定向与验证AUTHORING_WORKFLOW.md 把文档的增删改迁变成一套可重复、可验证的流程与本仓库 docs/scripts 中的脚本一一对应。准备变更应用 STYLEGUIDE 核对源码准确性与写作用 INFORMATION_ARCHITECTURE 找到规范所有者与重叠页面阅读目标页、相邻页与相关侧边栏页面或子系统变化快时检查近期历史必要时阅读对应页面指南与 COMPONENTS.md。用仓库脚本移动页面在docs/下执行脚本源码见 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目标确认目标路由与内容家族匹配确认没有遗留旧的自撰链接重新生成重定向并跑一次生产构建。删除或合并页面同样在docs/下执行脚本源码见 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脚本会更新入站链接、侧边栏、重定向并在适用时清理空的父分类。删除后要确认关键信息已并入替换页、复查改写后的链接文字与锚点、若删除子页连带删除了空分类则恢复预期侧边栏条目、重新生成重定向并跑生产构建。维护重定向vercel.redirects.json是自撰的事实来源vercel.json是生成产物。修改自撰重定向后运行pnpm generate-vercel-redirects生成器generate-vercel-redirects.mjs会拒绝重复来源、拒绝重定向链、为符合条件的/llms.txt创建伴生重定向并从生成的 llms-txt 目标中移除片段。这些行为都有对应测试覆盖例如 generate-vercel-redirects.test.ts 中的rejects duplicate authored sources与rejects redirect chains用例。注意绝不直接编辑生成的vercel.json只有任务包含仓库变更时才提交它。验证变更按变更类型选择最窄的检查集合纯散文 MDX 至少跑 MDX 格式化、Remark 与 Valefrontmatter 跑格式化与pnpm validate侧边栏在路由或导航变化时还要跑构建移动或删除要跑聚焦脚本测试、重定向、验证与构建重定向要跑生成器测试、生成、验证与构建MDX 组件或 llms-txt 处理器要跑聚焦 Vitest 测试、格式化、验证与构建主题或导航行为要跑聚焦单元或 Playwright 测试与构建。docs/下的常用命令pnpm format:mdx:check pnpm format:check pnpm lint:remark pnpm lint:vale:ai pnpm validate pnpm test pnpm build支持聚焦文件参数或聚焦测试文件时优先使用。生产构建是路由解析、MDX 编译与生成的 llms-txt 输出的最终证明。收尾时运行git diff --check确认只有预期文件被改动检查残留的路由名、临时文本、调试输出与生成产物对照任务与源码发现核对最终页面并把无关失败单独陈述而不是弱化或跳过检查。把规范落进日常文档工作这套体系的可贵之处在于写作规范STYLEGUIDE、信息架构INFORMATION_ARCHITECTURE、页面指南DOC / GUIDE_INTEGRATION / REFERENCE、组件约定COMPONENTS、图表约定DIAGRAM与维护流程AUTHORING_WORKFLOW六份文档互相咬合且每条规则都能在本仓库中找到对应物docs/src/content/en/{docs,integrations,reference}三大家族目录、各自的sidebars.js、docs/scripts下的移动/删除/重定向脚本及其测试、docs/src/theme/Mermaid渲染主题、以及面向 llms-txt 提取的data-slot与data-llms-ignore约定。对贡献者而言最简上手路径是改哪类页面就读哪份页面指南动结构就走脚本加验证涉及组件或图表再取用对应规范。对想建立自有文档体系的项目而言这套规范文件 可执行脚本 测试兜底的组合本身就是一份可以直接借鉴的工程蓝图。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考