# AI 文档生成器 (/docs/plugin-system/builtin-plugins/aiDoc)



# AI 文档生成器 [#ai-文档生成器]

本插件用于自动生成符合 Skills 规范的接口知识文档，让编码助手准确感知项目中的所有 API，避免对函数名和参数进行猜测。通常与其他模板（alova、axios 等）配合使用。

## 主要功能 [#主要功能]

* 自动生成 `SKILL.md` 总览索引和按 tag 分组的 API 参考文档
* 支持自定义模板路径和输出目录
* 支持自动安装 Skill 到主流编码助手（Cursor、Claude Code、Windsurf 等）
* 支持在 `.env.local` 中通过逗号分隔配置多个编码助手，一次生成同时安装到多个助手

## 基本使用 [#基本使用]

```javascript
import { defineConfig } from "wormajs";
import { alova, aiDoc } from "wormajs/plugin";

export default defineConfig({
  generator: [
    {
      input: "https://api.example.com/openapi.json",
      output: "src/api",
      plugins: [alova(), aiDoc()],
    },
  ],
});
```

## 配置参数 [#配置参数]

```typescript
interface AiDocConfig {
  /** 自定义模板路径，不传则使用内置模板 */
  template?: string;
  /** 输出目录名，默认为 'aidocs' */
  outputDir?: string;
  /** 是否自动安装 Skill 到编码助手，默认 false */
  installSkill?: boolean;
}

function aiDoc(config?: AiDocConfig): ApiPlugin;
```

### 参数说明 [#参数说明]

| 参数名            | 类型        | 默认值        | 描述                 |
| -------------- | --------- | ---------- | ------------------ |
| `template`     | `string`  | —          | 自定义模板路径，不传则使用内置模板  |
| `outputDir`    | `string`  | `'aidocs'` | 输出目录名              |
| `installSkill` | `boolean` | `false`    | 是否自动安装 Skill 到编码助手 |

## 生成结构 [#生成结构]

<Files>
  <Folder name="aidocs">
    <File name="SKILL.md" />

    <Folder name="references">
      <Folder name="pet">
        <File name="addPet.md" />

        <File name="getPetById.md" />

        <File name="findPetsByStatus.md" />
      </Folder>

      <Folder name="user">
        <File name="getUserList.md" />

        <File name="createUser.md" />
      </Folder>
    </Folder>
  </Folder>
</Files>

* **`SKILL.md`**：总览索引，列出所有 API 端点和对应文档链接
* **`references/{tag}/{api}.md`**：按 tag 分组，每个 API 端点一个独立文档，包含请求方法、路径、参数 Schema 和请求/响应示例

> 关于生成内容的结构详情和使用方式，请参阅 [AI Skills 集成](/ai-skills)。

## 自动安装 Skill [#自动安装-skill]

启用 `installSkill: true` 后，执行 `worma gen` 时会自动将生成的 Skill 安装到编码助手中。

### 配置步骤 [#配置步骤]

1. **在项目根目录创建 `.env.local`**，配置编码助手名称：

```ini
# Worma aiDoc skill installer configuration
# Please set the coding agent(s) you are using (e.g. cursor, claude-code, windsurf).
# You can configure multiple agents comma-separated, e.g. agent=cursor,claude-code.
# Supported agents list: https://www.npmjs.com/package/skills#supported-agents
agent=cursor
```

> 如需同时安装到多个编码助手，使用逗号分隔即可，例如 `agent=cursor,claude-code,windsurf`。worma 会自动去重，并为每个助手执行一次安装。

2. **运行生成命令**：

```bash
worma gen
```

worma 会读取 `.env.local` 中的 `agent` 配置，自动将生成的 Skill 安装到对应助手中。支持的主流编码助手列表请参考 [skills 文档](https://www.npmjs.com/package/skills#supported-agents)。

> `.env.local` 首次运行时如不存在会自动创建，并在 `.gitignore` 中追加 `*.local` 规则，避免敏感配置被提交。