feat(proxy): introduce configurable Guard Pipeline system

[ding113]

No description provided.

[claude]

代码审查总结

✅ 架构优化亮点

这个 PR 引入了 Guard Pipeline 系统,将原本硬编码的请求检查流程重构为可配置的管道模式,这是一次优秀的架构改进。主要优点:

1. 职责分离清晰:将请求路由逻辑(proxy-handler.ts)与检查步骤定义(guard-pipeline.ts)解耦
2. 可扩展性强:新增检查步骤只需在 Steps 对象中注册,无需修改核心逻辑
3. 类型安全:通过 GuardStepKey 类型确保编译时检查,避免运行时错误
4. 按需配置:count_tokens 请求使用精简的 pipeline(跳过限流、会话追踪、敏感词检查),减少不必要的开销

📋 代码质量评估

优点:

• ✅ 代码清晰易读,注释完善(英文注释 + 中文注释混用,符合项目风格)
• ✅ 保持向后兼容,所有原有的 Guard 实现未被修改,仅作为适配器包装
• ✅ 正确处理 count_tokens 并发计数逻辑(proxy-handler.ts:24,49)
• ✅ i18n 命名空间修复正确(providers.types → settings.providers.types)

代码细节分析:

1. Guard Pipeline 实现(guard-pipeline.ts)

优点:

• GuardPipeline 接口设计简洁,run() 方法返回 Response | null 符合直觉
• Steps 对象使用 Record<GuardStepKey, GuardStep> 确保类型完整性
• 预设配置(CHAT_PIPELINE、COUNT_TOKENS_PIPELINE)可读性高

潜在改进点:

1. 错误处理:pipeline.run() 中如果某个 step.execute() 抛出异常,会导致流程中断。建议添加错误边界处理
2. 日志追踪:建议在 pipeline 执行时记录 debug 级别日志,方便排查问题

2. Proxy Handler 简化(proxy-handler.ts)

优点:

• 代码行数从 90+ 减少到 54 行(减少约 40%),大幅提升可读性
• count_tokens 逻辑处理正确(跳过并发计数和 message 追踪)

潜在问题:

• 注释编号混乱:proxy-handler.ts:23,48 的注释仍然是 "9. 增加并发计数" 和 "11. 减少并发计数",但实际上 pipeline 已经包含了步骤 1-8。建议更新注释编号或改为描述性注释

3. Count Tokens 优化(session.ts)

优点:

• isCountTokensRequest() 实现简洁,使用 getEndpoint() 方法复用现有逻辑
• 端点路径硬编码 /v1/messages/count_tokens 符合 Claude API 规范

建议:

• 考虑将端点路径提取为常量,避免魔法字符串

4. I18n 命名空间修复

3 个文件的 useTranslations 调用已正确更新,符合项目的国际化结构。

🔍 测试建议

建议在合并前验证以下场景:

1. 正常聊天请求:确保完整的 pipeline 生效(包括限流、敏感词检查)
2. Count Tokens 请求:验证跳过了限流和 session 追踪
3. Pipeline 早退出:模拟认证失败、限流触发等场景,确保 early exit 逻辑正确
4. 并发计数:验证 SessionTracker.incrementConcurrentCount 和 decrementConcurrentCount 正确配对

📊 代码统计

• 新增:147 行(guard-pipeline.ts)
• 删除:56 行(简化 proxy-handler.ts)
• 净增:+111 行(大部分是结构化的 pipeline 定义)
• 文件修改:6 个
• 影响范围:代理请求处理核心流程

🎯 总体评价

推荐合并,这是一次高质量的重构,显著提升了代码的可维护性和扩展性。建议在后续迭代中:

1. 添加单元测试覆盖 GuardPipelineBuilder 和各个 GuardStep
2. 考虑将 pipeline 配置外部化(如环境变量或数据库),支持运行时调整
3. 添加 pipeline 执行的 metrics(每个步骤的耗时、成功率等)

---

标签:已添加 enhancement 标签 ✅

[claude]

建议: 添加错误边界处理和日志追踪,提升可调试性:

async run(session: ProxySession): Promise<Response | null> {
  logger.debug('[GuardPipeline] Starting pipeline', { 
    steps: steps.map(s => s.name) 
  });
  
  for (const step of steps) {
    try {
      logger.debug(`[GuardPipeline] Executing step: ${step.name}`);
      const res = await step.execute(session);
      if (res) {
        logger.debug(`[GuardPipeline] Early exit at step: ${step.name}`);
        return res;
      }
    } catch (error) {
      logger.error(`[GuardPipeline] Step ${step.name} failed`, error);
      throw error; // 保持现有行为,或根据策略决定是否继续
    }
  }
  
  logger.debug('[GuardPipeline] Pipeline completed successfully');
  return null;
}

这样可以在日志中清晰地追踪每个步骤的执行情况。

[claude]

建议: 更新注释编号或改为描述性注释,因为 pipeline 已经包含了步骤 1-8:

// 在所有检查通过后,请求开始前增加并发计数(跳过 count_tokens)
if (session.sessionId && !session.isCountTokensRequest()) {
  await SessionTracker.incrementConcurrentCount(session.sessionId);
}

这样更符合重构后的代码结构。

[claude]

建议: 将端点路径提取为常量,避免魔法字符串:

// 在文件顶部定义
export const CLAUDE_ENDPOINTS = {
  COUNT_TOKENS: '/v1/messages/count_tokens',
  MESSAGES: '/v1/messages',
} as const;

// 在方法中使用
isCountTokensRequest(): boolean {
  const endpoint = this.getEndpoint();
  return endpoint === CLAUDE_ENDPOINTS.COUNT_TOKENS;
}

这样更易于维护和修改。