@cnbcool/cnb-api-generate 2.19.0 → 2.20.0

package/client/lib/format-output.ts

@@ -1,5 +1,6 @@
 import { printJSON } from './print-json';
 import { summarizeResponse } from './summary-extractors';
+import { normalizeErrorBody } from '../utils/normalize-error-body';
 
 /**
  * 精简响应对象（非 verbose 模式使用）
@@ -42,6 +43,20 @@ export function isStandardResponse(response: any): boolean {
   return response && typeof response === 'object' && typeof response.status === 'number' && 'data' in response;
 }
 
+/**
+ * 失败响应归一化：非 2xx 且响应体是 HTML/纯文本时，换成一句可读原因。
+ * 详见 cnb/skills/cnb-skill#562（不再把第三方整页 HTML 打给用户）。
+ * 精简/verbose 两条路径共用，保证任何模式下都看不到整页 HTML。
+ */
+function normalizeFailure(response: any): any {
+  if (!isStandardResponse(response)) return response;
+
+  const info = normalizeErrorBody(response.status, response.data, response.contentType);
+  if (!info) return response;
+
+  return { ...response, data: info };
+}
+
 /**
  * 格式化 CLI 输出
  * - verbose 模式：完整 JSON（含 trace、header 等全部字段）
@@ -53,24 +68,27 @@ export function isStandardResponse(response: any): boolean {
  * @param toolKey 当前 tool 标识，格式为 "module/tool"，用于匹配摘要配置
  */
 export function formatOutput(response: any, verbose: boolean, summary: boolean, toolKey: string): string {
-  // --verbose 模式：输出完整原始信息
+  // 失败响应先收敛成可读原因，再走各自的输出策略
+  const target = normalizeFailure(response);
+
+  // --verbose 模式：输出完整原始信息（失败响应已归一化，不打印整页 HTML）
   if (verbose) {
-    return printJSON(response, verbose);
+    return printJSON(target, verbose);
   }
 
   // converter 可能返回裸 data（没有标准 {status, data} 结构），直接输出
-  if (!isStandardResponse(response)) {
+  if (!isStandardResponse(target)) {
     if (summary) {
-      const summarized = summarizeResponse(response, toolKey);
+      const summarized = summarizeResponse(target, toolKey);
       if (summarized !== null) {
         return printJSON(summarized);
       }
     }
-    return printJSON(response);
+    return printJSON(target);
   }
 
   // 精简响应
-  const compact = compactResponse(response);
+  const compact = compactResponse(target);
 
   // summary 模式：对特定 tool 应用摘要提取（仅成功响应）
   if (summary && compact.status >= 200 && compact.status < 300) {

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 { ISSUE_SHORTCUTS, PR_SHORTCUTS, SKILLS_SHORTCUTS, type ShortcutDefinition } from '../shortcuts';
+import { getModuleShortcuts, SKILLS_SHORTCUTS, type ShortcutDefinition } from '../shortcuts';
 
 interface FlatOption {
   optKey: string;
@@ -106,16 +106,6 @@ 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;
-  if (moduleName === 'skills') return SKILLS_SHORTCUTS;
-  return [];
-}
-
 /**
  * 模块下未匹配到任何子命令时的兜底处理。
  *
@@ -192,7 +182,7 @@ export function registerModuleCommands(program: Command): void {
 
     // 为快捷命令注册 Commander 子命令（别名）
     // 复用对应真实 tool 的选项定义，但跳过 path 参数（由环境变量自动注入）
-    const shortcuts = getShortcutsForModule(moduleName);
+    const shortcuts = getModuleShortcuts(moduleName);
     for (const shortcut of shortcuts) {
       // 如果快捷命令名与真实 tool 名重复，跳过（真实 tool 优先）
       if (registeredNames.has(shortcut.shortName)) continue;

package/client/shortcuts.ts

@@ -24,7 +24,7 @@ export interface ShortcutDefinition {
   custom?: boolean;
   /** 显示用的中文说明 */
   description: string;
-  /** 自动注入的 data 参数（如 close/open 的状态值、create 的 work_mode） */
+  /** 自动注入的 data 参数（如 close/open 的状态值、create-issue 的 work_mode） */
   autoData?: Record<string, any>;
   /** --data 的使用提示（展示用） */
   dataTip?: string;
@@ -233,6 +233,17 @@ function buildAutoPath(moduleName: string, repoOnly: boolean): Record<string, st
   return { repo, number };
 }
 
+/**
+ * 按模块名取快捷命令列表；非快捷命令模块（含 undefined）返回空数组。
+ * 本文件与 lib/register-modules.ts 共用，避免两处各留一份模块名映射。
+ */
+export function getModuleShortcuts(moduleName: string | undefined): ShortcutDefinition[] {
+  if (moduleName === 'issues') return ISSUE_SHORTCUTS;
+  if (moduleName === 'pulls') return PR_SHORTCUTS;
+  if (moduleName === 'skills') return SKILLS_SHORTCUTS;
+  return [];
+}
+
 /**
  * 尝试将用户输入的 module + tool 解析为快捷命令
  *
@@ -244,16 +255,8 @@ export function resolveShortcut(
 ): ResolvedShortcut | null {
   if (!moduleName || !toolName) return null;
 
-  const shortcuts = moduleName === 'issues'
-    ? ISSUE_SHORTCUTS
-    : moduleName === 'pulls'
-      ? PR_SHORTCUTS
-      : moduleName === 'skills'
-        ? SKILLS_SHORTCUTS
-        : null;
-  if (!shortcuts) return null;
-
-  const matched = shortcuts.find((s) => s.shortName === toolName);
+  const matched = getModuleShortcuts(moduleName)
+    .find((s) => s.shortName === toolName);
   if (!matched) return null;
 
   let realTool = matched.realTool;

package/client/utils/normalize-error-body.ts

@@ -0,0 +1,151 @@
+/**
+ * 失败响应归一化（见 cnb/skills/cnb-skill#562）
+ *
+ * 问题：网关/反向代理出错时返回的是一整页 HTML（502 Bad Gateway、登录页等），
+ * 而 `text/html` 命中 core.ts 的 isText 分支，原样进入 response.data，
+ * 于是 CLI 把整页 HTML 打印给用户——几百行噪音，看不到失败原因。
+ *
+ * 策略：仅当 HTTP 非 2xx 且响应体不是 JSON 时，把正文换成一句可读原因。
+ * - 结构化的 JSON 错误体（errmsg/message/...）原样保留，不丢后端信息
+ * - 成功响应完全不动
+ * - HTML 里能认出来的标题（<title>、<h1>）会带上，通常是 "502 Bad Gateway" 这类关键信息
+ */
+
+/** 归一化后放进 data 的结构 */
+export interface ApiErrorInfo {
+  /** 一句话可读原因：失败原因 + 状态码 */
+  message: string;
+  /** 从 HTML 标题里认出来的站点提示，如 "502 Bad Gateway" */
+  detail?: string;
+  /** 原始正文类型，帮助判断是谁挡在了前面 */
+  contentType?: string;
+}
+
+const MAX_DETAIL_LENGTH = 120;
+
+/** 原始响应体的最大保留长度（兜底截断，避免整页灌进上下文） */
+const MAX_RAW_LENGTH = 300;
+
+/** 常见网关/服务错误页的状态码描述，兜底用 */
+const STATUS_TEXT: Record<number, string> = {
+  400: '请求参数不合法',
+  401: '未登录或登录态已失效',
+  403: '没有操作权限',
+  404: '资源不存在',
+  405: '接口不支持该请求方法',
+  408: '请求超时',
+  413: '请求体过大',
+  429: '请求过于频繁，请稍后重试',
+  500: '服务端内部错误',
+  502: '网关错误，上游服务不可用',
+  503: '服务暂不可用',
+  504: '网关超时，上游服务未响应',
+};
+
+function isHtml(contentType: string | undefined, text: string): boolean {
+  const type = (contentType || '').toLowerCase();
+  if (type.includes('text/html') || type.includes('application/xhtml')) return true;
+  return /^\s*(<!doctype\s+html|<html[\s>])/i.test(text);
+}
+
+function decodeEntities(raw: string): string {
+  return raw
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/&amp;/gi, '&');
+}
+
+function squeeze(raw: string): string {
+  return decodeEntities(raw.replace(/<[^>]*>/g, ' ')).replace(/\s+/g, ' ').trim();
+}
+
+/** 从 HTML 中提取标题与正文首段，作为失败原因的补充 */
+export function extractHtmlHint(html: string): string | undefined {
+  const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1];
+  const h1 = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i)?.[1];
+  const center = html.match(/<center[^>]*>([\s\S]*?)<\/center>/i)?.[1];
+
+  const candidates = [title, h1, center, html.replace(/<(script|style)[\s\S]*?<\/\1>/gi, ' ')]
+    .map((item) => (item ? squeeze(item) : ''))
+    .filter(Boolean);
+
+  const hint = candidates.find((item) => item.length > 0);
+  if (!hint) return undefined;
+  return hint.length > MAX_DETAIL_LENGTH ? `${hint.slice(0, MAX_DETAIL_LENGTH)}…` : hint;
+}
+
+function looksLikeStructuredJson(text: string): boolean {
+  const trimmed = text.trim();
+  if (!/^[[{]/.test(trimmed)) return false;
+  try {
+    const parsed = JSON.parse(trimmed);
+    return !!parsed && typeof parsed === 'object';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 非 JSON 的正文统一收敛成短字符串：
+ * - HTML 只保留能认出来的标题
+ * - 其它文本（纯文本、XML、截断的 JSON）压成一行并截断
+ */
+function shortenRawBody(text: string, contentType: string | undefined): { detail?: string; body: string } {
+  if (isHtml(contentType, text) || /\[cnb-api\] formatResponse error/i.test(text)) {
+    return { detail: extractHtmlHint(text), body: '' };
+  }
+
+  const flat = squeeze(text);
+  if (!flat) return { body: '' };
+  return { body: flat.length > MAX_RAW_LENGTH ? `${flat.slice(0, MAX_RAW_LENGTH)}…` : flat };
+}
+
+function describeStatus(status: number): string {
+  return STATUS_TEXT[status] || (status >= 500 ? '服务端错误' : '请求失败');
+}
+
+/**
+ * 响应体是不是结构体（string/number/boolean 之外的都算）。
+ * 结构体说明后端已给出机器可读错误，原样保留；null 视为「没有错误体」。
+ */
+function isStructuredBody(data: unknown): boolean {
+  if (data === null) return true;
+  return typeof data === 'object';
+}
+
+/**
+ * 归一化一次失败响应。
+ *
+ * @param status HTTP 状态码（拿不到时不处理，返回 null）
+ * @param data 原始响应体
+ * @param contentType 响应 Content-Type
+ * @returns 可读的错误数据；成功响应或结构化错误体返回 null（保持原样）
+ */
+export function normalizeErrorBody(
+  status: number | undefined,
+  data: unknown,
+  contentType?: string,
+): ApiErrorInfo | null {
+  if (typeof status !== 'number' || (status >= 200 && status < 300)) return null;
+  if (isStructuredBody(data)) return null;
+
+  const text = typeof data === 'string' ? data : '';
+
+  // 文本其实是 JSON 错误体（只是被当成 text/* 处理了），交回原始数据，别覆盖
+  if (text && looksLikeStructuredJson(text)) return null;
+
+  const { detail, body } = shortenRawBody(text, contentType);
+  const reason = detail || body;
+  const label = `${status} ${describeStatus(status)}`;
+
+  const info: ApiErrorInfo = {
+    message: reason ? `${label}：${reason}` : label,
+  };
+  if (detail && body && body !== detail) info.detail = body;
+  if (contentType) info.contentType = contentType;
+
+  return info;
+}

package/package.json

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

package/quick-commands.json

@@ -1,6 +1,6 @@
 {
   "issues": [
-    { "shortName": "create",              "realTool": "create-issue",                             "description": "创建 issue",           "autoData": { "work_mode": true }, "dataTip": "--title 标题" },
+    { "shortName": "create-issue",        "realTool": "create-issue",                             "description": "创建 issue",           "autoData": { "work_mode": true }, "hideInSkill": true, "dataTip": "--title 标题" },
     { "shortName": "get",                 "realTool": "get-issue",                                "description": "获取详情" },
     { "shortName": "list-comments",       "realTool": "list-issue-comments",                      "description": "获取评论列表" },
     { "shortName": "comment",             "realTool": "post-issue-comment",                       "description": "评论",                "dataTip": "--body 内容" },

package/skills-template/SKILL.md

@@ -13,8 +13,6 @@ description: CNB 平台交互命令，支持代码仓库、Issue、PR、CI、制
 
 - **默认摘要省流**：默认精简输出，加 `--verbose` 输出完整数据。
 - **多行用单引号**：bash 参数为多行文本时用单引号，降低命令注入风险。
-- **创建 issue 默认带 `--work-mode`**：`cnb issues create` 已默认开启工作模式，不用再显式传。
-  用真实 tool 名 `cnb issues create-issue` 时则需自己加 `--work-mode`，否则创建出来的是普通 issue。
 
 ## issue/pr 访问说明