使用 Cursor SDK 构建程序化智能体

我们推出了 Cursor SDK,让您可以使用驱动 Cursor 的同一套 runtime、harness 和模型来构建智能体。

现在只需几行 TypeScript 代码,您就能调用在 Cursor 桌面应用、CLI 和 Web 应用中运行的智能体。您既可以在自己的机器上运行,也可以在 Cursor 云端基于专用 VM 运行,并使用任何前沿模型。

运行 npm install @cursor/sdk 即可开始使用。您也可以使用 Cursor 原生的 /sdk 技能,帮助您开始构建。

import { Agent } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

const run = await agent.send("Summarize what this repository does");

for await (const event of run.stream()) {
  console.log(event);
}

我们构建了几个示例项目,您可以从一个公开 仓库 访问。您可以 fork 并在此基础上扩展,以适配自己的使用场景。

Cursor SDK 现已面向所有用户开放公开 Beta,并按照标准的 token 用量计费。请在我们的 公告文档 中了解更多信息。

  • API 已围绕持久化智能体和按提示划分的运行进行重构,因此后续消息、状态、流式传输和取消操作现在都以运行为范围。
  • 新增了一流的运行流式传输支持,包含 SSE 事件、通过 Last-Event-ID 进行重连,以及更清晰的终止状态。
  • 新增了明确的智能体生命周期控制,包括归档、取消归档和永久删除。
  • 统一了 v1 的响应和错误结构,包括结构化错误代码、items 列表响应,以及独立的 agent / run 对象。

多任务处理、工作树和多根工作区

此次发布带来了全新的多任务处理方式:通过异步子智能体同时处理多个任务;还改进了工作树体验,并新增了多根工作区,便于跨仓库进行修改。

在智能体窗口中进行多任务处理

使用 /multitask 时,Cursor 会运行异步子智能体来并行处理您的请求,而不是将其加入队列。它还会将较大的任务拆分成更小的部分,交由一组异步子智能体同时攻克。

如果队列中已经有消息,您也可以让 Cursor 对这些消息执行多任务处理,而无需等待当前运行结束。

智能体窗口中的 工作树

我们已在智能体窗口中新增全新改进的 工作树

您可以在不同分支间于后台运行隔离任务。准备好测试更改时,只需一键即可将任意分支移到本地前台。

智能体窗口中的多根工作区

单个智能体会话现在可以将目标设为由多个文件夹组成的可复用工作区。

这样,Cursor 就能跨仓库修改前端、后端和共享库,而无需在智能体每次切换仓库时都重新指定目标。

画布

Cursor 现在可以通过创建交互式画布来回答问题。

这些可视化内容可以包括使用表格、框体、图示和图表等内置组件构建的仪表盘和自定义界面,也可以包含 Cursor 现有的组件,例如差异视图和待办事项列表。

智能体窗口 中,画布是可持久保留的产物,位于侧边栏中,与终端、浏览器和版本控制并列显示。

Cursor 3.1 的智能体窗口或编辑器中试用。更多信息请参阅我们的公告

CLI 调试模式与 /btw 支持

我们为 Cursor CLI 带来了一些体验优化,让你在终端中使用智能体更加顺手。

CLI 中的调试模式

使用 /debug 定位根因,并修复那些难以复现或难以理解的棘手缺陷。在 调试模式 中,Cursor 会提出假设、添加日志语句,并利用运行时信息在进行针对性修复前精准定位问题。

CLI 中的 /btw 支持

您可以快速追问一个旁支问题,而不会打断智能体的主要任务。/btw 让您无需停止当前运行,即可就 Cursor 正在进行的更改获取说明。

CLI 中的配置菜单

/config 会在 CLI 中打开一个交互式设置面板,您可以在其中查看和更改各项行为设置,例如模型选择、默认设置、运行时偏好等。

您也可以使用 /update-cli-config 技能,让 Cursor 为您应用配置更改。

CLI 中的自定义状态栏

