# cursor2api

个人项目：把 Cursor 官方 SDK（`@cursor/sdk`）接到本地 Gateway / stdio MCP，给 Codex 主代理当
**Worker**，并提供 OpenAI Responses **文本**兼容层。

推荐路径：

**Sol（Codex 主代理）→ cursor2api MCP Worker → Cursor SDK → Grok 4.6**

这不是完整的 Codex 模型 Provider，也不是原生跨 Provider subagent。Codex 原生子代理仍走 Codex
自己的模型配置；Grok 实现必须通过 Worker 工具。

只用官方 `CURSOR_API_KEY`，从
[Cursor Dashboard → Integrations](https://cursor.com/dashboard/integrations) 创建。不要使用 Cursor
桌面 cookie 或非官方 API。

## 当前能力

可用：

- Worker：`cursor_execute` 执行一个有边界的任务；`cursor_batch_execute` 并行 1–3 个互不重叠的范围；
  异步 `cursor_start` / `cursor_status` / `cursor_result` / `cursor_followup` / `cursor_cancel` 仍可用。
- 设置了 `CURSOR_API_KEY` 时使用真实 `SdkCursorAdapter`。WebUI 状态显示 `backend=cursor` 或
  `backend=fake`。
- `/v1/responses` 文本 stream 与 non-stream。
- 隔离 Codex 会话可以把 `model_provider = "cursor_relay"` 指到本机 Gateway（仅文本路径）。
- WebUI：Overview、Setup、Models、Runs、Playground、Logs、Codex Setup、Settings。

不要指望：

- Function tool Capture/Resume（tool bridge 为 NO-GO）。`/v1/responses` 只保证文本，不保证完整工具循环。
- 原生 Codex 跨 Provider subagent。当前 Codex 子线程会继承父会话的 `model_provider = "openai"`，并拒绝
  `grok-4.6`。日常 Grok 工作不要 spawn 原生 subagent。

未设置 `CURSOR_API_KEY` 时，生产路径不会静默落到 Fake Grok；`/v1/responses` 返回
`missing_cursor_api_key`。Fake 适配器仅在显式 `CURSOR_BACKEND=fake`（或测试注入）时启用。

## 快速开始（Windows）

需要 Node.js `>=22.13`。

如果希望由 Codex 自动完成安装与 MCP 注册，让它在解压后的仓库根目录阅读并执行
[`INSTALL.md`](INSTALL.md)。

```powershell
cd cursor2api
npm.cmd install
copy .env.example .env
# 在 .env 填写 CURSOR_API_KEY 与 CURSOR_RELAY_API_KEY
npm.cmd run typecheck
npm.cmd run test
npm.cmd run lint
```

`scripts\dev.ps1` 一次启动 Gateway 与 WebUI（先 `tsc -b`）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\dev.ps1
```

- WebUI：http://127.0.0.1:5173
- Gateway：http://127.0.0.1:8787 ，探活 http://127.0.0.1:8787/healthz

`scripts\stop.ps1` 同时关闭二者：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\stop.ps1
```

stdio MCP 由 Codex 拉起，不受这两个脚本管理。

## 环境变量

复制 `.env.example` 为 `.env`。Gateway 与 MCP stdio 都从本仓库根目录加载 `.env`，不依赖调用方 cwd。
不要把真实密钥写入仓库或本文档。

| 变量                   | 作用                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `CURSOR_API_KEY`       | 官方 Cursor API Key。Worker、模型目录、真实 `/v1/responses` 都需要它。                           |
| `CURSOR_RELAY_API_KEY` | Codex / OpenAI 兼容客户端访问本机 `/v1` 的 Bearer。未设置时本地默认为 `sk-cursor2api-dev`。      |
| `CURSOR_BACKEND`       | 仅 `fake` 启用 Fake 适配器。有 `CURSOR_API_KEY` 时走真实 SDK。                                   |
| `RESPONSES_BACKEND`    | 仅用于 `npm.cmd run responses:server`：`fake` 或 `cursor`。有 Key 时默认 `cursor`。              |
| `RESPONSES_COMPAT`     | `strict`（默认）或 `codex-text`。`smoke:codex` 会设成 `codex-text`，避免 Codex 带 tools 时 501。 |
| `CURSOR_LIVE_TEST`     | 设为 `1` 且存在 `CURSOR_API_KEY` 时才跑 live Cursor 测试。                                       |

Gateway 默认监听 `127.0.0.1:8787`，数据目录 `.data`（`scripts\dev.ps1` 会设置 `DATA_DIR`）。

## WebUI

打开 http://127.0.0.1:5173 。开发服务器把 `/api`、`/v1`、`/healthz` 代理到 Gateway。

| 页面        | 内容                                                                                          |
| ----------- | --------------------------------------------------------------------------------------------- |
| Overview    | 网关状态（`backend=`、Cursor auth、Grok 4.6）。按天汇总 token，并显示 input / output / 总量。 |
| Models      | 展示真实 Cursor 模型目录，可选择模型与参数并保存为 Worker 默认。                              |
| Setup       | 本地接入检查清单。                                                                            |
| Runs / Logs | 查看与取消 Worker 任务、按 `job_id` 拉事件。                                                  |
| Playground  | 试调 `/v1/responses` 文本接口。工具编辑器关闭（tool bridge NO-GO）。                          |
| Codex Setup | 生成带本机绝对路径的 Provider 与 MCP 片段。                                                   |
| Settings    | 默认监听与 Worker 行为说明。                                                                  |

## Codex MCP 接入

先构建，再用绝对路径注册 stdio MCP（Codex 可能从任意 cwd 启动它）：

```powershell
npm.cmd run typecheck
$node = (Get-Command node).Source
$script = (Resolve-Path .\apps\gateway\dist\mcp-stdio.js).Path
codex mcp add cursor2api -- $node $script
codex mcp get cursor2api
```

注册后重启 Codex。MCP 进程从本仓库 `.env` 读取 `CURSOR_API_KEY`，密钥不会写入 Codex 配置。

若用 `codex mcp add` 注册，在当前 Codex `config.toml` 的 `[mcp_servers.cursor2api]` 下补上
`tool_timeout_sec = 1200`（xhigh Worker 可能超过 Codex MCP 默认超时），或从 WebUI **Codex Setup**
复制完整片段。

把 `ROOT` 换成仓库根目录的绝对路径，`command` 换成 `node.exe` 的绝对路径：

```toml
[mcp_servers.cursor2api]
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["ROOT\\apps\\gateway\\dist\\mcp-stdio.js"]
cwd = "ROOT"
tool_timeout_sec = 1200
enabled = true
```

用户级 Provider 片段见 `integrations/codex/config.example.toml`。不要把
`model_provider = "cursor_relay"` 设成 Codex 全局默认，否则 Sol 主会话也会切到 Cursor relay。

协调策略见仓库根目录 `AGENTS.md`，副本 `integrations/codex/AGENTS.example.md`。官方文档：
[Codex MCP](https://developers.openai.com/codex/mcp)。

卸载：`codex mcp remove cursor2api`。

## MCP 生命周期

`cursor2api` 是本地 **stdio MCP server**。Codex 在初始化已启用的 MCP 时拉起该命令，不是每次
`cursor_start` 都新开进程。进程通常随 Codex 宿主会话存活，在宿主退出 / 重启、stdio 断开或进程失败时结束。

HTTP Gateway 与 WebUI 是另一组进程：关掉 Gateway 不会关掉 stdio MCP。

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\mcp.ps1 status
# 前台调试，Ctrl+C 结束；不能接到已运行的 Codex
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\mcp.ps1 start
# 停掉本仓库对应进程；Codex 在 enabled 时可能再次拉起
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\mcp.ps1 stop
```

持久关闭：把当前 Codex `config.toml` 里 `[mcp_servers.cursor2api]` 的 `enabled` 设为 `false`，然后重启
Codex。不要在 Worker 任务运行中 stop MCP。

## Worker 工具与任务分配

### 先判断是否值得委派

Grok Worker 每次都需要定位文件、读取相关上下文、执行任务并返回摘要。对于很小的改动，这部分成本可能比实际修改更高，
反而降低速度并增加 token 消耗。因此，不要因为任务“边界明确”就自动委派。

通常由 Sol 直接完成：

- 只涉及 1–3 个紧密相关文件的简单修改；
- 文档、配置、文案、样式、清理和明显的小型 bug；
- 读取少量代码、执行几条命令就能完成和验证的工作；
- Worker 结果后的快速修正或局部审查。

适合交给 Grok Worker：

- 有实质工作量的多文件功能实现；
- 需要较多代码阅读、调试和测试的独立任务；
- 大范围但规则清楚的重复修改；
- 虽然文件少，但算法或实现本身复杂的任务。

文件数量只是判断信号，不是硬性门槛。核心原则是：**只有 Grok 节省的执行工作明显大于它重新加载上下文的成本时才委派。**

| 工具                   | 用途                                                                            |
| ---------------------- | ------------------------------------------------------------------------------- |
| `cursor_models`        | 列出 Cursor 模型与当前默认。                                                    |
| `cursor_execute`       | 提交一个有边界的任务，等待并返回精简结果。默认复用同一 workspace 的 Agent。     |
| `cursor_batch_execute` | 并行 1–3 个任务；每个必须有 `allowed_files`，范围不可重叠；始终使用独立 Agent。 |
| `cursor_start`         | 启动任务并立即返回 `job_id`。适合可取消或预计超过约五分钟的工作。               |
| `cursor_status`        | 精简进度。约每 5–6 分钟看一次；仅在无法判断是否卡住时传 `verbose=true`。        |
| `cursor_result`        | 取终态结果。                                                                    |
| `cursor_followup`      | 向同一 Agent 追加指令；每个任务最多一次，且紧接原任务。                         |
| `cursor_cancel`        | 取消进行中的任务。                                                              |

推荐流程：

1. Sol 先判断任务是否值得委派；小改动直接完成。
2. 需要委派时，写一份紧凑契约：绝对 `cwd`、objective、`allowed_files`、constraints、checks、`risk`。
3. 默认 `cursor_execute`：**Sol → Worker → Grok 实现 / 测试 / 自审 → 精简结果 → Sol 验收**。
4. 长任务或需要取消时用 `cursor_start`，间歇 `cursor_status`，终态再 `cursor_result`。
5. `cursor_batch_execute` 只用于 2–3 个文件范围互不重叠、且各自有足够工作量的独立任务。
6. 不希望沿用上一轮 Worker 上下文时，设 `reuse_session=false`。

`cursor_execute` 必填 `objective`、`cwd`；可选 `allowed_files`、`constraints`、`checks`、
`risk`（`low` / `medium` / `high`）、`model`、`params`、`reuse_session`。

## 模型与参数

默认模型 **`grok-4.6`**，默认参数 **`effort=xhigh`**、**`fast=false`**。这是目录解析与 WebUI
持久化默认，不是唯一组合。

在 **Models** 页可刷新真实目录、选择其他模型与参数并保存为后续 Worker 默认。单次任务可用 `model` /
`params` 覆盖。

建议（可被任务覆盖）：小型机械改动由 Sol 直接完成；需要委派的大批量机械修改用 `effort=medium`；常规实现用 `high`；
难调试或算法用 `xhigh`。除非明确更在意延迟，否则保持 `fast=false`。

## OpenAI Responses 文本接口

`POST http://127.0.0.1:8787/v1/responses`

- 只保证文本 stream 与 non-stream，不声称完整工具循环兼容。
- 需要 `Authorization: Bearer <CURSOR_RELAY_API_KEY>`。
- 未配置 `CURSOR_API_KEY` 时返回 `missing_cursor_api_key`。
- `strict` 模式下带 function `tools` 会得到 `501 tool_bridge_unavailable`。

Playground 可做文本试调用。隔离 Codex Provider 冒烟：`npm.cmd run smoke:codex`。

## 脚本与测试

| 命令                                      | 用途                                             |
| ----------------------------------------- | ------------------------------------------------ |
| `npm.cmd run typecheck` / `test` / `lint` | 类型检查、单测、lint                             |
| `npm.cmd run check`                       | typecheck + test + lint + format 一次跑完        |
| `scripts\dev.ps1` / `scripts\stop.ps1`    | 同时启动 / 关闭 Gateway 与 WebUI                 |
| `scripts\mcp.ps1 status/start/stop`       | 查看或手动控制本仓库 stdio MCP                   |
| `npm.cmd run mcp:stdio`                   | 前台跑 MCP stdio（调试）                         |
| `npm.cmd run start`                       | 只启动 Gateway                                   |
| `npm.cmd run smoke:cursor`                | 实时模型发现（需要 Key）                         |
| `npm.cmd run smoke:grok-text`             | 实时文本补全（需要 Key）                         |
| `npm.cmd run smoke:responses`             | `/v1/responses` 文本冒烟                         |
| `npm.cmd run smoke:codex`                 | 隔离 Codex → `cursor_relay`                      |
| `npm.cmd run smoke:worker-live`           | 实时 Worker 改文件（`CURSOR_LIVE_TEST=1` + Key） |
| `npm.cmd run e2e`                         | Playwright UI（会安装 Chromium）                 |

Live Cursor 测试需要同时设置 `CURSOR_LIVE_TEST=1` 和 `CURSOR_API_KEY`。

## 仓库安全

- 复制 `.env.example` 为 `.env`；永远不要提交 `.env`、API Key、SQLite 数据、日志或运行数据。
- Fake backend 测试是默认行为；真实 Cursor 测试需要显式 opt-in，并会消耗账号用量。
- 报告漏洞或分享诊断信息前，先阅读 [SECURITY.md](SECURITY.md)。

## 常见问题

**端口占用。** `scripts\dev.ps1` 需要 8787 与 5173 空闲。先跑 `scripts\stop.ps1`。

**`backend=fake` 或没有真实模型。** `.env` 里要有有效 `CURSOR_API_KEY`，且不要设
`CURSOR_BACKEND=fake`。到 Models 页刷新目录。

**MCP 工具超时。** 确认 `tool_timeout_sec = 1200`。xhigh 任务可能很长。

**主工具列表里没看到 Cursor 工具。** 先用 `/mcp` 确认 `cursor2api` 已连接；修改配置后重启 Codex。部分运行环境会把
MCP 工具延迟加载，不显示在顶层清单中，但仍可通过完整 MCP 工具名调用。

**停了 Gateway，Codex 仍能调 MCP。** 正常。stdio MCP 由 Codex 拉起，与 HTTP Gateway 分开。

**想用原生 Sol → Grok subagent。** 当前 Codex 版本不可用，继续走 MCP Worker。

**主会话也变成 Grok。** 不要把 `model_provider = "cursor_relay"` 写成全局默认。

## 贡献与归属

开发流程见 [CONTRIBUTING.md](CONTRIBUTING.md)，项目归属见 [CONTRIBUTORS.md](CONTRIBUTORS.md)，发布步骤见
[docs/PUBLISHING_CHECKLIST.md](docs/PUBLISHING_CHECKLIST.md)。

尚未选择开源许可证。在原作者与仓库所有者达成一致之前，默认保留所有版权权利。