Cursor SDK 的最新功能、改进和修复，涵盖 npm 上的 @cursor/sdk 和 PyPI 上的 cursor-sdk。
1.0.27¶
- 限制智能体的工具集。
tools可将模型可用的内置工具限定在允许列表中 ([]表示仅文本) ，disallowedTools则会移除指定工具，同时保留其余工具。两者都接受"read"等公开名称，以及"shell"和"mcp"等能力组；TypeScript 中使用tools、disallowedTools，Python 中使用tools、disallowed_tools。目前仅支持本地智能体，且不会在resume后保留。 - 在 TypeScript 中通过浏览器登录。
Cursor.auth.login()会打开浏览器登录流程、生成 API 密钥，并将其存储在~/.cursor/sdk/auth.json中；Cursor.auth.status()和Cursor.auth.logout()则提供其余相关功能。登录后，Agent.create()和Cursor.*的读取操作无需apiKey或CURSOR_API_KEY。 - 本地智能体的用量和成本。 TypeScript 中的
agent.getUsage()和 Python 中的agent.get_usage()现也支持本地智能体，并返回按轮次细分的数据。传入先前结果中的runId可将范围缩小到单个轮次。 - 以 Cursor GitHub App 身份创建 PR。 TypeScript 中的
cloud.openAsCursorGithubApp和 Python 中的open_as_cursor_github_app用于控制 PR 的作者身份。服务账户密钥默认使用该 App 身份；用户密钥默认使用密钥所有者身份。 - 多根本地工作区。 传入
local.dirs可从多个文件夹加载规则、技能和项目上下文；cwd仍是唯一的主工作目录。这替代了cwd的数组形式，后者始终只使用第一项。 - 更清晰的 Python 错误。 先前仅显示为“内部错误”的失败现在会包含底层消息和代码。
- 管理员命令拒绝列表适用于本地运行。 与团队管理员拒绝列表匹配的 shell 命令会在执行前被策略消息拒绝，包括会跳过批准提示的路径。
1.0.26¶
- 首次发送前预热本地工作区。
platform.prewarmLocalWorkspace(options)会预先解析规则、技能、MCP 服务器和忽略文件，因此首次对该工作区调用send()时可立即开始。它会返回一个可在关闭时调用的 release 函数。 - 控制工作区扫描的缓存时长。
configureCursorSdk({ local: { workspaceScanCacheTtlMs } })可设置工作区扫描的缓存时长，CURSOR_RIPWALK_CACHE_TTL_MS环境变量可为托管部署设置相同的值。长期运行且使用稳定 checkout 的服务器现在可跳过重复扫描。 - 自定义工具无需批准提示即可运行。 通过
customTools传入的主机定义工具，在沙盒化或 Auto-review 模式的本地运行中不再因交互式批准错误而失败。拒绝规则和沙盒限额仍然适用。 - 已签名的 macOS 二进制文件。
@cursor/sdk的 macOS 平台包现在提供经过代码签名的二进制文件，因此不再被 Gatekeeper 和端点安全工具拦截。 - 更清晰的 Python 异常层级。
PermissionDeniedError、BadRequestError和InternalServerError现在直接继承自CursorSDKError，而非AuthenticationError、ConfigurationError和NetworkError，因此except块会捕获名称所对应的异常。 - 修复 Python 中偶发的启动失败。 大约每 64 次智能体启动中就有 1 次会在首次发送前失败。现在启动已更加可靠。
1.0.25¶
- 按需获取已计费用量和费用。 TypeScript 中的
agent.getUsage()和 Python 中的agent.get_usage()可返回云端代理的 token 用量、已计费用及按每次运行划分的明细，Agent.getUsage(agentId)无需 handle 即可使用。费用由服务器计算，包含折扣，并会在运行结束后不久结算。目前仅支持云端；本地运行会抛出带类型的配置错误。
1.0.24¶
- TypeScript 和 Python 现已同步发布。 从 1.0.24 起，npm 上的
@cursor/sdk与 PyPI 上的cursor-sdk均从同一版本发布，并使用相同的版本号。Python 版本不再落后于 TypeScript。 - 长时间运行的流更可靠。 高负载运行中的流式响应不再会在中途断开；此前，这在长轮次中会表现为 Python 客户端的网络错误。
1.0.23¶
- Cloud 运行中每次发送的环境变量。 传入
send(prompt, { cloud: { envVars } })可将环境变量限定于单次运行，包括创建智能体时的首次发送。Agent.create({ cloud: { envVars } })仍会设置智能体级别的默认值。 - 失败运行的错误详情。 失败的本地和 Cloud 运行现在会提供包含
message和code字段的结构化错误，无需解析日志即可了解具体问题。run.wait()的行为保持不变。 - Python 中的 token 用量。 运行流会发出包含每轮 token 计数的类型化
usage消息，累积总量可通过run.usage和RunResult.usage获取，与 1.0.22 的 TypeScript 保持一致。 - 更可靠的本地运行历史记录。 磁盘上的运行历史记录现在可在写入中断后保持完整，修复了进程崩溃后导致运行无法恢复的一类问题。
- 修复 Bun 中的流式传输停滞问题。 Bun 下的运行流在长响应时不再停滞。
1.0.22¶
- 每次运行的 Token 用量。 本地运行会通过
run.stream()为每轮发出usage事件，并通过run.wait()返回累计总量。云端运行也会在其流和wait()结果中提供相同的用量；对于已分离的本地句柄，累计总量会持久保存，因此重新连接的进程仍可获取这些数据。
1.0.21¶
- 支持在 Bun 下运行智能体。
agent.send()现可在 Bun 下运行，行为与 Node 中一致。此更新还修复了新安装的 Node 可能缺少必需依赖的问题。 - Python 中更易用的运行时名称。 List API 和
get_run现支持runtime="cloud"、"local"和"auto"，与文档中列出的值一致。
1.0.20¶
- SDK 现已可在 Bun 中正常导入。 在 Bun 中导入
@cursor/sdk不再会崩溃。Bun 中运行智能体将于 1.0.21 支持。
