Cursor BYOK · Cursor 自定义模型 · Cursor 本地代理 · Cursor 接入第三方 API · Cursor 用自己的 key · Cursor 成本统计 · Cursor agent 自托管
关键词：Cursor byok / Cursor 自定义 LLM / OpenAI 兼容接入 Cursor / Anthropic Claude 接入 Cursor / Cursor 模型路由 / Cursor prompt cache / Cursor agent 本地化 / Cursor marketplace 真实账号共存
这是 leookun/cursor-byok 的增强分支。在上游基础上做了一轮架构级重构 + 一整套成本与用量统计能力，解决原版的几个硬伤：
| 痛点 | 上游原版 | 本 fork |
|---|---|---|
| 开着 byok 能否登录真实 Cursor 账号 | 伪造 Ultra 假账号覆盖真实登录态，无法登录/退出 | 三条控制面分离，真实账号与 byok 共存，登录/退出/marketplace 全功能 |
| marketplace / customize | mock 假数据，能看不能装（安装 404） | 官方透传，插件/MCP/skills/subagents/rules/commands/hooks 全可用 |
| 获取模型列表 | 手填 modelID | 一键拉取 provider /v1/models + 多选批量添加 + 上下文窗口自动回填 |
| 模型定价匹配 | 无 | 候选匹配（去命名空间/版本/日期/推理努力后缀）+ FRESH/TOTAL/legacy 成本语义（避免缓存部分重复计费） |
| 用量与成本可视化 | 基础 token 计数 | ECharts 使用统计仪表盘：按日趋势 / 模型 / Provider 维度 + 真实消耗 token + 缓存命中率 + 成本估算 |
| 默认 token 参数 | 65536 输出 / 固定压缩预留 | 128K 输出（对齐 Opus 5 / 4.8 等旗舰上限）+ 动态压缩预留（按通道上下文窗口 8% 自适应） |
| 路由可靠性 | 单 channel，主渠道失败即断 | 多 provider 候选链 + 熔断 failover（主→备自动切换，已输出不切换，熔断兜底） |
| 更新安全 | checksum 校验 | gpt-5.6 全量安全审计 35/37 项闭合：ed25519 强制签名 + 每机器独立 CA + loopback 信任分离 + SSRF 防护 + workspace 写路径围栏 + 流资源预算 |
完整架构与接口分类见 docs/接口与架构速查.md，重构决策历程见 docs/架构重构记录.md。
核心变化：真实 Cursor 账号与 byok 自定义模型共存。
- 伪造一个 Ultra 假账号写入 Cursor 的真实本地数据库，覆盖你的真实登录态——开着 byok 就无法登录/退出自己的 Cursor 账号
- marketplace / customize 是 mock 的假数据，能看不能装（插件卡片显示但安装 404）
- 假 Ultra 身份与真实账号混用，UI 状态不一致
把 Cursor 的请求分成三条互不干扰的面：
| 控制面 | 处理方式 | 结果 |
|---|---|---|
| 身份 / marketplace / 登录 | 官方透传（真实 Cursor 账号） | 登录/退出/marketplace 浏览/安装/卸载/customize 全功能正常 |
| 订阅 / 套餐 / 用量 | 本地 mock（无限制 Pro） | 模型选择器不锁 auto，不被真实套餐限制 |
| 模型推理 / 数据面 | byok 本地（你的 provider key） | 自定义模型路由 + 成本统计 |
效果：开着 byok，既能用你自己的 key/模型，又能用真实 Cursor 账号的完整 marketplace，还能正常登录/退出账号。
- 每机器独立 CA：不再随二进制分发共享 CA 私钥，首次启动为每台机器生成独立 CA
- 更新强制签名：
update.json启用 ed25519 签名校验，release token 泄露也无法伪造可被接受的更新 - loopback 信任分离：内部信任走独立私有头
X-Cursor-BYOK-Relay-Proof，不再占用Authorization；真实 Cursor 凭证只回原始*.cursor.sh，绝不发给第三方 provider - 写路径围栏：LLM 写文件仅限工作区与终端目录，拒绝写入
~/.ssh等敏感路径
Tab 代码补全 / Git Commit / 分支名生成（StreamCpp / CppConfig / WriteGitCommitMessage 等）默认走官方 api2.cursor.sh 上游——也就是用你自己的 Cursor 账号额度，不会被默默导向任何第三方。
历史上 1.0.x 曾把这些流量硬编码到作者共享池 tab.leokun.cn，1.1.1 起改为可配置：
- 配置页 → Tab 补全服务地址：留空 = 走官方 Cursor 上游（默认，最透明）；填自建
cursor-tab-server地址可回源自己的账号 - 流量目的地在前端 UI 一目了然，不再有写死在二进制里的第三方私有域名
2.0.0 是 1.1.0 之后的收尾大版本：完成 gpt-5.6 全量静态安全审计、并入生产级路由能力、收口计费正确性与性能。完整审计证据见 docs/AUDIT_2026-07-26.md，发版变更见 release-notes.md。
按修复面归纳：SSRF 防护 + provider redirect 禁跟随 + conversation 目录逃逸防护；workspace 写路径围栏（realpath 双 EvalSymlinks）+ 子代理只读 capability；流资源预算（字节/事件/单条 64KiB/证书缓存 TTL）；配置字段级 patch 事务 + 倍率 NaN/Inf 校验；CA 加载校验 + 文件权限 0600/0700 迁移；发布链 ed25519 验签前置 + manifest 限流 + 版本对齐；生命周期显式状态机 + 阶段失败定向回滚 + 会话崩溃一致性。未闭合项：F-15（本地 MITM 客户端认证，需架构决策）、F-07/F-01/F-09/F-17（留后续策略）。
同 modelID 配多个适配器时按优先级组成主→备候选链，主候选在输出内容前失败（连接错误 / 5xx / 429 / 流超时）自动切下一个，已开始输出的请求绝不切换避免双发。熔断器接入：单个 provider 连续失败或错误率过高自动熔断，熔断中的候选排到候选链末尾兜底。
EventIndex 独立持久化不被 500 条截断影响 turn 计费；GetThoughtAnnotation 反向索引消除全量扫描；realTotalTokens 按 InputTokenSemantics 修正；model_pricing_candidates 7 段候选匹配 + 内置定价表同步 v3.18.0。
2.0.7 收口 docs/AUDIT_2026-07-29_独立全量审查.md 中「行为偏离-3」的两项外网工具强化——全部免费、零部署，无需任何配置即开箱可用。
- 多 provider BYOK：WebSearch 不再硬编码 DuckDuckGo HTML 抓取。在「Web 工具」配置卡选 Bing / Serper / Tavily，填对应 API key 即走各家官方 HTTPS JSON（自带 key = BYOK，质量与时效性远优于 HTML 抓取）。
- 缺 key 不静默失败：选了需 key 的 provider 但未填 key → 工具结果显式告警「需配置 API key」，不再静默返回空。
- DuckDuckGo JSON lite 端点（默认免费）：不配 provider 时首选 DuckDuckGo Instant Answer JSON 端点（
api.duckduckgo.com/?format=json，官方、结构化、不依赖易变 HTML class，更稳）；空结果再回退原 HTML 抓取路径，保证覆盖率不降。
- 正文 LRU 缓存：同一 URL 10 分钟内反复 WebFetch（模型多步推理反复抓同一页 / 多并发 stream 命中同一文档）走进程内缓存（4MiB 上限 + 10min TTL），免重复外网请求 + readability 解析，降延迟与被封概率。URL 规范化为键（去 fragment / 默认端口 / query 排序），不同写法命中同一缓存项。失败不缓存。
- 内网 host 白名单：WebFetch 默认 SSRF 硬拒绝所有非公网 IP（安全基线）。现可在配置卡加 host 白名单，显式放行企业内网 Wiki/Confluence 等；空表 = 最安全（拒绝所有内网），白名单是用户显式放行叠加在硬编码基线之上，不削弱默认防护。
@codebase / @docs / Repository Index 的真实向量检索依赖 Cursor 云索引，纯本地 BYOK 无法实现。改为在「按路由面覆盖」里给 file_sync（Codebase/Repository）与 network_service（@docs）面加官方透传开关：切「直连 Cursor」即用本人 Cursor 账号的真索引走上游透传；留「本地」=桩化登记（安全特性，阻断代码上传到第三方 provider，非缺陷）。默认仍全本地。
2.0.7 一并闭合独立审计的 P0/P1 项：AwaitShell 正则泄漏 + 无界 buffer（P0-1/2）、half-open permit 漏放致渠道卡死（P0-3）、state.vscdb 并发写竞争（P0-4）、F-20 截断判定过激（P1-2）、RequestKnobs 共享 map 污染（P1-3）、熔断错误率不滑动（P1-4）、EventIndex prune 淘汰 turn 计费（P1-5）、Config 路由模式不持久化（P1-7）、乐观更新回滚与磁盘脱节（P1-8）、prefix cache 跨天失效（行为偏离-1）、成本平方权重（P2-1）、EChart 无 ResizeObserver（P2-7）、后台轮询不暂停（P2-8）、死代码清理（P3-1）。逐条 ✅ 标注 + 修复历史见审计文档第九节。
一个桌面应用（Wails v3 + Go 后端 + Vue 3 前端），在本地起一个与 Cursor 兼容的 agent 服务，把 Cursor 客户端的 chat / agent 请求转发到你自己配置的模型 provider。它不是 Cursor 的替代品，而是一个本地中间人代理 + 本地 agent 执行内核。
适用场景：
- 想用第三方 OpenAI 兼容 / Anthropic 兼容 API 驱动 Cursor 的 chat 与 agent
- 想用真实 Cursor 账号的 marketplace / customize，同时用自己的 key 跑模型
- 想自托管整套 agent 服务，不被单一平台锁定
- 想精确统计每个模型、每次请求的 token 消耗与成本
- 本地服务：启动 HTTP/Connect-RPC 服务，对外暴露与 Cursor 兼容的接口
- 流量导入：向 Cursor 注入代理设置 + 安装本地 CA 证书，把 Cursor 流量导向本地
- 请求分流：
- 模型/数据面请求 → 本地 backend 做 prompt 编译、历史投影、tool call 处理后，调用你配置的 provider
- 身份/marketplace/登录请求 → 原样透传到 Cursor 官方后端（携带你的真实登录态）
- 订阅/套餐请求 → 本地 mock 成无限制，避免真实套餐锁模型
- agent 内核：本地重建类 Cursor 的 agent 执行循环（tool 调用、shell、文件编辑、codebase 索引、上下文压缩、usage 统计、会话回放）
| 类型 | 协议 | 示例 |
|---|---|---|
| OpenAI 兼容 | /v1/responses、/v1/chat/completions、自定义路径 |
OpenAI 官方、各类第三方 OpenAI 兼容网关 |
| Anthropic 兼容 | Anthropic Messages API | Claude 官方、Bedrock/Vertex 透出等 |
内置 120+ 模型定价表（Anthropic Claude / OpenAI GPT / Google Gemini / xAI Grok / DeepSeek / Kimi / Doubao / Qwen / GLM / MiniMax / MiMo / Mistral / Cohere 等），覆盖 2026 年主流旗舰（Claude Opus 5 / 4.8、GPT-5.6、Gemini 3.x、Grok 4.5 等）。
每条模型配置含：baseURL、apiKey、modelID、provider 类型、端点、reasoning effort、thinking budget、自定义请求头、额外请求参数、context window、max tokens、成本倍率。
- Cursor（当前版本，代码内硬编码 Cursor 的
state.vscdb路径、扩展 proto、settings keys）
- 一键获取模型列表：根据 baseURL/apiKey 调 provider
/v1/models，自动探测候选端点（OpenAI/v1/models↔ Anthropic 兼容后缀剥离） - 多选批量添加：勾选多个模型一次性追加，继承当前表单的接口地址/密钥/端点/自定义参数
- 上下文窗口自动回填：内置 models.dev 缓存表 + 候选匹配，拉到的模型自动反查上下文窗口（1M / 400K / 256K / 200K 等），免去手填
- 模型适配器管理：GUI 增删改查、单测 / 批量并发测试（并发 10）
- 额外参数 / 自定义请求头：高级字段按需开启，覆盖请求体或请求头。配法和禁用字段见 docs/额外参数与自定义请求头配置.md
- 使用统计仪表盘：ECharts 按日趋势图（四类 token 堆叠面积 + 成本折线双轴）、模型统计表、Provider 统计表、请求日志（最近 500 条）
- 真实消耗 token 口径：fresh_input + output + cache_creation + cache_read（cc-switch 口径）
- 候选匹配定价：去命名空间（
openai./anthropic.）、-vN版本、日期后缀、推理努力后缀（-low/-medium/-high）、前缀回退，让openai.gpt-5/claude-opus-4-6-20251114都能命中价目 - FRESH/TOTAL/legacy 成本语义：OpenAI 系列的 input 已扣除缓存部分（避免重复计费），Anthropic 系列按 legacy 口径，三家计费差异自动校准
- per-adapter 成本倍率：每个模型可单独设倍率（1=官方原价），全局默认倍率可覆盖
- 缓存命中率：默认口径 / 计入缓存创建两种可切换
- 真实账号共存：1.0.0 起，开着 byok 也能登录/退出真实 Cursor 账号，marketplace/customize 全功能可用
- 两种运行模式：本地服务模式（默认，请求经本地 backend 转发到你配置的模型）/ 直连 Cursor 模式（放行到官方，默认关闭）
- prompt cache：Anthropic cache breakpoints、OpenAI prompt_cache_key
- thinking / reasoning：深度思考、reasoning effort 控制、按 provider 差异化注入 disable 字段
- 动态压缩预留：按通道上下文窗口自适应（8%，min 16K / max 80K），不再固定 10000
- 128K 默认最大输出：对齐 Claude Opus 5 / 4.8 / Sonnet 5 等旗舰输出上限
- WebSearch 多 provider：Bing / Serper / Tavily BYOK + DuckDuckGo JSON lite 端点免 key 降级，缺 key 显式告警
- WebFetch 正文缓存 + host 白名单：同 URL 10min LRU 缓存；内网 host 白名单放行企业 Wiki/Confluence（默认 SSRF 硬拒绝基线不削）
- 会话持久化：
~/.cursor-local-assistant-v2/下 config / history / logs
- 自动更新：从本仓库 release 拉取带 ed25519 签名的
update.jsonmanifest - 多语言 GUI：简体中文、English、日本語
- 跨平台：Windows / macOS / Linux
- 从 Releases 下载对应平台压缩包
- 解压到任意目录，启动应用
- 在「模型配置」中添加你的模型适配器（填 baseURL / apiKey / modelID，或点「获取模型列表」一键拉取）
- 启动本地服务（首次需 UAC 提权安装 CA 证书）
- 登录你的 Cursor 账号（1.0.0 新能力：开着 byok 也能正常登录）
- 再启动 Cursor——顺序很重要：先开插件、装好 CA、配好模型、登录账号，最后才开 Cursor
顺序错误是最常见的"不工作"原因。
1. 启动 cursor-switch 插件
2. 首次启动会申请 UAC 安装本地 CA 证书 → 同意
3. 在「模型配置」添加你的 provider（点「获取模型列表」可一键拉取并多选批量添加）→ 测试连通
4. 启动本地服务（开关打到"启动"）
5. 登录你的 Cursor 账号（插件内或 Cursor 内均可，1.0.0 起不再冲突）
6. 启动 Cursor → 打开对话，选择你的 byok 模型 → 打开 marketplace 验证完整界面
如果对话界面锁在 auto 无法选择 byok 模型，检查是否装的是 1.0.0+。旧版会因假账号与真实账号冲突而锁 auto，1.0.0 已通过"套餐/用量统一 mock 成无限制 Pro"修复。
Cursor 自身的版本更新与插件不能同时进行：插件开着时，Cursor 的更新检查会失败或被代理拦截。正确流程：
- 关闭 cursor-switch 插件（停止本地服务）
- 打开 Cursor，检查并安装更新
- 更新完成后重新启动插件，再继续使用
1.0.0 首次启动会自动清理历史假账号注入：检测到旧版写入的假 Ultra 指纹时，安全删除仍等于假值的字段（绝不动真实值），清理后需重新登录一次 Cursor 账号。
依赖：Go ≥1.25、Node.js、yarn、wails3 CLI（v3.0.0-alpha.74）、protoc 工具链。
# 生成 proto 代码（首次或 proto 变更后）
wails3 task common:generate:proto
# 构建 Windows amd64 发行包（产物：bin/windows-64.zip）
wails3 task build:windows:amd64纯 Go 后端快速构建（开发自测用）：
GOOS=windows CGO_ENABLED=0 GOARCH=amd64 go build -tags production -trimpath \
-ldflags="-w -s -H windowsgui -X cursor/internal/buildinfo.Version=2.0.1" \
-o "bin/Cursor助手.exe" .多平台发行通过 GitHub Actions 自动构建（.github/workflows/release.yml）。发版前置与签名流程见 docs/RELEASE_SIGNING.md。
简述：
- 同步版本号三处合一：
build/config.yml(info.version)、build/windows/info.json(file_version/ProductVersion)、build/windows/wails.exe.manifest(version) - 更新
release-notes.md写本次变更 - 提交并推送到
main - 打 tag 触发：
git tag v1.0.0 && git push origin v1.0.0 - 发版后本地补签
update.json（签名私钥在维护者本地，CI 不持有）：
gh release download v1.0.0 --pattern update.json --dir /tmp/
go run ./scripts/release sign --manifest /tmp/update.json
gh release upload v1.0.0 /tmp/update.json --clobber版本号含 beta / rc 等字样时自动标记为 prerelease。
internal/
relayauth/ 进程级 relay proof（MITM→backend 信任头）
mitm/ 本地 MITM 代理（凭证捕获、proof 注入）
backend/
server/ HTTP 路由、中间件、凭证捕获、policy
server/upstream/ 出站凭证策略（CredentialOriginalCursor 等）
server/config/ loopback 强制、路由模式、定价表 + 候选匹配
forwarder/ agent 执行内核（actor/compaction/tool/usage_store）
agent/model/ 模型适配器（openai.go / anthropic.go / router.go）
host.go 路由分类总表（透传 vs 本地 mock）
cursor/ Cursor 客户端注入（证书、settings、state.vscdb 修复）
netproxy/ 系统级网络代理（含 no-redirect 客户端）
updater/ 自动更新 + ed25519 签名校验
certs/ 每机器独立 CA 生成
client/ fetch-models + 上下文窗口回填
bridge/ 使用统计仪表盘后端 + 成本计算（FRESH/TOTAL/legacy）
buildinfo/ 版本与发布目标
frontend/ Vue 3 + vue-router + Tailwind + i18n + ECharts
proto/ Cursor 兼容 proto 定义
cursor-tab-server/ Cursor Tab 补全反向代理（独立程序）
docs/ 文档（架构速查 / 重构记录 / 发版签名 / 开发指南）
- 接口与架构速查 — 全部路由分类、凭证链路、调试方法
- 架构重构记录 — 1.0.0 三条控制面分离的决策与踩坑历程
- 发版与签名 — 发版前置、ed25519 签名、旧 CA 处理
- 开发指南 — 开发循环、proto/bindings 再生、测试范式
- 新模型上线 SOP — 新模型发布时如何加定价 + 上下文窗口
- 独立全量审计 2026-07-29 — P0/P1/P2/P3 逐条 ✅ 标注 + 修复历史
PR 前请跑 go vet ./... + go test ./...，并确保版本号三处合一（CI check.yml 会校验）。
新模型上市时，往 internal/backend/server/config/pricing.go 的 pricingModelSeed 加定价记录、往 internal/client/model_context_window.go 的 contextWindowByModelID 加上下文窗口即可，两张表都是纯数据。
MIT。本项目基于 leookun/cursor-byok 衍生，感谢原作者。