cnb-api-generate

基于 swagger2.0 生成 TypeScript 代码与 Agent Skill 的工具。

• cag：生成基于 @cnb/request 和 @reduxjs/toolkit 的 TypeScript 代码，Interface / Enum 与 swagger.json 强绑定。
• csg：基于 swagger 生成 Agent Skill（SKILL.md + CLI）。

为什么需要

前后端各维护一套接口定义时，后端 swagger.json 变更无法触达前端：编译能过，运行时才报错；Interface / Enum 靠手写，容易写错或重复定义。

使用本工具后，Interface / Enum 与请求函数全部由 swagger.json 生成，swagger.json 一变重新生成即可在编译期发现类型错误，同时自动生成 jsDoc 注释。

安装

npm install @cnbcool/cnb-api-generate -D
# or
yarn add @cnbcool/cnb-api-generate -D

必须搭配 @cnb/request 使用。

快速使用

在运行 cag 的目录下创建 cag.config.js：

module.exports = {
  target: '<swagger.json 文件地址>',
}

npx cag
# or
yarn cag

cag.config.js

target

swagger.json 的文件位置，相对 cag.config.js。

outputDir

生成代码的输出目录，相对 cag.config.js。

printeReduxAction

是否输出 Redux Action 代码，默认 true。

requestDependencyMap

自定义请求模块中依赖的函数与 TypeScript 定义。

[key in string]: {
  path: string;
  isDefault: boolean;
}

基于 @cnb/request 已内置，无需配置。

生成 SKILL

文件配置

module.exports = {
  target: './template/swagger.json',
  skillsOutputDir: `./`,
}

执行命令

npx csg

生成目录结构：

| SKILL.md
| scripts/
| - core/
| - modules/

环境变量依赖

• CNB_API_ENDPOINT：可选，自定义 API 地址（默认 https://api.cnb.cool）
• CNB_TOKEN：OpenAPI 令牌
• CNB_WEB_ENDPOINT：与 CNB_API_ENDPOINT 对应的根域名（默认 https://cnb.cool）

skills list 命令

生成的 Skill 内置 cnb skills list，用于列出本地 skills：

cnb skills list -p -a codebuddy --json

| 参数 | 说明 | | --- | --- | | --json | 以 JSON 输出 | | -p | 查询项目（仓库）级 skills | | -a codebuddy | 按 agent 过滤（此处为当前 NPC 的 agent 名） |