统一AI代理网关：实现多后端智能路由与无缝集成
项目背景：解决多AI工具的后端管理难题
在现代开发流程中，开发者常需同时使用Cursor IDE、Claude Code CLI等智能编程工具。然而，这些工具通常绑定特定服务商（如Antigravity、Anthropic、OpenAI），导致跨平台调用受限。更棘手的是，各工具采用不同通信协议（gRPC、SSE流式HTTP），且账号配额独立管理，一旦某个服务额度耗尽，工作流即刻中断。
为此，本项目构建了一个统一代理网关，作为中介层，将上游客户端（Cursor、Claude CLI）与下游多种后端服务（官方/第三方模型）连接起来。它不仅支持协议转换，还实现了智能路由、负载均衡和自动故障转移，使用户可自由切换最优模型，无需手动干预。
核心架构设计
1. 协议兼容层：打通通信壁垒
针对Cursor使用的私有ConnectRPC/gRPC协议，代理实现完整协议栈，包括流式工具调用循环，确保客户端感知不到中间层存在。对于Claude CLI，则提供标准Anthropic Messages API的SSE端点，保持接口一致性。
2. 智能路由引擎
请求到达后，系统根据以下维度进行决策：
- 模型标识符：优先匹配精确模型名（如
claude-3-5-sonnet-latest），否则按前缀匹配。 - 账号状态：检查配额、速率限制及健康状态，剔除不可用账号。
- 降级策略：当首选后端不可用时，自动切换至备用服务（如从Claude API降级至Google Cloud Code的Gemini模型）。
- 优先级配置：可通过
priority字段自定义账号调度顺序。
3. 账号池与配额管理
每个后端类型维护一个账号池，包含多个可用凭证。代理实时监控各账号的剩余配额与冷却时间，动态调整请求分配。当某账号触发限流或配额耗尽时，自动将其从队列中移出，并切换到下一个可用账号，实现无缝容错。
4. 上下文与会话管理
代理负责维护对话历史，处理长上下文压缩，并确保工具调用的协议映射正确。即使在不同后端间切换，也能保证会话连贯性与功能完整性。
与同类方案对比
| 特性 | CLIProxyAPI | Agent Vibes |
|---|---|---|
| 协议兼容性 | 通用兼容（如OpenAI/Claude API） | 原生级兼容（实现Cursor gRPC） |
| 目标客户端 | 命令行工具、可配置SDK | Cursor、Claude CLI 等原生客户端 |
| 集成深度 | 轻量级端点转发 | 深度嵌入运行时，支持完整功能链 |
| 适用场景 | 简单代理需求 | 高可靠性、多后端无缝切换 |
安装与配置实操
环境准备
- 操作系统：macOS (Apple Silicon / Intel)、Linux、Windows WSL2 均支持。
- Cursor版本：必须为
v3.1.14，不兼容新版本。 - Node.js ≥ 24（仅源码构建时需要）。
- 关闭全局代理或VPN，避免域名劫持。
扩展安装（推荐方式）
- 从 GitHub Releases 下载对应平台的
.vsix文件： - macOS Apple Silicon:agent-vibes-darwin-arm64-0.1.16.vsix- Windows x64:agent-vibes-win32-x64-0.1.16.vsix - 使用 Cursor 命令行安装：
cursor --install-extension ./agent-vibes-darwin-arm64-0.1.16.vsix --force - 重启 Cursor，观察侧边栏是否出现代理图标。
关键配置步骤
- 生成本地证书：
打开命令面板，执行Agent Vibes: Generate SSL Certificates。
工具会调用mkcert为localhost和agent.cursor.com创建受信任证书。 - 启用端口转发：
执行Agent Vibes: Enable Port Forwarding。
自动修改/etc/hosts并启动本地8000端口监听，将流量重定向至代理服务。 - 添加后端账号：
通过仪表盘进入Accounts标签页，配置以下三类服务：- Antigravity/Google Cloud Code：使用
agent-vibes sync --ide或--tools命令同步令牌，避免手动复制失效密钥。 - Claude API：提供 API Key 与基础地址，支持官方及第三方兼容服务。
- OpenAI 兼容：支持 Azure OpenAI、自建代理等，需填写 Base URL 与 Key。
- Antigravity/Google Cloud Code：使用
- 运行诊断测试：
在Diagnostics页面点击 "Run All Checks" ，验证：- SSL 证书是否受信任
- DNS 解析是否指向 127.0.0.1
- 端口转发是否生效
- 后端账号是否在线
首次使用验证
完成配置后，彻底重启 Cursor。在聊天框输入问题或触发代码编辑，观察：
- 能否正常获取响应？
- 仪表盘
Analytics是否记录请求数据？ - 日志中是否显示具体路由路径（如 "Sent to Claude API via third-party-proxy"）？
高级功能详解
路由策略优化
支持基于模型名称的灵活路由规则：
prefix：如配置team-a，则只接受以该前缀开头的请求。forceModelPrefix：强制所有请求使用指定前缀，增强隔离性。quotaFallbackModel：当所有 Google Cloud Code 账号配额耗尽时，自动转接至指定 Gemini 模型，保障服务连续性。
账号配置文件示例
OpenAI 兼容后端配置（openai-compat-accounts.json）
{
"accounts": [
{
"label": "azure-gpt-4o",
"baseUrl": "https://your-resource.openai.azure.com/openai/deployments/gpt-4o",
"apiKey": "your-key",
"apiVersion": "2024-02-01",
"proxyUrl": "http://127.0.0.1:7890",
"maxContextTokens": 128000
}
]
}proxyUrl：为单个账号设置专属代理出口。maxContextTokens：决定最大上下文长度，防止跨账号能力溢出。
Claude API 配置（claude-api-accounts.json）
{
"forceModelPrefix": false,
"accounts": [
{
"label": "official-claude",
"apiKey": "sk-ant-xxx",
"baseUrl": "https://api.anthropic.com",
"headers": { "anthropic-beta": "max-tokens-3-5-sonnet-2025-10-22" }
},
{
"label": "proxy-service",
"apiKey": "sk-third-yyy",
"baseUrl": "https://claude.proxy.example.com",
"stripThinking": true,
"excludedModels": ["claude-3-haiku*"],
"priority": 5
}
]
}stripThinking：移除不支持的thinking字段。excludedModels：通配符排除不支持的模型。models数组：可显式声明支持模型列表，跳过自动探测。
运维与排错指南
常见问题排查
| 现象 | 原因 | 解决方案 |
|---|---|---|
| AI无响应 | 网络转发未生效 | 运行诊断检查 DNS Resolution 与 Traffic Forwarding |
| 401/403 错误 | API Key 错误或已失效 | 更新凭证或重新同步账号 |
| 429 Too Many Requests | 配额耗尽或处于冷却期 | 等待恢复或添加新账号 |
| SSL 证书不受信任 | 应用未重启 | 完全关闭所有浏览器与 Cursor 后重开 |
| 诊断失败 | 系统代理干扰 | 临时关闭全局代理或加入直连列表 |
日志定位
若图形界面无法提供足够信息，可查看以下路径的日志文件：
- 主桥接日志：
- macOS:/private/var/folders/.../T/agent-vibes-bridge.log
- Linux:/tmp/agent-vibes-bridge.log
- Windows:%TEMP%\agent-vibes-bridge.log - 详细协议日志：
存在于<临时目录>/agent-vibes-logs/，按日期分文件，含完整请求/响应内容。
源码结构与开发入门
项目结构概览
agent-vibes/
├── apps/
│ └── protocol-bridge/
│ ├── src/
│ │ ├── protocol/ # 协议适配层
│ │ │ ├── cursor/ # Cursor gRPC 实现
│ │ │ └── anthropic/ # Claude SSE 实现
│ │ ├── llm/ # 后端提供商
│ │ │ ├── google/ # Antigravity & Cloud Code
│ │ │ ├── anthropic/ # Claude API 客户端
│ │ │ └── openai/ # OpenAI 兼容客户端
│ │ └── context/ # 会话管理
└── scripts/ # 平台脚本（hosts、转发、同步）
本地构建与运行
# 克隆并安装依赖
git clone https://github.com/funny-vibes/agent-vibes.git
cd agent-vibes
npm install
npm run build
# 链接到全局命令
npm link
# 生成证书并启动
agent-vibes cert
agent-vibes forward hosts
agent-vibes forward on
agent-vibes # 启动代理服务
扩展开发调试
Cursor 扩展位于 apps/vscode-extension/ 目录。开发时：
- 运行
npm run watch启动编译监视。 - 在 Cursor 中按下
F5，打开扩展开发宿主窗口，加载本地版本。
通过本工具，开发者可摆脱单一服务商绑定，构建一个高度灵活、稳定可靠的多后端智能编程环境，真正实现"任我所用"的高效开发体验。
