cursor-api

说明

• 当前版本已稳定，若发现响应出现缺字漏字，与本程序无关。
• 若发现首字慢，与本程序无关。
• 若发现响应出现乱码，也与本程序无关。
• 属于官方的问题，请不要像作者反馈。
• 本程序拥有堪比客户端原本的速度，甚至可能更快。
• 本程序的性能是非常厉害的。
• 根据本项目开源协议，Fork的项目不能以作者的名义进行任何形式的宣传、推广或声明。
• 更新的时间跨度达5月有余了，求赞助，项目不收费，不定制。
• 推荐自部署，官方网站 仅用于作者测试，不保证稳定性。

快速开始

本节将引导你从零开始完成：构建 -> 配置 -> 添加 Cursor Token -> 发起第一次对话请求。

1. 构建

方式一：本地编译（推荐开发调试）

需要 Rust nightly 工具链：

rustup default nightly

编译并运行（使用系统原生 TLS 根证书）：

cargo run --no-default-features --features native-roots

或编译 release 版本：

cargo build --release

编译产物位于 target/release/cursor-api，可直接拷贝到任意目录运行：

./target/release/cursor-api

方式二：Docker（推荐生产部署）

docker build -t cursor-api .
docker run -d --name cursor-api -p 3000:3000 --env-file .env cursor-api

2. 配置 AUTH_TOKEN

AUTH_TOKEN 是本服务的管理密码，所有管理操作（添加/删除 Token、查看日志、修改代理等）都通过它认证，同时也是调用 Chat API 的默认凭据。

在项目根目录创建 .env 文件（可从 .env.example 复制），设置：

AUTH_TOKEN=your-secret-password

将 your-secret-password 替换为你自己的密码。之后所有 API 请求都通过 Authorization: Bearer your-secret-password 认证。

重要： AUTH_TOKEN 不是 Cursor 的登录 Token，而是你为本服务设置的管理密码。

3. 获取并添加 Cursor Token

服务本身不内置 Cursor 账号凭据，需要你从 Cursor 编辑器提取 session token 并添加到服务中。

第一步：获取 Cursor Token

从 Cursor 编辑器本地数据库提取（详见下方 获取key 章节），以 macOS 为例：

sqlite3 "$HOME/Library/Application Support/Cursor/User/globalStorage/state.vscdb" \
  "SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken';"

你会得到一个以 eyJ 开头的长字符串，这就是你的 Cursor Token。

第二步：启动服务

# 本地编译运行
cargo run --no-default-features --features native-roots

# 或使用已编译的二进制
./target/release/cursor-api

服务默认监听 http://localhost:3000。

第三步：添加 Token 到服务

curl -X POST http://localhost:3000/tokens/add \
  -H "Authorization: Bearer your-secret-password" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      {"token": "eyJ...你的Cursor Token..."}
    ]
  }'

成功响应：

{"status":"success","tokens_count":1,"message":"New tokens have been added and reloaded"}

4. 发起对话请求

现在可以像调用 OpenAI API 一样使用了：

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer your-secret-password" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3.7-sonnet",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

5. 使用二进制文件部署

编译 release 后，只需要以下文件即可独立部署：

your-deploy-dir/
├── cursor-api        # 编译产物 (从 target/release/cursor-api 复制)
└── .env              # 环境变量配置文件

启动方式：

cd your-deploy-dir
./cursor-api

服务启动后会自动读取同目录下的 .env 文件，数据（Token、代理配置、日志等）默认存储在 ./data/ 目录中（可通过 DATA_DIR 环境变量修改）。

常见问题排查

快速对照表

错误信息	原因	解决方式
unauthorized	AUTH_TOKEN 不匹配	检查 .env 中的 AUTH_TOKEN 值与请求头中的 Bearer Token 是否一致
no_tokens	未添加 Cursor Token	通过 /tokens/add 接口添加 Token
tls handshake eof	系统代理干扰 TLS 握手	见下方详细说明
error sending request（无更多细节）	TLS 根证书不匹配	见下方详细说明
unauthenticated	Cursor Token 失效	重新从 Cursor 编辑器获取 Token 并添加
model_not_supported	模型名称不正确	通过 GET /v1/models 查看可用模型列表

问题一：tls handshake eof — 系统代理导致 TLS 握手失败

现象：

{"type":"error","code":"request_failed","message":"Request failed: error sending request: client error (Connect): tls handshake eof","param":null}

原因： 服务默认使用 sys（系统代理）作为通用代理。当本机有代理软件（如 Clash、V2Ray 等）运行时，Rust 的 reqwest/rustls 客户端通过系统代理发起 HTTPS 请求，代理可能无法正确中转 TLS 握手，导致上游服务器直接断开连接。

解决方式： 将通用代理切换为 non（不使用任何代理，直连上游）：

# 添加 non 代理选项
curl -X POST http://localhost:3000/proxies/add \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"proxies":{"non":"non"}}'

# 将通用代理设为 non
curl -X POST http://localhost:3000/proxies/set-general \
  -H "Authorization: Bearer <AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"non"}'

如果你需要代理才能访问外网，应配置一个明确可用的代理 URL（如 http://127.0.0.1:7890），而不是使用 sys。

注意： 代理配置会在重启后重置为默认值 sys。如果每次重启都遇到此问题，需在启动后重新执行上述命令。

问题二：error sending request（无详细信息）— TLS 根证书问题

现象：

{"type":"error","code":"request_failed","message":"Request failed: error sending request","param":null}

与问题一不同的是，错误信息中没有 tls handshake eof 等具体描述，且已排除代理问题（已切换为 non）。

原因： 项目有两种 TLS 根证书 feature：

Feature	说明	适用场景
webpki-roots（默认）	使用内嵌的 Mozilla 根证书包	Docker 容器 / 无系统证书的环境
native-roots	使用操作系统的根证书存储	本地开发 / macOS / Windows

在 macOS 上本地运行时，如果使用默认的 webpki-roots 编译，内嵌的根证书包可能不包含上游服务（如 api2.cursor.sh）证书链所需的根证书，导致 TLS 验证静默失败。

解决方式： 本地编译运行时使用 native-roots：

# 开发调试
cargo run --no-default-features --features native-roots

# 编译 release
cargo build --release --no-default-features --features native-roots

提示： Docker 部署使用默认的 webpki-roots 即可，无需修改。native-roots 仅在本地直接运行二进制文件时推荐使用。

问题三：代理配置重启后重置

现象： 每次重启服务后，通用代理又变回 sys，需要重新手动切换为 non。

原因： 代理配置的持久化依赖 data/proxies.bin 文件。首次启动时如果没有该文件，会使用默认配置（sys）。

解决方式： 在切换代理后，确认 data/proxies.bin 文件已生成。代理配置通过管理接口修改后会自动保存。如果反复重置，检查 DATA_DIR 环境变量指向的目录是否有写权限。

---

