db73cf5a39
Includes the current working directory changes. Historical commits and release binaries are excluded to limit Gitea storage. Source base: d7515973fbfd6dd2001fa156c483455b8081c7cb
173 lines
8.6 KiB
Markdown
173 lines
8.6 KiB
Markdown
# Local-Cursor
|
||
|
||
本地运行的 Cursor IDE 代理工具。通过 MITM 代理劫持 Cursor 的 AI 请求，转发到自定义模型 API（OpenAI / Anthropic 兼容），支持本地助手模式与直连上游模式；同时适配 CLI 版 cursor-agent，并提供 Skill 分发、一键汉化、使用量统计等增强功能。
|
||
|
||
> 基于 [cursor-byok](https://github.com/leookun/cursor-byok.git) 衍生，感谢原作者。本项目仅供学习与个人使用，请支持正版 Cursor。
|
||
|
||
## 功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 请求劫持与转发 | MITM 代理劫持 Cursor AI 请求，转发到自定义 API |
|
||
| 多模型渠道 | 支持同时配置多个 OpenAI / Anthropic 兼容渠道 |
|
||
| 模型批量拉取 | 通过 `/v1/models` 端点拉取可用模型列表，勾选后批量添加渠道 |
|
||
| Skill 管理 | 内置 Skill（含斜杠命令）分发到任意打开过的 Cursor 项目，开关即装/卸 |
|
||
| Cursor 状态面板 | 自动检测 Cursor 安装目录与运行状态，5 秒心跳刷新，支持手动指定路径 |
|
||
| 一键汉化 | 自动检测安装目录，运行社区汉化包（自动适配 fnm/nvm 等 Node 环境） |
|
||
| Tab 补全 | 可配置上游 Tab 补全服务地址（可选 Docker 部署） |
|
||
| 模型测速 | 内置模型渠道延迟/吞吐量基准测试 |
|
||
| 会话统计 | 使用量持久化与聚合统计，支持定时刷新与累计/本次运行两种口径 |
|
||
| CA 证书管理 | 自动注入 CA 证书到系统信任链 |
|
||
| Cursor 设置注入 | 自动写入代理、HTTP/2、证书配置，并写入 `update.mode: none` 禁用自动更新 |
|
||
| CLI 代理适配 | 自动检测 CLI 版 cursor-agent，生成 wrapper + preload，重定向 TCP 连接 |
|
||
| 快速启动 | 运行时自动注册开始菜单快捷方式，Flow Launcher / PowerToys Run 可直接检索 |
|
||
| 网络代理感知 | 自动检测系统/环境变量代理并适配出站连接 |
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────┐
|
||
│ Cursor IDE │
|
||
│ (settings.json 注入 http.proxy) │
|
||
└────────────┬─────────────────────────────────────┘
|
||
│ HTTPS CONNECT
|
||
▼
|
||
┌──────────────────────┐ 白名单域名(.cursor.sh)
|
||
│ MITM Proxy Server │ ────────────────► ┌──────────────────┐
|
||
│ (127.0.0.1:28080) │ │ Backend Server │
|
||
│ │ ◄──────────────── │ (127.0.0.1:28090)│
|
||
│ 非白名单域名直连回源 │ 转发+路由 └────────┬─────────┘
|
||
└──────────────────────┘ │
|
||
┌────────┴────────┐
|
||
│ Forwarder │
|
||
│ BidiAppend/SSE │
|
||
│ Prompt 编译 │
|
||
│ Provider 调用 │
|
||
└────────┬────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ Custom API │
|
||
│ (OpenAI/Anthropic)│
|
||
└─────────────────┘
|
||
|
||
┌──────────────────────────────────────────────────┐
|
||
│ CLI 版 cursor-agent │
|
||
│ (agent.cmd wrapper + tls-bypass.cjs preload) │
|
||
└────────────┬─────────────────────────────────────┘
|
||
│ TCP 重定向 (patch net.connect/tls.connect)
|
||
▼
|
||
┌──────────────────────┐
|
||
│ CLI HTTPS Listener │
|
||
│ (127.0.0.1:39092) │ ← HTTPS+HTTP/2，跳过 MITM
|
||
│ 复用 Backend 路由 │
|
||
└──────────────────────┘
|
||
```
|
||
|
||
**IDE 模式**：Cursor 通过注入的 `http.proxy` 将请求发往本地 MITM 代理（`:28080`），白名单域名解密后转发到本地后端（`:28090`），按 `routing.mode` 选择本地处理或上游转发。
|
||
|
||
**CLI 模式**：CLI 的 connect-node 使用 HTTP/2，无法被 goproxy MITM，因此通过 Node preload 在 TCP 层把 `api2/api3.cursor.sh` 重定向到本地 HTTPS+HTTP/2 监听器（`:39092`），复用同一后端路由。
|
||
|
||
## 默认端口
|
||
|
||
| 服务 | 地址 | 说明 |
|
||
|------|------|------|
|
||
| Backend Server | `127.0.0.1:28090` | 嵌入式 HTTP 后端 |
|
||
| MITM Proxy | `127.0.0.1:28080` | Cursor 流量劫持代理 |
|
||
| CLI HTTPS | `127.0.0.1:39092` | CLI 专用 HTTPS+HTTP/2 监听器 |
|
||
| Tab 补全 | `18041`（可选） | Docker 部署的 Tab 补全服务 |
|
||
|
||
## 安装与使用
|
||
|
||
1. 从 [Releases](../../releases) 下载对应平台分发包并安装/解压。
|
||
2. 启动后点击「开启服务」，程序自动完成 CA 证书注入、Cursor settings.json 注入与 CLI wrapper 生成。
|
||
3. 在「模型配置」中添加渠道，或使用「拉取模型」从 API 端点批量导入。
|
||
4. 配置完成后正常使用 Cursor / cursor-agent 即可，流量将走你配置的模型。
|
||
|
||
程序运行时会自动注册开始菜单快捷方式，Flow Launcher、PowerToys Run 等启动器可直接检索 `Local-Cursor`。
|
||
|
||
## 配置
|
||
|
||
首次启动后自动生成 `~/.cursor-local-assistant-v2/config.yaml`，关键字段：
|
||
|
||
```yaml
|
||
providerStreamIdleTimeout: 240
|
||
backendListenAddr: "127.0.0.1:28090"
|
||
proxyListenAddr: "127.0.0.1:28080"
|
||
cliHttpsListenAddr: "127.0.0.1:39092"
|
||
modelAdapters:
|
||
- displayName: "My Model"
|
||
type: "openai" # openai | anthropic
|
||
baseURL: "https://api.example.com"
|
||
apiKey: "sk-xxx"
|
||
modelID: "gpt-4"
|
||
reasoningEffort: "medium" # low | medium | high | xhigh
|
||
openAIEndpoint: "/v1/responses" # /v1/responses | /v1/chat/completions
|
||
contextWindowTokens: 500000 # 留空使用默认 500K
|
||
maxCompletionTokens: 278000 # 留空使用默认 278K
|
||
routing:
|
||
mode: "local" # local | upstream
|
||
homeMetrics:
|
||
includeCacheWriteInHitRate: false
|
||
refreshIntervalSeconds: 60 # 统计定时刷新间隔（秒，最小 5）
|
||
persistentMode: true # 累计统计
|
||
tabServerBaseURL: ""
|
||
tabServerToken: ""
|
||
```
|
||
|
||
## 构建与开发
|
||
|
||
### 前置依赖
|
||
|
||
- Go 1.25+
|
||
- Node.js 20+（含 yarn，可用 corepack）
|
||
- [Wails v3 CLI](https://wails.io/)：`go install github.com/wailsapp/wails/v3/cmd/wails3@latest`
|
||
- protoc + protoc-gen-go + protoc-gen-connect-go（生成 `gen/`，运行 `task sync:proto` 或手动执行 `build/Taskfile.yml` 中的 generate:proto）
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 前端依赖
|
||
corepack yarn install --cwd frontend
|
||
|
||
# 生成 Wails 前端绑定（修改 service 后需要）
|
||
wails3 generate bindings -clean -d frontend/bindings
|
||
|
||
# 构建当前平台分发包
|
||
task build
|
||
|
||
# 开发模式
|
||
task dev
|
||
```
|
||
|
||
## 数据目录
|
||
|
||
所有数据存储在 `~/.cursor-local-assistant-v2/`：
|
||
|
||
```
|
||
~/.cursor-local-assistant-v2/
|
||
├── config.yaml # 用户配置
|
||
├── data/
|
||
│ ├── ca.crt # 注入 CA 证书
|
||
│ ├── codebase-index/ # 代码库索引
|
||
│ └── docs-index/ # 文档索引
|
||
├── history/
|
||
│ ├── usage.json # 使用量聚合统计
|
||
│ └── <conversation_id>/ # 会话状态
|
||
├── logs/ # 运行日志
|
||
├── cli/ # CLI wrapper 与 preload（自动生成）
|
||
└── rules/ # 用户规则
|
||
```
|
||
|
||
## 免责声明
|
||
|
||
本项目通过本地代理方式修改 Cursor 的请求路由，仅供学习研究。请购买正版 Cursor 订阅，因使用本项目产生的任何问题与原作者及本项目维护者无关。
|
||
|
||
## License
|
||
|
||
[MIT](LICENSE)
|
||
|
||
## 致谢
|
||
|
||
- [cursor-byok](https://github.com/leookun/cursor-byok.git) — 原项目
|
||
- [Wails v3](https://wails.io/) — 桌面框架
|
||
- [@polang233/cursor-language-pack](https://www.npmjs.com/package/@polang233/cursor-language-pack) — Cursor 汉化包 |