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

# 開發

擁有 Mastra 專案後，就可以開始開發、執行及測試 Agent。

## 在本機執行 Mastra

若要快速查看 Agent 的運作情形，最簡單的方式是使用 [Mastra Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview)。在專案根目錄中，使用 [`mastra dev`](https://mastra.zisheng.pro/zh-TW/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-TW/docs/server/mastra-client) 連接前端。

變更 `src/mastra/` 目錄中的內容時，開發伺服器會自動重新啟動，因此開發過程中不需要手動重啟。

## 使用 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/zh-TW/docs) 建立專案時，該指令會自動安裝 Mastra Skill，讓 coding Agent 能夠找到並使用它。

### Mastra CLI

使用 [`mastra` CLI](https://mastra.zisheng.pro/zh-TW/reference/cli/mastra)，為 coding Agent 提供測試更新及檢查結果的回饋迴圈。CLI 可讓它存取 Agent、Workflow、Tool、記憶體、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/` 下，並把相關 primitive 分組到各自的檔案或資料夾中。使用 `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-TW/reference/project-structure)。

## 檔案式 Agent

> **Beta:** 檔案式 Agent 目前處於 Beta 階段，在穩定版推出前可能有所變更。
>
> 檔案式探索只會透過 `mastra dev` 或 `mastra build` 執行。如果應用程式直接匯入 `mastra`，包括透過 Web 框架或伺服器轉接器匯入，將不會探索檔案式 Agent。請在程式碼中註冊這些 Agent，或將 Mastra 作為獨立伺服器執行。

> **📹 觀看影片:** [如何建立第一個檔案式 Agent](https://www.youtube.com/watch?v=5Kfn-oYkJNg\&t=18s)

使用檔案式 Agent 時，Mastra 會自動從 `src/mastra/` 下受支援的檔案中[探索](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/config) Agent 及相關 primitive。你可以按照慣例組織這些檔案，不必將每個 primitive 匯入並註冊至 [`Mastra`](https://mastra.zisheng.pro/zh-TW/reference/core/mastra-class) 執行個體。

檔案系統會直接呈現專案結構，因此你和 coding Agent 不必追查程式碼中各項目的連接方式，就能了解整個專案如何組成。

你可以在整個專案中使用檔案式 Agent，也可以搭配程式碼中定義的 primitive 逐步採用。目前尚未支援 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-TW/reference/file-based-agents/tools)              | 模型可以呼叫的函式               |
| [`skills/<skill-name>.md`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/skills)           | Agent 在相關情境下會載入的詳細指引    |
| [`memory.ts`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/memory)                        | 對話記錄和工作環境               |
| [`workspace.ts` and `workspace/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/workspace) | 檔案系統和 shell 存取權         |
| [`subagents/<agent-id>/`](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/subagents)         | 父 Agent 可以委派工作的專業 Agent |

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

瀏覽[檔案式 Agent 參考](https://mastra.zisheng.pro/zh-TW/reference/file-based-agents/config)，查看所有支援的檔案慣例和設定選項。