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

# 開發

建立 Mastra 項目後，你便可以開始開發、運行及測試 Agent。

## 在本機運行 Mastra

要最快查看 Agent 的運作情況，可使用 [Mastra Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)。在項目根目錄中，使用 [`mastra dev`](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra) 啟動 Studio 和本機開發伺服器：

**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 並檢查其運行記錄。

開發伺服器亦會為 Agent、Tool 和 Workflow 提供 API。開啟 [`http://localhost:4111/api`](http://localhost:4111/api) 瀏覽可用內容，然後使用 [Mastra Client](https://mastra.zisheng.pro/zh-HK/docs/server/mastra-client) 連接前端。

當 `src/mastra/` 目錄內有變更時，開發伺服器會自動重新啟動，因此開發期間毋須手動重新啟動。

## 使用 AI 建構

Mastra 提供 Skill 和 CLI，協助編程助手編寫高質素的 Mastra 程式碼。

### Mastra Skill

AI 模型對 Mastra API 的認識未必是最新的。使用 [Mastra Skill](https://github.com/mastra-ai/skills)，為編程助手提供實作指引、最佳做法，以及取得最新 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/zh-HK/docs) 建立項目時，該命令會自動安裝 Mastra Skill，讓編程助手能夠找到並使用它。

### Mastra CLI

使用 [`mastra` CLI](https://mastra.zisheng.pro/zh-HK/reference/cli/mastra)，為編程助手建立測試更新和檢查結果的反饋迴圈。CLI 讓它能夠存取 Agent、Workflow、Tool、memory、Evals、Trace 和日誌。

例如，編程助手可以運行 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)，讓編程助手學會如何使用 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/zh-HK/reference/project-structure)。

## 以文件為基礎的 Agent

> **Beta:** 以文件為基礎的 Agent 目前處於 beta 階段，在穩定版本推出前可能會有變更。
>
> 以文件為基礎的探索功能只會透過 `mastra dev` 或 `mastra build` 運行。如果應用程式直接匯入 `mastra`（包括透過網絡框架或伺服器適配器匯入），便不會找到以文件為基礎的 Agent。請在程式碼中註冊這些 Agent，或將 Mastra 作為獨立伺服器運行。

> **📹 觀看影片:** [如何建立第一個以文件為基礎的 Agent](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)

使用以文件為基礎的 Agent 時，Mastra 會自動從 `src/mastra/` 下受支援的文件中[找到](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/config) Agent 和相關基本元件。你可按慣例組織這些文件，毋須逐一匯入每個基本元件並在 [`Mastra`](https://mastra.zisheng.pro/zh-HK/reference/core/mastra-class) 實例上註冊。

文件系統會直接呈現項目結構，因此你和編程助手毋須追查程式碼中各部分的連接方式，也能了解項目如何組合起來。

你可以在整個項目中使用以文件為基礎的 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/zh-HK/reference/file-based-agents/tools)            | 模型可以調用的函數              |
| [`skills/<skill-name>.md`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/skills)         | Agent 在相關情況下載入的詳細指引    |
| [`memory.ts`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/memory)                      | 對話記錄和工作情境              |
| [`workspace.ts` 和 `workspace/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/workspace) | 文件系統和 shell 存取權限       |
| [`subagents/<agent-id>/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/subagents)       | 父 Agent 可委派工作的專門 Agent |

將每項功能放在使用它的 Agent 旁。開發伺服器啟動或重新啟動時，Mastra 會找到並註冊這些文件。

瀏覽[以文件為基礎的 Agent 參考](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/config)，查看所有受支援的文件慣例和設定選項。