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

# 建立文件管理工具

本指南會教你建立一個用於維護項目文件的文件管理工具。它會建立結構清晰的 Markdown 檔案、妥善整理文件，並防止意外覆蓋檔案。你會設定 Workspace 檔案系統，並建立一個附有文件管理指示的 Agent，然後透過對話提示生成及更新文件。

## 前置要求

- 已安裝 Node.js `v22.13.0` 或以上版本
- 支援的 [Model Provider](https://mastra.zisheng.pro/zh-HK/models) 所提供的 API 金鑰
- 現有的 Mastra 項目（如要設定新項目，請參閱[安裝指南](https://mastra.zisheng.pro/zh-HK/guides/getting-started/quickstart)）

## 設定 Workspace

Workspace 使用本機檔案系統管理文件。Agent 會在 Workspace 目錄內讀寫檔案。在 `src/mastra/index.ts` 檔案中，匯入 [`Workspace`](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class) 及 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-filesystem) 類別。

```typescript
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` 作為文件索引：

```markdown
# Project Documentation

Welcome to the documentation!

## Sections

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

加入一份範例指南，讓 Agent 了解現有文件的風格：

````markdown
# 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：

```typescript
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` 實例，以完成 Agent 定義：

```typescript
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](https://mastra.zisheng.pro/zh-HK/docs/studio/overview)，並與 Agent 互動以查看實際運作情況。

**npm**:

```bash
npm run dev
```

**pnpm**:

```bash
pnpm run dev
```

**Yarn**:

```bash
yarn dev
```

**Bun**:

```bash
bun run dev
```

開啟 [localhost:4111](http://localhost:4111)，然後前往文件管理 Agent。

### 建立新文件

要求 Agent 建立教學：

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

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

````md
# 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 })
})
```
````

### 更新現有文件

嘗試更新現有文件：

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

Agent 應先讀取現有的 `getting-started.md` 檔案，並找出正確的插入位置。它應加入新的部分，而不影響現有內容。

### 整理文件

要求 Agent 建立索引：

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

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

## 後續步驟

你可以透過以下方式擴充此管理員：

- 加入 BM25 或向量搜尋，以尋找相關文件
- 為文件範本建立 Skill
- 根據源碼自動生成文件
- 與 GitHub 整合，在 commit 時更新文件
- 加入驗證，檢查連結及格式