> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 开发

拥有 Mastra 项目后，就可以开始开发、运行和测试 Agent。

## 在本地运行 Mastra

查看 Agent 运行效果最快的方法是使用 [Mastra Studio](https://mastra.zisheng.pro/docs/studio/overview)。在项目根目录中，使用 [`mastra dev`](https://mastra.zisheng.pro/reference/cli/mastra) 启动 Studio 和本地开发 Server：

**npm**:

```bash
npx mastra dev
```

**pnpm**:

```bash
pnpm dlx mastra dev
```

**Yarn**:

```bash
yarn dlx mastra dev
```

**Bun**:

```bash
bun x mastra dev
```

在 [`http://localhost:4111`](http://localhost:4111) 打开 Studio，以测试 Agent 并检查其运行记录。

开发 Server 还会公开 Agent、Tool 和 Workflow 的 API。打开 [`http://localhost:4111/api`](http://localhost:4111/api) 浏览可用内容，然后使用 [Mastra Client](https://mastra.zisheng.pro/docs/server/mastra-client) 连接前端。

`src/mastra/` 目录中的更改会自动重启开发 Server，因此构建过程中无需手动重启。

## 使用 AI 构建

Mastra 提供 Skill 和 CLI，帮助 coding agent 编写高质量的 Mastra 代码。

### Mastra Skill

AI 模型掌握的 Mastra API 知识可能不是最新的。使用 [Mastra Skill](https://github.com/mastra-ai/skills) 为 coding agent 提供实现指导、最佳实践以及获取最新 Mastra 文档的说明。

手动安装 Skill：

**npm**:

```bash
npx skills add mastra-ai/skills
```

**pnpm**:

```bash
pnpm dlx skills add mastra-ai/skills
```

**Yarn**:

```bash
yarn dlx skills add mastra-ai/skills
```

**Bun**:

```bash
bun x skills add mastra-ai/skills
```

定期更新 Skill 以获取最新指导：

**npm**:

```bash
npx skills update mastra
```

**pnpm**:

```bash
pnpm dlx skills update mastra
```

**Yarn**:

```bash
yarn dlx skills update mastra
```

**Bun**:

```bash
bun x skills update mastra
```

> **备注:** 使用 [create mastra](https://mastra.zisheng.pro/docs) 创建项目时，该命令会自动安装 Mastra Skill，以便 coding agent 发现并使用它。

### Mastra CLI

使用 [`mastra` CLI](https://mastra.zisheng.pro/reference/cli/mastra) 为 coding agent 提供反馈循环，以测试更新并检查结果。CLI 让它能够访问 Agent、Workflow、Tool、Memory、Evals、Trace 和日志。

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

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

请记得安装 [Mastra Skill](#mastra-skill)，让 coding agent 学会使用 CLI。

## 项目结构

采用框架时，首要决策之一是如何组织项目。建议将框架代码放在 `src/mastra/` 下，并将相关原语分组到各自的文件或文件夹中。使用 `src/mastra/index.ts` 作为配置和注册这些原语的中心位置。

最小项目可以采用以下结构：

```text
src/
  mastra/
    agents/
      agent.ts
    tools/
      tool.ts
    workflows/
      workflow.ts
    scorers/
      scorer.ts
    skills.ts
    index.ts
```

有关默认布局和推荐约定，请参阅[项目结构参考](https://mastra.zisheng.pro/reference/project-structure)。

## 基于文件的 Agent

> **Beta:** 基于文件的 Agent 目前处于 beta 阶段，在稳定之前可能会发生变化。
>
> 基于文件的发现仅通过 `mastra dev` 或 `mastra build` 运行。如果应用直接导入 `mastra`（包括通过 Web 框架或 Server 适配器导入），则不会发现基于文件的 Agent。请在代码中注册这些 Agent，或将 Mastra 作为独立 Server 运行。

> **📹 观看:** [如何创建第一个基于文件的 Agent](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)

使用基于文件的 Agent 时，Mastra 会自动从 `src/mastra/` 下受支持的文件中[发现](https://mastra.zisheng.pro/reference/file-based-agents/config) Agent 和相关原语。你可以按照约定组织这些文件，而无需在 [`Mastra`](https://mastra.zisheng.pro/reference/core/mastra-class) 实例中逐个导入和注册原语。

文件系统会直接呈现项目结构，因此你和 coding agent 无需追踪代码中各部分的连接方式，也能了解项目如何组合在一起。

你可以在整个项目中使用基于文件的 Agent，也可以将其与代码中定义的原语并用，逐步采用。目前尚未支持所有 Mastra 功能或使用场景。

### 创建第一个 Agent

基于文件的 Agent 位于 `src/mastra/agents/` 下自己的目录中。要创建可运行的 Agent，请添加用于模型和运行时选项的 `config.ts` 文件，以及用于常驻提示词的 `instructions.md` 文件：

```text
src/mastra/agents/
  writing-assistant/
    config.ts
    instructions.md
```

目录名称会成为 Agent 的默认 `id` 和 `name`。在此示例中，Mastra 会将 Agent 注册为 `writing-assistant`。

```typescript
import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})
```

```markdown
Rewrite text clearly and concisely.
```

运行 `npx mastra dev`，打开 Studio，然后选择 `writing-assistant` 进行测试。

### 发现机制

Mastra 使用路径来发现基于文件的能力并为其命名。Agent 目录提供默认的 Agent `id` 和 `name`。例如，`tools/search_docs.ts` 会将 Tool 注册为 `search_docs`，而 `skills/style-guide.md` 会将 Skill 注册为 `style-guide`。扩展路径见下文。

### 扩展 Agent

当 Agent 需要更多功能时，添加相应文件或目录：

| 路径                                                                                                  | 添加的功能                   |
| --------------------------------------------------------------------------------------------------- | ----------------------- |
| [`tools/<tool-name>.ts`](https://mastra.zisheng.pro/reference/file-based-agents/tools)              | 模型可以调用的函数               |
| [`skills/<skill-name>.md`](https://mastra.zisheng.pro/reference/file-based-agents/skills)           | Agent 在相关情况下加载的详细指导     |
| [`memory.ts`](https://mastra.zisheng.pro/reference/file-based-agents/memory)                        | 对话历史记录和工作上下文            |
| [`workspace.ts` and `workspace/`](https://mastra.zisheng.pro/reference/file-based-agents/workspace) | 文件系统和 shell 访问权限        |
| [`subagents/<agent-id>/`](https://mastra.zisheng.pro/reference/file-based-agents/subagents)         | 父 Agent 可以委派任务的专用 Agent |

将每项能力放在使用它的 Agent 旁边。开发 Server 启动或重启时，Mastra 会发现并注册这些文件。

浏览[基于文件的 Agent 参考](https://mastra.zisheng.pro/reference/file-based-agents/config)，了解所有受支持的文件约定和配置选项。