@cnbcool/cnb-api-generate 2.7.7 → 2.8.1

package/built/utils/flatten-tool-options.js

@@ -84,12 +84,9 @@ function flattenToolOptions(toolInfo) {
                 ? (0, clean_array_desc_1.cleanArrayDesc)((0, trim_summary_1.trimSummary)(prop.description || ''))
                 : (0, trim_summary_1.trimSummary)(prop.description || '');
             const arrayHint = isArray ? ' (可多次传入)' : '';
-            const fileRefHint = !isArray && prop.type === 'string' && key === 'body'
-                ? ' (支持 @file 引用)'
-                : '';
             const desc = isRequired
-                ? `[必填] ${rawDesc}${arrayHint}${fileRefHint}`
-                : `${rawDesc}${arrayHint}${fileRefHint}`;
+                ? `[必填] ${rawDesc}${arrayHint}`
+                : `${rawDesc}${arrayHint}`;
             const opt = {
                 optKey,
                 valuePlaceholder,
@@ -100,13 +97,26 @@ function flattenToolOptions(toolInfo) {
             };
             options.push(opt);
         }
+        // 若 body 中存在 string 类型的 `body` 字段，提供独立的 --body-file 选项，
+        // 从指定文件读取内容作为正文（适合多行/长文本，避免 shell 参数长度限制）。
+        const bodyProp = bodyDef.schema.properties.body;
+        if (bodyProp && bodyProp.type === 'string') {
+            options.push({
+                optKey: 'body-file',
+                valuePlaceholder: '<path>',
+                description: '从文件读取内容作为 body 正文',
+                required: false,
+                isArray: false,
+                source: 'body',
+            });
+        }
     }
     // body 存在时添加 --data fallback
     if (bodyDef) {
         options.push({
             optKey: 'data',
             valuePlaceholder: '<json>',
-            description: 'Request body (JSON 字符串或 @file 引用，可替代逐个 body 字段)',
+            description: 'Request body (JSON 字符串，可替代逐个 body 字段)',
             required: false,
             isArray: false,
             source: 'body',

package/client/lib/format-params.ts

@@ -1,5 +1,5 @@
 import { helpData } from './help-data';
-import { tryParseJSON, tryReadFileRef } from './parsers';
+import { tryParseJSON, readFileContent } 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';
@@ -14,6 +14,27 @@ export function getToolParamDefs(moduleName: string, toolName: string) {
   return toolHelp.help?.parameter || {};
 }
 
+/**
+ * 将 body 字段值按 schema 类型写入 target。
+ *   - array 值：原样保留
+ *   - string 字段：保留原始字符串（避免纯数字字符串被转 number）
+ *   - 其他字段：走 tryParseJSON 以兼容嵌套 JSON
+ */
+function assignBodyValue(
+  target: Record<string, any>,
+  key: string,
+  value: any,
+  propType: string | undefined,
+): void {
+  if (Array.isArray(value)) {
+    target[key] = value;
+  } else if (propType === 'string') {
+    target[key] = value;
+  } else {
+    target[key] = tryParseJSON(value as string);
+  }
+}
+
 /**
  * 格式化参数
  * 支持新的 --key value 扁平格式，同时向后兼容旧的 --path/--query JSON 格式。
@@ -51,8 +72,20 @@ export function formatParams(
       'module', 'tool', 'help', 'short', 'verbose', 'h', 'v',
     ]);
 
+    // --body-file: 从指定文件读取内容作为 body 字段正文（适合多行/长文本）。
+    // 仅当 tool 存在 string 类型的 body 字段时，flatten-tool-options 才注册该选项。
+    // restoreOriginalKeys 已把 commander 的 camelCase（bodyFile）还原为 body-file，这里兼容两种形态。
+    // 读取到内容后在最后统一写入 formatted.data.body（优先级最高）。
+    reservedKeys.add('body-file');
+    reservedKeys.add('bodyFile');
+    let bodyFromFile: string | undefined;
+    const bodyFileRef = (params['body-file'] ?? (params as any).bodyFile);
+    if (typeof bodyFileRef === 'string' && bodyFileRef.length > 0) {
+      bodyFromFile = readFileContent(bodyFileRef);
+    }
+
     // --data 是 CLI 通用 fallback 选项（见 flatten-tool-options.ts，仅在 tool 有 body 时注册），
-    // 接收 JSON 字符串（或 @file 引用）作为 body 整体。
+    // 接收 JSON 字符串作为 body 整体。
     // 仅当 'data' 不是该 tool 真实的 path/query/body 字段名时才启用 fallback 语义，
     // 否则按 swagger 定义当业务字段处理（保留 commit 120d557 引入的能力）。
     //
@@ -68,7 +101,7 @@ export function formatParams(
     if (dataIsFallback) {
       reservedKeys.add('data');
       if (typeof params.data === 'string' && params.data.length > 0) {
-        const parsed = tryParseJSON(tryReadFileRef(params.data));
+        const parsed = tryParseJSON(params.data);
         if (bodyIsArrayType && Array.isArray(parsed)) {
           dataArrayFromFlag = parsed;
         } else if (!bodyIsArrayType && parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
@@ -177,16 +210,7 @@ export function formatParams(
       } else if (bodyProps[key]) {
         // body 字段（无冲突，直接用原 key）
         if (!formatted.data) formatted.data = {};
-        if (Array.isArray(value)) {
-          formatted.data[key] = value;
-        } else if (bodyProps[key].type === 'string') {
-          // schema 定义为 string 类型时，保持原始字符串，不做 JSON 解析
-          // 避免纯数字字符串（如 "123"）被转为 number
-          // 支持 @file 语法：从文件读取长文本内容（避免 shell 长参数截断）
-          formatted.data[key] = tryReadFileRef(value as string);
-        } else {
-          formatted.data[key] = tryParseJSON(value as string);
-        }
+        assignBodyValue(formatted.data, key, value, bodyProps[key].type);
       } else {
         // 处理 d- 前缀（冲突时 CLI 以 d- 前缀传入）
         const stripped = (key.startsWith('d-') || key.startsWith('d_'))
@@ -236,7 +260,7 @@ export function formatParams(
           const originalKey = key.replace(/^d[-_]/, '');
           if (bodyProps[originalKey]) {
             if (!formatted.data) formatted.data = {};
-            formatted.data[originalKey] = Array.isArray(value) ? value : tryParseJSON(value as string);
+            assignBodyValue(formatted.data, originalKey, value, bodyProps[originalKey].type);
           } else {
             if (!formatted.query) formatted.query = {};
             formatted.query[key] = typeof value === 'string' && !isNaN(Number(value)) ? Number(value) : value;
@@ -287,6 +311,13 @@ export function formatParams(
     } else if (dataBaseFromFlag) {
       formatted.data = { ...dataBaseFromFlag, ...(formatted.data || {}) };
     }
+
+    // --body-file 优先级最高：覆盖 --body 逐字段值与 --data 中的 body，
+    // 确保「从文件读取正文」的显式意图最终生效。
+    if (bodyFromFile !== undefined) {
+      if (!formatted.data) formatted.data = {};
+      formatted.data.body = bodyFromFile;
+    }
   }
 
   // formatted.query 仅在用户真传了 query 值时才存在；toolFunction 第 1 形参形态

package/client/lib/parsers.ts

@@ -21,37 +21,31 @@ export function tryParseJSON(str: string | boolean | undefined): any {
 }
 
 /**
- * 尝试从文件引用或 stdin 读取内容（类似 curl 的 @file / @- 语法）
- *
- * 注意：一旦用户显式使用 @ 前缀，就表示其意图是读取文件/stdin。
- * 此时若文件不存在或读取失败，应直接报错退出，避免把 "@/path/xxx"
- * 字面量当作正文发送出去导致数据错误。
+ * 从指定路径读取文件内容（用于 --body-file）。
+ * 支持 `-` 表示从 stdin 读取，读取失败直接报错退出。
  */
-export function tryReadFileRef(str: string | boolean | undefined) {
-  if (typeof str !== 'string' || !str.startsWith('@')) return str;
-
-  const ref = str.slice(1);
-
-  // @- 表示从 stdin 读取
-  if (ref === '-') {
+export function readFileContent(filePath: string): string {
+  // - 表示从 stdin 读取
+  if (filePath === '-') {
     try {
       return fs.readFileSync(0, 'utf8').trim();
     } catch (e) {
-      console.error(`从 stdin 读取失败: ${e.message}`);
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error(`从 stdin 读取失败: ${msg}`);
       process.exit(1);
     }
   }
 
-  // @/path/to/file 表示从文件读取
-  if (!fs.existsSync(ref)) {
-    console.error(`文件不存在: ${ref}`);
-    process.exit(1);
-  }
-
   try {
-    return fs.readFileSync(ref, 'utf8').trim();
+    return fs.readFileSync(filePath, 'utf8').trim();
   } catch (e) {
-    console.error(`读取文件失败: ${ref} - ${e.message}`);
+    const { code } = e as NodeJS.ErrnoException;
+    if (code === 'ENOENT') {
+      console.error(`文件不存在: ${filePath}`);
+    } else {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error(`读取文件失败: ${filePath} - ${msg}`);
+    }
     process.exit(1);
   }
 }

package/package.json

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

package/skills-template/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cnb-api
-description: CNB 平台交互命令，支持仓库、Issue、PR、流水线、制品库等操作。
+description: CNB 平台交互命令，支持 Issue/PR 评论、提交 PR、CI 日志查询、代码仓库/制品库读写等操作。
 ---
 
 # cnb-api
@@ -12,12 +12,17 @@ description: CNB 平台交互命令，支持仓库、Issue、PR、流水线、
 <$QUICK_COMMANDS$>
 
 注意事项：
-- **链接结构**：Issue 链接格式为 `<host>/<slug>/-/issues/<number>`，PR 链接格式为 `<host>/<slug>/-/pulls/<number>`。在生成或引用链接时请遵循此结构。
 - **参数自动识别**：快捷命令中的 Issue/PR 编号会自动从环境变量识别，无需额外传递。
-- **默认仅需摘要**：默认会精简响应输出结果，只返回核心字段。添加 `--verbose` 输出完整数据。
-- **单引号传参**：传递多行文本参数时，使用单引号可防止命令注入攻击，并减少不必要的转义。
+- **默认仅需摘要**：默认会精简响应输出结果，添加 `--verbose` 输出完整数据。
+- **单引号传参**：当 bash 的参数为多行文本时，使用单引号可减少防止命令注入攻击。
 - **快捷命令适用范围**: 快捷命令只能操作当前仓库的当前 Issue/PR，跨仓库或跨编号操作请参考 `更多 API`。
-- **npc提及和召唤的区别**: 评论中直接 @npc 会召唤 npc 干活，如果只提及不召唤，应该去掉 `@` 符号，或使用反引号包裹 `@npc`。 
+- **关于提及和召唤**: 评论中直接 @npc 会召唤 npc 干活，如果只提及不召唤，应使用反引号包裹 `@npc`。
+
+## 常用链接
+
+在生成链接时请遵循下面的结构：
+- Issue: `<host>/<slug>/-/issues/<number>`
+- PR: `<host>/<slug>/-/pulls/<number>`
 
 ## 更多 API