@cnbcool/cnb-api-generate 2.16.7 → 2.16.9

package/README.md

@@ -1,23 +1,15 @@
 # cnb-api-generate
 
-`cnb-api-generate`是一款基于`swagger2.0`标准协议生成基于`@cnb/request`和`@reduxjs/toolkit`的`Typescript`代码的工具。将`Typescript`中的`Interface`和`Enum`与`swagger.json`强绑定。并自动对请求函数的依赖分析并引入。
+基于 `swagger2.0` 生成 TypeScript 代码与 Agent Skill 的工具。
 
-## 解决了什么问题？
-长期以来，前后端开发都是两套代码甚至多套代码各自维护。前端基于后端提供的接口定义，例如`swagger.json`中定义的接口入参出参，自行编写`Typescript`代码，用`Typescript`重新定义一遍接口的入参出参(`Interface`和`Enum`)。然后自行引用这些定义的入参出参(`Interface`和`Enum`)。
+- `cag`：生成基于 `@cnb/request` 和 `@reduxjs/toolkit` 的 TypeScript 代码，`Interface` / `Enum` 与 `swagger.json` 强绑定。
+- `csg`：基于 `swagger` 生成 Agent Skill（`SKILL.md` + CLI）。
 
-看似一切都很正常，实际上这里有一个致命问题，当后端接口主动或被动发生变更时，前端无感知。但是代码却能正常编译通过，当进入到运行时时，就会出现错误。问题核心就在于前端自行维护入参出参(`Interface`和`Enum`)和`swargger.json`中的定义是脱钩的。当后端代码发生变化，通过编译重新生成了`swargger.json`，但是新的`swargger.json`的变化并不能触达到前端。
+## 为什么需要
 
-- ❎ 与`swargger.json`脱钩，`swargger.json`变化无法触发前端，编译通过，运行报错。
-- ❎ 手动定义`Interface`和`Enum`，可能存在认为失误写错代码。
-- ❎ 可能存在多个重复定义的`Interface`和`Enum`。
+前后端各维护一套接口定义时，后端 `swagger.json` 变更无法触达前端：编译能过，运行时才报错；`Interface` / `Enum` 靠手写，容易写错或重复定义。
 
-当使用`cnb-api-generate`后，`Interface`和`Enum`完全基于`swargger.json`中的定义自动生成标准的`Typescript`代码。并根据前端`CNB`的前端技术栈，完全自动生成多态化的网络函数调用，并自动完成对`Interface`和`Enum`的依赖注入。
-
-- 💯 `swargger.json`与所有的前端网络调用函数代码强绑定，当`swargger.json`变化后，重新生成前端代码，实现`Typescript`代码重新生成，从而在编译时就能发现类型错误的问题。
-- 💯 `Interface`和`Enum`的定义完全自动化，完全基于`swargger.json`，无需人为干预。
-- 💯 生成的代码更规范，抹除因开发人员水平差异导致编写的`Typescript`代码质量参差不齐。
-- 💯 完善的jsDos定义，除了生成`Typescript`代码外，还会根据`swargger.json`定义每个参数的说明，自动生成jsDos的注释。
-- 💯 从生成的代码和注释质量倒推接口的文档规范。
+使用本工具后，`Interface` / `Enum` 与请求函数全部由 `swagger.json` 生成，`swagger.json` 一变重新生成即可在编译期发现类型错误，同时自动生成 jsDoc 注释。
 
 ## 安装
 
@@ -27,13 +19,15 @@ npm install @cnbcool/cnb-api-generate -D
 yarn add @cnbcool/cnb-api-generate -D
 ```
 
+> 必须搭配 `@cnb/request` 使用。
+
 ## 快速使用
 
-在运行`cag`目录下创建`cag.config.js`文件。
+在运行 `cag` 的目录下创建 `cag.config.js`：
 
 ```javascript
 module.exports = {
-  target: '<swargger.json文件地址>',
+  target: '<swagger.json 文件地址>',
 }
 ```
 
@@ -43,26 +37,20 @@ npx cag
 yarn cag
 ```
 