使用 /statusline 自定义状态栏,显示您关心的会话和运行时信号,包括当前模式、分支、环境、活动任务提示或其他会话元数据。

  • 您现在可以从任意位置调出模型选择器来切换模型,无需先清空提示。
  • 如果 Cursor 检测到您已连续三次启用自动运行,现在会主动建议您开启它,以避免陷入没完没了的审批循环。
  • AskQuestion 工具和调试模式现在可以更顺畅地处理纯文本回复。
  • 现已支持从剪贴板粘贴图片,包括在一些原生不支持粘贴的终端中使用 Ctrl+V
  • 页脚现在会显示您的工作目录、工作树和当前分支。

  • 您现在可以使用 Ctrl+Z 稳定地将 CLI 挂到后台运行。
  • 自动运行现已可在调试模式和规划模式等其他模式中使用。
  • 修复了退出 CLI 后后台 shell 进程可能仍会继续运行的问题。
  • 修复了斜杠命令的处理和匹配问题。
  • 修复了 Cmd+Delete、Vim 快捷键以及 Ctrl 修饰键组合的键盘处理问题。

智能体窗口中的平铺布局与升级版语音输入

作为 Cursor 3 的一部分,此次发布对智能体窗口界面进行了多项改进。

平铺布局

将当前视图拆分为多个窗格,以并行运行和管理多个智能体。平铺布局让您无需在各个选项卡之间来回切换,也能更轻松地同时处理多项任务并比较不同智能体的输出。

您可以展开窗格以专注于某个对话,将智能体拖入各个平铺区域,并使用快捷键快速导航和整理。您的设置也会在不同会话之间保留。

升级版语音输入

语音输入听写现在更可靠、更准确。它会录下您的整段语音,并通过批量 STT 进行转写,从而获得更高质量的语音转文本效果。

您可以按住 Ctrl+M 开始说话,录音时我们还在 UI 中新增了波形、计时器,以及取消和确认按钮等控件。

空白状态下的分支选择

此前,从空白状态启动智能体时,通常默认使用您当前所在的分支。现在,您可以先搜索并选择一个分支,然后直接在该分支上启动云端智能体。

这样可以减少切换分支的额外步骤,并降低在错误分支上误运行的概率。

从 diff 跳转到文件

从 diff 直接跳到文件中的对应行。到达后,您即可充分利用编辑器的全部功能:手动修改、使用 Tab、转到定义等。

搜索文件的筛选器

在“Search in Files”中使用 include/exclude 筛选器,可将代码搜索范围限定到特定文件集合。

  • 语音输入处理期间,提示按钮现在会保持原位。
  • Plan 选项卡现在具备与文件相同的文档行为:支持可靠加载、脏状态跟踪、在 Plan 变更时重新加载,以及保存、复制和导出 markdown。
  • 新建智能体会话现在默认会在您偏好的项目目标中启动。
  • 文件选项卡名称现在会在当前智能体可见的选项卡范围内解析,而不再尝试在所有其他智能体的选项卡中保持全局唯一。
  • Cmd-K 现在显示更少但更相关的智能体结果,并限制为最近的匹配结果集 (即与您的查询匹配,且来自最近范围内的条目) 。
  • 在 macOS 上,文本现已采用抗锯齿渲染,字符边缘更清晰。
  • Design Mode 现在支持使用键盘在元素树中上下及横向导航,以便在评论前选中相应的 UI 元素。
  • 智能体窗口现在会避免执行非必要的高开销更新和获取操作。
  • 关闭选项卡时现在更不容易导致文件树异常,恢复速度也更快。
  • 现在会限制本地 diff 获取,以减少 SCM 视图中的 CPU/网络峰值和卡顿。
  • 文件树现在能更可靠地响应变更,也更不容易闪烁、显示过时内容或漏掉更新。
  • 扩展事件 (例如文件变更、诊断更新) 现在会限定在各自的工作区内,从而减少跨项目干扰。
  • 在长聊天中按回车发送后续消息,以前可能会卡住一秒多;现在几乎是即时的。
  • 将掉帧时间缩短约 87% 后,大型编辑现在的流式显示更加顺畅。

  • 修复了一个在滚动浏览长对话时会卡顿的缺陷。现在即使在线程很长时也依然流畅。
  • 修复了一个在智能体对话中包含大量 diff 或代码块时会闪烁并卡死的缺陷。