错误规则检测

Claude Code Hub 的错误规则检测系统是一个智能化的错误分类引擎，负责识别上游 AI 供应商返回的各类错误，并根据错误类型决定最优的处理策略。该系统通过可配置的规则引擎，实现精准的错误分类、智能重试决策和用户友好的错误响应。

错误分类体系

系统将错误分为五个类别，每个类别有不同的处理策略：

规则匹配机制

三种匹配类型

错误规则支持三种匹配方式，按性能从高到低排序：

匹配流程

检测器按以下顺序执行匹配，确保最优性能：

1. Contains 匹配：遍历所有 contains 规则，检查错误消息是否包含指定字符串
2. Exact 匹配：使用 HashMap O(1) 查找精确匹配的错误消息
3. Regex 匹配：按优先级顺序执行正则表达式匹配

预置错误规则

系统内置约 30 条预定义规则，覆盖常见的 AI 供应商错误场景：

错误响应覆盖

覆盖功能

每条规则可配置响应覆盖，将原始错误转换为更友好的消息：

• overrideResponse：替换整个响应体
• overrideStatusCode：覆盖 HTTP 状态码（限 400-599）

支持的响应格式

系统支持三种主流 AI API 的错误响应格式：

Claude 格式：

{
  "type": "error",
  "error": {
    "type": "prompt_limit",
    "message": "你的提示词超出了 token 限制"
  }
}

OpenAI 格式：

{
  "error": {
    "message": "你的提示词超出了 token 限制",
    "type": "invalid_request_error",
    "code": "context_length_exceeded"
  }
}

Gemini 格式：

{
  "error": {
    "code": 400,
    "message": "你的提示词超出了 token 限制",
    "status": "INVALID_ARGUMENT"
  }
}

缓存与同步

三层缓存结构

检测器使用三层缓存优化性能：

1. 规则缓存：按匹配类型分类存储规则
2. 检测结果缓存：使用 WeakMap 缓存每个 Error 对象的检测结果
3. 正则表达式缓存：预编译的正则表达式对象

缓存同步机制

规则更新时，系统通过双通道事件机制同步缓存：

• 进程内事件：通过 EventEmitter 通知当前进程
• 跨进程事件：通过 Redis Pub/Sub 通知其他实例

默认规则同步策略

系统启动时自动同步默认规则，遵循以下策略：

安全防护

ReDoS 防护

所有正则表达式规则在加载时都会进行 ReDoS（正则表达式拒绝服务）风险检测。存在风险的模式会被跳过并记录警告日志。

并发保护

检测器使用 Promise 锁和加载标志防止并发重载：

• 初始化时使用 Promise 锁确保只执行一次
• 重载时检查 isLoading 标志避免重复执行

数据库故障处理

当数据库加载失败时，检测器会保留现有缓存继续工作，并在下次请求时重试加载。

管理界面

在设置页面的「错误规则」选项卡中，你可以：

• 查看规则列表：显示所有规则的状态、模式、类别
• 添加自定义规则：创建新的错误匹配规则
• 编辑现有规则：修改规则的模式、类别或覆盖响应
• 测试规则匹配：输入错误消息测试匹配结果
• 刷新缓存：手动触发规则缓存同步

配置示例

基础规则（Contains 匹配）

{
  "pattern": "rate limit exceeded",
  "matchType": "contains",
  "category": "rate_limit",
  "description": "通用速率限制错误"
}

正则规则（带响应覆盖）

{
  "pattern": "prompt is too long.*(\\d+).*tokens.*(\\d+).*maximum",
  "matchType": "regex",
  "category": "prompt_limit",
  "description": "Token 超限错误",
  "overrideResponse": {
    "type": "error",
    "error": {
      "type": "prompt_limit",
      "message": "你的提示词超出了模型的 token 限制，请缩短输入内容"
    }
  },
  "overrideStatusCode": 400
}

精确匹配规则

{
  "pattern": "Invalid API key",
  "matchType": "exact",
  "category": "auth_error",
  "description": "API 密钥无效"
}

最佳实践

规则设计建议

1. 优先使用 Contains：对于简单的关键词匹配，Contains 性能最优
2. 谨慎使用 Regex：只在需要复杂模式匹配时使用正则表达式
3. 设置合理优先级：高优先级规则会先被检查，将常见错误的规则设为高优先级
4. 提供友好消息：使用 overrideResponse 将技术性错误转换为用户可理解的提示

监控建议

• 定期检查被跳过的 ReDoS 风险规则
• 监控规则匹配的命中率，优化低效规则
• 关注 NON_RETRYABLE_CLIENT_ERROR 类别的错误，这些通常是用户输入问题

相关文档

• 熔断器 - 了解熔断器如何与错误分类配合工作
• 智能路由 - 了解错误如何触发供应商切换
• 限流 - 了解速率限制相关的错误处理