->cnb-api-generate必须搭配@cnb/request使用！！！
-
-
 ## cag.config.js
-`cnb-api-generate`基本不需要任何配置，为了灵活支持输入输出文件的位置和引用代码的自定义位置，提供一些简单的配置。
 
 ### target
-指定`swagger.json`的文件位置，路径为相对cag.config.js的路径。
+`swagger.json` 的文件位置，相对 `cag.config.js`。
 
 ### outputDir
-指定输出的生成代码的目录，路径为相对cag.config.js的路径。
+生成代码的输出目录，相对 `cag.config.js`。
 
 ### printeReduxAction
-是否输出`Redux Action`代码，默认为`true`。
+是否输出 `Redux Action` 代码，默认 `true`。
 
 ### requestDependencyMap
-用于定义请求模块中依赖的函数与Typescript的定义
+自定义请求模块中依赖的函数与 TypeScript 定义。
 
-- path -> 模块所在路径
-- isDefault -> 是否default导出
 ```typescript
 [key in string]: {
   path: string;
@@ -70,309 +58,17 @@ yarn cag
 }
 ```
 
-> 基于@cnb/request，已内置，无需配置
-
-## Example
-`cnb-api-generate`基于`swargger`中定义的类型生成三类型代码，`Interface`、`Enum`和`Api`。其中`Api`会基于`swargger`中对接口的分类进行目录级归类输出。
-
-### Interface
-对`swagger`中定义的`definitions`处理，生成`Interface`。
-```json
-"dto.AiAutoPrResult": {
-    "type": "object",
-    "properties": {
-        "buildLogUrl": {
-            "description": "构建链接",
-            "type": "string"
-        },
-        "message": {
-            "description": "message",
-            "type": "string"
-        },
-        "sn": {
-            "description": "构建号",
-            "type": "string"
-        }
-    }
-}
-```
-
-interfaces/dto.aiautoprresult.ts
-```typescript
-export interface DtoAiAutoPrResult {
-  /**
-   * 构建链接
-   */
-  buildLogUrl?: string;
-  /**
-   * message
-   */
-  message?: string;
-  /**
-   * 构建号
-   */
-  sn?: string;
-}
-
-```
-
-#### 依赖其他Interface
-在`swagger`的定义中，`definitions`是可以互相依赖的。`cnb-api-generate`会自动处理好所有依赖的文件引入，确保代码正常使用。
-
-```json
-"api.CommitObject": {
-    "type": "object",
-    "properties": {
-        "author": {
-            "$ref": "#/definitions/api.Signature"
-        },
-        "comment_count": {
-            "type": "integer"
-        },
-        "committer": {
-            "$ref": "#/definitions/api.Signature"
-        },
-        "message": {
-            "type": "string"
-        },
-        "tree": {
-            "$ref": "#/definitions/api.CommitObjectTree"
-        },
-        "verification": {
-            "$ref": "#/definitions/api.CommitObjectVerification"
-        }
-    }
-}
-```
-interfaces/api.commitobject.ts
-```typescript
-import { ApiSignature } from "./api.signature";
-import { ApiCommitObjectTree } from "./api.commitobjecttree";
-import { ApiCommitObjectVerification } from "./api.commitobjectverification";
-export interface ApiCommitObject {
-  author?: ApiSignature;
-  comment_count?: number;
-  committer?: ApiSignature;
-  message?: string;
-  tree?: ApiCommitObjectTree;
-  verification?: ApiCommitObjectVerification;
-}
-```
-
-### Enum
-对`swagger`中定义的`definitions`处理，生成`Interface`。
-
-```json
-"constant.ActivityType": {
-    "type": "string",
-    "enum": [
-        "mine",
-        "fork",
-        "follow",
-        "star",
-        "join_group",
-        "create_repo",
-        "user_create_release",
-        "repo_create_release",
-        "user_deploy_success",
-        "repo_deploy_success",
-        "at_user",
-        "comment"
-    ],
-    "x-enum-comments": {
-        "AtUser": "AtUser @用户",
-        "Comment": "Comment pr,issue 评论",
-        "CreateRepo": "CreateRepo 创建仓库",
-        "Follow": "Follow 用户 follow",
-        "Fork": "Fork 仓库 fork",
-        "JoinGroup": "JoinGroup 加入组织",
-        "Mine": "Mine 与我相关的动态",
-        "RepoCreateRelease": "RepoCreateRelease 仓库发布版本",
-        "RepoDeploySuccess": "RepoDeploySuccess 仓库部署版本",
-        "Star": "Star 仓库 star",
-        "UserCreateRelease": "UserCreateRelease 用户发布版本",
-        "UserDeploySuccess": "UserDeploySuccess 用户部署版本"
-    },
-    "x-enum-descriptions": [
-        "Mine 与我相关的动态",
-        "Fork 仓库 fork",
-        "Follow 用户 follow",
-        "Star 仓库 star",
-        "JoinGroup 加入组织",
-        "CreateRepo 创建仓库",
-        "UserCreateRelease 用户发布版本",
-        "RepoCreateRelease 仓库发布版本",
-        "UserDeploySuccess 用户部署版本",
-        "RepoDeploySuccess 仓库部署版本",
-        "AtUser @用户",
-        "Comment pr,issue 评论"
-    ],
-    "x-enum-varnames": [
-        "Mine",
-        "Fork",
-        "Follow",
-        "Star",
-        "JoinGroup",
-        "CreateRepo",
-        "UserCreateRelease",
-        "RepoCreateRelease",
-        "UserDeploySuccess",
-        "RepoDeploySuccess",
-        "AtUser",
-        "Comment"
-    ]
-}
-```
-
-enums/constant.activitytype.ts
-```typescript
-export enum ConstantActivityType {
-  /* Mine 与我相关的动态 */
-  Mine = "mine",
-  /* Fork 仓库 fork */
-  Fork = "fork",
-  /* Follow 用户 follow */
-  Follow = "follow",
-  /* Star 仓库 star */
-  Star = "star",
-  /* JoinGroup 加入组织 */
-  JoinGroup = "join_group",
-  /* CreateRepo 创建仓库 */
-  CreateRepo = "create_repo",
-  /* UserCreateRelease 用户发布版本 */
-  UserCreateRelease = "user_create_release",
-  /* RepoCreateRelease 仓库发布版本 */
-  RepoCreateRelease = "repo_create_release",
-  /* UserDeploySuccess 用户部署版本 */
-  UserDeploySuccess = "user_deploy_success",
-  /* RepoDeploySuccess 仓库部署版本 */
-  RepoDeploySuccess = "repo_deploy_success",
-  /* AtUser @用户 */
-  AtUser = "at_user",
-  /* Comment pr,issue 评论 */
-  Comment = "comment",
-}
-```
-
-### Api
-`cnb-api-generate`是为cnb量身定做的代码生成工具，所以基于`@cnb/request`和`@reduxjs/toolkit`生成调用代码，并且自动完成对生成的`interface`和`enum`的引用依赖。
-
-```json
-"/user/gpg-keys/{id}": {
-    "delete": {
-        "security": [
-            {
-                "BearerAuth": []
-            }
-        ],
-        "consumes": [
-            "application/json"
-        ],
-        "produces": [
-            "application/json",
-            "application/vnd.cnb.web+json"
-        ],
-        "tags": [
-            "Users"
-        ],
-        "summary": "删除用户 GPG key",
-        "operationId": "DeleteGPGKey",
-        "parameters": [
-            {
-                "type": "string",
-                "description": "gpg id",
-                "name": "id",
-                "in": "path",
-                "required": true
-            }
-        ],
-        "responses": {
-            "200": {
-                "description": "OK"
-            },
-            "404": {
-                "description": "Not Found",
-                "schema": {
-                    "$ref": "#/definitions/die.WebError"
-                }
-            },
-            "500": {
-                "description": "Internal Server Error",
-                "schema": {
-                    "$ref": "#/definitions/die.WebError"
-                }
-            }
-        }
-    }
-}
-```
-
-apis/users/delete-gpg-key.ts
-
-```typescript
-import type { IncomingMessage } from "http";
-import { createAsyncThunk } from "@reduxjs/toolkit";
-import fetch from "@/request";
-import { CnbRequestOptions, CnbRequestResult } from "@cnb/request";
-import { AxiosRequestConfig } from "axios";
-import { DieWebError } from "../../interfaces/die.weberror";
-
-/**
- * @description Other reuqest params
- */
-type RequestConfig<DataType = any> = AxiosRequestConfig<DataType> & {
-  options?: CnbRequestOptions;
-  req?: IncomingMessage;
-};
-
-/**
- * @description DeleteGPGKeyRes Success Response Type
- */
-export type DeleteGPGKeyRes = unknown;
-
-/**
- * @description DeleteGPGKeyError Error Response Type
- */
-export type DeleteGPGKeyError = DieWebError;
-
-/**
-* @description No description
-* @tags Users
-* @name deleteGPGKey
-* @summary 删除用户 GPG key
-* @request delete:/user/gpg-keys/{id}
-
-----------------------------------
-* @param {string} arg0
-* @param {RequestConfig} arg1 - Other reuqest params
-*/
-export async function deleteGPGKey(
-  id: string,
-  {req, options, ...axiosConfig}: RequestConfig = {},
-): Promise<CnbRequestResult<DeleteGPGKeyRes, DeleteGPGKeyError>> {
-  return await fetch.request<DeleteGPGKeyRes, DeleteGPGKeyError>({
-    ...axiosConfig,
-    _next_req: req,
-    options: options,
-    url: `/user/gpg-keys/${id}`,
-    _apiTag: "/user/gpg-keys/{id}",
-    method: "delete",
-  });
-}
-```
-
-## 生成SKILL
+> 基于 `@cnb/request` 已内置，无需配置。
 
