Créer un gestionnaire de documentation

Dans ce guide, vous créerez un gestionnaire de documentation qui maintient les documents de votre projet. Il crée des fichiers Markdown bien structurés et conserve une documentation organisée tout en évitant les écrasements accidentels. Vous configurerez un système de fichiers de Workspace et créerez un Agent avec des instructions de gestion documentaire. Vous utiliserez ensuite des prompts conversationnels pour générer et mettre à jour la documentation.

Prérequis

• Node.js v22.13.0 ou version ultérieure est installé
• Une clé API d’un fournisseur de modèles pris en charge
• Un projet Mastra existant (suivez le guide d’installation pour configurer un nouveau projet)

Configurer le Workspace

Le Workspace utilise un système de fichiers local pour gérer les fichiers de documentation. L’Agent lit et écrit les fichiers dans le répertoire du Workspace. Dans votre fichier src/mastra/index.ts, importez les classes Workspace et 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,
})

À la racine de votre projet, créez un dossier nommé workspace. C’est là que tous les fichiers de documentation seront stockés et gérés par l’Agent.

Ajouter une documentation d’exemple

Dans le répertoire workspace, créez les dossiers suivants :

• docs/guides/ : pour les guides pratiques
• docs/api/ : pour la documentation de référence de l’API
• docs/tutorials/ : pour les tutoriels pas à pas

Créez workspace/docs/README.md comme index de la documentation :

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

Ajoutez un guide d’exemple afin que l’Agent puisse voir le style de documentation existant :

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()
```

Créer le gestionnaire de documentation

Il est maintenant temps de créer l’Agent gestionnaire de documentation. Cet Agent aura des instructions pour créer et mettre à jour des fichiers Markdown dans le Workspace. Créez un fichier src/mastra/agents/docs-manager.ts et définissez l’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',
})

Définissez l’Agent en l’important dans src/mastra/index.ts et en l’enregistrant auprès de l’instance 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 },
})

Tester le gestionnaire de documentation

Démarrez Studio et interagissez avec l’Agent pour le voir à l’œuvre.

npm

npm run dev

pnpm

pnpm run dev

Yarn

yarn dev

Bun

bun run dev

Ouvrez localhost:4111, puis accédez au gestionnaire de documentation.

Créer un nouveau document

Demandez à l’Agent de créer un tutoriel :

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

L’Agent devrait créer un fichier tel que docs/tutorials/authentication-setup.md. Les réponses d’Agent étant non déterministes, le contenu exact variera, mais vous devriez obtenir un résultat semblable à celui-ci :

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

Mettre à jour un document existant

Essayez de mettre à jour un document existant :

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

L’Agent devrait lire le fichier getting-started.md existant et trouver le bon point d’insertion. Il devrait ajouter la nouvelle section sans perturber le contenu existant.

Organiser la documentation

Demandez à l’Agent de créer un index :

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

L’Agent devrait créer un fichier tel que /docs/tutorials/index.md qui renvoie vers tous les tutoriels disponibles.

Étapes suivantes

Vous pouvez étendre ce gestionnaire afin de :

• Ajouter une recherche BM25 ou vectorielle pour trouver la documentation pertinente
• Créer des Skills pour les modèles de documentation
• Mettre en place une génération automatisée de documentation depuis le code source
• Intégrer GitHub pour mettre à jour la documentation lors des commits
• Ajouter une validation des liens et du formatage