Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

8.4 KB
Raw Blame
/**
 * providerErrors.ts (shared, 跨进程) —— 供应商上游错误的结构化分类器(SSoT)。
 *
 * 消费方:
 *   - main / maker-host/provider-diagnostics.ts(设置页「测试连接」的结果判定);
 *   - main / proxy host 的只读响应观察器(会话内上游错误 → 广播 PROVIDER_UPSTREAM_ERROR);
 *   - renderer / utils(code → i18n 文案映射,`providerError.<code>` 键族)。
 *
 * 纯函数、零依赖:分类是确定性代码逻辑(规则 9),基于 HTTP status + 上游错误体的模式匹配。
 * pattern 覆盖 Anthropic / OpenAI 原生错误形状与常见兼容网关(litellm / OpenRouter / 各家
 * Anthropic 兼容端点)的措辞。新增 pattern 需要真实错误体为证,不凭推测加。
 */

/** 结构化错误码 —— renderer 按 `providerError.<code>` 取 i18n 文案。 */
import {
  matchesDeterministicUsageExhaustionText,
  redactSensitiveText,
} from '@cindy/maker-shared/error-redaction';

export type ProviderErrorCode =
  /** 401:key 无效 / OAuth token 失效。 */
  | 'AUTH_INVALID'
  /** 403:key 有效但无权访问(区域 / 套餐 / 模型权限)。 */
  | 'AUTH_FORBIDDEN'
  /** 429 / 529:限流或过载,可重试。 */
  | 'RATE_LIMITED'
  /** 402 / 余额不足措辞:配额或余额耗尽。 */
  | 'QUOTA_EXCEEDED'
  /** 模型 id 不存在 / 无权使用该模型。 */
  | 'MODEL_NOT_FOUND'
  /** 404 且非模型问题:baseUrl 路径不对(端点不存在)。 */
  | 'ENDPOINT_NOT_FOUND'
  /** 上下文 / prompt 超长。 */
  | 'CONTEXT_TOO_LONG'
  /** 400 且命中「不认识的请求字段」类措辞:wire 兼容性问题(端点不完全兼容该协议)。 */
  | 'WIRE_INCOMPATIBLE'
  /** 5xx:上游服务端错误,可重试。 */
  | 'UPSTREAM_ERROR'
  /** 网络层不可达(DNS / 连接被拒 / 连接超时),可重试。 */
  | 'UPSTREAM_UNREACHABLE'
  /** 请求超时(探测 10s / 观察侧不产生此码)。 */
  | 'TIMEOUT'
  /** 无法归类。 */
  | 'UNKNOWN';

export interface ProviderErrorClassification {
  code: ProviderErrorCode;
  /** 是否值得原样重试(限流 / 网络抖动 / 上游 5xx)。 */
  retryable: boolean;
  /** 上游原始信息摘要(日志 / 详情展开用;UI 主文案走 i18n,不直接展示 detail)。 */
  detail?: string;
}

export interface ProviderErrorInput {
  /** HTTP 状态码;网络层失败时缺省。 */
  status?: number;
  /** 上游错误响应体文本(截断后传入即可,分类只看前几 KB)。 */
  bodyText?: string;
  /** 网络层错误码(ECONNREFUSED / ENOTFOUND / ETIMEDOUT / abort 等)。 */
  networkErrorCode?: string;
}

/** 网络层「不可达」错误码集合(Node fetch/undici 常见值)。 */
const UNREACHABLE_CODES = new Set([
  'ECONNREFUSED',
  'ENOTFOUND',
  'EAI_AGAIN',
  'ECONNRESET',
  'EHOSTUNREACH',
  'ENETUNREACH',
  'UND_ERR_CONNECT_TIMEOUT',
  'UND_ERR_SOCKET',
]);

/** 超时类错误码(AbortSignal.timeout 抛 TimeoutError / AbortError)。 */
const TIMEOUT_CODES = new Set(['ETIMEDOUT', 'ABORT_ERR', 'TimeoutError', 'AbortError']);

// ── 错误体 pattern(大小写不敏感;只在对应 status 分支内使用,避免误伤)───────────
/** 模型不存在 / 无权使用:Anthropic "model: xxx not found"、OpenAI "The model `x` does not exist"、
 *  litellm "Invalid model name"、通用 "model_not_found"。 */
const MODEL_NOT_FOUND_RE =
  /model[^\n]{0,80}(not.{0,4}(found|exist)|does not exist|invalid|unknown|unsupported)|model_not_found|invalid model/i;
/** 上下文超长:Anthropic "prompt is too long"、OpenAI "maximum context length"、通用 token limit 措辞。 */
const CONTEXT_TOO_LONG_RE =
  /prompt is too long|maximum (?:context|prompt) length|context.{0,20}(length|window).{0,40}(exceed|too)|context_length_exceeded/i;
/** wire 兼容性:端点不认识请求里的字段 / 参数(典型:litellm/Azure 对 Anthropic-only 字段报错)。 */
const WIRE_RE =
  /(unknown|unexpected|unsupported|extra|unrecognized).{0,16}(field|parameter|argument|inputs?|property|request param)|extra inputs are not permitted|invalid_request_error[^\n]{0,120}(field|param)/i;
