CCursor 架构揭秘：三层补丁 + 本地 BYOK Server 是如何劫持 Cursor 请求的（完整原理指南）

CCursor（Cursor++）是一个让 Cursor IDE 支持 Bring Your Own Key（自带 API Key）的开源工具：它在 Cursor 进程内启动一个本地 BYOK Server，通过三层补丁拦截发往官方 API 的 ConnectRPC 与 REST 请求，并将其重定向到本地服务，最终路由到你自己的 Anthropic、OpenAI、Gemini 或任意 OpenAI 兼容端点，从而绕过官方订阅直接使用 Cursor 的完整 Agent 能力。

一、它解决了什么问题 🤔

Cursor 的 Chat 与 Agent 功能默认只能走官方服务器计费。CCursor 的思路很直接：

1. 不破解 Cursor 的加密与签名逻辑，而是在请求发出前就地改道；
2. 在 Cursor 扩展宿主（Extension Host）进程里嵌入一个本地 HTTP 服务（Fastify + ConnectRPC），监听127.0.0.1；
3. 把模型调用、会话摘要、账号/订阅查询等请求全部交给本地服务处理，LLM 流量则转发到你配置的 Provider。

所有补丁都先创建备份文件，一条命令即可完全还原，这也是它区别于"魔改安装包"的关键设计。

二、总览：一次 Agent 请求的完整旅程 🧭

安装器 install.js 揭示了完整补丁顺序，可以把整个架构理解为"三层拦截 + 一个中枢"：

Cursor IDE │ ├─ 第 1 层：inject-patch（renderer 渲染进程） │ └─ 拦截 ConnectRPC + REST → 改道到本地 BYOK Server │ ├─ 第 2 层：always-local / agent-host patch（扩展宿主进程） │ └─ 重写 http/https.request + 扩展签名绕过 │ └─ 中枢：Cursor++ 扩展（本地 BYOK Server @ 127.0.0.1:39831） ├─ Fastify + ConnectRPC（27 个服务） ├─ LLM：Anthropic / OpenAI / Gemini SDK ├─ Agent：多轮工具调用编排器 └─ 配置：~/.ccursor/providers.json + routes.json

为什么必须三层？因为 Cursor 的 AI 流量分散在多个独立进程中：渲染进程负责界面请求，cursor-always-local与cursor-agent-host是两个独立的扩展宿主进程。Node 内置模块的 monkey patch 无法跨进程生效，所以每个入口都要单独打补丁——这正是"三层"的由来。

三、第 1 层：Renderer 补丁，拦截界面层请求 🎯

补丁入口在 patch-inject.js，它用 AST（acorn 解析）定位 Cursor 打包文件里的 ConnectRPC 客户端模块（锚点是callback-client.js/promise-client.js），注入一段 hook，职责包括：

• 包装 ConnectRPC transport（__byokWrapTransport），把命中白名单的请求改道到本地 Server；
• 包装fetch，把 REST 端点（如/auth/poll）重定向到本地；
• 订阅本地 Server 的 SSE 事件流，BYOK 开关切换后自动刷新模型选择器，无需重启 Cursor。

一个有趣的细节：注入的 hook 会在请求头里加上x-client-wid（窗口 ID），本地 Server 据此把日志按窗口分流，实现每个 Cursor 窗口独立的彩色日志面板。白名单规则并不写死在补丁里，而是运行时从~/.ccursor/routes.json加载并支持watchFile热重载——改动配置立即生效。

四、第 2 层：扩展宿主补丁，HTTP 白名单路由器 🛡️

这一层的核心是一段"进程内 HTTP/1.1 白名单路由器"，源码见 node-http11-router.js。原理是对 Node 内置http.request/https.request/http.get/https.get做函数替换：

• 目标主机是 Cursor 官方 API（api2/api3/...cursor.sh等）且路径命中routes.json白名单 → 改写为发往本地 Server；
• 其他一切请求 → 调用原始函数直通官方，不产生任何副作用；
• 补丁前先注入"等待本地 Server 就绪"逻辑，避免请求打到还没启动的端口。

patch-always-local.js 还负责一个关键动作：扩展签名绕过——把extensionHostProcess.js里的签名校验if(!x.valid)替换为if(!1)，让 Cursor++ 扩展能在扩展宿主中正常加载（这也是必须打补丁的原因）。

五、第 3 层：Agent Host 补丁，堵住新进程的逃生通道 🚪

Cursor 3.13+ 引入了独立的cursor-agent-host扩展（Agent 模式的独立传输通道），3.9+ 又把部分 HTTP 传输移到了alwaysLocalSingleton单例进程。这些新进程不受第 2 层补丁影响，CCursor 用两个专项补丁覆盖：

