Cursor SDK 的自定义商店、自定义工具与自动审查

Custom stores, custom tools, and auto-review for the Cursor SDK

二〇二六年六月六日 · 英文原文

摘要

Cursor 在 TypeScript 和 Python SDK 中发布新功能，支持 agent 和 run 元数据的 JSONL 或自定义存储、通过函数定义暴露自定义工具、自动审查路由本地工具调用，以及嵌套任意深度的子 agent。可靠性改进包括运行关联 requestId、可靠 wait()、安全检查点释放和 HTTP/1.1 云端流式传输。性能优化包括更轻量导入、自包含 TypeScript 类型和捆绑 ripgrep。Composer 2 自动路由到 Composer 2.5。Python SDK 0.1.6 修复工作区范围 list_runs 和未找到错误。

我们在 TypeScript 和 Python SDK 中发布了一批新功能。现在你可以选择 agent 和 run 元数据的持久化方式，将自己的函数作为工具暴露给 agent，通过自动审查路由本地工具调用，以及嵌套任意深度的子 agent。本次发布还带来了一系列可靠性、性能和平台修复，使得本地和云端 SDK agent 更容易在生产脚本、CI 和自定义集成中运行。

自定义工具
现在你可以通过 Agent.create() 或每次 send() 时传入 local.customTools 中的函数定义，将你自己的工具交给本地 agent。SDK 通过一个名为 custom-user-tools 的内置 MCP 服务器将这些工具暴露给 agent，因此模型通过与其他 MCP 工具相同的路径和权限门来调用你的代码。在此之前，暴露自定义能力需要你自己搭建一个 stdio 或远程 HTTP MCP 服务器，并将其接入 agent。现在只需一个函数定义即可。自定义工具对父 agent 的所有子 agent 也可见，因此你定义一次的工具在整个运行过程中都可使用。

自动审查
默认情况下，本地 SDK agent 执行工具调用时无需请求批准，因为在无头运行中没有人类参与。设置 local.autoReview 即可将这些调用路由到自动审查。一个分类器决定哪些调用自动执行，哪些需要暂缓，而不是完全绕过审查。你可以通过 permissions.json 中的自然语言指令来控制该分类器。autoRun.allow_instructions 字段描述倾向于允许的调用形式，autoRun.block_instructions 描述需要暂缓审查的调用。例如，你可以允许对构建产物的只读检查，但始终暂停删除等破坏性操作。

{
  "autoRun": {
    "allow_instructions": [
      "对 ./dist 下构建产物的只读检查是可以的。"
    ],
    "block_instructions": [
      "始终暂停删除操作，以便我有机会审查它们。"
    ]
  }
}

JSONL 和自定义存储
两个 SDK 都会持久化 agent 和 run 元数据，以便在进程重启后恢复 agent。此前，该存储是 SQLite。现在你可以选择使用 JSONL 存储，它会写入一个纯文本、仅追加的文件，你可以读取、比较差异并纳入版本控制。SqliteLocalAgentStore 和 JsonlLocalAgentStore 都直接导出。如果默认存储都不适合你的环境，可以实现公共接口 LocalAgentStore，并通过 local.store 传入。为临时 CI 运行构建内存存储，或者当你希望 agent 状态与应用数据共存时，使用 Postgres 作为后端。Python SDK 通过桥接暴露了 host、JSONL 和组合 JSONL 存储。

嵌套子 agent
子 agent 现在可以生成自己的子 agent，以此类推。一个审查子 agent 可以委托给测试编写者，后者可以进一步委托，每一层都保持自己的 prompt 和模型。无需额外开启；子 agent 会话会注册执行 Task 所需的执行器，因此对于任何定义了子 agent 的 agent，嵌套会自动生效。

可靠性、性能和平台改进
本次发布还包括两个 SDK 的一系列质量改进。

可靠性

运行关联：每次 send() 现在都携带一个平台生成的 requestId，暴露在 Run 和 RunResult 上，并在内存、SQLite 和 JSONL 存储中持久化。无需从 agentId 推断，即可将脚本或 CI 运行与后端日志、分析和支持线程关联起来。
本地运行的可靠 wait()：本地运行在终端结果写入之前不再解析 wait()。Hydration 会持续刷新，直到运行达到最终状态，因此自动化读取的是完整结果。
释放时的安全检查点：当根引用缺失但检查点 blob 仍然存在时，释放本地 agent 不再移除检查点数据。只有当确实没有需要保留的内容时，agent 目录才会被清除。
通过 HTTP/1.1 的云端流式传输：云端 agent 会话现在可以在某些代理、旧版 Node fetch 栈以及某些 CI 镜像使用的 HTTP/1.1 传输上正确流式传输。HTTP/2 行为不变。

性能和打包

更轻量的导入：导入 @cursor/sdk 不再立即加载完整的本地 agent 栈。仅使用云端和仅使用类型的消费者在首次本地调用之前跳过本地运行时开销，API 无变化。首次本地调用会进行一次一次性导入，之后保持缓存。
自包含的 TypeScript 类型：发布的 .d.ts 文件不再引用未发布的工作区包。这修复了 skipLibCheck: false 下的 TS2305 和 TS2307 错误，以及 TurnEndedUpdate 等流类型上的隐式 any。
捆绑的 ripgrep：本地 shell 运行使用捆绑的平台 rg 二进制文件，无需修改全局 PATH。在 Windows 上，前置 ripgrep 不再覆盖 Path 变量。

模型

Composer 2 路由到 Composer 2.5：仍固定使用已退役的 composer-2 slug 的 SDK 客户端会自动路由到 Composer 2.5，保持快速变体不变，因此旧脚本仍可运行。

Python SDK

工作区范围的 list_runs：Client、AsyncClient 和 Agent.list_runs 接受可选的 cwd，桥接会回退到其启动工作区。这修复了当桥接作为子进程运行时出现的虚假“agent not found”结果。
更清晰的未找到错误：查找不在已解析工作区中的 agent 会返回清晰的未找到错误，而不是模糊的内部错误。
0.1.6 发布和分析：cursor-sdk 0.1.6 记录了 Buildkite 发布路径，并将 SDK 使用标记为 sdk-python-，以便更清晰地进行分析。

运行 npm install @cursor/sdk 或 pip install cursor-sdk 进行升级。固定使用 composer-2 的脚本会自动迁移到 Composer 2.5，requestId 是对 run 元数据模式的安全补充。有关完整详情，请参阅 TypeScript 和 Python 文档。

译自 Cursor · changelog · 录于二〇二六年六月六日