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

# 构建文档管理器

在本指南中，你将构建一个维护项目文档的文档管理器。它会创建结构良好的 Markdown 文件并保持文档井然有序，同时防止意外覆盖。你将设置 Workspace 文件系统，并创建一个包含文档管理说明的 Agent。然后，你会使用对话式提示词生成和更新文档。

## 前提条件

- 已安装 Node.js `v22.13.0` 或更高版本
- 受支持的 [Model Provider](https://mastra.zisheng.pro/models) 提供的 API 密钥
- 现有的 Mastra 项目（按照[安装指南](https://mastra.zisheng.pro/guides/getting-started/quickstart)设置新项目）

## 设置 Workspace

该 Workspace 使用本地文件系统管理文档文件。Agent 会读取和写入 Workspace 目录中的文件。在 `src/mastra/index.ts` 文件中导入 [`Workspace`](https://mastra.zisheng.pro/reference/workspace/workspace-class) 和 [`LocalFilesystem`](https://mastra.zisheng.pro/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` 实例：

```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/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 创建一份教程：

```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 集成，在提交时更新文档
- 添加校验来检查链接和格式