@cnbcool/cnb-api-generate 2.0.0 → 2.1.1

package/client/lib/format-output.ts

@@ -1,3 +1,4 @@
+import { printJSON } from './print-json';
 import { summarizeResponse } from './summary-extractors';
 
 /**
@@ -49,7 +50,7 @@ export function isStandardResponse(response: any): boolean {
 export function formatOutput(response: any, verbose: boolean, summary: boolean, toolKey: string): string {
   // --verbose 模式：输出完整原始信息
   if (verbose) {
-    return JSON.stringify(response, null, 2);
+    return printJSON(response, verbose);
   }
 
   // converter 可能返回裸 data（没有标准 {status, data} 结构），直接输出
@@ -57,10 +58,10 @@ export function formatOutput(response: any, verbose: boolean, summary: boolean,
     if (summary) {
       const summarized = summarizeResponse(response, toolKey);
       if (summarized !== null) {
-        return JSON.stringify(summarized, null, 2);
+        return printJSON(summarized);
       }
     }
-    return JSON.stringify(response, null, 2);
+    return printJSON(response);
   }
 
   // 精简响应
@@ -74,5 +75,5 @@ export function formatOutput(response: any, verbose: boolean, summary: boolean,
     }
   }
 
-  return JSON.stringify(compact, null, 2);
+  return printJSON(compact);
 }

package/client/lib/format-params.ts

@@ -111,7 +111,15 @@ export function formatParams(
       } else if (bodyProps[key]) {
         // body 字段（无冲突，直接用原 key）
         if (!formatted.data) formatted.data = {};
-        formatted.data[key] = Array.isArray(value) ? value : tryParseJSON(value as string);
+        if (Array.isArray(value)) {
+          formatted.data[key] = value;
+        } else if (bodyProps[key].type === 'string') {
+          // schema 定义为 string 类型时，保持原始字符串，不做 JSON 解析
+          // 避免纯数字字符串（如 "123"）被转为 number
+          formatted.data[key] = value;
+        } else {
+          formatted.data[key] = tryParseJSON(value as string);
+        }
       } else {
         // 处理 d- 前缀（冲突时 CLI 以 d- 前缀传入）
         const stripped = (key.startsWith('d-') || key.startsWith('d_'))

package/client/lib/print-json.ts

@@ -0,0 +1,12 @@
+/**
+ * 将数据转换为格式化的 JSON 字符串
+ * @param data 要序列化的数据（可以是任意类型）缩进）
+ * @param verbose 是否 verbose 模式
+ * @returns 格式化的 JSON 字符串，如果序列化失败则返回错误信息的 JSON
+ */
+export function printJSON(
+  data: Record<string, any> | Array<any>,
+  verbose: boolean = false
+): string {
+  return verbose ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}

package/client/lib/register-modules.ts

@@ -3,7 +3,7 @@ import { trimSummary } from './trim-summary';
 import { helpData } from './help-data';
 import { flatOptionsData } from './flat-options-data';
 import { executeAction } from './execute-action';
