Mastra 文档参考页写作规范编写可被精确检索的 API 与 CLI 参考文档【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 仓库的文档站点在docs/src/content/en/reference目录下维护着一套面向 API、配置、CLI 与类型的参考页Reference pages并配套发布了专门约束这类页面写作方式的风格指南 REFERENCE.md。本文以该指南为骨架结合仓库中真实的参考页如 Agent class、Agent.generate()、CLI commands与组件源码系统讲解参考页的类型划分、Frontmatter 规范、参数表格写法、方法签名、CLI 与事件对象文档的编写要点。读完本文你将掌握为 Mastra乃至任意开源项目编写行为精确、配置可查、便于实现工作直接引用的参考文档的完整方法论。参考页的定位让精确行为与配置一搜即得参考页Reference pages服务于docs/src/content/en/reference下的所有 API、配置、CLI、类型与查找类页面。与教程tutorial和概念文档concept不同参考页有三个核心目标让精确行为与配置容易找到读者带着这个参数到底接受什么类型、默认值是什么的问题而来页面必须在结构上直接给出答案完整记录公开契约文档的详尽程度要足以支撑读者直接依据文档完成实现工作而不必翻源码链接到概念文档概念解释和任务引导交给docs/src/content/en/docs下的页面参考页通过链接指向它们避免在参考页里展开长篇概念叙述。这一定位决定了参考页结构化、表格化、签名优先的写作风格能上表格的字段用表格能写签名的地方给反引号签名能用链接解决的概念讲解绝不在参考页里重复展开。选择参考页类型先定结构再动笔指南要求先根据主题选择匹配的结构共列出七类参考页| 类型 | 适用对象 | | - | - | | class or factory | 类与工厂函数如Agent类、createTool工厂 | | standalone function or method | 独立函数或方法如Agent.generate()| | options or configuration object | 选项与配置对象 | | return value, event, stream, or result type | 返回值、事件、流、结果类型 | | CLI command | 命令行命令 | | package or subsystem overview | 包或子系统总览 | | migration reference | 迁移参考 |一个参考页可以只记录一个原语primitive也可以覆盖紧密相关的 API 表面a tightly related API surface。关键约束是当读者需要把相关信息放在一起查找时不要强行拆开。例如 Agent class 一页同时覆盖了构造函数参数、线程信号方法、工具钩子与编辑覆盖因为这些内容属于同一类目下读者需要对照查阅的完整 API 表面。Frontmatter 与标题统一Reference: $NAME | $CATEGORY模式标题统一采用Reference: $NAME | $CATEGORY模式。以 Agent class 的 Frontmatter 为真实范例--- title: Reference: Agent class | Agents description: The Agent class is the foundation for creating AI agents in Mastra. It provides methods for generating responses and streaming interactions. packages: - mastra/core --- # Agent class要点归纳description 字段一句话说明该 API 的职责与受支持的配置直接服务于检索与摘要packages 字段声明 API 所属的 npm 包如mastra/core、mastra方便按包维度聚合参考页H1 直接使用类名、命令名、类型名或子系统名函数类页面当带括号是既定惯例时标题中保留括号如Agent.generate()见 generate.mdx 的# Agent.generate()版本标注只有当最低包版本确实影响读者时才在 H1 之后紧跟一行**Added in:**。对于长期存在的 API 以及初始版本已隐含的新包省略该标注。开头与用法示例先交代是什么、何时用每个参考页应以一段简短描述开头说明该 API 的用途与读者何时使用它当存在替代 API 需要读者抉择时应链接到替代方案。例如 Agent.generate() 开头即说明.generate()提供非流式响应生成接收消息与可选生成选项——这是与流式stream()并列时需要读者做出选择的关键信息。当最小示例有助于读者定位时应在靠前位置放置用法示例。示例遵循import 之后紧跟最小可用用法的结构import { Name } from mastra/package; // Minimal supported usage但也有一条反向约束不要为了塞示例而强行示例——如果示例在签名之外没有增加任何信息就不要放。纯签名页或查找页可以直接从参数、语法或命令用法开始。参数、属性与选项统一使用PropertiesTable结构化参数、属性与配置应使用PropertiesTable组件而不是手写 Markdown 表格。该组件在 COMPONENTS.md 中与参考页指南配套说明其受支持的对象形状以当前参考页为准。PropertiesTable的底层实现位于 PropertiesTable.tsx从源码可以看出它支持的结构能力每个条目包含name、type、description可选isOptional与defaultValue默认值会渲染为 value见 PropertiesTable.tsx通过properties字段递归嵌套子参数外层条目带type内层用parameters数组承载子字段见 COMPONENTS.md 中的嵌套示例description支持行内 Markdown反引号代码与链接组件内部通过正则拆分渲染见 PropertiesTable.tsx。以 generate.mdx 中的onIterationComplete为例它演示了三层嵌套回调函数类型 →IterationCompleteContext上下文 →context.text、context.finishReason、context.toolCalls等字段每个字段标注类型与用途。编写时对每个条目都应尽量给出name、type、description并在源码支持的前提下补充isOptional、defaultValue与嵌套字段。方法与函数反引号签名做标题每个方法或函数使用反引号签名作为小节标题### methodName(value, options?)为每个方法记录读者需要的信息目的共享表格未覆盖的参数返回值抛出的错误与重要失败行为副作用、生命周期或持久化行为以及当用法不显然时的示例。返回类型当返回类型不明显时显式声明Returns: $TYPE自定义返回对象用 interface、表格或链接的类型引用记录。例如 agent.mdx 中sendMessage()明确写返回{ accepted: PromiseSendAgentSignalAccepted, signal: CreatedAgentSignal, persisted?: Promisevoid }并逐个解释accepted在不同路由决策wake/deliver/persist/discard下的解析语义分组当按类目分组能改善查找体验时对方法分组但分组层级以恰好够用为准不要添加空的类目层级。CLI 参考语法、参数、默认值、环境变量与副作用CLI 命令参考页如 CLI commands应包含语法参数与选项默认值所需的构建或初始化状态环境变量重要副作用常见调用的简短示例。例如mastra dev一节就完整覆盖了作用与产物启动暴露 Studio 与 REST 端点的服务器各 flag--https、--inspect、--inspect-brk、--custom-args、--request-context-presets及其冲突约束如--inspect与--inspect-brk不能同时使用环境变量配置MASTRA_SKIP_PEERDEP_CHECK1跳过 peer 依赖检查、MASTRA_DEV_NO_CACHE1禁用构建缓存、MASTRA_CONCURRENCY限制并行度、OPENAI_BASE_URL/ANTHROPIC_BASE_URL自定义 provider 端点前置状态声明mastra start前必须先mastra build用 note 醒目标注。任务式走查task walkthroughs应保留在/docs或/integrations下CLI 参考页只链接过去不重复展开。环境变量、区域解析顺序环境变量 → CLI flag → 配置文件 → 凭据 → 交互式提示这类信息在 mastra.mdx 中均有逐条说明是 CLI 参考默认值与副作用的示范。事件、流与结果对象形状、判别字段与生命周期保证对于事件、流与结果对象需要记录对象或事件的形状判别字段discriminating fields每种变体何时出现顺序或生命周期保证完成与错误行为以及展示消费模式的指南链接。指南还给出了两条表达原则能力矩阵与稳定枚举用表格例如 mastra.mdx 中mastra experiment build的协议退出码用表格呈现0完成、10带条目错误完成、20致命失败、21可重试失败、30取消、31超时、70协议失败精确的对象形状用代码块例如Agent.generate()的返回对象中工具数组使用 Mastra 的 chunk 格式、数据包裹在payload中generate.mdx 用一段循环response.toolCalls与step.toolResults的代码展示了toolCall.payload.toolName、toolCall.payload.args的读取方式并链接到 ChunkType 参考 供流式版本对照。内容编排顺序以查找路径为第一优先级指南给出的通用顺序是usage用法→ parameters参数→ properties属性→ methods方法→ return values返回值→ domain-specific details领域细节。但顺序不是死的当读者需要先获得领域上下文或不同的查找路径时调整顺序。两条补充规则大型类参考可以在正式表格之间穿插用法与领域特定小节但要保持标题可预测避免同一选项在多处重复参考页的结构服务于读者能找到它要找的东西这个目标参考页索引页 index.mdx 通过卡片组件聚合各子系统入口因此页面自身的标题层级也应当保持稳定、可扫描。参考页特定规则指南在末尾给出三条硬性规则只记录公共导出与受支持的契约public exports and supported contracts内部实现细节不属于参考页职责迁移与兼容性说明紧贴受影响的 API放在该 API 所在小节内而不是集中堆砌在页面末尾当共享类型或行为发生变化时同步更新相关参考页——这是维护期文档质量的兜底约束。小结Mastra 的参考页写作规范本质上回答了一个问题如何让文档的精确信息密度足够高使读者能直接依据参考页完成实现工作。核心方法可以浓缩为四句话按主题选择七种页面结构之一并保持信息聚合用Reference: $NAME | $CATEGORY统一标题、用PropertiesTable统一参数呈现方法用反引号签名、CLI 覆盖语法/默认值/环境变量/副作用、事件对象交代判别字段与生命周期保证最后只记录公共契约、把兼容性说明放在受影响的 API 旁边。遵循这套规范产出的参考页既是开发者查参数的工具也是文档系统可被精确检索、引用和持续维护的契约层。如需进一步实践可对照 REFERENCE.md 阅读仓库内的真实参考页构造函数与信号方法参考 agent.mdx、执行选项与返回结构参考 generate.mdx、CLI 命令参考 mastra.mdx参数表格组件实现见 PropertiesTable.tsx。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考