建置文件管理員

本指南將帶你建置一個維護專案文件的文件管理員。它會建立結構良好的 Markdown 檔案、維持文件井然有序，並防止意外覆寫。你將設定 Workspace filesystem，並建立具有文件管理指示的 Agent，接著使用對話式提示詞產生及更新文件。

先決條件

• 已安裝 Node.js v22.13.0 或更新版本
• 受支援的 Model Provider 所提供的 API 金鑰
• 現有的 Mastra 專案（請依照安裝指南建立新專案）

設定 Workspace

Workspace 使用本機 filesystem 管理文件檔案。Agent 會讀寫 Workspace 目錄內的檔案。在 src/mastra/index.ts 檔案中，匯入 Workspace 與 LocalFilesystem 類別。

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: resolve(import.meta.dirname, '../../workspace'),
  }),
})

export const mastra = new Mastra({
  workspace,
})

在專案根目錄建立名為 workspace 的新資料夾。Agent 會在此儲存及管理所有文件檔案。

新增範例文件

在 workspace 目錄內建立以下資料夾：

• docs/guides/：用於操作指南
• docs/api/：用於 API 參考文件
• docs/tutorials/：用於逐步教學

建立 workspace/docs/README.md 作為文件索引：

workspace/docs/README.md

# Project Documentation

Welcome to the documentation!

## Sections

- [Guides](./guides/): How-to guides
- [API](./api/): API reference
- [Tutorials](./tutorials/): Step-by-step tutorials

新增範例指南，讓 Agent 能查看現有的文件風格：

workspace/docs/guides/getting-started.md

# Getting Started

Quickstart guide for the project.

## Installation

```bash npm2yarn
npm install example-package
```

## Quick example

```typescript
import { Example } from 'example-package'

const example = new Example()
example.run()
```

建立文件管理員

接著建立文件管理員 Agent。此 Agent 會收到在 Workspace 中建立及更新 Markdown 檔案的指示。建立新檔案 src/mastra/agents/docs-manager.ts 並定義 Agent：

src/mastra/agents/docs-manager.ts

import { Agent } from '@mastra/core/agent'

export const docsManager = new Agent({
  id: 'docs-manager',
  name: 'Docs Manager',
  instructions: `You are a documentation manager that creates and maintains markdown docs.

When creating new docs:
1. Ask for topic and target audience
2. Create well-structured markdown with clear sections
3. Include relevant code examples with syntax highlighting
4. Save in the appropriate directory:
   - /docs/guides/ for user guides and how-tos
   - /docs/api/ for API reference
   - /docs/tutorials/ for step-by-step tutorials

When updating existing docs:
1. ALWAYS read the file first
2. Make targeted updates without removing unrelated content
3. Preserve existing structure and formatting

Use kebab-case naming for files (getting-started.md).
Always explain what you're creating and why.`,
  model: 'openai/gpt-5.6-sol',
})

在 src/mastra/index.ts 中匯入 Agent，並向 Mastra 執行個體註冊：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
import { docsManager } from './agents/docs-manager'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: resolve(import.meta.dirname, '../../workspace'),
  }),
})

export const mastra = new Mastra({
  workspace,
  agents: { docsManager },
})

測試文件管理員

啟動 Studio 並與 Agent 互動，查看實際運作情形。

npm

npm run dev

pnpm

pnpm run dev

Yarn

yarn dev

Bun

bun run dev

開啟 localhost:4111，然後前往文件管理員。

建立新文件

要求 Agent 建立教學：

Create a tutorial for setting up authentication. Cover installation, configuration, and a basic example.

Agent 應建立類似 docs/tutorials/authentication-setup.md 的檔案。由於 Agent 的回應具有非確定性，實際內容會有所不同，但你應該會看到類似以下的內容：

# Authentication Setup

Learn how to add authentication to your application.

## Installation

Install the auth package:

```bash npm2yarn
npm install @example/auth
```

## Configuration

Create a config file:

```typescript
// auth.config.ts
export const authConfig = {
  provider: 'oauth',
  clientId: process.env.AUTH_CLIENT_ID,
  secret: process.env.AUTH_SECRET,
}
```

## Basic example

```typescript
import { createAuth } from '@example/auth'
import { authConfig } from './auth.config'

const auth = createAuth(authConfig)

app.get('/protected', auth.requireAuth(), (req, res) => {
  res.json({ user: req.user })
})
```

更新現有文件

試著更新現有文件：

Update the getting started guide to include a section on configuration after the Quick Example

Agent 應讀取現有的 getting-started.md 檔案並找出適當的插入位置，且應在不影響現有內容的情況下新增章節。

整理文件

要求 Agent 建立索引：

List all tutorial files and create an index page that links to all of them

Agent 應建立類似 /docs/tutorials/index.md 的檔案，連結至所有可用的教學。

後續步驟

你可以擴充此管理員，以便：

• 新增 BM25 或向量搜尋以尋找相關文件
• 為文件範本建立 Skills
• 從原始碼自動產生文件
• 與 GitHub 整合，在提交時更新文件
• 新增驗證以檢查連結與格式