获取key

注意： 从浏览器 cursor.com 获取的 token 类型为 web，无法用于 Chat API。必须使用 Cursor 编辑器本地存储的 session 类型 token。

方式一：从 Cursor 编辑器本地数据库获取（推荐）

Cursor 编辑器将 session token 存储在本地 SQLite 数据库中，可直接提取：

macOS：

sqlite3 "$HOME/Library/Application Support/Cursor/User/globalStorage/state.vscdb" \
  "SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken';"

Linux：

sqlite3 "$HOME/.config/Cursor/User/globalStorage/state.vscdb" \
  "SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken';"

Windows（PowerShell）：

sqlite3 "$env:APPDATA\Cursor\User\globalStorage\state.vscdb" `
  "SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken';"

方式二：从浏览器获取（仅供参考，不推荐）

1. 访问 www.cursor.com 并完成注册登录
2. 在浏览器中打开开发者工具（F12）
3. 在 Application-Cookies 中查找名为 WorkosCursorSessionToken 的条目，并复制其第三个字段。请注意，%3A%3A 是 :: 的 URL 编码形式，cookie 的值使用冒号 (:) 进行分隔。

⚠️ 此方式获取的 token 类型为 web，可能无法用于 Chat API，建议使用方式一。

配置说明

环境变量

• PORT: 服务器端口号（默认：3000）
• AUTH_TOKEN: 认证令牌（必须，用于API认证）
• ROUTE_PREFIX: 路由前缀（可选）
• DEBUG: 是否启用调试日志（默认：false）
• DEBUG_LOG_FILE: 调试日志文件路径（默认：debug.log）
• BYPASS_MODEL_VALIDATION: 跳过模型名校验，允许任意模型名透传（默认：false）

更多请查看 /env-example

日志查看

1. 调试日志文件：设置 DEBUG=true 和 DEBUG_LOG_FILE=debug.log 后，详细的调试信息会写入该文件。包含 Anthropic/OpenAI 请求的完整链路日志（请求模型、thinking 状态、tools 数量、Cursor 响应状态、上游错误详情等）。
2. 请求日志 API：通过 GET /logs 查看日志页面，或通过 POST /logs/get 获取 JSON 格式的请求日志（需 Bearer Token 认证）。
3. 终端标准输出：运行时的启动信息和错误会直接输出到终端。

Token文件格式（已弃用）

.tokens 文件：每行为token和checksum的对应关系：

# 这里的#表示这行在下次读取要删除
token1,checksum1
token2,checksum2

该文件可以被自动管理，但用户仅可在确认自己拥有修改能力时修改，一般仅有以下情况需要手动修改：

• 需要删除某个 token
• 需要使用已有 checksum 来对应某一个 token

模型列表

模型列表支持动态更新，详见更新模型列表说明。以下为常用模型（完整列表通过 GET /v1/models 获取）：

Claude 系列：

claude-4.6-sonnet-medium / claude-4.6-sonnet-medium-thinking
claude-4.6-opus-high / claude-4.6-opus-max
claude-4.6-opus-high-thinking / claude-4.6-opus-max-thinking
claude-4.5-opus-high / claude-4.5-opus-high-thinking
claude-4.5-sonnet / claude-4.5-sonnet-thinking
claude-4.5-haiku / claude-4.5-haiku-thinking
claude-4-sonnet / claude-4-sonnet-thinking
claude-4-sonnet-1m / claude-4-sonnet-1m-thinking

GPT 系列：

gpt-5.3-codex-{low,medium,high,xhigh}[-fast]
gpt-5.2-{low,medium,high,xhigh}[-fast]
gpt-5.2-codex-{low,medium,high,xhigh}[-fast]
gpt-5.1-codex-max-{low,medium,high,xhigh}[-fast]
gpt-5.1-codex-mini-{low,medium,high}
gpt-5.1-high
gpt-5-mini

其他模型：

gemini-3.1-pro / gemini-3-pro / gemini-3-flash / gemini-2.5-flash
grok-code-fast-1
kimi-k2.5
default / composer-1.5 / composer-1

测试 chat 接口

curl -X POST http://localhost:3000/tokens/add \
  -H "Authorization: Bearer 123456" \
  -H "Content-Type: application/json" \
  -d '{"tokens": [{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhdXRoMHx1c2VyXzAxS0cxNU5CM0tHMTVaUVlKQUpCMVZRSjU3IiwidGltZSI6IjE3NzMxMzYxNTIiLCJyYW5kb21uZXNzIjoiMDczODlmZmYtMTI1NS00Yjc3IiwiZXhwIjoxNzc4MzIwMTUyLCJpc3MiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLmN1cnNvci5zaCIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwgb2ZmbGluZV9hY2Nlc3MiLCJhdWQiOiJodHRwczovL2N1cnNvci5jb20iLCJ0eXBlIjoic2Vzc2lvbiJ9.XsywiahijYj8-FBmJRH2HKpekkVBEZJnRxuirgV_VlE"}]}'

接口说明

基础对话

• 接口地址: /v1/chat/completions
• 请求方法: POST
• 认证方式: Bearer Token
  1. 使用环境变量 AUTH_TOKEN 进行认证
  2. 使用 .token 文件中的令牌列表进行轮询认证 在v0.1.3的rc版本更新中移除.token文件
  3. 自v0.1.3-rc.3起支持直接使用 token,checksum 进行认证，但未提供配置关闭 v0.3.0起不再支持
  4. 使用 /build-key 构建的动态密钥认证
  5. 使用 /config 设置的共享Token进行认证 (关联：环境变量SHARED_TOKEN)
  6. 日志中的缓存 token key 的两种表示方式认证 (/build-key 同时也会给出这两种格式作为动态密钥的别名，该数字key本质为一个192位的整数)

请求格式

{
  "model": string,
  "messages": [
    {
      "role": "system" | "user" | "assistant", // 也可以是 "developer" | "human" | "ai"
      "content": string | [
        {
          "type": "text" | "image_url",
          "text": string,
          "image_url": {
            "url": string
          }
        }
      ]
    }
  ],
  "stream": boolean,
  "stream_options": {
    "include_usage": boolean
  }
}

响应格式

如果 stream 为 false:

{
  "id": string,
  "object": "chat.completion",
  "created": number,
  "model": string,
  "choices": [
    {
      "index": number,
      "message": {
        "role": "assistant",
        "content": string
      },
      "finish_reason": "stop" | "length"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

如果 stream 为 true:

data: {"id":string,"object":"chat.completion.chunk","created":number,"model":string,"choices":[{"index":number,"delta":{"role":"assistant","content":string},"finish_reason":null}]}

data: {"id":string,"object":"chat.completion.chunk","created":number,"model":string,"choices":[{"index":number,"delta":{"content":string},"finish_reason":null}]}

data: {"id":string,"object":"chat.completion.chunk","created":number,"model":string,"choices":[{"index":number,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Anthropic Messages API（兼容 Claude Code）

• 接口地址: /v1/messages
• 请求方法: POST
• 认证方式: x-api-key 或 Authorization: Bearer
• 兼容 Anthropic Messages API 格式，支持 tool use、thinking（extended thinking）、streaming

请求格式

{
  "model": "claude-4.6-sonnet-medium",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "stream": true,
  "thinking": {"type": "enabled", "budget_tokens": 5000},
  "tools": [...]
}

• 当请求包含 thinking.type = "enabled" 时，模型名会自动追加 -thinking 后缀（如 claude-4.6-sonnet-medium → claude-4.6-sonnet-medium-thinking）
• tools 支持完整 JSON Schema（含 enum、anyOf、items、嵌套对象等）

配合 Claude Code 使用

在 Claude Code 的配置文件（~/.claude.json）中添加：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:3000",
    "ANTHROPIC_API_KEY": "<AUTH_TOKEN>",
    "ANTHROPIC_MODEL": "claude-4.6-sonnet-medium",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-4.6-sonnet-medium"
  }
}

将 <AUTH_TOKEN> 替换为 .env 中设置的 AUTH_TOKEN 值。

注意： Claude Code 会自动开启 thinking 模式。如果 thinking 模型变体不可用，可设置 BYPASS_MODEL_VALIDATION=true 并更换为其他模型。

获取模型列表

• 接口地址: /v1/models
• 请求方法: GET
• 认证方式: Bearer Token

查询参数

可选的 JSON 请求体用于作为请求模型列表的参数：

{
  "is_nightly": boolean,                    // 是否包含 nightly 版本模型，默认 false
  "include_long_context_models": boolean,   // 是否包含长上下文模型，默认 false  
  "exclude_max_named_models": boolean,      // 是否排除 max 命名的模型，默认 false
  "additional_model_names": [string]        // 额外包含的模型名称列表，默认空数组
}

注意: 认证可选，查询参数可选且认证时生效，未提供时使用默认值。

响应格式

{
  "object": "list",
  "data": [
    {
      "id": string,
      "display_name": string,
      "created": number,
      "created_at": string,
      "object": "model",
      "type": "model", 
      "owned_by": string,
      "supports_thinking": boolean,
      "supports_images": boolean,
      "supports_max_mode": boolean,
      "supports_non_max_mode": boolean
    }
  ]
}

更新模型列表说明

每次携带Token时都会拉取最新的模型列表，与上次更新需距离至少30分钟。additional_model_names 可以用添加额外模型。

Token管理接口

简易Token信息管理页面

• 接口地址: /tokens
• 请求方法: GET
• 响应格式: HTML页面
• 功能: 调用下面的各种相关API的示例页面

获取Token信息

• 接口地址: /tokens/get
• 请求方法: POST
• 认证方式: Bearer Token
• 响应格式:

{
  "status": "success",
  "tokens": [
    [
      number,
      string,
      {
        "bundle": {
          "primary_token": string,
          "secondary_token": string, // 可选
          "checksum": {
            "first": string,
            "second": string,
          },
          "client_key": string, // 可选，非空时显示
          "config_version": string, // 可选
          "session_id": string, // 可选
          "proxy": string, // 可选
          "timezone": string, // 可选
          "gcpp_host": object, // 可选
          "user": { // 可选
            "email": string,
            "name": string,
            "updated_at": string,
            "picture": string, // 可选
            "is_on_new_pricing": boolean
          }
        },
        "status": "enabled" | "disabled",
        "stripe": { // 可选
          "membership_type": "free" | "free_trial" | "pro" | "pro_plus" | "ultra" | "enterprise",
          "payment_id": string, // 可选
          "days_remaining_on_trial": number,
          "subscription_status": "trialing" | "active" | "incomplete" | "incomplete_expired" | "past_due" | "canceled" | "unpaid" | "paused", // 可选
          "verified_student": boolean, // 可选
          "is_on_student_plan": boolean // 可选
        }
      }
    ]
  ],
  "tokens_count": number
}

设置Token信息

• 接口地址: /tokens/set
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

[
  [
    string,
    {
      "bundle": {
        "primary_token": string,
        "secondary_token": string, // 可选
        "checksum": {
          "first": string,
          "second": string,
        },
        "client_key": string, // 可选
        "config_version": string, // 可选
        "session_id": string, // 可选
        "proxy": string, // 可选
        "timezone": string, // 可选
        "gcpp_host": object, // 可选
        "user": { // 可选
          "email": string,
          "name": string,
          "updated_at": string,
          "picture": string, // 可选
          "is_on_new_pricing": boolean
        }
      },
      "status": "enabled" | "disabled",
      "stripe": { // 可选
        "membership_type": "free" | "free_trial" | "pro" | "pro_plus" | "ultra" | "enterprise",
        "payment_id": string, // 可选
        "days_remaining_on_trial": number,
        "subscription_status": "trialing" | "active" | "incomplete" | "incomplete_expired" | "past_due" | "canceled" | "unpaid" | "paused", // 可选
        "verified_student": boolean // 可选
      }
    }
  ]
]

• 响应格式:

{
  "status": "success",
  "tokens_count": number,
  "message": "Token files have been updated and reloaded"
}

添加Token

• 接口地址: /tokens/add
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "tokens": [
    {
      "alias": string, // 可选，无则自动生成
      "token": string,
      "checksum": string, // 可选，无则自动生成
      "client_key": string, // 可选，无则自动生成
      "session_id": string, // 可选
      "config_version": string, // 可选
      "proxy": string, // 可选
      "timezone": string, // 可选
      "gcpp_host": string // 可选
    }
  ],
  "status": "enabled" | "disabled"
}

• 响应格式:

{
  "status": "success",
  "tokens_count": number,
  "message": string  // "New tokens have been added and reloaded" 或 "No new tokens were added"
}

删除Token

• 接口地址: /tokens/del
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "aliases": [string], // 要删除的token列表
  "include_failed_tokens": boolean // 默认为false
}

• 响应格式:

{
  "status": "success",
  "failed_tokens": [string] // 可选，根据include_failed_tokens返回，表示未找到的token列表
}

• expectation说明:
  • simple: 只返回基本状态
  • updated_tokens: 返回更新后的token列表
  • failed_tokens: 返回未找到的token列表
  • detailed: 返回完整信息（包括updated_tokens和failed_tokens）

设置Tokens标签（已弃用）

• 接口地址: /tokens/tags/set
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "tokens": [string],
  "tags": {
    string: null | string // 键可以为 timezone: 时区标识符 或 proxy: 代理名称
  }
}

• 响应格式:

{
  "status": "success",
  "message": string  // "标签更新成功"
}

更新令牌Profile

• 接口地址: /tokens/profile/update
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

[
  string // aliases
]

• 响应格式:

{
  "status": "success",
  "message": "已更新{}个令牌配置, {}个令牌更新失败"
}

更新令牌CV

• 接口地址: /tokens/config-version/update
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

[
  string // aliases
]

• 响应格式:

{
  "status": "success",
  "message": "已更新{}个令牌配置版本, {}个令牌更新失败"
}

刷新令牌

• 接口地址: /tokens/refresh
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

[
  string // aliases
]

• 响应格式:

{
  "status": "success",
  "message": "已刷新{}个令牌, {}个令牌刷新失败"
}

设置令牌状态

• 接口地址: /tokens/status/set
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "aliases": [string],
  "status": "enabled" | "disabled"
}

• 响应格式:

{
  "status": "success",
  "message": "已设置{}个令牌状态, {}个令牌设置失败"
}

设置令牌别名

• 接口地址: /tokens/alias/set
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "{old_alias}": "{new_alias}"
}

• 响应格式:

{
  "status": "success",
  "message": "已设置{}个令牌别名, {}个令牌设置失败"
}

设置Tokens代理

• 接口地址: /tokens/proxy/set
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "aliases": [string],
  "proxy": string  // 可选，代理地址，null表示清除代理
}

• 响应格式:

{
  "status": "success",
  "message": "已设置{}个令牌代理, {}个令牌设置失败"
}

设置Tokens时区

• 接口地址: /tokens/timezone/set
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "aliases": [string],
  "timezone": string  // 可选，时区标识符（如"Asia/Shanghai"），null表示清除时区
}

• 响应格式:

{
  "status": "success",
  "message": "已设置{}个令牌时区, {}个令牌设置失败"
}

构建API Key

• 接口地址: /build-key
• 请求方法: POST
• 认证方式: Bearer Token (当SHARE_AUTH_TOKEN启用时需要)
• 请求格式:

{
  "token": string,               // 格式: JWT
  "checksum": {
    "first": string,             // 格式: 长度为64的Hex编码字符串
    "second": string,            // 格式: 长度为64的Hex编码字符串
  },
  "client_key": string,          // 格式: 长度为64的Hex编码字符串
  "config_version": string,      // 格式: UUID
  "session_id": string,          // 格式: UUID
  "secret": string,              // 可选，没什么用
  "proxy_name": string,          // 可选，指定代理
  "timezone": string,            // 可选，指定时区
  "gcpp_host": string,           // 可选，代码补全区域
  "disable_vision": boolean,       // 可选，禁用图片处理能力
  "enable_slow_pool": boolean,     // 可选，启用慢速池
  "include_web_references": boolean,
  "usage_check_models": {          // 可选，使用量检查模型配置
    "type": "default" | "disabled" | "all" | "custom",
    "model_ids": string  // 当type为custom时生效，以逗号分隔的模型ID列表
  }
}

• 响应格式:

{
  "keys": [string]    // 成功时返回生成的key
}

或出错时:

{
  "error": string  // 错误信息
}

说明：

1. 此接口用于生成携带动态配置的API Key，是对直接传token与checksum模式的升级版本，在0.3起，直接传token与checksum的方式已经不再适用

2. 生成的key格式为: sk-{encoded_config}，其中sk-为默认前缀(可配置)

3. usage_check_models配置说明:

   • default: 使用默认模型列表(同下 usage_check_models 字段的默认值)
   • disabled: 禁用使用量检查
   • all: 检查所有可用模型
   • custom: 使用自定义模型列表(需在model_ids中指定)

4. 在当前版本，keys数组长度总为3，后2个基于缓存，仅第1个使用过才行：

   1. 完整key，旧版本也存在
   2. 数字key的base64编码版本
   3. 数字key的明文版本

5. 数字key是一个128位无符号整数与一个64位无符号整数组成的，比通常使用的uuid更难破解。

获取Config Version

• 接口地址: /config-version
• 请求方法: POST
• 认证方式: Bearer Token (当SHARE_AUTH_TOKEN启用时需要)
• 请求格式:

{
  "token": string,               // 格式: JWT
  "checksum": {
    "first": string,             // 格式: 长度为64的Hex编码字符串
    "second": string,            // 格式: 长度为64的Hex编码字符串
  },
  "client_key": string,          // 格式: 长度为64的Hex编码字符串
  "session_id": string,          // 格式: UUID
  "proxy_name": string,          // 可选，指定代理
  "timezone": string,            // 可选，指定时区
  "gcpp_host": string            // 可选，代码补全区域
}

• 响应格式:

{
  "config_version": string    // 成功时返回生成的UUID
}

或出错时:

{
  "error": string  // 错误信息
}

代理管理接口

简易代理信息管理页面

• 接口地址: /proxies
• 请求方法: GET
• 响应格式: HTML页面
• 功能: 调用下面的各种相关API的示例页面

获取代理配置信息

• 接口地址: /proxies/get
• 请求方法: POST
• 响应格式:

{
  "status": "success",
  "proxies": {
    "proxies": {
      "proxy_name": "non" | "sys" | "http://proxy-url",
    },
    "general": string // 当前使用的通用代理名称
  },
  "proxies_count": number,
  "general_proxy": string,
  "message": string // 可选
}

设置代理配置

• 接口地址: /proxies/set
• 请求方法: POST
• 请求格式:

{
  "proxies": {
    "{proxy_name}": "non" | "sys" | "http://proxy-url"
  },
  "general": string  // 要设置的通用代理名称
}

• 响应格式:

{
  "status": "success",
  "proxies_count": number,
  "message": "代理配置已更新"
}

添加代理

• 接口地址: /proxies/add
• 请求方法: POST
• 请求格式:

{
  "proxies": {
    "{proxy_name}": "non" | "sys" | "http://proxy-url"
  }
}

• 响应格式:

{
  "status": "success",
  "proxies_count": number,
  "message": string  // "已添加 X 个新代理" 或 "没有添加新代理"
}

删除代理

• 接口地址: /proxies/del
• 请求方法: POST
• 请求格式:

{
  "names": [string],  // 要删除的代理名称列表
  "expectation": "simple" | "updated_proxies" | "failed_names" | "detailed"  // 默认为simple
}

• 响应格式:

{
  "status": "success",
  "updated_proxies": {  // 可选，根据expectation返回
    "proxies": {
      "proxy_name": "non" | "sys" | "http://proxy-url"
    },
    "general": string
  },
  "failed_names": [string]  // 可选，根据expectation返回，表示未找到的代理名称列表
}

设置通用代理

• 接口地址: /proxies/set-general
• 请求方法: POST
• 请求格式:

{
  "name": string  // 要设置为通用代理的代理名称
}

• 响应格式:

{
  "status": "success",
  "message": "通用代理已设置"
}

代理类型说明

• non: 表示不使用代理
• sys: 表示使用系统代理
• 其他: 表示具体的代理URL地址（如 http://proxy-url）

注意事项

1. 代理名称必须是唯一的，添加重复名称的代理会被忽略
2. 设置通用代理时，指定的代理名称必须存在于当前的代理配置中
3. 删除代理时的 expectation 参数说明：
   • simple: 只返回基本状态
   • updated_proxies: 返回更新后的代理配置
   • failed_names: 返回未找到的代理名称列表
   • detailed: 返回完整信息（包括updated_proxies和failed_names）

错误格式

所有接口在发生错误时会返回统一的错误格式：

{
  "status": "error",
  "code": number,   // 可选
  "error": string,  // 可选，错误详细信息
  "message": string // 错误提示信息
}

配置管理接口

配置页面

• 接口地址: /config
• 请求方法: GET
• 响应格式: HTML页面
• 功能: 提供配置管理界面,可以修改页面内容和系统配置

更新配置

• 接口地址: /config
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "action": "get" | "update" | "reset",
  "path": string,
  "content": {
    "type": "default" | "not_found" | "redirect" | "plain_text" | "html" | "css" | "js",
    "value": string  // type=redirect时为URL, type=plain_text/html/css/js时为对应内容
  },
  "vision_ability": "none" | "base64" | "all", // "disabled" | "base64-only" | "base64-http"
  "enable_slow_pool": boolean,
  "enable_long_context": boolean,
  "usage_check_models": {
    "type": "none" | "default" | "all" | "list",
    "content": string
  },
  "enable_dynamic_key": boolean,
  "share_token": string,
  "calibrate_token": string,
  "include_web_references": boolean
}

• 响应格式:

{
  "status": "success",
  "message": string,
  "data": {
    "content": {
      "type": "default" | "not_found" | "redirect" | "plain_text" | "html" | "css" | "js",
      "value": string
    },
    "vision_ability": "none" | "base64" | "all",
    "enable_slow_pool": boolean,
    "enable_long_context": boolean,
    "usage_check_models": {
      "type": "none" | "default" | "all" | "list",
      "content": string
    },
    "enable_dynamic_key": boolean,
    "share_token": string,
    "calibrate_token": string,
    "include_web_references": boolean
  }
}

注意：usage_check_models 字段的默认值为非"cursor-small"、"deepseek-v3.1"、"grok-3-mini"的所有模型。

这些模型将默认进行使用量检查。您可以通过配置接口修改此设置。

日志管理接口

获取日志接口

• 接口地址: /logs
• 请求方法: GET
• 响应格式: 根据配置返回不同的内容类型(默认、文本或HTML)

获取日志数据

• 接口地址: /logs/get
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

{
  "query": {
    // 分页与排序控制
    "limit": number,             // 可选，返回记录数量限制
    "offset": number,            // 可选，起始位置偏移量
    "reverse": boolean,          // 可选，反向排序，默认false（从旧到新），true时从新到旧

    // 时间范围过滤
    "from_date": string,         // 可选，开始日期时间，RFC3339格式
    "to_date": string,           // 可选，结束日期时间，RFC3339格式

    // 用户标识过滤
    "user_id": string,           // 可选，按用户ID精确匹配
    "email": string,             // 可选，按用户邮箱过滤（支持部分匹配）
    "membership_type": string,   // 可选，按会员类型过滤 ("free"/"free_trial"/"pro"/"enterprise")

    // 核心业务过滤
    "status": string,            // 可选，按状态过滤 ("pending"/"success"/"failure")
    "model": string,             // 可选，按模型名称过滤（支持部分匹配）
    "include_models": [string],  // 可选，包含特定模型
    "exclude_models": [string],  // 可选，排除特定模型

    // 请求特征过滤
    "stream": boolean,           // 可选，是否为流式请求
    "has_chain": boolean,        // 可选，是否包含对话链
    "has_usage": boolean,        // 可选，是否有usage信息

    // 错误相关过滤
    "has_error": boolean,        // 可选，是否包含错误
    "error": string,             // 可选，按错误过滤（支持部分匹配）

    // 性能指标过滤
    "min_total_time": number,    // 可选，最小总耗时（秒）
    "max_total_time": number,    // 可选，最大总耗时（秒）
    "min_tokens": number,        // 可选，最小token数（input + output）
    "max_tokens": number         // 可选，最大token数
  }
}

• 响应格式:

{
  "total": number,
  "logs": [
    {
      "id": number,
      "timestamp": string,
      "model": string,
      "token_info": {
        "key": string,
        "stripe": { // 可选
          "membership_type": "free" | "free_trial" | "pro" | "pro_plus" | "ultra" | "enterprise",
          "payment_id": string, // 可选
          "days_remaining_on_trial": number,
          "subscription_status": "trialing" | "active" | "incomplete" | "incomplete_expired" | "past_due" | "canceled" | "unpaid" | "paused", // 可选
          "verified_student": boolean // 可选
        }
      },
      "chain": {
        "prompt": [ // array or string
          {
            "role": string,
            "content": string
          }
        ],
        "delays": [
          string,
          [
            number, // chars count
            number // time
          ]
        ],
        "usage": { // optional
          "input": number,
          "output": number,
        }
      },
      "timing": {
        "total": number
      },
      "stream": boolean,
      "status": string,
      "error": string
    }
  ],
  "timestamp": string,
  "status": "success"
}

• 说明：
  • 所有查询参数都是可选的
  • 管理员可以查看所有日志，普通用户只能查看与其token相关的日志
  • 如果提供了无效的状态或会员类型，将返回空结果
  • 日期时间格式需遵循 RFC3339 标准，如："2024-03-20T15:30:00+08:00"
  • 邮箱和模型名称支持部分匹配

获取日志令牌

• 接口地址: /logs/tokens/get
• 请求方法: POST
• 认证方式: Bearer Token
• 请求格式:

[
  string
]

• 响应格式:

{
  "status": "success",
  "tokens": {
    "{key}": {
      "primary_token": string,
      "secondary_token": string, // 可选
      "checksum": {
        "first": string,
        "second": string,
      },
      "client_key": string, // 可选，非空时显示
      "config_version": string, // 可选
      "session_id": string, // 可选
      "proxy": string, // 可选
      "timezone": string, // 可选
      "gcpp_host": object, // 可选
      "user": { // 可选
        "email": string,
        "name": string,
        "updated_at": string,
        "picture": string, // 可选
        "is_on_new_pricing": boolean
      }
    }
  },
  "total": number,
  "timestamp": string
}

静态资源接口

获取共享样式

• 接口地址: /static/shared-styles.css
• 请求方法: GET
• 响应格式: CSS文件
• 功能: 获取共享样式表

获取共享脚本

• 接口地址: /static/shared.js
• 请求方法: GET
• 响应格式: JavaScript文件
• 功能: 获取共享JavaScript代码

获取其他资源

• 接口地址: /static/{path}

• 请求方法: GET

• 请求参数:

  • path: 静态文件的相对路径

• 响应格式:

  • 成功响应 (200 OK):

    • Headers:
      • Content-Type: 根据文件扩展名自动设置（见下方MIME类型映射表）
      • Content-Length: 文件大小
    • Body: 文件的二进制内容

  • 文件不存在或大小超过4GiB (404 Not Found):

    • Headers:
      • Content-Type: text/plain; charset=utf-8
    • Body: 错误信息

• 支持的MIME类型映射:

  • 文本类型: html, htm, txt, css, js, mjs, csv, xml, md, markdown
  • 图像类型: jpg, jpeg, png, gif, webp, svg, bmp, ico, tiff, tif, avif
  • 音频类型: mp3, mp4a, wav, ogg, oga, weba, aac, flac, m4a
  • 视频类型: mp4, mpeg, mpg, webm, ogv, avi, mov, qt, flv
  • 文档类型: pdf, doc, docx, xls, xlsx, ppt, pptx
  • 压缩文件: zip, rar, 7z, gz, gzip, tar
  • 字体类型: ttf, otf, woff, woff2
  • 其他类型: 默认为 application/octet-stream

• 功能: 获取从环境变量DATA_DIR指定的目录下的子目录static下的文件。

环境变量示例

• 接口地址: /env-example
• 请求方法: GET
• 响应格式: 文本文件
• 功能: 获取环境变量配置示例

健康检查接口

• 接口地址: /health 或 /(重定向)
• 请求方法: GET
• 认证方式: 无需
• 响应格式: 根据配置返回不同的内容类型(默认JSON、文本或HTML)

响应结构

{
  "status": "success",
  "service": {
    "name": "cursor-api",
    "version": "1.0.0",
    "is_debug": false,
    "build": {
      "version": 1,
      "timestamp": "2024-01-15T10:30:00Z",
      "is_debug": false,
      "is_prerelease": false
    }
  },
  "runtime": {
    "started_at": "2024-01-15T10:00:00+08:00",
    "uptime_seconds": 1800,
    "requests": {
      "total": 1250,
      "active": 3,
      "errors": 12
    }
  },
  "system": {
    "memory": {
      "used_bytes": 134217728,
      "used_percentage": 12.5,
      "available_bytes": 1073741824
    },
    "cpu": {
      "usage_percentage": 15.2,
      "load_average": [0.8, 1.2, 1.5]
    }
  },
  "capabilities": {
    "models": ["gpt-4", "claude-3"],
    "endpoints": ["/chat", "/completions", "/embeddings"],
    "features": ["streaming", "function_calling", "vision"]
  }
}

字段说明

字段	类型	说明
status	string	服务状态: "success", "warning", "error"
service.name	string	服务名称
service.version	string	服务版本
service.is_debug	boolean	是否为调试模式
service.build.version	number	构建版本号(仅preview功能启用时)
service.build.timestamp	string	构建时间戳
service.build.is_prerelease	boolean	是否为预发布版本
runtime.started_at	string	服务启动时间
runtime.uptime_seconds	number	运行时长(秒)
runtime.requests.total	number	总请求数
runtime.requests.active	number	当前活跃请求数
runtime.requests.errors	number	错误请求数
system.memory.used_bytes	number	已使用内存(字节)
system.memory.used_percentage	number	内存使用率(%)
system.memory.available_bytes	number	可用内存(字节,可选)
system.cpu.usage_percentage	number	CPU使用率(%)
system.cpu.load_average	array	系统负载[1分钟,5分钟,15分钟]
capabilities.models	array	支持的模型列表
capabilities.endpoints	array	可用的API端点
capabilities.features	array	支持的功能特性

其他接口

随机生成一个uuid

• 接口地址: /gen-uuid
• 请求方法: GET
• 响应格式:

string

随机生成一个hash

• 接口地址: /gen-hash
• 请求方法: GET
• 响应格式:

string

随机生成一个checksum

• 接口地址: /gen-checksum
• 请求方法: GET
• 响应格式:

string

随机生成一个token

• 接口地址: /gen-token
• 请求方法: GET
• 响应格式:

string

获取当前的tsheader

• 接口地址: /get-tsheader
• 请求方法: GET
• 响应格式:

string

获取用户信息（已弃用）

• 接口地址: /userinfo
• 请求方法: POST
• 认证方式: 请求体中包含token
• 请求格式:

{
  "token": string
}

• 响应格式:

{
  "usage": {
    "premium": {
      "num_requests": number,
      "total_requests": number,
      "num_tokens": number,
      "max_requests": number,
      "max_tokens": number
    },
    "standard": {
      "num_requests": number,
      "total_requests": number,
      "num_tokens": number,
      "max_requests": number,
      "max_tokens": number
    },
    "start_of_month": string
  },
  "user": {
    "email": string,
    "name": string,
    "id": string,
    "updated_at": string
  },
  "stripe": {
    "membership_type": "free" | "free_trial" | "pro" | "enterprise",
    "payment_id": string,
    "days_remaining_on_trial": number
  }
}

如果发生错误，响应格式为:

{
  "error": string
}

获取更新令牌（已弃用）

• 接口地址: /token-upgrade
• 请求方法: POST
• 认证方式: 请求体中包含token
• 请求格式:

{
  "token": string
}

• 响应格式:

{
  "status": "success" | "failure" | "error",
  "message": string,
  "result": string // optional
}

基础校准（已弃用）

• 接口地址: /basic-calibration
• 请求方法: POST
• 认证方式: 请求体中包含token
• 请求格式:

{
  "token": string
}

• 响应格式:

{
  "status": "success" | "error",
  "message": string,
  "user_id": string,
  "create_at": string
}

注意: user_id 和 create_at 字段在校验失败时可能不存在。

Copilot++ 接口文档

1. 相关接口都需要 x-client-key, 格式请见 /gen-hash（32字节）。
2. Cookie FilesyncCookie 是16字节，工作区不变即不变。
3. 关于形如 AWSALBAPP-0 的 Cookie 具有7天有效期，可能变化，详情请查阅 Amazon 相关文档。
4. FilesyncCookie 和 AWSALBAPP 总是被 /file/upload 或 /file/sync。
5. 以下所有接口都使用 POST 方法，且都需要认证。

获取代码补全服务的配置信息

• 接口地址: /cpp/config

请求格式

{
  "is_nightly": boolean,  // 可选，是否使用nightly版本
  "model": string,        // 模型名称
  "supports_cpt": boolean // 可选，是否支持CPT
}

响应格式

{
  "above_radius": number,                                        // 可选，上方扫描半径
  "below_radius": number,                                        // 可选，下方扫描半径
  "merge_behavior": {                                            // 可选，合并行为
    "type": string,
    "limit": number,                                             // 可选，限制
    "radius": number                                             // 可选，半径
  },
  "is_on": boolean,                                              // 可选，是否开启
  "is_ghost_text": boolean,                                      // 可选，是否使用幽灵文本
  "should_let_user_enable_cpp_even_if_not_pro": boolean,         // 可选，非专业用户是否可以启用
  "heuristics": [                                                // 启用的启发式规则列表
    "lots_of_added_text",
    "duplicating_line_after_suggestion",
    "duplicating_multiple_lines_after_suggestion",
    "reverting_user_change",
    "output_extends_beyond_range_and_is_repeated",
    "suggesting_recently_rejected_edit"
  ],
  "exclude_recently_viewed_files_patterns": [string],            // 最近查看文件排除模式
  "enable_rvf_tracking": boolean,                                // 是否启用RVF跟踪
  "global_debounce_duration_millis": number,                     // 全局去抖动时间(毫秒)
  "client_debounce_duration_millis": number,                     // 客户端去抖动时间(毫秒)
  "cpp_url": string,                                             // CPP服务URL
  "use_whitespace_diff_history": boolean,                        // 是否使用空白差异历史
  "import_prediction_config": {                                  // 导入预测配置
    "is_disabled_by_backend": boolean,                           // 是否被后端禁用
    "should_turn_on_automatically": boolean,                     // 是否自动开启
    "python_enabled": boolean                                    // Python是否启用
  },
  "enable_filesync_debounce_skipping": boolean,                  // 是否启用文件同步去抖动跳过
  "check_filesync_hash_percent": number,                         // 文件同步哈希检查百分比
  "geo_cpp_backend_url": string,                                 // 地理位置CPP后端URL
  "recently_rejected_edit_thresholds": {                         // 可选，最近拒绝编辑阈值
    "hard_reject_threshold": number,                             // 硬拒绝阈值
    "soft_reject_threshold": number                              // 软拒绝阈值
  },
  "is_fused_cursor_prediction_model": boolean,                   // 是否使用融合光标预测模型
  "include_unchanged_lines": boolean,                            // 是否包含未更改行
  "should_fetch_rvf_text": boolean,                              // 是否获取RVF文本
  "max_number_of_cleared_suggestions_since_last_accept": number, // 可选，上次接受后清除建议的最大数量
  "suggestion_hint_config": {                                    // 可选，建议提示配置
    "important_lsp_extensions": [string],                        // 重要的LSP扩展
    "enabled_for_path_extensions": [string]                      // 启用的路径扩展
  }
}

获取可用的代码补全模型列表

• 接口地址: /cpp/models

请求格式

无

响应格式

{
  "models": [string],     // 可用模型列表
  "default_model": string // 可选，默认模型
}

上传文件

• 接口地址: /file/upload

请求格式

{
  "uuid": string,                    // 文件标识符
  "relative_workspace_path": string, // 文件相对于工作区的路径
  "contents": string,                // 文件内容
  "model_version": number,           // 模型版本
  "sha256_hash": string              // 可选，文件的SHA256哈希值
}

响应格式

{
  "error": string // 错误类型：unspecified, non_existant, hash_mismatch
}

同步文件变更

• 接口地址: /file/sync

请求格式

{
  "uuid": string,                                // 文件标识符
  "relative_workspace_path": string,             // 文件相对于工作区的路径
  "model_version": number,                       // 模型版本
  "filesync_updates": [                          // 文件同步更新数组
    {
      "model_version": number,                   // 模型版本
      "relative_workspace_path": string,         // 文件相对于工作区的路径
      "updates": [                               // 单个更新请求数组
        {
          "start_position": number,              // 更新开始位置
          "end_position": number,                // 更新结束位置
          "change_length": number,               // 变更长度
          "replaced_string": string,             // 替换的字符串
          "range": {                             // 简单范围
            "start_line_number": number,         // 开始行号
            "start_column": number,              // 开始列
            "end_line_number_inclusive": number, // 结束行号（包含）
            "end_column": number                 // 结束列
          }
        }
      ],
      "expected_file_length": number             // 预期文件长度
    }
  ],
  "sha256_hash": string                          // 文件的SHA256哈希值
}

响应格式

{
  "error": string // 错误类型：unspecified, non_existant, hash_mismatch
}

流式代码补全

• 接口地址: /cpp/stream

请求格式

{
  "current_file": {                                               // 当前文件信息
    "relative_workspace_path": string,                            // 文件相对于工作区的路径
    "contents": string,                                           // 文件内容
    "rely_on_filesync": boolean,                                  // 是否依赖文件同步
    "sha256_hash": string,                                        // 可选，SHA256哈希值
    "top_chunks": [                                               // 顶级代码块
      {
        "content": string,                                        // 内容
        "range": {                                                // 最简单范围
          "start_line": number,                                   // 开始行
          "end_line_inclusive": number                            // 结束行（包含）
        },
        "score": number,                                          // 分数
        "relative_path": string                                   // 相对路径
      }
    ],
    "contents_start_at_line": number,                             // 内容开始行
    "cursor_position": {                                          // 光标位置
      "line": number,                                             // 行号
      "column": number                                            // 列号
    },
    "dataframes": [                                               // 数据框信息
      {
        "name": string,                                           // 名称
        "shape": string,                                          // 形状
        "data_dimensionality": number,                            // 数据维度
        "columns": [                                              // 列
          {
            "key": string,                                        // 键
            "type": string                                        // 类型
          }
        ],
        "row_count": number,                                      // 行数
        "index_column": string                                    // 索引列
      }
    ],
    "total_number_of_lines": number,                              // 总行数
    "language_id": string,                                        // 语言ID
    "selection": {                                                // 选择范围
      "start_position": {                                         // 开始位置
        "line": number,                                           // 行号
        "column": number                                          // 列号
      },
      "end_position": {                                           // 结束位置
        "line": number,                                           // 行号
        "column": number                                          // 列号
      }
    },
    "alternative_version_id": number,                             // 可选，替代版本ID
    "diagnostics": [                                              // 诊断信息
      {
        "message": string,                                        // 消息
        "range": {                                                // 范围
          "start_position": {                                     // 开始位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          },
          "end_position": {                                       // 结束位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          }
        },
        "severity": "error" | "warning" | "information" | "hint", // 严重程度
        "related_information": [                                  // 相关信息
          {
            "message": string,                                    // 消息
            "range": {                                            // 范围
              "start_position": {                                 // 开始位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              },
              "end_position": {                                   // 结束位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              }
            }
          }
        ]
      }
    ],
    "file_version": number,                                       // 可选，文件版本
    "cell_start_lines": [number],                                 // 单元格开始行
    "workspace_root_path": string                                 // 工作区根路径
  },
  "diff_history": [string],                                       // 差异历史
  "model_name": string,                                           // 可选，模型名称
  "linter_errors": {                                              // 可选，Linter错误
    "relative_workspace_path": string,                            // 文件相对于工作区的路径
    "errors": [                                                   // 错误数组
      {
        "message": string,                                        // 错误消息
        "range": {                                                // 范围
          "start_position": {                                     // 开始位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          },
          "end_position": {                                       // 结束位置
            "line": number,                                       // 行号
            "column": number                                      // 列号
          }
        },
        "source": string,                                         // 可选，来源
        "related_information": [                                  // 相关信息数组
          {
            "message": string,                                    // 相关信息消息
            "range": {                                            // 相关信息范围
              "start_position": {                                 // 开始位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              },
              "end_position": {                                   // 结束位置
                "line": number,                                   // 行号
                "column": number                                  // 列号
              }
            }
          }
        ],
        "severity": "error" | "warning" | "information" | "hint"  // 可选，严重程度
      }
    ],
    "file_contents": string                                       // 文件内容
  },
  "context_items": [                                              // 上下文项
    {
      "contents": string,                                         // 内容
      "symbol": string,                                           // 可选，符号
      "relative_workspace_path": string,                          // 相对工作区路径
      "score": number                                             // 分数
    }
  ],
  "diff_history_keys": [string],                                  // 差异历史键
  "give_debug_output": boolean,                                   // 可选，提供调试输出
  "file_diff_histories": [                                        // 文件差异历史
    {
      "file_name": string,                                        // 文件名
      "diff_history": [string],                                   // 差异历史
      "diff_history_timestamps": [number]                         // 差异历史时间戳
    }
  ],
  "merged_diff_histories": [                                      // 合并差异历史
    {
      "file_name": string,                                        // 文件名
      "diff_history": [string],                                   // 差异历史
      "diff_history_timestamps": [number]                         // 差异历史时间戳
    }
  ],
  "block_diff_patches": [                                         // 块差异补丁
    {
      "start_model_window": {                                     // 开始模型窗口
        "lines": [string],                                        // 行
        "start_line_number": number,                              // 开始行号
        "end_line_number": number                                 // 结束行号
      },
      "changes": [                                                // 变更
        {
          "text": string,                                         // 文本
          "range": {                                              // 范围
            "start_line_number": number,                          // 开始行号
            "start_column": number,                               // 开始列
            "end_line_number": number,                            // 结束行号
            "end_column": number                                  // 结束列
          }
        }
      ],
      "relative_path": string,                                    // 相对路径
      "model_uuid": string,                                       // 模型UUID
      "start_from_change_index": number                           // 开始变更索引
    }
  ],
  "is_nightly": boolean,                                          // 可选，是否为nightly版本
  "is_debug": boolean,                                            // 可选，是否为调试模式
  "immediately_ack": boolean,                                     // 可选，立即确认
  "enable_more_context": boolean,                                 // 可选，启用更多上下文
  "parameter_hints": [                                            // 参数提示
    {
      "label": string,                                            // 标签
      "documentation": string                                     // 可选，文档
    }
  ],
  "lsp_contexts": [                                               // LSP上下文
    {
      "uri": string,                                              // URI
      "symbol_name": string,                                      // 符号名称
      "positions": [                                              // 位置
        {
          "line": number,                                         // 行
          "character": number                                     // 字符
        }
      ],
      "context_items": [                                          // 上下文项
        {
          "uri": string,                                          // 可选，URI
          "type": string,                                         // 类型
          "content": string,                                      // 内容
          "range": {                                              // 可选，范围
            "start_line": number,                                 // 开始行
            "start_character": number,                            // 开始字符
            "end_line": number,                                   // 结束行
            "end_character": number                               // 结束字符
          }
        }
      ],
      "score": number                                             // 分数
    }
  ],
  "cpp_intent_info": {                                            // 可选，代码补全意图信息
    "source": string                                              // 来源
  },
  "workspace_id": string,                                         // 可选，工作区ID
  "additional_files": [                                           // 附加文件
    {
      "relative_workspace_path": string,                          // 相对工作区路径
      "is_open": boolean,                                         // 是否打开
      "visible_range_content": [string],                          // 可见范围内容
      "last_viewed_at": number,                                   // 可选，最后查看时间
      "start_line_number_one_indexed": [number],                  // 从1开始索引的起始行号
      "visible_ranges": [                                         // 可见范围
        {
          "start_line_number": number,                            // 开始行号
          "end_line_number_inclusive": number                     // 结束行号（包含）
        }
      ]
    }
  ],
  "control_token": "quiet" | "loud" | "op",                       // 可选，控制标记
  "client_time": number,                                          // 可选，客户端时间
  "filesync_updates": [                                           // 文件同步更新
    {
      "model_version": number,                                    // 模型版本
      "relative_workspace_path": string,                          // 相对工作区路径
      "updates": [                                                // 更新数组
        {
          "start_position": number,                               // 开始位置（字符偏移量）
          "end_position": number,                                 // 结束位置（字符偏移量）
          "change_length": number,                                // 变更长度
          "replaced_string": string,                              // 替换的字符串
          "range": {                                              // 范围
            "start_line_number": number,                          // 开始行号
            "start_column": number,                               // 开始列
            "end_line_number_inclusive": number,                  // 结束行号（包含）
            "end_column": number                                  // 结束列
          }
        }
      ],
      "expected_file_length": number                              // 预期文件长度
    }
  ],
  "time_since_request_start": number,                             // 请求开始后的时间
  "time_at_request_send": number,                                 // 请求发送时的时间
  "client_timezone_offset": number,                               // 可选，客户端时区偏移
  "lsp_suggested_items": {                                        // 可选，LSP建议项
    "suggestions": [                                              // 建议
      {
        "label": string                                           // 标签
      }
    ]
  },
  "supports_cpt": boolean                                         // 可选，是否支持CPT
}

响应格式 (SSE流格式)

事件类型及对应数据格式：

1. model_info

{
  "type": "model_info",
  "is_fused_cursor_prediction_model": boolean,
  "is_multidiff_model": boolean
}

2. range_replace

{
  "type": "range_replace",
  "start_line_number": number,
  "end_line_number_inclusive": number,
  "text": string
}

3. cursor_prediction

{
  "type": "cursor_prediction",
  "relative_path": string,
  "line_number_one_indexed": number,
  "expected_content": string,
  "should_retrigger_cpp": boolean
}

4. text

{
  "type": "text",
  "text": string
}

5. done_edit

{
  "type": "done_edit"
}

6. done_stream

{
  "type": "done_stream"
}

7. debug

{
  "type": "debug",
  "model_input": string,
  "model_output": string,
  "total_time": string,   // 可选
  "stream_time": string,
  "ttft_time": string,
  "server_timing": string // 可选
}

8. error

{
  "type": "error",
  "message": string
}

9. stream_end

{
  "type": "stream_end"
}

来源可选值

• line_change
• typing
• option_hold
• linter_errors
• parameter_hints
• cursor_prediction
• manual_trigger
• editor_change
• lsp_suggestions

鸣谢

感谢以下项目和贡献者:

• cursor-api - 本项目本身
• zhx47/cursor-api - 提供了本项目起步阶段的主要参考
• luolazyandlazy/cursorToApi