@cnbcool/cnb-api-generate 2.17.1 → 2.17.2

package/client/lib/execute-action.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { showShort, resolveShortcut } from '../shortcuts';
+import { showShort, resolveShortcut, mergeShortcutParams } from '../shortcuts';
 import { handleUpload, handleIssueCreateUpload, type UploadPathParams } from '../utils/upload';
 import { diagnoseBuild } from './build-diagnostics';
 import { analyzeBuildTiming } from './build-timing';
@@ -76,31 +76,24 @@ export async function executeAction(
   if (shortcut) {
     params.module = shortcut.module;
     params.tool = shortcut.tool;
-
-    for (const [key, value] of Object.entries(shortcut.autoPath)) {
-      if (!params[key]) {
-        params[key] = value;
-      }
-    }
-
-    if (shortcut.autoData) {
-      for (const [key, value] of Object.entries(shortcut.autoData)) {
-        if (params[key] === undefined) {
-          params[key] = value;
-        }
-      }
-    }
+    // 用户显式传入的 --repo / --number 优先，未传时用环境变量自动注入的 autoPath 兜底
+    mergeShortcutParams(params, shortcut);
   }
 
   if (!params.tool) {
     parentCmd.help();
   }
 
-  // 上传命令走独立分支：只需 --file + autoPath，跳过 formatParams 常规流程
+  // 上传命令走独立分支：只需 --file + path 参数，跳过 formatParams 常规流程。
+  // params 中已合并好 autoPath：用户显式传入的 --repo / --number 优先，
+  // 未传时由环境变量兜底，因此这里直接取 params 即可。
   if (shortcut?.upload) {
     const isVerbose = !!opts.verbose;
     const toolFunction = loadToolFunction(shortcut.module, shortcut.tool, parentCmd);
-    const pathParams = shortcut.autoPath as UploadPathParams;
+    const pathParams: UploadPathParams = {
+      repo: (params.repo as string) || shortcut.autoPath.repo || '',
+      number: (params.number as string) || shortcut.autoPath.number,
+    };
     let data: any;
 
     if (shortcut.tool === 'post-asset-group') {
@@ -116,7 +109,7 @@ export async function executeAction(
 
   if (shortcut?.tool === '__get-ci-logs__') {
     const result = await diagnoseBuild({
-      repo: process.env.CNB_REPO_SLUG || '',
+      repo: (params.repo as string) || '',
       sn: (opts.sn as string) || undefined,
       prNumber: process.env.CNB_PULL_REQUEST_IID || undefined,
     });
@@ -126,7 +119,7 @@ export async function executeAction(
 
   if (shortcut?.tool === '__get-ci-timing__') {
     const result = await analyzeBuildTiming({
-      repo: process.env.CNB_REPO_SLUG || '',
+      repo: (params.repo as string) || '',
       sn: (opts.sn as string) || undefined,
       prNumber: process.env.CNB_PULL_REQUEST_IID || undefined,
     });

package/client/lib/format-params.ts

@@ -1,6 +1,5 @@
-import { removeSlashes } from 'slashes';
 import { helpData } from './help-data';
-import { tryParseJSON, readFileContent } from './parsers';
+import { tryParseJSON, readFileContent, unescapeString } from './parsers';
 import { buildNestedFieldMap } from '../utils/build-nested-field-map';
 import type { NestedFieldMapping } from '../utils/build-nested-field-map';
 import { restoreOriginalKeys } from '../utils/restore-original-keys';
@@ -25,8 +24,11 @@ export function getToolParamDefs(moduleName: string, toolName: string) {
  *   - 其他字段：走 tryParseJSON 以兼容嵌套 JSON
  *
  * 说明：shell 在单/双引号下不解释 `\n`，外部程序（包括本 CLI 经 commander）
- * 收到的是字面的反斜杠 + n。这里用 slashes.removeSlashes 做一次反解析，
+ * 收到的是字面的反斜杠 + n。这里用 unescapeString 做一次反解析，
  * 让 `--body "a\n b"` 与 `echo -e` 体验一致，正确还原为真实换行/制表符等。
+ *
+ * 不能用 slashes.removeSlashes：其「无损伤规则」会吞掉不认识的反斜杠，
+ * 把 `C:\path` 变成 `C:path`、`\s` 变成 `s`，静默损坏路径与正则片段。
  */
 /**
  * 过滤非法字符（如 \u0000 NUL），避免破坏环境变量和 HTTP 传输。
@@ -61,7 +63,7 @@ function assignBodyValue(
   if (Array.isArray(value)) {
     target[key] = value;
   } else if (propType === 'string') {
-    target[key] = typeof value === 'string' ? filterIllegalChars(removeSlashes(value)) : value;
+    target[key] = typeof value === 'string' ? filterIllegalChars(unescapeString(value)) : value;
   } else {
     target[key] = tryParseJSON(value as string);
   }
@@ -121,10 +123,10 @@ function assignMapField(
       if (rawV === 'true') v = true;
       else if (rawV === 'false') v = false;
     } else {
-      // 与 assignBodyValue 不同：map value 不做 removeSlashes 反解。
-      // 原因：环境变量常见值（URL / Windows 路径 / JWT 等）中的反斜杠会被
-      // removeSlashes 无损伤规则误吞（如 "C:\path" → "C:path"）。
-      // shell 侧的转义（$VAR / 引号）用户已经掌控；这里仅过滤非法 NUL 字符。
+      // 与 assignBodyValue 的 string 字段不同：map value 不做转义反解。
+      // 原因：环境变量常见值（URL / Windows 路径 / JWT 等）中的反斜杠一旦被
+      // 误吞（如 "C:\path" → "C:path"）就会损坏数据；且 map 值通常是原始串，
+      // 用户没有「像 --body 那样写 \n」的预期。这里仅过滤非法 NUL 字符。
       v = filterIllegalChars(rawV);
     }
     map[k] = v;

package/client/lib/parsers.ts

@@ -50,6 +50,29 @@ export function readFileContent(filePath: string): string {
   }
 }
 
+/**
+ * 解析字符串中的转义序列
+ * 支持：\n \t \r \\ \a \f \v \e
+ * 不支持（避免破坏代码片段）：\xHH \uHHHH \UHHHHHHHH \0NNN \c
+ * 不认识的转义序列原样保留（如 \s \d \w 等正则元字符）
+ * @param str 要解析的字符串
+ * @returns 解析后的字符串
+ */
+export function unescapeString(str: unknown): any {
+  if (typeof str !== 'string') return str;
+  const map: Record<string, string> = {
+    n: '\n',
+    t: '\t',
+    r: '\r',
+    '\\': '\\',
+    a: '\x07',
+    f: '\f',
+    v: '\v',
+    e: '\x1B',
+  };
+  return str.replace(/\\(n|t|r|\\|a|f|v|e)/g, (_: string, seq: string) => map[seq]);
+}
+
 /**
  * 解析 commander 未识别的未知选项
  * commander 开启 allowUnknownOption 后，未知选项会残留在 process.argv 中，

package/client/lib/register-modules.ts

@@ -30,6 +30,19 @@ interface FlatOption {
 const AUTO_INJECTED_PATH_KEYS = new Set(['repo', 'number', 'review_id']);
 const AUTO_INJECTED_DISPLAY_KEYS = new Set(['repo', 'number', 'review-id']);
 
+/**
+ * 为不走 registerToolOptions 的快捷命令（upload / CI 自定义命令）注册
+ * 由环境变量自动注入的 path 参数，使其可被显式覆盖。
+ * - repo：始终注册，未传时由 autoPath 从 CNB_REPO_SLUG 回填
+ * - number：仅在命令所属接口真的需要 number 时注册，避免帮助里出现「有选项但静默无效」
+ */
+function registerAutoInjectedPathOptions(cmd: Command, needNumber?: boolean): void {
+  cmd.option('--repo <string>', '仓库名称（可选，默认取 CNB_REPO_SLUG）');
+  if (needNumber) {
+    cmd.option('--number <string>', '编号（可选，默认取 CNB_ISSUE_IID / CNB_PULL_REQUEST_IID）');
+  }
+}
+
 /**
  * 为单个 tool 子命令注册 Commander options
  * 直接读取预生成的 flat-options.json 中已扁平化的参数定义，无需运行时计算
@@ -41,23 +54,28 @@ function registerToolOptions(toolCmd: Command, moduleName: string, toolName: str
   if (!toolOptions) return;
 
   for (const [, opt] of Object.entries(toolOptions) as [string, FlatOption][]) {
-    // 快捷命令下：仅跳过"由 shortcut.autoPath 从环境变量自动注入"的 path 参数
-    // （repo / number / review_id）。其余 path 参数（如 img_path、file_path）
-    // 仍需要 NPC 通过 --xxx 显式传入，因此保留注册且保留 required 标记。
-    if (
-      skipPathMandatory
+    // 快捷命令下，"由 shortcut.autoPath 从环境变量自动注入"的 path 参数
+    // （repo / number / review_id）改为注册为【可选】参数，而非直接跳过。
+    // 这样既保留环境变量自动注入的省流默认行为（executeAction 中
+    // `if (!params[key])` 仅在用户未显式传值时回填 autoPath），
+    // 又允许用户显式覆盖，例如 `cnb pulls get --repo x/y --number 97`
+    // 或跨 Issue/PR 场景下查询其它编号。
+    // 其余 path 参数（如 img_path、file_path）仍需显式传入，保留 required 标记。
+    const isAutoInjectedPath = skipPathMandatory
       && opt.source === 'path'
-      && (AUTO_INJECTED_PATH_KEYS.has(opt.optKey) || AUTO_INJECTED_DISPLAY_KEYS.has(opt.optKey))
-    ) {
-      continue;
-    }
+      && (AUTO_INJECTED_PATH_KEYS.has(opt.optKey) || AUTO_INJECTED_DISPLAY_KEYS.has(opt.optKey));
+
+    // 自动注入参数在快捷命令下是「可选、可覆盖」的，去掉源描述里与语义冲突的 [必填] 前缀
+    const autoInjectedDesc = isAutoInjectedPath
+      ? `${opt.description.replace(/^\[必填\]\s*/, '')}（可选，默认取当前 Issue/PR 环境变量）`
+      : opt.description;
 
     const option = new Option(
       `--${opt.optKey} ${opt.valuePlaceholder}`.trim(),
-      opt.description,
+      autoInjectedDesc,
     );
 
-    if (opt.required && opt.source === 'path') {
+    if (opt.required && opt.source === 'path' && !isAutoInjectedPath) {
       option.makeOptionMandatory();
     }
 
@@ -98,6 +116,40 @@ function getShortcutsForModule(moduleName: string): ShortcutDefinition[] {
   return [];
 }
 
+/**
+ * 模块下未匹配到任何子命令时的兜底处理。
+ *
+ * Commander 允许未知位置参数落到兜底 action，静默打印帮助并 return 会让调用方
+ * 拿到 exit 0 —— 对自动化（含 AI Agent）是「失败伪装成成功」：拼错一个字母
+ * （如 submit-reviewx）不会发出任何请求，却与成功调用一样返回 0，
+ * Agent 据此认为命令已生效。
+ *
+ * 因此这里向 stderr 输出双语报错并置非零退出码，让调用方能靠退出码判失败。
+ * 不传位置参数（仅 `cnb pulls`）时仍打印帮助并返回 0；
+ * 显式 `--help` / `-h` 由 Commander 内建路径处理，不会走到这里。
+ *
+ * 文案沿用本仓库既有惯例（见 execute-action.ts 的 buildToolNotFoundMessage）：
+ * 中文行 `错误：` 开头、英文行 `Error:` 开头，两条平行，且都给出模块级与全局帮助入口。
+ *
+ * 区分「选项」与「命令」是因为 sub 上开了 allowUnknownOption()：
+ * 所有未识别的 token 都会塞进 [tool]，模块级选项（如 `cnb issues --repo foo/bar`、
+ * `cnb pulls --json`）同样落到这里。这类输入的真实错因是漏写子命令或选错了选项，
+ * 报成「未知命令」会把选项名当命令名，排障方向也带偏。
+ */
+function guardUnknownTool(moduleName: string, sub: Command, toolArg: string | undefined): void {
+  if (!toolArg) {
+    sub.help();
+    return;
+  }
+  const kind = toolArg.startsWith('-') ? '选项' : '命令';
+  const kindEn = toolArg.startsWith('-') ? 'option' : 'command';
+  console.error(`错误：未知${kind}「${toolArg}」。`);
+  console.error(`可通过 \`cnb ${moduleName} --help\` 查看该模块支持的工具列表，或用 \`cnb --help\` 查看全部模块。`);
+  console.error(`Error: unknown ${kindEn} "${toolArg}". Please check the name.`);
+  console.error(`Run \`cnb ${moduleName} --help\` to list tools of this module, or \`cnb --help\` for all modules.`);
+  process.exitCode = 1;
+}
+
 /**
  * 为每个模块注册子命令，使 cnb <module> -h 显示模块帮助
  * 每个 tool 的参数通过 Commander 的 option 系统注册，--help 自动展示参数说明
@@ -159,11 +211,19 @@ export function registerModuleCommands(program: Command): void {
       // 按命令类别注册选项：upload / ci 自定义 / 普通 swagger 命令
       if (shortcut.upload) {
         shortcutCmd.requiredOption('--file <string>', '本地文件路径。必填。');
+        // 是否需要 number 由接口本身决定，而非 shortcut.repoOnly：
+        // - post-issue-comment-*-asset-upload-url（issue 评论上传）：path 为 repo + number
+        // - post-asset-group（创建 issue 时上传）：path 只有 repo，number 传了也会被忽略
+        // - pull 侧 upload-files / upload-imgs：按仓库维度上传，同样不需要 number
+        const needNumber = shortcut.realTool !== 'post-asset-group' && !shortcut.repoOnly;
+        registerAutoInjectedPathOptions(shortcutCmd, needNumber);
       } else if (
         shortcut.realTool === '__get-ci-logs__' ||
         shortcut.realTool === '__get-ci-timing__'
       ) {
         shortcutCmd.option('--sn <string>', '构建号（可选，默认自动从环境变量或 PR 状态获取）');
+        // CI 命令按仓库维度查询，允许显式覆盖环境变量中的仓库
+        shortcutCmd.option('--repo <string>', '仓库名称（可选，默认取 CNB_REPO_SLUG）');
       } else {
         registerToolOptions(shortcutCmd, moduleName, shortcut.realTool, true);
       }
@@ -179,12 +239,8 @@ export function registerModuleCommands(program: Command): void {
     sub
       .argument('[tool]', '工具名称（支持快捷命令）')
       .action(async (toolArg: string | undefined, _opts: Record<string, any>) => {
-        if (toolArg) {
-          // 此处已不会再命中快捷命令（因为已注册为子命令），仅作兜底
-          sub.help();
-          return;
-        }
-        sub.help();
+        // 此处已不会再命中快捷命令（因为已注册为子命令），仅作兜底
+        guardUnknownTool(moduleName, sub, toolArg);
       });
   }
 
@@ -225,7 +281,7 @@ export function registerModuleCommands(program: Command): void {
     skillsSub
       .argument('[tool]', '工具名称（支持快捷命令）')
       .action(async (toolArg: string | undefined, _opts: Record<string, any>) => {
-        skillsSub.help();
+        guardUnknownTool('skills', skillsSub, toolArg);
       });
   }
 }

package/client/shortcuts.ts

@@ -285,3 +285,34 @@ export function resolveShortcut(
   };
 }
 
+/**
+ * 将快捷命令的 autoPath / autoData 合并进用户传入的参数。
+ *
+ * 优先级：用户显式传入 > 环境变量自动注入（autoPath）> 常量默认值（autoData）。
+ * - autoPath（repo / number / review_id）：用户未传或传空值时用环境变量兜底
+ * - autoData（如 close 的 state='closed'）：仅在用户完全未传时兜底
+ *
+ * 这样 `--repo` / `--number` 可作为可选参数显式覆盖环境变量，
+ * 未传时保持原有「从环境变量自动注入」的省流行为。
+ *
+ * @param params 用户传入参数（会被就地修改）
+ * @param shortcut 解析后的快捷命令定义
+ * @returns 合并后的 params
+ */
+export function mergeShortcutParams(
+  params: Record<string, any>,
+  shortcut: Pick<ResolvedShortcut, 'autoPath' | 'autoData'> | null | undefined,
+): Record<string, any> {
+  if (!shortcut) return params;
+  for (const [key, value] of Object.entries(shortcut.autoPath || {})) {
+    if (!params[key]) {
+      params[key] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(shortcut.autoData || {})) {
+    if (params[key] === undefined) {
+      params[key] = value;
+    }
+  }
+  return params;
+}

package/package.json

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