第6章 Mastra 开发指南：本地运行与 AI 辅助构建

开发

拥有 Mastra 项目后，即可开始开发、运行和测试你的 agent。

本地运行 MastraDirect link

在 Mastra Studio 中查看 agent 运行状态是最快的方式。在项目根目录运行 mastra dev 命令，即可启动 Studio 和本地开发服务器：

npx mastra dev
pnpm dlx mastra dev
yarn dlx mastra dev
bun x mastra dev

访问 http://localhost:4111 打开 Studio，即可测试 agent 并查看其运行记录。

开发服务器还暴露了针对 agent、工具和 workflow 的 API。访问 http://localhost:4111/api 浏览可用接口，然后使用 Mastra Client 连接你的前端。

src/mastra/ 目录下的任何更改都会自动重启开发服务器，因此在开发过程中无需手动重启。

使用 AI 构建Direct link

Mastra 提供技能和 CLI，协助 coding agent 编写高质量的 Mastra 代码。

Mastra 技能Direct link

AI 模型可能不了解 Mastra API 的最新状态。利用 Mastra 技能可为 coding agent 提供实施指导与最佳实践，包括获取最新 Mastra 文档的指令。Coding agent 还可以与 Mastra Factory 交互。

手动安装技能的方法如下：

npx skills add mastra-ai/skills
pnpm dlx skills add mastra-ai/skills
yarn dlx skills add mastra-ai/skills
bun x skills add mastra-ai/skills

定期更新技能以获取最新指导：

npx skills update mastra
pnpm dlx skills update mastra
yarn dlx skills update mastra
bun x skills update mastra

使用 create mastra 创建项目时，该命令会自动安装 Mastra 技能，以便 coding agent 发现并使用它们。

Mastra CLIDirect link

使用 mastra CLI 为 coding agent 提供测试更新和检查结果反馈闭环。CLI 使其能够访问 agents、workflows、tools、memory、evals、traces 和 logs。

例如，coding agent 可以运行 agent，然后拉取 traces 检查结果：

npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
npx mastra api --url http://localhost:4111 trace list

记得先安装 Mastra skills，让编码智能体学会使用 CLI。 项目结构 采用框架时首先要决定的问题之一就是项目怎么组织。我们建议把框架相关代码放在 src/mastra/ 目录下，相关的原语按各自文件或文件夹分组，并在 src/mastra/index.ts 中统一配置和注册。 一个最简项目大概长这样： src/
mastra/
agents/
agent.ts
tools/
tool.ts
workflows/
workflow.ts
scorers/
scorer.ts
skills.ts
index.ts
默认布局和推荐约定请参考项目结构文档。 基于文件的 agent 注意：基于文件的发现机制只能在 mastra dev 或 mastra build 时运行。如果你的应用直接导入 mastra（包括通过 web 框架或 server adapter），就无法发现基于文件的 agent。这种情况请在代码中注册这些 agent，或者把 Mastra 作为独立服务运行。 📹 观看：如何创建你的第一个基于文件的 agent 使用基于文件的 agent 时，Mastra 会自动从 src/mastra/ 下符合约定的文件中发现 agent 及相关原语。你只需按约定组织文件，无需在 Mastra 实例上逐个导入并注册原语。 文件系统直接对应你的项目结构，这样你和编码智能体不用去追踪代码里的各种装配逻辑，就能明白整个项目是怎么组合起来的。 你可以在整个项目中使用基于文件的 agent，也可以与代码中定义的原语混合使用、逐步迁移。目前并非所有 Mastra 功能和使用场景都已支持。 创建你的第一个 agent 基于文件的 agent 存放在 src/mastra/agents/ 下的独立目录中。要创建一个可用的 agent，需要添加一个 config.ts 文件来配置模型和运行时选项，再加一个 instructions.md 文件存放常驻提示词： src/mastra/agents/
writing-assistant/
config.ts
instructions.md
目录名会作为 agent 的默认 id 和名称。在本例中，Mastra 会把这个 agent 注册为 writing-assistant。 src/mastra/agents/writing-assistant/config.tsimport { agentConfig } from '@mastra/core/agent'

export default agentConfig({
model: 'openai/gpt-5.6-sol',
})
src/mastra/agents/writing-assistant/instructions.mdRewrite text clearly and concisely.
在终端运行 `npx mastra dev`，打开 Studio，选择 writing-assistant 进行测试。 How discovery works Mastra 通过文件路径来发现并命名基于文件的能力。Agent 目录提供默认的 agent id 和名称。例如，tools/search_docs.ts 会将工具注册为 search_docs，而 skills/style-guide.md 会将技能注册为 style-guide。相关扩展路径见下文。 Extend your agent 当 agent 需要更多功能时，可以添加文件或目录： tools/.ts — 模型可调用的函数 skills/.md — agent 在相关场景下加载的详细指引 memory.ts — 对话历史和上下文信息 workspace.ts 及 workspace/ — 文件系统和 shell 访问权限 subagents// — 父 agent 可委派任务的专职子 agent 每项能力应放置在使用它的 agent 旁边。Mastra 在开发服务器启动或重启时会发现并注册这些文件。 查阅基于文件的 agents 参考文档，了解所有支持的文件约定和配置选项。