cursor-openai-byok 1.0.2

package/README.md

@@ -0,0 +1,252 @@
+# cursor-openai-byok
+
+`cursor-openai-byok` 是 Cursor 的本地 BYOK 桥接器。它把 Cursor 里选中的自定义模型转发到任意 OpenAI-compatible provider。
+
+## 支持范围
+
+- macOS 和 Windows。
+- Cursor 3.8.x。其它版本会由 `doctor` 或 `install` 拒绝，除非显式 `--force`。
+- OpenAI Responses API 风格 provider，包括文本和图片输入。
+- OpenAI Chat Completions 风格 provider，包括文本和图片输入。
+- 多 provider、多 model 映射。
+
+首版目标是 Cursor chat/agent 所需能力，不包含 audio、embeddings 等非 chat 端点。
+
+## 安装
+
+推荐使用 npm 或 pnpm 一次性运行 CLI。安装命令不会自动修改 Cursor；只有显式执行 `install` 时才会 patch Cursor、安装扩展并同步模型。
+
+npm:
+
+```bash
+npx --yes cursor-openai-byok@latest configure
+# 编辑 ~/.cursor-openai-byok/config.json，填入 provider 和 API key
+npx --yes cursor-openai-byok@latest install
+npx --yes cursor-openai-byok@latest doctor
+```
+
+pnpm:
+
+```bash
+pnpm dlx cursor-openai-byok@latest configure
+# 编辑 ~/.cursor-openai-byok/config.json，填入 provider 和 API key
+pnpm dlx cursor-openai-byok@latest install
+pnpm dlx cursor-openai-byok@latest doctor
+```
+
+`npx` 和 `pnpm dlx` 每次都会临时下载并运行当前发布包，不要求全局安装。
+
+安装会做三件事：
+
+- 校验 `~/.cursor-openai-byok/config.json` 或 `%USERPROFILE%\.cursor-openai-byok\config.json`
+- Patch Cursor 3.8.x 的 workbench bundle
+- 安装 Cursor 扩展，由扩展在 Cursor 启动时启动 daemon，并在 Cursor 退出时停止 daemon
+
+安装后重启 Cursor。
+
+## 离线 zip 安装
+
+macOS:
+
+```bash
+unzip cursor-openai-byok-macos-arm64.zip
+cd cursor-openai-byok
+node bin/cursor-openai-byok.js configure
+# 编辑 ~/.cursor-openai-byok/config.json，填入 provider 和 API key
+./scripts/install.sh
+```
+
+Windows PowerShell:
+
+```powershell
+Expand-Archive .\cursor-openai-byok-windows-x64.zip
+cd .\cursor-openai-byok
+node .\bin\cursor-openai-byok.js configure
+# 编辑 $env:USERPROFILE\.cursor-openai-byok\config.json，填入 provider 和 API key
+.\scripts\install.ps1
+```
+
+## 配置模型
+
+编辑配置文件：
+
+macOS:
+
+```bash
+open ~/.cursor-openai-byok/config.json
+```
+
+Windows:
+
+```powershell
+notepad "$env:USERPROFILE\.cursor-openai-byok\config.json"
+```
+
+示例：
+
+```json
+{
+  "$schemaVersion": 1,
+  "server": { "host": "127.0.0.1", "port": 39832 },
+  "defaults": { "model": "gpt-5.5" },
+  "providers": [
+    {
+      "id": "fastskills",
+      "name": "FastSkills",
+      "type": "openai-responses",
+      "baseUrl": "https://api-hw.fastskills.ai/v1",
+      "apiKey": "sk-xxx",
+      "models": [
+        {
+          "displayName": "gpt-5.5",
+          "apiModel": "gpt-5.5",
+          "supportsTools": true,
+          "supportsStreaming": true,
+          "supportsImages": true,
+          "contextTokenLimit": 258000,
+          "maxOutputTokens": 32000
+        },
+       {
+          "displayName": "gpt-5.4",
+          "apiModel": "gpt-5.4",
+          "supportsTools": true,
+          "supportsStreaming": true,
+          "contextTokenLimit": 258000,
+          "maxOutputTokens": 32000
+        }
+      ]
+    }
+  ]
+}
+```
+
+`displayName` 是 Cursor 下拉框里看到和选择的名字。
+
+`apiModel` 是实际发给 provider 的 `model` 字段。
+
+`supportsImages` 控制 Cursor 是否把图片输入交给这个模型，并让 daemon 转成 OpenAI 的 `input_image` / `image_url` 格式。
+
+你可以添加任意 OpenAI-compatible provider，只要它兼容 `/v1/responses` 或 `/v1/chat/completions`。
+
+如果你之前已经用过 ccursor，并且 `~/.ccursor/providers.json` 里已有 provider，可以迁移：
+
+```bash
+node bin/cursor-openai-byok.js configure --import-ccursor
+```
+
+迁移命令只写入本机配置文件，不会把 API key 打包进 zip。
+
+## 常用命令
+
+使用 npm/pnpm 时：
+
+```bash
+npx --yes cursor-openai-byok@latest doctor
+npx --yes cursor-openai-byok@latest models
+npx --yes cursor-openai-byok@latest logs
+npx --yes cursor-openai-byok@latest restart
+npx --yes cursor-openai-byok@latest uninstall
+```
+
+离线 zip 解压目录内也可以直接运行：
+
+```bash
+node bin/cursor-openai-byok.js doctor
+node bin/cursor-openai-byok.js models
+node bin/cursor-openai-byok.js logs
+node bin/cursor-openai-byok.js restart
+node bin/cursor-openai-byok.js uninstall
+```
+
+`start|stop|restart` 只是手动调试命令。正常使用时不需要单独启动 server；Cursor 启动后扩展会自动拉起，Cursor 退出时会自动关闭。
+
+## 配置页面
+
+在 Cursor 命令面板运行：
+
+```text
+Cursor OpenAI BYOK: Open Settings
+```
+
+配置页面支持：
+
+- 查看 server running/stopped 状态
+- Start / Stop / Restart server
+- 打开配置文件
+- 打开日志文件
+- 查看当前配置的模型映射
+
+## 验证
+
+运行：
+
+```bash
+node bin/cursor-openai-byok.js doctor
+```
+
+然后重启 Cursor，在模型下拉框里选择配置的 `displayName`，发送一句 `只回复 pong`。
+
+成功时日志里应该能看到：
+
+- daemon `/health` 正常
+- Cursor patch 已安装
+- Cursor 扩展已安装
+- 选择模型命中本地 BYOK
+- Cursor 收到 first token 并完成 stream
+
+## 卸载
+
+macOS:
+
+```bash
+./scripts/uninstall.sh
+```
+
+Windows:
+
+```powershell
+.\scripts\uninstall.ps1
+```
+
+卸载会停止 daemon、删除 Cursor 扩展，并从安装时的备份恢复 Cursor bundle。
+
+## npm 发布
+
+首次发布前需要 npmjs 账号。可以使用 `zhangever@gmail.com` 注册账号，完成邮箱验证并启用 2FA。浏览器已登录 Gmail 只用于接收验证邮件，不代表已经登录 npm。
+
+发布前确认本机 npm registry 指向官方源：
+
+```bash
+npm config set registry https://registry.npmjs.org/
+npm login --registry=https://registry.npmjs.org/
+```
+
+发布前验证：
+
+```bash
+npm test
+node bin/cursor-openai-byok.js doctor
+npm run package
+npm pack --dry-run --json
+```
+
+确认 tarball 只包含 `lib/` 构建产物、CLI 入口、安装脚本和文档，不包含 `src/`、`extension/`、`dist/*.zip`、`test/`、本地配置或 API key 后发布：
+
+```bash
+npm publish --registry=https://registry.npmjs.org/ --access public
+```
+
+本地 tarball 可以这样验证 CLI 入口：
+
+```bash
+npm pack
+npx --yes --package ./cursor-openai-byok-<version>.tgz cursor-openai-byok help
+pnpm dlx ./cursor-openai-byok-<version>.tgz help
+```
+
+发布后验证：
+
+```bash
+npx --yes cursor-openai-byok@latest help
+pnpm dlx cursor-openai-byok@latest help
+```

