Local-Cursor/README.md

# Local-Cursor

本地运行的 Cursor IDE 代理工具。通过 MITM 代理劫持 Cursor 的 AI 请求，转发到自定义模型 API（OpenAI / Anthropic 兼容），支持本地助手模式与直连上游模式；同时适配 CLI 版 cursor-agent，并提供 Skill 分发、一键汉化、使用量统计等增强功能。

> 基于 [cursor-byok](https://github.com/leookun/cursor-byok.git) 衍生，感谢原作者。本项目仅供学习与个人使用，请支持正版 Cursor。

下载：[最新公开发布](https://stupidbrain.sbs/FuDie0915/Local-Cursor/releases/latest)；[v1.1.9 审查与升级说明](docs/review-v1.1.9.md)。

## 功能

| 功能 | 说明 |
|------|------|
| 请求劫持与转发 | 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.26.10（项目已固定工具链，语言基线 1.26.0）
- 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 证书
│   ├── local-ca.pem     # 本机私有 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 汉化包