-基于swagger生成Agent Skill。
+## 生成 SKILL
 
 ### 文件配置
-cag.config.js
+
 ```javascript
 module.exports = {
   target: './template/swagger.json',
   skillsOutputDir: `./`,
 }
-
 ```
 
 ### 执行命令
@@ -381,7 +77,7 @@ module.exports = {
 npx csg
 ```
 
-生成如下目录结构：
+生成目录结构：
 
 ```
 | SKILL.md
@@ -392,8 +88,20 @@ npx csg
 
 ### 环境变量依赖
 
-skills运行需要依赖以下环境变量
+- `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：
+
+```shell
+cnb skills list -p -a codebuddy --json
+```
 
-- CNB_API_ENDPOINT: 可选：自定义 API 地址（默认为 https://api.cnb.cool）
-- CNB_TOKEN: openapi令牌
-- CNB_WEB_ENDPOINT: 与CNB_API_ENDPOINT相对应的根域名（默认为 https://cnb.cool）
+| 参数 | 说明 |
+| --- | --- |
+| `--json` | 以 JSON 输出 |
+| `-p` | 查询项目（仓库）级 skills |
+| `-a codebuddy` | 按 agent 过滤（此处为当前 NPC 的 agent 名） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnbcool/cnb-api-generate",
-  "version": "2.16.7",
+  "version": "2.16.9",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",

package/quick-commands.json

@@ -36,6 +36,6 @@
     { "shortName": "get-files",      "realTool": "get-pr-files",              "description": "获取 PR 附件",     "repoOnly": true, "dataTip": "--file-path 附件路径" }
   ],
   "skills": [
-    { "shortName": "list", "realTool": "__skills-list__", "description": "列出本地 skills", "custom": true, "dataTip": "-p -a agent --json" }
+    { "shortName": "list", "realTool": "__skills-list__", "description": "列出本地 skills", "custom": true, "dataTip": "-p -a codebuddy --json" }
   ]
 }