Cursor

Cursor V2 经由官方 @cursor/sdk TypeScript 包运行。V2 的执行不使用 Cursor 的 ACP 传输。

前提条件

• Node.js 22.13 或更新版本。本仓库所支持的 Node 版本满足这一要求。
• 在「设置 > 提供方（provider）> Cursor」中用 Cursor 登录，或在 CURSOR_API_KEY 中提供 Cursor API 密钥。
• 用于浏览器登录或 CURSOR_API_KEY 的账户，需要付费的 Cursor 计划。
• Cursor SDK 所接受的模型。auto 会作为其 default 模型选择发送给 SDK。

适配器（adapter）目前使用 SDK 的本地智能体运行时，因此这些运行都在所选的 T3 Code 工作区中进行。Cursor 云端智能体需要仓库和云环境方面的配置，而 T3 Code 尚未暴露这些配置。

自定义的 Cursor MCP 服务器和插件并不在 T3 Code 中配置。智能体打开时，它们从环境（environment）所在机器上的 Cursor 配置加载：项目（project）的 .cursor/mcp.json、用户的 ~/.cursor/mcp.json，以及 ~/.cursor/plugins 下已安装的插件。插件工具可以在没有登录时出现；OAuth MCP 服务器仍然需要凭据。将 cwd 设为 T3 的项目根目录后运行 agent mcp login <server>（令牌会写入 ~/.cursor/projects/<folder-slug>/mcp-auth.json）。Cursor 桌面应用的 Connections 身份验证不会写入该文件，本地 SDK 自己也无法完成交互式 MCP OAuth——身份验证尝试会失败，消息类似 “MCP authentication is not supported in local SDK runs”，或者提示身份验证服务器不支持动态客户端注册。在添加或更改技能、插件或 MCP 服务器之后，或者在 CLI 登录成功之后，请使用 重启智能体会话。

登录

选择 登录，然后打开登录页面，并在浏览器中完成。登录结束后，T3 Code 会自动更新。连接到远程环境时也同样适用。在移动端，对于已经配置好的 Cursor 实例，请使用「设置 > 提供方」。

每个提供方实例都在运行它的那份环境上保留自己的登录。你的 Cursor 编辑器登录和 CLI 登录是分开的。一旦配置了 CURSOR_API_KEY，就会覆盖浏览器登录；去掉这一覆盖，才能使用浏览器流程。

在同一处设置中使用 更换账户 或 退出登录。两者都会停止该实例正在运行的对话线程（thread），并保留它们的历史。退出登录会忘掉已保存的凭据；若要在生成的密钥过期之前撤销它，请到 Cursor 仪表板的 API 密钥中将其删除。

V2 能力映射

适配器支持：

• 创建并恢复本地的 Cursor 智能体对话线程；
• 在回合（turn）之间更改模型以及模型参数；
• 助手文本、推理、工具活动、计划与待办的流式传输；
• 限定在对话线程内的 T3 Code MCP 工具，以及磁盘上随环境存在的 Cursor MCP 与插件；
• 图片附件；
• 中断、排队的应用消息，以及由编排器（orchestrator）掌握的中断/重启引导；
• 通过 Agent.messages.list() 获得的提供方对话快照；
• Cursor 的 task 子智能体，它们被投影为只读的子应用对话线程，并带有各自的工具活动与最终结果。

公共 SDK 目前并不暴露原生的智能体分叉、对话回滚、主动引导或交互式审批回调。直接的主动引导被标明为不受支持；V2 的引导使用编排器的中断并重启路径，并在各个提供方回合之间保留应用的运行身份。同一提供方下的 Cursor 分叉，会使用编排器的可移植完整对话线程上下文交接，进入一个全新的 Cursor 智能体。SDK 具备进程内的自定义回调工具，但 V2 适配器有意改为使用经过身份验证、且限定在对话线程内的 MCP 服务器。

可移植交接会概括符合条件的时间线条目，并且可能省略长消息的末尾。若这次分叉所承接的工作要求精确指令必须原样延续，请先阅读可移植交接中的上下文。

Cursor 的任务事件（event）里包含一个 agentId，但本地 SDK 并不会把该标识符注册为可恢复的智能体：Agent.resume() 会返回 AgentNotFoundError。因此适配器不会把提供方对话线程挂到原生任务投影上，也不会对外给出子智能体的对话线程 ID。投影出的子线程是只读的：请从父对话线程发送消息。

运行时模式会映射到本地 SDK 所暴露的控制项：完全访问会禁用它的沙箱，受限模式通常会启用沙箱。在 Windows 上，当 Cursor Auto-review 开启时，Auto 与 Supervised 会在没有文件系统隔离的情况下运行，因为 SDK 在该平台不支持文件系统沙箱。未开启 Auto-review 的受限模式，包括默认的 Auto-accept edits 模式，仍然会请求沙箱，并且无法在 Windows 上启动。显式的沙箱策略仍然具有决定权，包括那些会被 Windows SDK 拒绝的限制性策略。显式的审批策略覆盖项控制着 Auto-review，而它并不会表现为 T3 Code 中的交互式审批流程。

现有的 Cursor 二进制路径和 API 端点设置属于 CLI/ACP 集成。Cursor V2 的执行不会启动那个二进制文件，SDK 也不提供 API 端点覆盖。

回放与实时测试

Cursor 的回放夹具守住 SDK 这一边界：智能体的打开与恢复、发送、有序的 onDelta 更新、终端结果、取消、消息快照以及关闭。真正的 V2 适配器、编排器、事件存储、投影以及检查点（checkpoint）逻辑，在测试中仍然会实际运行。

对照真实 SDK 录制夹具：

pnpm --filter t3 record:cursor-replay --scenario simple

使用 --out <path> 可以录制一次临时探测，而不会替换已签入的夹具。当传入的场景无效时，录制器会列出所支持的场景。