AI 文档生成器

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

主要功能

自动生成 SKILL.md 总览索引和按 tag 分组的 API 参考文档
支持自定义模板路径和输出目录
支持自动安装 Skill 到主流编码助手（Cursor、Claude Code、Windsurf 等）
支持通过 agent 指定单个或多个编码助手，一次生成可同时安装到多个助手（自动去重）

基本使用

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()],
    },
  ],
});

配置参数

// 编码助手名称（与 skills 包支持的助手对应）。skills 为纯 CLI 包且不导出类型，
// 故此处自行维护一份；亦可使用 string 直接传入。
type SkillAgent =
  | "cursor"
  | "claude-code"
  | "codex"
  | "windsurf" /* …其余助手见类型定义 */;

interface AiDocConfig {
  /** 自定义模板路径，不传则使用内置模板 */
  template?: string;
  /** 输出目录名，默认为 'aidocs' */
  outputDir?: string;
  /**
   * 要安装 Skill 的编码助手。
   * - 省略（默认）：不安装 Skill。
   * - `SkillAgent` / `SkillAgent[]`：直接指定安装目标。
   * - `string`：以逗号分隔的编码助手名称，直接作为安装目标，
   *   例如 `"cursor"` 或 `"cursor, claude-code"`。
   * 也可结合 `parseAgentFile` 从配置文件读取助手名称。
   */
  agent?: SkillAgent | SkillAgent[] | string;
}

function aiDoc(config?: AiDocConfig): ApiPlugin;

参数说明

参数名	类型	默认值	描述
`template`	`string`	—	自定义模板路径，不传则使用内置模板
`outputDir`	`string`	`'aidocs'`	输出目录名
`agent`	`SkillAgent \| SkillAgent[] \| string`	—	要安装 Skill 的编码助手：省略则不安装；`SkillAgent`/`SkillAgent[]` 直接指定目标；字符串则作为逗号分隔的安装目标（自动去重）

生成结构

SKILL.md

addPet.md

getPetById.md

findPetsByStatus.md

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

关于生成内容的结构详情和使用方式，请参阅 AI Skills 集成。

自动安装 Skill

agent 支持以下取值，执行 worma gen 时会按配置将生成的 Skill 安装到对应编码助手：

省略（默认）：不安装。
string：以逗号分隔的编码助手名称，直接作为安装目标，例如 "cursor" 或 "cursor, claude-code"。

aiDoc({ agent: "cursor" }); // 安装到 cursor
aiDoc({ agent: "cursor, claude-code" }); // 安装到多个助手（自动去重）

通过配置文件指定编码助手

如果你希望把编码助手维护在独立配置文件里（便于按用户 / 环境区分），可使用导出的 parseAgentFile(filePath?) 解析 key=value 格式的文件（与环境变量文件相同，# 开头的行会被忽略）。可传入文件路径读取指定文件（例如读取 .env.local）；省略路径时，默认读取项目根目录下的 .wormaagent.local：

# .wormaagent.local
agent=cursor, claude-code

import { aiDoc, parseAgentFile } from "@alova/worma";

const cfg = parseAgentFile(); // 默认读取 ./.wormaagent.local -> cfg.agent === 'cursor, claude-code'
aiDoc({ agent: cfg.agent });

const cfg2 = parseAgentFile('.env.local'); // 传入路径读取指定文件
aiDoc({ agent: cfg2.agent });

parseAgentFile 返回 { [key]: string } 键值对，便于把其它自定义字段一并读取后再传入配置。

把 .wormaagent.local 加入 .gitignore

.wormaagent.local 通常包含个人的编码助手偏好（如你本地使用的 cursor、claude-code 等）。请把它加入项目的 .gitignore，避免提交到仓库、覆盖或干扰团队其他成员的 agent 设置：

# .gitignore
.wormaagent.local

运行生成命令

worma gen

worma 会按上述配置把生成的 Skill 安装到对应助手中。支持的主流编码助手列表请参考 skills 文档。

AI 文档生成器

On this page