mirror of
https://wget.la/https://github.com/leookun/cursor-byok
synced 2026-10-03 18:23:51 +08:00
docs: update README to reflect recent changes and improve clarity
This commit is contained in:
leookun
+214
@@ -0,0 +1,214 @@
|
||||
<div align="center">
|
||||
|
||||
# cursor-byok
|
||||
|
||||
cursor-byok 是一个运行在本机的 Cursor 模型网关，帮助你在 Cursor 中使用自己配置的模型服务。
|
||||
|
||||
[English README](./README.md) · [使用指南](https://docs.leokun.cn) · [下载](https://github.com/leookun/cursor-byok/releases/latest) · [提交问题](https://github.com/leookun/cursor-byok/issues)
|
||||
|
||||
[](https://github.com/leookun/cursor-byok/releases/latest)
|
||||
[](https://github.com/leookun/cursor-byok/releases)
|
||||
[](./LICENSE)
|
||||
[](https://github.com/leookun/cursor-byok/releases/latest)
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 项目简介
|
||||
|
||||
cursor-byok 是一个开源的本地模型网关。它在你的设备上运行服务，接收 Cursor 发出的 Agent 请求，将请求转发到你配置的模型服务，并尽可能保留 Cursor Agent 的工具调用、Skills、MCP 和多轮对话能力。
|
||||
|
||||
你可以连接兼容 OpenAI 或 Anthropic 协议的服务，自定义服务地址、模型 ID、API Key 和请求参数，也可以使用 Cursor 平台默认选项之外的模型通道。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> cursor-byok 免费且开源，但你连接的模型服务商可能会按用量收费。本项目是独立项目，与 Cursor 或其开发者没有关联，也未获得其认可。
|
||||
|
||||
## 主要功能
|
||||
|
||||
- **自定义模型通道**：配置自己的 API 地址、凭据和模型 ID。
|
||||
- **多种 API 协议**：支持 OpenAI Responses API、OpenAI Chat Completions API 和 Anthropic Messages API 兼容服务。
|
||||
- **模型管理**：添加、复制、编辑、排序模型配置，并批量测试连接。
|
||||
- **连接性能测试**：查看首字延迟、生成速度、总耗时和原始服务商响应。
|
||||
- **Agent 工作流**：继续使用工具调用、Skills、MCP 和多轮对话。
|
||||
- **会话指标**：查看 Token 用量、缓存命中率、对话轮次和估算价值。
|
||||
- **TAB 补全服务**：在公益服务、官方直连和自定义服务之间选择连接方式。
|
||||
- **跨平台运行**：支持 macOS、Windows 和 Linux。
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 从 [GitHub Releases](https://github.com/leookun/cursor-byok/releases/latest) 下载适合你操作系统的最新版本。
|
||||
2. 启动 cursor-byok，打开 **Cursor 配置**，按提示初始化本地 CA（证书颁发机构）。
|
||||
3. 在模型设置中添加模型，填写服务地址、API Key 和模型名称，然后保存并运行 **测试**。
|
||||
4. 确认测试通过后，保持 cursor-byok 运行。
|
||||
5. 打开或重启 Cursor，在模型列表中选择已配置的模型，开始使用 Agent。
|
||||
|
||||
完整的安装步骤、配置说明和故障处理，请参阅[中文使用指南](https://docs.leokun.cn/zh/docs)。
|
||||
|
||||
> [!TIP]
|
||||
> 首次完成配置后，建议完全退出并重新启动 Cursor，再新开一个对话。使用自定义模型时，请在模型列表中手动选择该模型，不要选择 **Auto**。
|
||||
|
||||
## 模型配置
|
||||
|
||||
每个模型配置都是独立的上游通道，可以单独设置服务商、协议、凭据和生成参数。
|
||||
|
||||
|
||||
|
||||
### 类型与协议选择
|
||||
|
||||
| 模型系列 | 模型类型 | 请求协议 |
|
||||
| --- | --- | --- |
|
||||
| Claude 系列 | **Anthropic** | Messages API |
|
||||
| GPT / OpenAI 系列 | **OpenAI** | **Responses API** |
|
||||
| 其他模型 | **OpenAI** | **Chat Completions API** |
|
||||
|
||||
GPT 系列建议使用 **Responses API**。如果使用 Chat Completions，可能无法保留提示词缓存，导致速度变慢和费用增加。
|
||||
|
||||
### 常用字段
|
||||
|
||||
- **模型类型**：选择 OpenAI 或 Anthropic，决定上游接口格式。
|
||||
- **请求协议**：OpenAI 类型需要继续选择 Responses API 或 Chat Completions API。
|
||||
- **服务器地址**：可以填写服务商基础地址，让应用按协议追加标准端点，也可以填写完整请求 URL 并原样使用。
|
||||
- **API Key**：填写上游服务要求的访问密钥。密钥保存在本机，用于发送模型请求。
|
||||
- **模型名称**：填写服务商接口接受的模型标识，也可以使用 **获取模型** 读取服务商返回的模型列表。
|
||||
- **显示名称**：Cursor 模型列表中显示的名称，不会改变发送给上游的模型标识。
|
||||
- **备注**：显示在 Cursor 的模型说明中。
|
||||
|
||||
还可以根据模型能力设置上下文窗口 Token、最大输出 Token、推理或思考强度、自定义 Headers，以及 OpenAI 或 Anthropic 的额外参数。自定义 Headers 和额外参数必须是 JSON 对象，只应填写服务商明确支持的字段。
|
||||
|
||||
保存配置后运行 **测试**，确认地址、协议、API Key、模型标识和流式响应都正常，再在 Cursor 中使用该模型。
|
||||
|
||||
## TAB 补全服务
|
||||
|
||||
Cursor 的 Tab 补全由独立的 TAB 服务处理，不经过模型通道。你可以在 **系统设置 → TAB 设置** 中选择以下模式：
|
||||
|
||||
- **使用公益服务（默认）**：使用项目作者部署的公共服务，无需额外配置。
|
||||
- **直连**：直接连接当前 Cursor 账号对应的官方 TAB 服务，适合账号拥有官方额度的情况。
|
||||
- **自定义**：自行部署 [`cursor-tab-server`](https://github.com/leookun/cursor-byok/tree/archive/v0.0.49/cursor-tab-server)，然后填写 TAB 服务地址。
|
||||
|
||||
修改 TAB 设置后，建议重启 Cursor 并新开一个对话，确保新的连接方式生效。
|
||||
|
||||
## 与官方账号并存
|
||||
|
||||
新版设计支持 cursor-byok 与 Cursor 官方服务并存：
|
||||
|
||||
- 直接在 Cursor 中登录自己的账号。如果之前使用旧版生成的 fake 账户，请先退出该账户，再登录自己的账号。
|
||||
- 账号拥有官方额度时，官方模型和本地模型可以随时切换混用。
|
||||
- **Auto 只使用官方模型**，不会自动使用你配置的本地模型。账号没有官方额度时，请手动选择自己配置的模型。
|
||||
- 插件、代码库索引等 Cursor 功能可以继续使用。
|
||||
|
||||
## 数据流转
|
||||
|
||||
```text
|
||||
Cursor 客户端
|
||||
│
|
||||
│ Agent 请求与工具结果
|
||||
▼
|
||||
cursor-byok 本地服务
|
||||
│
|
||||
│ OpenAI / Anthropic 兼容请求
|
||||
▼
|
||||
你配置的模型 API
|
||||
```
|
||||
|
||||
API Key、模型配置和应用设置保存在本机。模型请求仍会发送到你选择的上游服务商，请根据对应服务商的隐私政策和计费规则使用。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
cursor-byok/
|
||||
├── apps/
|
||||
│ ├── desktop/ # React、Vite、Tauri 桌面应用
|
||||
│ └── docs/ # Next.js 与 Fumadocs 中文/英文文档站
|
||||
├── server/ # 本地服务、Cursor 请求处理和模型转发
|
||||
├── crates/
|
||||
│ └── semble-core/ # 本地代码索引与搜索核心库
|
||||
├── cursor-proto/ # Cursor 协议定义
|
||||
├── benchmarks/ # 代码搜索和索引基准测试
|
||||
├── images/ # README 展示图片
|
||||
├── Cargo.toml # Rust 工作区配置
|
||||
└── Makefile # 常用开发、检查和构建命令
|
||||
```
|
||||
|
||||
## 本地开发
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Rust 工具链和 Cargo
|
||||
- Node.js 与 npm
|
||||
- Tauri 2 的系统构建依赖
|
||||
- Docker（仅在构建 Docker 镜像时需要）
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm --prefix apps/desktop install
|
||||
npm --prefix apps/docs install
|
||||
```
|
||||
|
||||
### 启动开发环境
|
||||
|
||||
启动桌面前端：
|
||||
|
||||
```bash
|
||||
make dev-web
|
||||
```
|
||||
|
||||
启动桌面应用：
|
||||
|
||||
```bash
|
||||
make dev-desktop
|
||||
```
|
||||
|
||||
启动文档站：
|
||||
|
||||
```bash
|
||||
make dev-docs
|
||||
```
|
||||
|
||||
文档站默认地址为 <http://localhost:3000>。
|
||||
|
||||
### 检查与构建
|
||||
|
||||
运行完整检查：
|
||||
|
||||
```bash
|
||||
make check
|
||||
```
|
||||
|
||||
分别构建各部分：
|
||||
|
||||
```bash
|
||||
make build-web # 构建桌面前端
|
||||
make build-server # 构建 Rust 本地服务
|
||||
make build-docs # 构建文档站
|
||||
make build-desktop # 构建 Tauri 桌面安装包
|
||||
make build-docker # 构建 Docker 镜像
|
||||
```
|
||||
|
||||
文档内容位于 `apps/docs/content/docs` 和 `apps/docs/content/blog`。修改文档侧边栏时同步更新 `apps/docs/content/docs/meta.json`。
|
||||
|
||||
## 路线图
|
||||
|
||||
项目将继续改进模型兼容性、Agent 工具、本地运行稳定性和自托管体验，并探索支持更多 IDE、聊天和 Agent 工作流。
|
||||
|
||||
计划与进展请参阅[发布路线图](https://github.com/leookun/cursor-byok/discussions/32)。
|
||||
|
||||
## 社区与反馈
|
||||
|
||||
- [中文使用指南](https://docs.leokun.cn/zh/docs)
|
||||
- [GitHub Issues](https://github.com/leookun/cursor-byok/issues)
|
||||
- [Telegram 社区](https://t.me/cursor_byok)
|
||||
- QQ 群：`1095916242`、`1094411438`、`1095918002`、`1094419321`
|
||||
|
||||
提交问题时，请附上操作系统、cursor-byok 版本、模型类型、请求协议、已脱敏的服务地址、错误信息和复现步骤。请勿公开 API Key 或其他凭据。
|
||||
|
||||
## 参与贡献
|
||||
|
||||
欢迎提交 Issue 和 Pull Request。提交代码前请先阅读项目中的开发说明，并运行 `make check` 确认格式、测试和前端构建检查通过。
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目采用 [MIT License](./LICENSE) 开源。
|
||||
Reference in New Issue
Block a user