-import { resolveShortcut } from '../shortcuts';
+import { ISSUE_SHORTCUTS, PR_SHORTCUTS, type ShortcutDefinition } from '../shortcuts';
 
 interface FlatOption {
   optKey: string;
@@ -22,19 +22,22 @@ interface FlatOption {
  * 为单个 tool 子命令注册 Commander options
  * 直接读取预生成的 flat-options.json 中已扁平化的参数定义，无需运行时计算
  */
-function registerToolOptions(toolCmd: Command, moduleName: string, toolName: string): void {
+function registerToolOptions(toolCmd: Command, moduleName: string, toolName: string, skipPathMandatory?: boolean): void {
   const moduleOptions = flatOptionsData[moduleName];
   if (!moduleOptions) return;
   const toolOptions: Record<string, FlatOption> = moduleOptions[toolName];
   if (!toolOptions) return;
 
   for (const [, opt] of Object.entries(toolOptions) as [string, FlatOption][]) {
+    // 快捷命令跳过 path 参数（由环境变量自动注入）
+    if (skipPathMandatory && opt.source === 'path') continue;
+
     const option = new Option(
       `--${opt.optKey} ${opt.valuePlaceholder}`.trim(),
       opt.description,
     );
 
-    if (opt.required && opt.source === 'path') {
+    if (opt.required && opt.source === 'path' && !skipPathMandatory) {
       option.makeOptionMandatory();
     }
 
@@ -61,6 +64,15 @@ function registerToolOptions(toolCmd: Command, moduleName: string, toolName: str
   }
 }
 
+/**
+ * 获取指定模块的快捷命令列表
+ */
+function getShortcutsForModule(moduleName: string): ShortcutDefinition[] {
+  if (moduleName === 'issues') return ISSUE_SHORTCUTS;
+  if (moduleName === 'pulls') return PR_SHORTCUTS;
+  return [];
+}
+
 /**
  * 为每个模块注册子命令，使 cnb <module> -h 显示模块帮助
  * 每个 tool 的参数通过 Commander 的 option 系统注册，--help 自动展示参数说明
@@ -75,6 +87,9 @@ export function registerModuleCommands(program: Command): void {
       .description(`${moduleName} 模块 (${toolEntries.length} tools)`)
       .helpOption('-h, --help', '显示帮助文档');
 
+    // 收集已注册的子命令名，避免快捷命令与真实 tool 名冲突
+    const registeredNames = new Set<string>();
+
     // 为每个 tool 注册子命令
     for (const [toolName, toolInfo] of Object.entries(tools) as [string, any][]) {
       const summary = trimSummary(toolInfo.summary || '');
@@ -95,6 +110,30 @@ export function registerModuleCommands(program: Command): void {
 
       // 根据 flat-options.json 注册参数选项
       registerToolOptions(toolCmd, moduleName, toolName);
+      registeredNames.add(toolName);
+    }
+
+    // 为快捷命令注册 Commander 子命令（别名）
+    // 复用对应真实 tool 的选项定义，但跳过 path 参数（由环境变量自动注入）
+    const shortcuts = getShortcutsForModule(moduleName);
+    for (const shortcut of shortcuts) {
+      // 如果快捷命令名与真实 tool 名重复，跳过（真实 tool 优先）
+      if (registeredNames.has(shortcut.shortName)) continue;
+
+      const shortcutCmd = sub
+        .command(shortcut.shortName)
+        .description(`[快捷] ${shortcut.description}`)
+        .option('-v, --verbose', '输出完整原始响应')
+        .helpOption('-h, --help', '显示帮助文档')
+        .showHelpAfterError(true)
+        .action(async (opts: Record<string, any>) => {
+          // 传入快捷命令名，executeAction 内部会通过 resolveShortcut 转换
+          await executeAction(moduleName, shortcut.shortName, opts, sub);
+        });
+
+      // 复用真实 tool 的选项，跳过 path 参数
+      registerToolOptions(shortcutCmd, moduleName, shortcut.realTool, true);
+      registeredNames.add(shortcut.shortName);
     }
 
     // 允许未匹配到子命令时也能正常执行（不报错）
@@ -102,18 +141,13 @@ export function registerModuleCommands(program: Command): void {
     sub.allowExcessArguments();
 
     // 模块级 action：处理未匹配到子命令的情况
-    // 如果输入了快捷命令名（如 cnb issues get），Commander 匹配不到真实 tool 子命令，
-    // 会走到这里，此时尝试 resolveShortcut 将其转换为真实 tool
     sub
       .argument('[tool]', '工具名称（支持快捷命令）')
-      .action(async (toolArg: string | undefined, opts: Record<string, any>) => {
+      .action(async (toolArg: string | undefined, _opts: Record<string, any>) => {
         if (toolArg) {
-          const shortcut = resolveShortcut(moduleName, toolArg);
-          if (shortcut) {
-            // 快捷命令匹配成功，走 executeAction 流程
-            await executeAction(moduleName, toolArg, opts, sub);
-            return;
-          }
+          // 此处已不会再命中快捷命令（因为已注册为子命令），仅作兜底
+          sub.help();
+          return;
         }
         sub.help();
       });

package/client/shortcuts.ts

@@ -67,7 +67,7 @@ function getPRNumber(): string {
 // 快捷命令定义
 // ============================================================
 
-const ISSUE_SHORTCUTS: ShortcutDefinition[] = [
+export const ISSUE_SHORTCUTS: ShortcutDefinition[] = [
   { shortName: 'get',            realTool: 'get-issue',            description: '获取详情' },
   { shortName: 'list-comments',  realTool: 'list-issue-comments',  description: '获取评论列表' },
   { shortName: 'comment',        realTool: 'post-issue-comment',   description: '评论',           dataTip: "--body 内容" },
@@ -81,7 +81,7 @@ const ISSUE_SHORTCUTS: ShortcutDefinition[] = [
   { shortName: 'upload-image',   realTool: 'post-issue-image-asset-upload-url', description: '上传图片', upload: true, dataTip: "--file 图片路径" },
 ];
 
-const PR_SHORTCUTS: ShortcutDefinition[] = [
+export const PR_SHORTCUTS: ShortcutDefinition[] = [
   { shortName: 'get',            realTool: 'get-pull',                description: '获取详情' },
   { shortName: 'list-files',     realTool: 'list-pull-files',         description: '获取文件变更' },
   { shortName: 'list-commits',   realTool: 'list-pull-commits',       description: '获取提交记录' },

package/package.json

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

package/skills-template/SKILL.md

@@ -12,30 +12,29 @@ description: CNB OpenAPI 交互能力，支持仓库、Issue、PR、流水线、
 issues 快捷命令：
 - `<$CNB_CLI_CMD$> issues get` — 获取 Issue 详情
 - `<$CNB_CLI_CMD$> issues list-comments` — 列出 Issue 评论
-- `<$CNB_CLI_CMD$> issues comment --data '{"body":"内容"}'` — 发表 Issue 评论
+- `<$CNB_CLI_CMD$> issues comment --body 内容` — 发表 Issue 评论
 - `<$CNB_CLI_CMD$> issues close` — 关闭 Issue
 - `<$CNB_CLI_CMD$> issues open` — 打开 Issue
 - `<$CNB_CLI_CMD$> issues list-labels` — 列出 Issue 标签
-- `<$CNB_CLI_CMD$> issues add-labels --data '{"labels":["标签"]}'` — 添加 Issue 标签
+- `<$CNB_CLI_CMD$> issues add-labels --labels bug --labels feature` — 添加 Issue 标签
 - `<$CNB_CLI_CMD$> issues list-assignees` — 查看 Issue 处理人
-- `<$CNB_CLI_CMD$> issues add-assignees --data '{"assignees":["用户名"]}'` — 添加 Issue 处理人
-- `<$CNB_CLI_CMD$> issues upload-file --data '{"file":"本地文件路径"}'` — 上传文件到 Issue
-- `<$CNB_CLI_CMD$> issues upload-image --data '{"file":"本地图片路径"}'` — 上传图片到 Issue
+- `<$CNB_CLI_CMD$> issues add-assignees --assignees username` — 添加 Issue 处理人
+- `<$CNB_CLI_CMD$> issues upload-file --file 文件路径` — 上传文件到 Issue
+- `<$CNB_CLI_CMD$> issues upload-image --file 图片路径` — 上传图片到 Issue
 
 pulls 快捷命令：
 - `<$CNB_CLI_CMD$> pulls get` — 获取 PR 详情
 - `<$CNB_CLI_CMD$> pulls list-files` — 列出 PR 变更文件
 - `<$CNB_CLI_CMD$> pulls list-commits` — 列出 PR 提交记录
 - `<$CNB_CLI_CMD$> pulls list-comments` — 列出 PR 评论
-- `<$CNB_CLI_CMD$> pulls comment --data '{"body":"内容"}'` — 发表 PR 评论
+- `<$CNB_CLI_CMD$> pulls comment --body 内容` — 发表 PR 评论
 - `<$CNB_CLI_CMD$> pulls list-labels` — 列出 PR 标签
-- `<$CNB_CLI_CMD$> pulls add-labels --data '{"labels":["标签"]}'` — 添加 PR 标签
+- `<$CNB_CLI_CMD$> pulls add-labels --labels ready --labels approved` — 添加 PR 标签
 - `<$CNB_CLI_CMD$> pulls check-status` — 查看 CI 状态
 - `<$CNB_CLI_CMD$> pulls list-reviews` — 查看评审列表
 - `<$CNB_CLI_CMD$> pulls list-assignees` — 查看 PR 处理人
-- `<$CNB_CLI_CMD$> pulls add-assignees --data '{"assignees":["用户名"]}'` — 添加 PR 处理人
-- `<$CNB_CLI_CMD$> pulls upload-file --data '{"file":"本地文件路径"}'` — 上传文件到 PR
-- `<$CNB_CLI_CMD$> pulls upload-image --data '{"file":"本地图片路径"}'` — 上传图片到 PR
+- `<$CNB_CLI_CMD$> pulls upload-file --file 文件路径` — 上传文件到 PR
+- `<$CNB_CLI_CMD$> pulls upload-image --file 图片路径` — 上传图片到 PR
 
 注意：
 - **路径参数自动注入**：仓库 slug、Issue/PR 编号优先从环境变量自动获取，无需额外传入任何其他参数