WebSocket 禁用逻辑（agent-websocket-guard.js）通过 AST 遍历找到nal_websocket_client传输选择器和官方域名白名单，将其强制关闭，确保 Agent 流量只能走可拦截的 HTTP 路径，而不是"false/auto"模式下悄悄切回官方 WebSocket。

六、本地 BYOK Server：真正的"总机" 📞

所有被劫持的请求最终汇入 Cursor++ 扩展启动的本地服务（默认127.0.0.1:39831），入口是 server/index.ts。它的构成：

• Fastify + ConnectRPC：services/index.ts 共注册了27 个服务，按 core（AiService / AgentService / BidiService）、completion、account、telemetry、infra、repo、mcp 分组，完整复刻了 Cursor 官方 API 的服务面；
• Agent 编排器：agentOrchestrator.ts 实现多轮工具调用循环，内置 22 个工具（Shell、Grep、Edit、WebSearch 等），配合 SQLite 做 checkpoint 持久化与自动摘要；
• LLM 路由：providerRuntime.ts 按providers.json中声明的模型解析出对应 Provider 运行时（Anthropic / OpenAI Chat / OpenAI Responses / Gemini），并统一处理 thinking 回传、prompt caching、跨 provider 切换降级等细节；
• 订阅状态 Stub：routes.json中BASE_REDIRECT里的两个 Stripe profile 端点永远生效，本地 Server 直接返回ultra会员、订阅 active 的假数据（见 server/index.ts）——这样即使关闭 BYOK 模式，没有付费账号的用户也不会被引导去付款。

拦截名单本身就是"请求劫持"的清单，定义在 defaults.js：byokMode开启时追加 Agent 主链路（agent.v1.AgentService/RunSSE、aiserver.v1.AiService/AvailableModels等）与一组账号/遥测 Stub；关闭时仅保留 Stripe 两项，其余请求全部直通官方。

七、一键安装与可逆卸载 ⚙️

整个流程只需一条命令（需 Node.js ≥ 18）：

npx @cometix/ccursor install # 安装并打补丁 npx @cometix/ccursor status # 检查安装状态 npx @cometix/ccursor uninstall # 从备份完整还原

安装器会按 install.js 的顺序执行 8 步：定位 Cursor → 释放默认配置到~/.ccursor/→ 安装扩展 → 依次注入三层补丁 → 修补 KaTeX 链接 → 提示重启。每一步都会先createBackup再写入，并同步更新 Cursor 的完整性校验和（checksum.js），保证补丁对"升级后重校验"依然生效；卸载时按备份逐一还原。

八、关键配置文件速查 📁

配置集中在~/.ccursor/目录：

providers.json的最小可用示例（详见 README.md）：

{ "providers": [ { "id": "my-anthropic", "name": "Anthropic", "type": "anthropic", "baseUrl": "https://api.anthropic.com", "auth": { "kind": "apiKey", "value": "sk-ant-..." }, "models": [ { "id": "claude-sonnet-4", "apiModel": "claude-sonnet-4-20250514", "displayName": "Claude Sonnet 4", "thinking": true, "contextTokenLimit": 200000 } ] } ] }

修改后无需重启 Cursor：扩展的文件 watcher 会触发 SSE 广播，界面模型列表即时刷新（hot-reload 是内置能力）。想深入阅读拦截与路由实现，可从仓库入手：git clone https://gitcode.com/gh_mirrors/cc/CCursor，重点看installer/src/的补丁脚本与Cursor++/src/server/的本地服务实现。

九、常见问题 FAQ ❓

• 装完不能登录官方账号？在侧边栏把 BYOK 开关切到 OFF，等待路由列表经 SSE 推送更新后即可正常登录——这正是 OFF 模式会移除大部分拦截规则的设计目的。
• 升级 Cursor 后失效？Cursor 改版可能改变 bundle 锚点（例如 3.17.8 缩短了模块路径名），运行status检查各补丁状态，按提示重装；补丁脚本对多版本都保留了兼容分支。
• LLM 返回 401/403/404？检查providers.json中的 API Key 与 baseUrl；模型不存在时在侧边栏面板添加对应模型条目。
• 会上传我的代码吗？全部流量只在你本机127.0.0.1与你自己配置的 Provider 之间流动，本地 Server 默认只监听回环地址。

十、小结 📌

CCursor 的架构可以浓缩为一句话："白名单改道 + 本地全量服务面 + 可逆补丁"。三层补丁分别覆盖渲染进程、旧版 always-local 进程和新的 Agent Host 进程，确保没有一条 AI 流量能绕过拦截；本地 BYOK Server 用 27 个服务完整复刻官方 API 语义，把"付费订阅"替换成"你的 API Key"。理解了这套机制，你也能看清它为何能稳定跨版本工作，以及卸载后为何能干干净净地还原 Cursor。