# @cnbcool/cnb-api-generate 中文文档

规范地址：https://npmcn.com/package/%40cnbcool/cnb-api-generate/

版本：2\.22\.0
npm 元数据更新时间：2026-11-09T10:42:54.292Z
中文译文更新时间：2026-11-10T04:30:02.732Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cnbcool/cnb-api-generate
原文对照：https://npmcn.com/package/%40cnbcool/cnb-api-generate/?lang=original
源码仓库：https://cnb.cool/cnb/skills/cnb-api-generate

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：466 kB，161 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：21 个
- 首次发布：2026-03-25T07:55:11.381Z
- 最新版本发布：2026-11-09T10:42:54.080Z
- 近 30 天下载量：7637（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：125（近 12 个月 125 个）

## 中文简介

页:1 `swagger2.0` → TypeScript → Agent Skill →。

## 安装

```sh
npm install @cnbcool/cnb-api-generate
```

也可以使用：`pnpm add @cnbcool/cnb-api-generate`、`yarn add @cnbcool/cnb-api-generate`、`bun add @cnbcool/cnb-api-generate`

## README

# 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 注释。

## 安装

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

> 必须搭配 `@cnb/request` 使用。

## 快速使用

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

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

```shell
npx cag
# or
yarn cag
```

## cag.config.js

### target

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

### outputDir

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

### printeReduxAction

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

### requestDependencyMap

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

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

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

## 生成 SKILL

### 文件配置

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

### 执行命令

```bash
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`）
-   `CNB_SSL_NO_VERIFY`：设为 `true` 时跳过 HTTPS 证书校验，适用于自签证书或私有化部署；仅作用于 cnb 自身请求，`git` 的 clone/push 需另配 `http.sslVerify=false`

## skills list 命令

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

```shell
cnb skills list -p -a codebuddy --json
```

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

## 常见问题

### @cnbcool/cnb-api-generate 是什么？

页:1 swagger2\.0 → TypeScript → Agent Skill →。

### 如何安装 @cnbcool/cnb-api-generate？

在项目目录运行 npm install @cnbcool/cnb-api-generate，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cag、csg，可以用 npx cag 直接运行。

### @cnbcool/cnb-api-generate 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cnbcool/cnb-api-generate 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cnbcool/cnb-api-generate 可以商用吗？

@cnbcool/cnb-api-generate 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cnbcool/cnb-api-generate 的下载量有多少？

根据 npm 官方下载统计，@cnbcool/cnb-api-generate 在 2026/10/10 – 2026/11/08 这 30 天内被下载 7,637 次，日均约 255 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cnbcool/cnb-api-generate 还在维护吗？

最新版本 2\.22\.0 发布于 2026/11/09（今天）；至今共发布 125 个版本，其中过去 12 个月发布了 125 个；首次发布于 2026/03/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。