/** 鉴权失败措辞(个别网关 401 语义但回 400/403 文本)。 */
const AUTH_RE = /invalid.{0,10}(api.?key|token)|authentication_error|unauthorized|api key not valid|令牌|鉴权失败/i;

/**
 * 单独暴露「余额 / 配额耗尽」的文案判定,供只拿得到一条错误 message、拿不到
 * status 与响应体的消费方使用(会话内 ErrorBanner:错误经 IPC 投影成字符串后,
 * classifyProviderError 的 status 分支已经用不上了)。
 *
 * 与 classifyProviderError 共用同一份 pattern,是为了不让「什么算余额耗尽」在两处
 * 各写一遍后漂移;本函数不参与分类优先级,加它不改变 classifyProviderError 的行为。
 * 新增 pattern 仍需真实错误体为证(见文件头注释)。
 */
export function matchesQuotaExhaustedText(text: string): boolean {
  return matchesDeterministicUsageExhaustionText(text);
}

/**
 * 状态码兜底:402 常以 `HTTP 402` / `status 402` / `code: 402` / `(402)` /
 * `402 Payment Required` 之类的形态透出到 message。只认**带状态码上下文**的 402 ——
 * 裸 `\b402\b` 会把正文里恰好出现的独立数字(报价、行号、金额)也判成额度耗尽,
 * 而这条判定会改写错误文案并挂上充值入口,误伤代价高。
 */
const HTTP_402_RE =
  /(?:\b(?:http|status|code|error)\b[^0-9a-z]{0,10}402\b|\(\s*402\s*\)|\b402\s+payment\s+required\b)/i;

/**
 * 只拿得到一条错误 message 时的「余额 / 配额耗尽」判定:文案 pattern + 带状态码上下文
 * 的 402。桌面错误横幅与 IM 渠道的失败说明共用这一份。
 */
export function isQuotaExhaustedErrorMessage(message: string): boolean {
  return matchesQuotaExhaustedText(message) || HTTP_402_RE.test(message);
}

/**
 * 分类一次供应商上游失败。确定性纯函数:同输入必同输出。
 * 优先级:网络层错误 > 明确 status > 错误体 pattern > UNKNOWN。
 */
export function classifyProviderError(input: ProviderErrorInput): ProviderErrorClassification {
  const { status, networkErrorCode } = input;
  const body = (input.bodyText ?? '').slice(0, 4096);
  const detail = body ? redactSensitiveText(body.slice(0, 500)) : undefined;

  if (networkErrorCode) {
    if (TIMEOUT_CODES.has(networkErrorCode)) return { code: 'TIMEOUT', retryable: true, detail: networkErrorCode };
    if (UNREACHABLE_CODES.has(networkErrorCode)) {
      return { code: 'UPSTREAM_UNREACHABLE', retryable: true, detail: networkErrorCode };
    }
    // 不认识的网络层错误码不硬归「不可达」——错误引导用户「检查网络」比承认「未知错误」更糟。
    return { code: 'UNKNOWN', retryable: false, detail: networkErrorCode };
  }

  if (status === undefined) return { code: 'UNKNOWN', retryable: false, detail };

  if (status === 401) return { code: 'AUTH_INVALID', retryable: false, detail };
  if (status === 402) return { code: 'QUOTA_EXCEEDED', retryable: false, detail };
  if (status === 403) {
    // 部分网关把 key 无效也报 403 —— 命中鉴权措辞时归 AUTH_INVALID(提示用户重填 key 更可行动)。
    if (AUTH_RE.test(body)) return { code: 'AUTH_INVALID', retryable: false, detail };
    return { code: 'AUTH_FORBIDDEN', retryable: false, detail };
  }
  if (status === 429 || status === 529) return { code: 'RATE_LIMITED', retryable: true, detail };
  if (status === 404) {
    if (MODEL_NOT_FOUND_RE.test(body)) return { code: 'MODEL_NOT_FOUND', retryable: false, detail };
    return { code: 'ENDPOINT_NOT_FOUND', retryable: false, detail };
  }
  if (status === 400 || status === 422) {
    if (MODEL_NOT_FOUND_RE.test(body)) return { code: 'MODEL_NOT_FOUND', retryable: false, detail };
    if (CONTEXT_TOO_LONG_RE.test(body)) return { code: 'CONTEXT_TOO_LONG', retryable: false, detail };
    if (matchesDeterministicUsageExhaustionText(body)) {
      return { code: 'QUOTA_EXCEEDED', retryable: false, detail };
    }
    if (AUTH_RE.test(body)) return { code: 'AUTH_INVALID', retryable: false, detail };
    if (WIRE_RE.test(body)) return { code: 'WIRE_INCOMPATIBLE', retryable: false, detail };
    return { code: 'UNKNOWN', retryable: false, detail };
  }
  if (status >= 500) return { code: 'UPSTREAM_ERROR', retryable: true, detail };

  return { code: 'UNKNOWN', retryable: false, detail };
}