企业官网建设流程全解析

Mastra 文档参考页写作规范：编写可被精确检索的 API 与 CLI 参考文档

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

Mastra 仓库的文档站点在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: Promise<SendAgentSignalAccepted>, signal: CreatedAgentSignal, persisted?: Promise<void> }，并逐个解释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_CHECK=1跳过 peer 依赖检查、MASTRA_DEV_NO_CACHE=1禁用构建缓存、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 通过卡片组件聚合各子系统入口，因此页面自身的标题层级也应当保持稳定、可扫描。

参考页特定规则

指南在末尾给出三条硬性规则：

1. 只记录公共导出与受支持的契约（public exports and supported contracts），内部实现细节不属于参考页职责；
2. 迁移与兼容性说明紧贴受影响的 API，放在该 API 所在小节内，而不是集中堆砌在页面末尾；
3. 当共享类型或行为发生变化时，同步更新相关参考页——这是维护期文档质量的兜底约束。

小结

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