@cnbcool/cnb-api-generate 1.0.2 → 1.1.1

package/built/skills-tools/generate-skill-cli-help.js

@@ -10,9 +10,45 @@ const logger = (0, debug_1.default)('csg:cli');
 function isBaseApiParamArrayData(schema) {
     return schema.type && schema.type === 'array';
 }
+/**
+ * 去除 summary/description 中的英文部分
+ * 如 "查询仓库的 Issues。List issues." → "查询仓库的 Issues"
+ * 纯英文文本不匹配时返回原文，不会丢失信息
+ */
+function trimEnglish(text) {
+    if (!text)
+        return '';
+    // 匹配中文句号"。"后面跟英文的模式
+    const match = text.match(/^(.*?[\u4e00-\u9fff].*?)[。.]\s*[A-Z]/);
+    if (match)
+        return match[1];
+    return text;
+}
+/**
+ * 从 description 中提取权限字符串
+ * 匹配格式如 "repo-issue:r"、"repo-code:rw"、"group-manage:rw"
+ * @param description 原始 description 文本
+ * @returns 逗号分隔的权限字符串，如 "repo-manage:rw,repo-code:rw"
+ */
+function extractPermission(description) {
+    if (!description)
+        return '';
+    const match = description.match(/([\w-]+:rw?)/g);
+    if (match)
+        return match.join(',');
+    return '';
+}
+/**
+ * 生成 skills CLI 的 help.json 数据
+ *
+ * 与旧版的差异：
+ * - summary/description 去除英文部分（节省 token）
+ * - 参数 description 同样去除英文
+ * - 新增 permission 字段（从 description 中提取权限字符串）
+ * - response schema 仍保留在 help.json 中，但 CLI 的 --help 输出不展示
+ */
 function generateSkillCliHelp(requestMap, defintionsMap) {
     var _a, _b, _c;
-    // 按照分类分为总help和每个模块的help
     const mainHelp = {};
     const modulesHelp = {};
     for (const [path, pathItem] of Object.entries(requestMap)) {
@@ -23,17 +59,20 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
             if (!modulesHelp[methodItem.category]) {
                 modulesHelp[methodItem.category] = {};
             }
+            const rawSummary = (methodItem.summary || '')
+                .replaceAll('\n', '')
+                .replaceAll(' *', '');
+            const rawDescription = (methodItem.description || '')
+                .replaceAll('\n', '')
+                .replaceAll(' *', '');
             modulesHelp[methodItem.category][methodItem.filename] = {
                 path: methodItem.path,
                 method: methodItem.method,
                 category: methodItem.category,
                 filename: methodItem.filename,
-                summary: (methodItem.summary || '')
-                    .replaceAll('\n', '')
-                    .replaceAll(' *', ''),
-                description: (methodItem.description || '')
-                    .replaceAll('\n', '')
-                    .replaceAll(' *', ''),
+                summary: trimEnglish(rawSummary) || rawSummary,
+                description: rawDescription,
+                permission: extractPermission(rawDescription),
                 help: {
                     parameter: {},
                     response: {},
@@ -46,7 +85,7 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
                     const item = {
                         type: parameter.type === 'integer' ? 'number' : parameter.type,
                         default: parameter.default,
-                        description: parameter.description,
+                        description: trimEnglish(parameter.description || '') || parameter.description,
                         name: parameter.name,
                         required: parameter.required || false,
                         enum: parameter.enum,
@@ -76,7 +115,6 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
                             else {
                                 item.schema.properties = { ...defintion.jsonData };
                             }
-                            // 没有$ref
                         }
                         else {
                             item.schema = parameter.schema;
@@ -86,7 +124,6 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
                         .parameter) === null || _b === void 0 ? void 0 : _b[parameter.in])) {
                         modulesHelp[methodItem.category][methodItem.filename].help.parameter[parameter.in] = {};
                     }
-                    // item不为空对象
                     switch (parameter.in) {
                         case 'path':
                         case 'query':
@@ -98,7 +135,7 @@ function generateSkillCliHelp(requestMap, defintionsMap) {
                     }
                 }
             }
-            // 获取返回数据
+            // 获取返回数据 schema
             const { responses } = methodItem.original;
             if (responses) {
                 for (const [statusCode, response] of Object.entries(responses)) {

package/built/utils/get-generate-license.js

@@ -14,7 +14,7 @@ function getGenerateLicense({ source }) {
  * ## THIS FILE WAS GENERATED VIA CNB-API-GENERATE                        ##
  * ##                                                                     ##
  * ## AUTHOR: bapelin                                                     ##
- * ## SOURCE: https://cnb.woa.com/cnb/frontend-science/cnb-api-generate   ##
+ * ## SOURCE: https://cnb.cool/cnb/frontend-science/cnb-api-generate   ##
  * -------------------------------------------------------------------------
  * @Version ${pkg.version}
  * @Source ${source}
@@ -30,7 +30,7 @@ function getApiGenerateLicense({ source }) {
  * ## THIS FILE WAS GENERATED VIA CNB-API-GENERATE                        ##
  * ##                                                                     ##
  * ## AUTHOR: bapelin                                                     ##
- * ## SOURCE: https://cnb.woa.com/cnb/frontend-science/cnb-api-generate   ##
+ * ## SOURCE: https://cnb.cool/cnb/frontend-science/cnb-api-generate   ##
  * -------------------------------------------------------------------------
  * @Version ${pkg.version}
  * @Source ${source}

package/client/core.ts

@@ -5,23 +5,55 @@ import { fetchResponseHandler } from "./fetch-response-handler";
 import { generateUniqueId } from './utils/generate-unique-id';
 
 
+/**
+ * 格式化 API 响应
+ * 构建包含以下字段的响应对象：
+ * - status: HTTP 状态码
+ * - trace: traceparent（用于调试追踪）
+ * - header: 原始分页 header（x-cnb-page 等）
+ * - page/pageSize/total/totalPages: 从 header 计算的分页信息（仅列表 API）
+ * - data: 响应体（JSON/文本/图片路径/base64）
+ * 
+ * 注意：所有字段始终保留，由 index.ts 的输出层决定展示哪些
+ */
 async function formatResponse(data: any, response: any) {
+  const status = response.status;
+  const trace = response.headers.get('traceparent');
+  const page = response.headers.get('x-cnb-page');
+  const pageSize = response.headers.get('x-cnb-page-size');
+  const total = response.headers.get('x-cnb-total');
+
   const responseData: {
     status: number;
-    trace: string;
-    header: Record<string, string>;
+    trace?: string;
+    header?: Record<string, string | null>;
+    page?: number;
+    pageSize?: number;
+    total?: number;
+    totalPages?: number;
     data: Record<string, any> | string | null;
   } = {
-    status: response.status,
-    trace: response.headers.get('traceparent'),
+    status,
+    trace,
     header: {
-      'x-cnb-page': response.headers.get('x-cnb-page'),
-      'x-cnb-page-size': response.headers.get('x-cnb-page-size'),
-      'x-cnb-total': response.headers.get('x-cnb-total'),
+      'x-cnb-page': page,
+      'x-cnb-page-size': pageSize,
+      'x-cnb-total': total,
     },
     data: null,
   };
 
+  // 分页信息（始终计算，输出层决定是否展示）
+  if (total != null) {
+    const pageNum = parseInt(page, 10) || 1;
+    const pageSizeNum = parseInt(pageSize, 10) || 10;
+    const totalNum = parseInt(total, 10) || 0;
+    responseData.page = pageNum;
+    responseData.pageSize = pageSizeNum;
+    responseData.total = totalNum;
+    responseData.totalPages = Math.ceil(totalNum / pageSizeNum);
+  }
+
   const contentType = response.headers.get('content-type') || '';
   const isJson = [
     'application/vnd.cnb.api+json',
@@ -77,7 +109,6 @@ async function formatResponse(data: any, response: any) {
     responseData.data = err?.message || 'Unknown Error';
   }
 
-
   if (responseData.status >= 200 && responseData.status < 300) {
     return await fetchResponseHandler(data._originParams, responseData);
   } 

package/client/fetch-response-handler.ts

@@ -1,10 +1,14 @@
 export async function fetchResponseHandler(fetchOriginParams: Record<string, any>, response: {
   status: number,
-  trace: string,
-  header: Record<string, string>
-  data: Record<string, any> | string | {                   // 二进制数据标识
+  trace?: string,
+  header?: Record<string, string | null>,
+  page?: number,
+  pageSize?: number,
+  total?: number,
+  totalPages?: number,
+  data: Record<string, any> | string | {
       type: 'base64';
-      data: string;     // base64 字符串
+      data: string; // base64 字符串
       mimeType: string; // 原始 MIME type，方便模型知道是什么文件
     }
   | null

package/client/index.ts

@@ -5,7 +5,6 @@ import path from 'path';
 import { showModuleHelp } from './modules.help';
 import { showToolHelp } from './tools.help';
 import { showShort, resolveShortcut } from './shortcuts';
-import util from 'util';
 
 const helpFileContent = fs.readFileSync(
   path.join(__dirname, 'help.json'),
@@ -17,33 +16,12 @@ if (!helpFileContent) {
 }
 
 const helpData = JSON.parse(helpFileContent);
+
 /**
  * 解析命令行参数
+ * 支持：--key value, --key=value, -k value (短参数), 位置参数 (module, tool)
  * @returns 解析后的参数对象
  */
-// function parseArguments(): Record<string, string | boolean | undefined> {
-//   const args = process.argv.slice(2);
-//   const result: Record<string, string | boolean | undefined> = {};
-
-//   for (let i = 0; i < args.length; i++) {
-//     const arg = args[i];
-
-//     // 检查是否是参数名（以--开头）
-//     if (arg.startsWith('--')) {
-//       const paramName = arg.slice(2);
-
-//       // 检查下一个参数是否是值（不是以--开头）
-//       if (i + 1 < args.length && !args[i + 1].startsWith('--')) {
-//         result[paramName] = args[i + 1];
-//         i++; // 跳过下一个参数（值）
-//       } else {
-//         result[paramName] = paramName === 'help' ? true : undefined;
-//       }
-//     }
-//   }
-//   return result;
-// }
-
 export function parseArguments() {
   const args = process.argv.slice(2);
   const result: Record<string, string | boolean | undefined> = {};
@@ -68,36 +46,33 @@ export function parseArguments() {
 
       const key = fullKey;
       
-      // 检查下一个参数是否是值
+      // 检查下一个参数是否是值（不以 - 开头）
       const nextArg = args[i + 1];
       const isNextArgValue = 
         i + 1 < args.length && 
         !nextArg.startsWith('--') && 
-        !nextArg.startsWith('-'); // 也防止捕获短参数作为值
+        !nextArg.startsWith('-');
 
       if (isNextArgValue) {
         result[key] = nextArg;
-        i += 2; // 跳过 key 和 value
+        i += 2;
       } else {
-        // 没有值，视为布尔标志 (flag)
-        // 特殊处理：如果用户显式想要 undefined 行为，可以在这里调整，但通常 CLI 中 flag 存在即为 true
+        // 没有值，视为布尔标志
         result[key] = true;
         i++;
       }
     } else if (arg.startsWith('-') && arg.length > 1 && !/^-?\d+$/.test(arg)) {
-      // --- 处理短参数 (Short flags, e.g., -h, -v) ---
-      // 注意：排除负数数字的情况
+      // --- 处理短参数 (e.g., -h, -v)，排除负数 ---
       const key = arg.slice(1);
       
-      // 简单处理：短参数通常不带长值，或者支持 -f value
       const nextArg = args[i + 1];
       const isNextArgValue = 
         i + 1 < args.length && 
         !nextArg.startsWith('--') && 
         !nextArg.startsWith('-');
 
-      if (isNextArgValue && key.length === 1) { 
-        // 只有单字符短参才自动吞并下一个值 (如 -o output.txt)，多字符连写 (如 -abc) 通常视为多个布尔旗标
+      // 只有单字符短参才吞并下一个值 (如 -o output.txt)
+      if (isNextArgValue && key.length === 1) {
         result[key] = nextArg;
         i += 2;
       } else {
@@ -116,7 +91,6 @@ export function parseArguments() {
     }
   }
 
-
   return result;
 }
 
@@ -136,13 +110,13 @@ function validateRequiredParams(
 
 /**
  * 尝试解析JSON字符串
+ * 先将真实控制字符转义为 JSON 合法形式，处理 shell/AI 传入的原始换行等情况
  * @param str 要解析的字符串
  * @returns 解析后的对象或原始字符串
  */
 function tryParseJSON(str: string | boolean | undefined): any {
   if (typeof str !== 'string') return str;
 
-  // 先将真实控制字符转义为 JSON 合法形式，处理 shell/AI 传入的原始换行等情况
   const escaped = str.replace(/[\x00-\x1F\x7F]/g, (ch) => {
     const map = { '\n': '\\n', '\r': '\\r', '\t': '\\t', '\b': '\\b', '\f': '\\f' };
     return map[ch] || '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0');
@@ -155,16 +129,9 @@ function tryParseJSON(str: string | boolean | undefined): any {
 }
 
 /**
- * 尝试从文件引用读取内容（支持 @filepath 语法，类似 curl -d @file）
- * @param str 要检查的字符串
- * @returns 文件内容或原始字符串
- */
-/**
- * 从文件引用或 stdin 读取内容（类似 curl 的 @file / @- 语法）
- * @param str 要检查的字符串
- * @returns 文件/stdin 内容或原始字符串
+ * 尝试从文件引用或 stdin 读取内容（类似 curl 的 @file / @- 语法）
  */
-function tryReadFileRef(str) {
+function tryReadFileRef(str: string | boolean | undefined) {
   if (typeof str !== 'string' || !str.startsWith('@')) return str;
 
   const ref = str.slice(1);
@@ -188,31 +155,92 @@ function tryReadFileRef(str) {
 }
 
 /**
- * 格式化参数对象
+ * 获取 tool 的参数定义（用于自动分发 --key value 到 path/query）
+ */
+function getToolParamDefs(moduleName: string, toolName: string) {
+  const toolHelp = helpData.modulesHelp?.[moduleName]?.[toolName];
+  if (!toolHelp) return null;
+  return toolHelp.help?.parameter || {};
+}
+
+/**
+ * 格式化参数
+ * 支持新的 --key value 扁平格式，同时向后兼容旧的 --path/--query JSON 格式。
+ * 根据 help.json 中的参数定义，自动将扁平参数分发到 path 或 query。
  * @param params 原始参数对象
- * @returns 格式化后的参数对象
+ * @returns 格式化后的参数对象，包含 module, tool, path, query, data 等
  */
 function formatParams(
   params: Record<string, string | boolean | undefined>,
 ): Record<string, any> {
-  const formatted: Record<string, any> = {};
-
-  // 处理每个参数
-  for (const [key, value] of Object.entries(params)) {
-    if (typeof value === 'string') {
-      formatted[key] = tryParseJSON(tryReadFileRef(value));
-    } else if (typeof value === 'boolean') {
-      formatted[key] = value;
+  const formatted: Record<string, any> = {
+    module: params.module,
+    tool: params.tool,
+  };
+
+  // 保留控制标志
+  if (params.help) formatted.help = true;
+  if (params.short) formatted.short = true;
+  if (params.verbose) formatted.verbose = true;
+
+  // 旧格式兼容：--path / --query / --data 是 JSON 字符串
+  if (typeof params.path === 'string') {
+    formatted.path = tryParseJSON(tryReadFileRef(params.path));
+  }
+  if (typeof params.query === 'string') {
+    formatted.query = tryParseJSON(tryReadFileRef(params.query));
+  }
+  if (typeof params.data === 'string') {
+    formatted.data = tryParseJSON(tryReadFileRef(params.data));
+  }
+
+  // 新格式：将其他 --key value 根据 help.json 自动分发到 path/query
+  const paramDefs = getToolParamDefs(
+    params.module as string,
+    params.tool as string,
+  );
+
+  if (paramDefs) {
+    const pathDef = paramDefs.path || {};
+    const queryDef = paramDefs.query || {};
+    const reservedKeys = new Set([
+      'module', 'tool', 'help', 'short', 'verbose',
+      'path', 'query', 'data', 'h', 'v',
+    ]);
+
+    for (const [key, value] of Object.entries(params)) {
+      if (reservedKeys.has(key)) continue;
+      if (typeof value === 'boolean') continue;
+
+      if (pathDef[key]) {
+        // 归入 path
+        if (!formatted.path) formatted.path = {};
+        formatted.path[key] = value;
+      } else if (queryDef[key]) {
+        // 归入 query
+        if (!formatted.query) formatted.query = {};
+        // 自动转数字
+        const paramType = queryDef[key].type;
+        if (paramType === 'number' && typeof value === 'string' && !isNaN(Number(value))) {
+          formatted.query[key] = Number(value);
+        } else {
+          formatted.query[key] = value;
+        }
+      } else {
+        // 未知参数，尝试放入 query（兼容）
+        if (!formatted.query) formatted.query = {};
+        formatted.query[key] = typeof value === 'string' && !isNaN(Number(value)) ? Number(value) : value;
+      }
     }
   }
 
-  // 当没有传递query时，要判断当前tool是否支持query
+  // 当没有传递 query 时，要判断当前 tool 是否支持 query
   if (formatted.query === undefined) {
-    const { module, tool } = formatted;
-    const toolsHelp = helpData.modulesHelp?.[module]?.[tool];
-    const toolsParam = toolsHelp?.help?.parameter || {};
-
-    if (toolsParam.query) {
+    const paramDefs2 = getToolParamDefs(
+      formatted.module,
+      formatted.tool,
+    );
+    if (paramDefs2?.query) {
       formatted.query = {};
     }
   }
@@ -220,9 +248,70 @@ function formatParams(
   return formatted;
 }
 
+/**
+ * 精简响应对象（非 verbose 模式使用）
+ * - 去掉 trace（仅错误时保留）
+ * - 去掉 header（原始 x-cnb-* 头）
+ * - 仅列表 API 时保留分页信息
+ */
+function compactResponse(response: any): any {
+  if (!response || typeof response !== 'object') return response;
+
+  const compact: any = { status: response.status };
+
+  // 仅错误时保留 trace
+  if (response.status >= 300 && response.trace) {
+    compact.trace = response.trace;
+  }
+
+  // 仅列表 API 时保留分页信息
+  if (response.total != null) {
+    compact.page = response.page;
+    compact.pageSize = response.pageSize;
+    compact.total = response.total;
+    compact.totalPages = response.totalPages;
+  }
+
+  compact.data = response.data;
+  return compact;
+}
+
+/**
+ * 判断是否是标准响应结构（有 status + data 字段）
+ * cag.config.js 中的 responseConverter 可能返回裸 data（不含 status），需要区分处理
+ */
+function isStandardResponse(response: any): boolean {
+  return response && typeof response === 'object' && typeof response.status === 'number' && 'data' in response;
+}
+
+/**
+ * 格式化 CLI 输出
+ * - verbose 模式：完整 JSON（含 trace、header 等全部字段）
+ * - 非标准响应（converter 返回裸 data）：直接 JSON 输出
+ * - 标准响应：精简 JSON（去掉 trace、header）
+ */
+function formatOutput(response: any, verbose: boolean): string {
+  // --verbose 模式：输出完整原始信息
+  if (verbose) {
+    return JSON.stringify(response, null, 2);
+  }
+
+  // converter 可能返回裸 data（没有标准 {status, data} 结构），直接输出
+  if (!isStandardResponse(response)) {
+    return JSON.stringify(response, null, 2);
+  }
+
+  // 精简响应
+  const compact = compactResponse(response);
+
+  return JSON.stringify(compact, null, 2);
+}
+
 /**
  * 显示帮助文档
- * @param moduleName 模块名称，如果指定则显示模块帮助
+ * - 无参数：显示顶层帮助（模块列表 + 参数说明 + 用法示例）
+ * - 指定 module：显示模块帮助（工具列表）
+ * - 指定 module + tool：显示工具帮助（参数详情 + 示例）
  */
 function showHelp(moduleName?: string, tool?: string): void {
   if (moduleName && tool) {
@@ -230,32 +319,49 @@ function showHelp(moduleName?: string, tool?: string): void {
   } else if (moduleName) {
     showModuleHelp(helpData, moduleName);
   } else {
-    let moduleListMsg = ``;
-    for (const [module, count] of Object.entries(helpData.mainHelp)) {
-      moduleListMsg += `- ${module}, tool数量(${count})\n  `;
+    const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
+
+    // 紧凑的模块列表
+    const moduleParts: string[] = [];
+    for (const [mod, count] of Object.entries(helpData.mainHelp)) {
+      moduleParts.push(`${mod}(${count})`);
     }
 
-    const helpMeg = `
-CNB OpenAPI CLI 工具\n
-可用模块：
-  ${moduleListMsg}
-参数说明：
-  <module> (必须) 模块名称 (例如: issues)，可直接配合 --help 查看该模块帮助
-  <tool>   (必须) 工具/动作名称 (例如: list-issues)
-  --path   (可选) 路径参数，JSON字符串
-  --query  (可选) 查询参数，JSON字符串
-  --data   (可选) 数据参数，JSON字符串
-  --help   (可选) 显示此帮助文档
-  --short  (可选) 显示操作当前仓库（Issue/PR）的快捷命令
-
-使用示例：
-  ${process.env.CNB_CLI_CMD} --help
-  ${process.env.CNB_CLI_CMD} --short
-  ${process.env.CNB_CLI_CMD} issues --help
-  ${process.env.CNB_CLI_CMD} issues list-issues --help
-  ${process.env.CNB_CLI_CMD} issues list-issues --path '{"repo": "my-project"}' --query '{"page": 1, "pageSize": 10}'
+    // 每行放几个模块
+    const lines: string[] = [];
+    let currentLine = '  ';
+    for (const part of moduleParts) {
+      if (currentLine.length + part.length > 78) {
+        lines.push(currentLine);
+        currentLine = '  ' + part + ' ';
+      } else {
+        currentLine += part + ' ';
+      }
+    }
+    if (currentLine.trim()) lines.push(currentLine);
+
+    const helpMsg = `
+CNB OpenAPI CLI
+
+模块(tool数量):
+${lines.join('\n')}
+
+参数:
+  <module>          模块名称 (如: issues, pulls, git)
+  <tool>            工具名称 (如: list-issues, get-issue)
+  --key value       路径或查询参数，CLI 自动识别归类
+  --data 'JSON'     请求体参数，JSON 字符串
+  --verbose         输出完整响应（含 trace、header）
+  --help            显示帮助文档
+  --short           显示当前仓库的快捷命令
+
+用法: ${cliCmd} issues list-issues --repo my-org/my-repo --page 1 --pageSize 10
+      ${cliCmd} issues create-issue --repo my-org/my-repo --data '{"title":"Bug"}'
+帮助: ${cliCmd} <module> --help
+      ${cliCmd} <module> <tool> --help
+快捷: ${cliCmd} --short
 `;
-    console.log(helpMeg);
+    console.log(helpMsg);
   }
 }
 
@@ -263,49 +369,55 @@ CNB OpenAPI CLI 工具\n
  * 主函数
  */
 async function main() {
-  // 解析命令行参数
   const params = parseArguments();
 
-  // 处理 --short：显示当前场景的快捷命令
+  // 处理 --short
   if (params.short) {
     showShort();
     process.exit(0);
   }
 
-  // 尝试解析快捷命令（如 cnb issues get → get-issue）
+  // 尝试解析快捷命令
   const shortcut = resolveShortcut(
     params.module as string | undefined,
     params.tool as string | undefined,
   );
   if (shortcut) {
-    // 快捷命令：替换为实际 tool 名
     params.tool = shortcut.tool;
 
-    // 自动注入 path 参数（如果用户没有手动传 --path）
-    if (!params.path) {
-      if (Object.keys(shortcut.autoPath).length > 0) {
-        params.path = JSON.stringify(shortcut.autoPath);
+    // 自动注入 path 参数（兼容新旧格式）
+    // 新格式：用户可能直接传了 --repo xxx，检查扁平参数是否已存在
+    const autoPathKeys = Object.keys(shortcut.autoPath);
+    const hasPathAlready = params.path || autoPathKeys.some(k => params[k]);
+
+    if (!hasPathAlready) {
+      if (autoPathKeys.length > 0) {
+        // 新格式：直接注入为扁平参数
+        for (const [key, value] of Object.entries(shortcut.autoPath)) {
+          if (!params[key]) {
+            params[key] = value;
+          }
+        }
       } else {
-        // 环境变量未设置，提示用户
         const envHint =
           params.module === 'issues'
             ? 'CNB_REPO_SLUG 和 CNB_ISSUE_IID'
             : 'CNB_REPO_SLUG 和 CNB_PULL_REQUEST_IID';
         console.error(
-          `快捷命令需要环境变量 ${envHint}，或手动传 --path 参数。\n` +
+          `快捷命令需要环境变量 ${envHint}，或手动传参数。\n` +
             `提示：运行 ${process.env.CNB_CLI_CMD || 'cnb'} --short 查看快捷命令详情。`,
         );
         process.exit(1);
       }
     }
 
-    // 自动注入 data 参数（如 close → {"state":"closed"}）
+    // 自动注入 data 参数
     if (shortcut.autoData && !params.data) {
       params.data = JSON.stringify(shortcut.autoData);
     }
   }
 
-  // 验证必须参数（当没有请求帮助时）
+  // 验证必须参数
   if (!validateRequiredParams(params)) {
     showHelp(
       params.module as string | undefined,
@@ -317,6 +429,22 @@ async function main() {
   // 格式化参数
   const formattedParams = formatParams(params);
 
+  // 参数预检：缺少必填 path 参数时自动输出 tool help
+  const toolHelpData = helpData.modulesHelp?.[formattedParams.module]?.[formattedParams.tool];
+  if (toolHelpData) {
+    const pathDef = toolHelpData.help?.parameter?.path;
+    if (pathDef) {
+      const missingRequired = Object.entries(pathDef)
+        .filter(([, p]: [string, any]) => p.required && !formattedParams.path?.[p.name])
+        .map(([k]) => `--${k}`);
+      if (missingRequired.length > 0) {
+        console.error(`缺少必填参数: ${missingRequired.join(', ')}\n`);
+        showToolHelp(helpData, formattedParams.module, formattedParams.tool);
+        process.exit(1);
+      }
+    }
+  }
+
   // 动态引入模块
   const toolPath = path.join(
     __dirname,
@@ -371,7 +499,7 @@ async function main() {
   }
 
   const data = await toolFunction(...toolsParam);
-  console.log(util.inspect(data, { showHidden: false, depth: null }));
+  console.log(formatOutput(data, !!formattedParams.verbose));
 }
 
 main();

package/client/modules.help.ts

@@ -1,3 +1,15 @@
+/**
+ * 去除 summary 中的英文部分（保留中文句号前的内容）
+ */
+function trimSummary(summary: string): string {
+  if (!summary) return '';
+  // 匹配中文句号"。"后面跟英文的模式，只保留中文部分
+  const match = summary.match(/^(.*?[\u4e00-\u9fff].*?)[。.]\s*[A-Z]/);
+  if (match) return match[1];
+  // 没有匹配到则返回原文
+  return summary;
+}
+
 /**
  * 显示模块帮助文档
  * @param helpData 帮助数据
@@ -10,27 +22,23 @@ export function showModuleHelp(helpData: any, moduleName: string): void {
     process.exit(1);
   }
 
-  let toolListMsg = ``;
-  for (const [tool, info] of Object.entries(moduleHelpData)) {
-    toolListMsg += `- ${(info as any).filename}, ${(info as any).summary}\n  `;
+  const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
+
+  let toolListMsg = '';
+  for (const [, info] of Object.entries(moduleHelpData)) {
+    const name = (info as any).filename;
+    const summary = (info as any).summary;
+    toolListMsg += `  ${name.padEnd(30)} ${summary}\n`;
   }
 
-  const helpMeg = `
-模块${moduleName}帮助文档\n
-可用工具：
-  ${toolListMsg}
-参数说明：
-  <module> (必须) 模块名称 (例如: issues)，可直接配合 --help 查看该模块帮助
-  <tool>   (必须) 工具/动作名称 (例如: list-issues)
-  --path   (可选) 路径参数，JSON字符串
-  --query  (可选) 查询参数，JSON字符串
-  --data   (可选) 数据参数，JSON字符串
-  --help   (可选) 显示此帮助文档
+  const helpMsg = `
+${moduleName} 模块
 
-使用示例：
-  ${process.env.CNB_CLI_CMD} issues --help
-  ${process.env.CNB_CLI_CMD} issues list-issues --help
-  ${process.env.CNB_CLI_CMD} issues list-issues --path '{"repo": "my-project"}' --query '{"page": 1, "pageSize": 10}'
+工具:
+${toolListMsg}
+用法: ${cliCmd} ${moduleName} <tool> --help
 `;
-  console.log(helpMeg);
+  console.log(helpMsg);
 }
+
+export { trimSummary };

package/client/tools.help.ts

@@ -1,7 +1,10 @@
-import util from 'util';
-import { schemaToJson } from './schemaToJson';
+import { trimSummary } from './modules.help';
+
 /**
  * 显示工具帮助文档
+ * - path 和 query 参数混合展示为统一的 --key value 格式（LLM 不需要区分来源）
+ * - body 参数展示顶层字段列表，从 schema.required 数组读取必填标记
+ * - 权限直接读 help.json 中预提取的 permission 字段
  * @param helpData 帮助数据
  * @param moduleName 模块名称
  * @param tool 工具名称
@@ -17,88 +20,105 @@ export function showToolHelp(
     process.exit(1);
   }
 
-  const { summary, description, help } = toolHelpData;
+  const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
+  const { summary, permission, help } = toolHelpData;
   const { parameter } = help;
   const { path, query, body } = parameter;
 
-  // path参数说明
-  let pathMsg = '';
-  const pathParamsExample: Record<string, string> = {};
+  // 收集所有扁平参数（path + query 混合展示）
+  const paramLines: string[] = [];
+  const exampleParts: string[] = [];
+
+  // path 参数
   if (path) {
-    pathMsg = `--path参数详细说明：
-${Object.keys(path)
-  .map((key) => {
-    if (path[key].required) {
-      pathParamsExample[key] = `<${path[key].type}>`;
+    for (const [key, param] of Object.entries(path) as any) {
+      const req = param.required ? ',必填' : '';
+      paramLines.push(`  --${key.padEnd(14)} (${param.type}${req}) ${param.description || ''}`);
+      if (param.required) {
+        exampleParts.push(`--${key} <${param.type}>`);
+      }
     }
-    return `  - ${key} (${path[key].type}) - ${path[key].description}(${path[key].required ? '必填' : '选填'})`;
-  })
-  .join('\n')}
-`;
   }
 
-  // query参数说明
-  let queryMsg = '';
-  const queryParamsExample: Record<string, string> = {};
+  // query 参数
   if (query) {
-    queryMsg = `--query详细参数：
-${Object.keys(query)
-  .map((key) => {
-    if (query[key].required) {
-      queryParamsExample[key] = `<${query[key].type}>`;
-    } else if (query[key].default !== undefined) {
-      queryParamsExample[key] = query[key].default;
+    for (const [key, param] of Object.entries(query) as any) {
+      const req = param.required ? ',必填' : '';
+      const enumStr = param.enum ? ` [${param.enum.join(',')}]` : '';
+      paramLines.push(`  --${key.padEnd(14)} (${param.type}${req}) ${param.description || ''}${enumStr}`);
+      if (param.required) {
+        exampleParts.push(`--${key} <${param.type}>`);
+      }
     }
-    return `  - ${key} (${query[key].type}) - ${query[key].description}(${query[key].required ? '必填' : '选填'})${query[key].enum ? `, [枚举: ${query[key].enum.join(', ')}]` : ''}`;
-  })
-  .join('\n')}
-`;
   }
 
-  // data参数说明
+  // body 参数
   let bodyMsg = '';
-  let bodyParamsExample: Record<string, string> = {};
+  let bodyExample = '';
   if (body) {
-    const { type, description, required, schema } = body;
+    const { schema } = body;
     if (schema) {
-      bodyParamsExample = schemaToJson(schema, {});
-      bodyMsg = `--data参数详细说明：
-${util.inspect(schema, { showHidden: false, depth: null })}`;
-    } else {
-      bodyMsg = `--data参数详细说明：
-  - ${type} - ${description}(${required ? '必填' : '选填'})
-`;
+      const bodyLines: string[] = [];
+      const bodyExampleObj: Record<string, string> = {};
+      const props = schema.type === 'array'
+        ? schema.items?.properties
+        : schema.properties;
+
+      // Swagger 的 required 是父级数组，不在每个 property 上
+      const requiredFields = new Set<string>(
+        schema.required || schema.items?.required || []
+      );
+
+      if (props) {
+        for (const [key, prop] of Object.entries(props) as any) {
+          const type = prop.type || 'object';
+          const isRequired = requiredFields.has(key);
+          const req = isRequired ? ',必填' : '';
+          // body 属性的 description 在生成时未 trim，运行时 trim
+          const desc = trimSummary(prop.description || '');
+          bodyLines.push(`  ${key.padEnd(16)} (${type}${req}) ${desc}`);
+          if (isRequired) {
+            bodyExampleObj[key] = `<${type}>`;
+          }
+        }
+      }
+
+      if (bodyLines.length > 0) {
+        bodyMsg = `\nBody (--data JSON):\n${bodyLines.join('\n')}`;
+      }
+      if (Object.keys(bodyExampleObj).length > 0) {
+        bodyExample = ` --data '${JSON.stringify(bodyExampleObj)}'`;
+      } else if (bodyLines.length > 0) {
+        // 没有 required 标记时，取前两个字段作为示例
+        const sampleKeys = Object.keys(props).slice(0, 2);
+        const sampleObj: Record<string, string> = {};
+        for (const k of sampleKeys) {
+          sampleObj[k] = `<${props[k].type || 'string'}>`;
+        }
+        if (sampleKeys.length > 0) {
+          bodyExample = ` --data '${JSON.stringify(sampleObj)}'`;
+        }
+      }
     }
   }
 
-  const exampleMsg = [
-    `node ./skills/scripts/core ${moduleName} ${tool}`,
-  ];
-  if (Object.keys(pathParamsExample).length > 0) {
-    exampleMsg.push(`--path '${JSON.stringify(pathParamsExample)}'`);
+  // 构建输出
+  let output = `${moduleName} ${tool} - ${summary}`;
+  if (permission) {
+    output += `\n权限: ${permission}`;
   }
-  if (Object.keys(queryParamsExample).length > 0) {
-    exampleMsg.push(`--query '${JSON.stringify(queryParamsExample)}'`);
+
+  if (paramLines.length > 0) {
+    output += `\n\n参数:\n${paramLines.join('\n')}`;
   }
-  if (Object.keys(bodyParamsExample).length > 0) {
-    exampleMsg.push(`--data '${JSON.stringify(bodyParamsExample)}'`);
+
+  if (bodyMsg) {
+    output += bodyMsg;
   }
 
-  const helpMeg = `
-工具${tool}帮助文档\n
-工具说明：
-  1. ${summary}
-  2. ${description}
-\n参数说明：
-  <module> (必须) 模块名称 (例如: issues)，可直接配合 --help 查看该模块帮助
-  <tool>   (必须) 工具/动作名称 (例如: list-issues)
-  --path   (可选) 路径参数，JSON字符串
-  --query  (可选) 查询参数，JSON字符串
-  --data   (可选) 数据参数，JSON字符串
-  --help   (可选) 显示此帮助文档
-${pathMsg && `\n${pathMsg}`}${queryMsg && `\n${queryMsg}`}${bodyMsg && `\n${bodyMsg}`}
-\n使用示例：
-  ${exampleMsg.join(' ')}
-`;
-  console.log(helpMeg);
+  // 示例
+  const exampleCmd = `${cliCmd} ${moduleName} ${tool}${exampleParts.length > 0 ? ' ' + exampleParts.join(' ') : ''}${bodyExample}`;
+  output += `\n\n示例: ${exampleCmd}`;
+
+  console.log(output);
 }

package/package.json

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

package/skills-template/SKILL.md

@@ -1,100 +1,21 @@
 ---
 name: cnb-api
-description: 提供与CNB（Cloud Native Build）OpenAPI的完整交互能力，支持项目、组织、代码仓库、Issue、PR、合并请求、流水线，制品库等核心功能的增删改查操作。适用于开发协作、代码管理和CI/CD流程管理场景。关键词：CNB、云原生构建、组织、代码仓库、Issue、PR、合并请求、流水线、制品库，查询、新增、修改、删除、评论、合并、审批。
+description: CNB OpenAPI 交互能力，支持仓库、Issue、PR、流水线、制品库等操作。
 ---
 
 # cnb-api
 
-## 概括
+操作 CNB 平台资源的 CLI 工具。
 
-本Skill提供完整的CNB的Openapi完整交互能力，用户可以使用此skills对CNB上的资源进行操作。
+## 使用
 
-## 适用场景
+1. `<$CNB_CLI_CMD$> --help` 查看所有模块
+2. `<$CNB_CLI_CMD$> <module> --help` 查看模块下的工具列表
+3. `<$CNB_CLI_CMD$> <module> <tool> --help` 查看工具参数
+4. 按参数说明执行
 
-当用户描述对CNB上的资源进行操作时，应该使用此skills进行操作。例如：
-- 查询cnb上某个仓库的Issue列表
-- 对cnb上的某个仓库的Issue或者pr进行评论。
-- ...
+## 规则
 
-## 核心原则
-
-### 准确性原则
-- **CRITICAL**: 必须先执行 `<$CNB_CLI_CMD$> --help` 获取最新的使用方式
-- **CRITICAL**: 必须通过使用 `<$CNB_CLI_CMD$>`命令行工具，按照帮助信息执行操作
-- **CRITICAL**: 禁止推测或臆断使用方式，严格基于脚本返回的帮助信息进行操作
-- **CRITICAL**: 不要询问用户"是否需要我执行"，直接根据帮助信息执行脚本，并返回结果
-
-## 脚本使用指南
-
-### 第一步：获取帮助信息
-在执行任何任务前，必须先运行以下命令获取最新的使用方式：
-
-```bash
-<$CNB_CLI_CMD$> --help
-```
-
-这将显示所有可用的模块及其工具列表。
-
-### 第二步：查看具体模块帮助
-使用 `--module` 参数查看特定模块的详细帮助：
-
-```bash
-<$CNB_CLI_CMD$> --module <模块名> -help
-```
-
-### 第三步：查看工具详细使用
-使用 `--module` 和 `--tool` 参数查看工具的详细参数说明：
-
-```bash
-<$CNB_CLI_CMD$> --module <模块名> --tool <工具名> --help
-```
-
-### 第四步：执行工具
-根据第三步获取的参数说明，执行工具：
-
-```bash
-<$CNB_CLI_CMD$> --module <模块名> --tool <工具名> --path '{"参数": "值"}' --query '{"参数": "值"}' --data '{"参数": "值"}'
-```
-
-**参数说明：**
-- `--module`: 必须参数，模块名称
-- `--tool`: 必须参数，工具名称
-- `--path`: 可选参数，路径参数，JSON字符串格式
-- `--query`: 可选参数，查询参数，JSON字符串格式
-- `--data`: 可选参数，数据参数，JSON字符串格式
-- `--help`: 可选参数，显示帮助文档
-
-### 第五步：处理结果
-
-每一个工具调用都会返回一个标准的JSON结构:
-- status: 一个http状态码
-- trace: 本次调用的traceID
-- header: 本次调用的header
-- data: 本次调用的openapi返回的实体内容
-
-#### header说明
-当请求列表时，会在header中包含以下字段说明列表的情况：
-- `x-cnb-page`: 当前页数
-- `x-cnb-page-size`: 每页条数
-- `x-cnb-total`: 总条数
-
-从中可以获取到列表的总条数，以及当前页数和每页条数，避免循环请求。
-
-#### status说明
-API 返回标准的 JSON 格式响应。请根据 HTTP 状态码判断请求是否成功：
-
-- 200: 请求成功
-- 400: 请求参数错误
-- 401: 未授权
-- 403: 禁止访问
-- 404: 资源不存在
-- 500: 服务器内部错误
-
-当本地调用返回的 `status` 在 200 ~ 299 之间，只需要返回 `data` 内容给用户。只有当 `status >= 300` 时，才将 `status` 和 `trace` 返回给用户。
-
-#### 资源处理
-
-当尝试下载图片进行图片分析时，遇到图片下载异常时，请使用以下工具进行图片下载！
-  ```bash
-  node scripts/core/index.js assets get-imgs --help
-```
+- 必须先 --help 获取参数，禁止猜测
+- 直接执行，不要询问用户确认
+- status 200-299 只返回 data 给用户，>=300 时附带 status 和 trace