Cursor¶

Cursor V2 通过官方的 @cursor/sdk TypeScript 包运行。它不使用 Cursor 的 ACP 传输来进行 V2 执行。

前提条件¶

• Node.js 22.13 或更新版本。本仓库支持的 Node 版本已满足此要求。
• 在 Settings > Providers > Cursor 中登录 Cursor，或在 CURSOR_API_KEY 中提供 Cursor API 密钥。
• 用于浏览器登录或 CURSOR_API_KEY 的账户需要拥有付费 Cursor 套餐。
• 被 Cursor SDK 接受的模型。auto 会作为其 default 模型选择发送给 SDK。

该适配器目前使用 SDK 的本地智能体运行时，因此运行操作会在所选的 T3 Code 工作区中执行。Cursor 云端智能体需要 T3 Code 尚未暴露的仓库和云环境配置。

自定义 Cursor MCP 服务器和插件不会在 T3 Code 中配置。当智能体打开时，它们会从环境机器上的 Cursor 配置中加载：项目 .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 登录后，请使用 Restart agent session。

登录¶

选择 Sign in，然后在浏览器中打开登录页面并完成登录。登录完成后，T3 Code 会自动更新。在连接到远程环境时也同样有效。在移动设备上，对于已配置的 Cursor 实例，请使用 Settings > Providers。

每个提供程序实例都会在运行它的环境上保留自己的登录状态。你的 Cursor 编辑器和 CLI 登录是分开的。已配置的 CURSOR_API_KEY 会覆盖浏览器登录；要使用浏览器流程，请移除该覆盖。

在同一个设置部分使用 Change account 或 Sign out。两者都会停止该实例正在运行的线程并保留其历史记录。退出登录会忘记已保存的凭据；要在生成的密钥过期前撤销它，请从你的 Cursor 控制台的 API 密钥中移除该密钥。

V2 能力映射¶

该适配器支持：

• 创建和恢复本地 Cursor 智能体线程；
• 在回合之间更改模型和模型参数；
• 助手文本、推理、工具活动、计划和待办事项的流式传输；
• 线程范围的 T3 Code MCP 工具，以及来自磁盘的周边 Cursor MCP/插件；
• 图片附件；
• 中断、排队应用消息，以及由编排器拥有的中断/重启控制；
• 通过 Agent.messages.list() 获取提供程序对话快照；
• Cursor task 子智能体，作为只读子应用线程呈现，包含其工具活动和最终结果。

公共 SDK 目前不暴露原生的智能体分叉、对话回滚、主动控制或交互式审批回调。直接主动控制被声明为不受支持，而 V2 控制则使用编排器的中断并重启路径，并在提供程序回合之间保留应用运行标识。同提供程序的 Cursor 分叉使用编排器的便携式全线程上下文交接，进入新的 Cursor 智能体。SDK 具有进程内自定义回调工具，但 V2 适配器有意使用经过认证的、线程范围的 MCP 服务器。

便携式交接会汇总符合条件的时间线条目，并可能省略长消息的结尾。在将分叉用于必须完整保留确切指令的工作之前，请阅读便携式交接中的上下文。

Cursor 任务事件包含 agentId，但本地 SDK 不会将该标识符注册为可恢复智能体：Agent.resume() 会返回 AgentNotFoundError。因此，适配器不会将提供程序线程附加到原生任务投影，也不会公布子智能体线程 ID。投影出的子线程是只读的：请从父线程发送消息。

运行时模式映射到本地 SDK 公开的控制：完全访问会禁用其沙箱，而受限模式通常会启用沙箱。在 Windows 上，当启用了 Cursor Auto-review 时，Auto 和 Supervised 会在没有文件系统隔离的情况下运行，因为 SDK 在那里不支持文件系统沙箱。没有 Auto-review 的受限模式（包括默认的 Auto-accept edits 模式）仍然会请求沙箱，且无法在 Windows 上启动。显式沙箱策略仍然具有权威性，包括 Windows SDK 拒绝的受限策略。显式审批策略会覆盖对 Auto-review 的控制，而 Auto-review 并未表示为交互式 T3 Code 审批流程。

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

重放和实时测试¶

Cursor 重放夹具保留了 SDK 边界：智能体打开/恢复、发送、有序的 onDelta 更新、终端结果、取消、消息快照和关闭。真实的 V2 适配器、编排器、事件存储、投影和检查点逻辑仍会在测试中运行。

使用以下命令针对真实 SDK 录制夹具：

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

使用 --out <path> 可录制临时探针，而不会替换已签入的夹具。当提供无效场景时，录制器会列出受支持的场景。