@cnbcool/cnb-api-generate 2.19.0 → 2.19.1

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/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.19.1",
   "main": "./built/index.js",
   "module": "./src/index.ts",
   "types": "./src/index.ts",