package/TROUBLESHOOTING.md

@@ -0,0 +1,84 @@
+# TROUBLESHOOTING
+
+## Cursor 提示 installation appears to be corrupt
+
+这是因为插件需要 patch Cursor app bundle。只要 `doctor` 正常且模型可用，可以忽略。
+
+如果要恢复：
+
+```bash
+node bin/cursor-openai-byok.js uninstall
+```
+
+## 模型下拉框里看不到模型
+
+检查：
+
+```bash
+node bin/cursor-openai-byok.js doctor
+node bin/cursor-openai-byok.js models
+```
+
+确认：
+
+- `config.json` 里有 `providers[].models[].displayName`
+- API key 不是 `sk-REPLACE_ME`
+- Cursor 版本是 3.8.x
+- 安装后已经重启 Cursor
+
+## 能看到模型，但发送消息没有响应
+
+先在 Cursor 命令面板打开配置页面：
+
+```text
+Cursor OpenAI BYOK: Open Settings
+```
+
+确认 server 是 `running`。也可以用 CLI 检查：
+
+```bash
+node bin/cursor-openai-byok.js restart
+node bin/cursor-openai-byok.js logs
+curl http://127.0.0.1:39832/health
+```
+
+正常使用时 server 不需要系统服务；它只应该在 Cursor 启动后由扩展拉起，并在 Cursor 退出时关闭。
+
+如果 provider 报错，日志会脱敏显示 HTTP 状态和错误片段。
+
+## provider 模型名不一致
+
+使用两个字段解决：
+
+- `displayName`: Cursor 展示名，比如 `my-gpt`
+- `apiModel`: provider 实际模型名，比如 `gpt-5.5`
+
+Cursor 选择 `displayName`，daemon 发请求时改成 `apiModel`。
+
+## 工具调用没有按预期执行
+
+首版会解析 OpenAI Responses / Chat Completions 的 tool call 流，并把 tool call 事件传回 Cursor patch。Cursor 端工具执行依赖 3.8.x 的内部 interaction bridge，如果 Cursor 版本或 bundle 结构变化，`doctor` 会要求更新 patch template。
+
+排查时先用普通文本聊天确认链路，再用只读工具调用 smoke test。
+
+## Windows 脚本执行策略阻止 install.ps1
+
+在 PowerShell 中使用：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
+```
+
+## 端口冲突
+
+默认端口是 `39832`。如需修改，编辑 `config.json`：
+
+```json
+{ "server": { "host": "127.0.0.1", "port": 39833 } }
+```
+
+修改后运行：
+
+```bash
+node bin/cursor-openai-byok.js restart
+```

package/bin/cursor-openai-byok.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+
+const { main } = require("../lib/cli");
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exitCode = 1;
+});

package/config.example.json

@@ -0,0 +1,48 @@
+{
+  "$schemaVersion": 1,
+  "server": {
+    "host": "127.0.0.1",
+    "port": 39832
+  },
+  "defaults": {
+    "model": "fastskills-gpt-5.5"
+  },
+  "providers": [
+    {
+      "id": "fastskills",
+      "name": "FastSkills",
+      "type": "openai-responses",
+      "baseUrl": "https://api-hw.fastskills.ai/v1",
+      "apiKey": "sk-REPLACE_ME",
+      "models": [
+        {
+          "displayName": "fastskills-gpt-5.5",
+          "apiModel": "gpt-5.5",
+          "supportsTools": true,
+          "supportsStreaming": true,
+          "supportsImages": true,
+          "contextTokenLimit": 258000,
+          "maxOutputTokens": 32000
+        }
+      ]
+    },
+    {
+      "id": "openai-compatible-chat",
+      "name": "OpenAI Compatible Chat Example",
+      "type": "openai-chat-completions",
+      "baseUrl": "https://example.com/v1",
+      "apiKey": "sk-REPLACE_ME",
+      "models": [
+        {
+          "displayName": "my-chat-model",
+          "apiModel": "provider-model-id",
+          "supportsTools": true,
+          "supportsStreaming": true,
+          "supportsImages": true,
+          "contextTokenLimit": 128000,
+          "maxOutputTokens": 8192
+        }
+      ]
+    }
+  ]
+}