构建文档管理器

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

前提条件

• 已安装 Node.js v22.13.0 或更高版本
• 受支持的 Model Provider 提供的 API 密钥
• 现有的 Mastra 项目（按照安装指南设置新项目）

设置 Workspace

该 Workspace 使用本地文件系统管理文档文件。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 或向量搜索，用于查找相关文档
• 为文档模板创建 Skill
• 根据源代码自动生成文档
• 与 GitHub 集成，在提交时更新文档
• 添加校验来检查链接和格式