昨晚，Cursor 官方账号发了一条推文，直接宣布 Cursor SDK 开放使用。一句话总结：以前你只能在 Cursor 这个 IDE 里用 Composer，现在可以把它当成一个 npm 包，装到你自己的 Node.js 项目里。

npm install @cursor/sdk

cursor/cookbook 这个新开的官方仓库，几个小时就拿到了 1.1k Star。对 Node.js 和 TypeScript 开发者来说，这是 2026 年到目前为止比较值得关注的一次发布，因为它把"AI 编程"这个能力，从一个独立的桌面工具，变成了你 package.json 里的一行依赖。

下面把这次发布拆开聊一下：它到底放出来了什么，能用来干什么，以及现在上手大概是什么手感。

这次到底放出来了什么

官方一次性放了三样东西：

第一，@cursor/sdk 这个 npm 包，TypeScript 原生，可以在 Node.js 进程里直接 import { Agent } from "@cursor/sdk"。

第二，文档站 cursor.com/docs/sdk/typescript，里面写清楚了 Agent 的生命周期、流式事件、MCP 接入、错误类型这些细节。

第三，开源 Cookbook 仓库 github.com/cursor/cookbook，里面塞了四个起手项目：一个 Quickstart、一个 Coding Agent CLI、一个 Web 端原型工具（app-builder）、一个 Agent 驱动的看板（agent-kanban）。这四个项目都是 TypeScript 写的，可以直接 clone 下来改。

发布的同时，官方还公布了几个早期客户：Rippling、Notion、C3 AI、Faire。这几家用 SDK 做的事情各不相同，有的拿来跑后台 Agent，有的把它接到 Bug 处理流程里，从工单一路拉到可合并的 PR，还有的把它接进 CI/CD，让 Agent 自己维护 codebase 的健康度。

定价上也没绕弯子，沿用现有的 token 计费规则，跑在 SDK 上的用量会进团队的统一 dashboard，带一个 SDK 标签做区分。

一段最小可跑的代码

官方文档里给的 Hello World 长这样：

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 repository");
for await (const event of run.stream()) {
  console.log(event);
}

几个细节值得拎出来说一下。

Agent.create 是入口，决定了这个 Agent 要在哪里跑。传 local: { cwd } 就是本地模式，Agent 直接在你当前的 Node 进程里读写文件；传 cloud 配置就是云端模式，Cursor 会在自己的隔离 VM 里克隆仓库、跑 Agent、推 PR。同一套 API，本地和云端只差一个字段。

model.id 这一行直接选模型。现在能用的有 Composer 2、Claude 系列、GPT 系列。如果你想拿 thinking 模式跑，可以这样写：

model: { id: "composer-2", params: [{ id: "thinking", value: "high" }] }

具体哪些模型 ID 可用、每个模型支持什么参数，可以通过 Cursor.models.list() 拿到，返回值是和你账号绑定的，所以不需要手动维护一份模型列表。

run.stream() 是异步迭代器，吐出来的 event 是带 discriminated union 的 SDKMessage，包含 system、user、assistant、thinking、tool_call、status、task、request 这几种类型。如果你不想自己 switch case，可以直接 await run.wait()，一次性拿到最终结果、token 用量和 git 元数据。

如果只是临时跑一个 prompt 不打算复用 Agent 实例，还有一个更短的写法：

const result = await Agent.prompt("Your question", options);

整体 API 设计上能看出 Cursor 是认真做了 TypeScript 工程化的。资源管理用了 await using 这个 ES2024 特性，让 Agent 在作用域结束时自动清理：

await using agent = await Agent.create({ /* ... */ });
// 块结束时自动清理

这不是套壳 Python SDK 翻译过来的，是按 Node.js 的写法重新设计的。

Local 和 Cloud 是同一套架构

Cursor 在公告里贴了一张架构图，把整个 SDK 的能力栈画得很清楚：

最下面是 Models 层，Composer、Claude、GPT、Other 并列。中间是 Harness 层，里面是 Agent Loop 和 MCP/Tools。上面分两条路：Managed Cloud 模式比 Local Workstation 多一层 Sandbox。

这张图的关键点是：Local 和 Cloud 用的是同一个 Harness。也就是说你在本地调通的 Agent 逻辑，挪到云端不需要改业务代码，只改 Agent.create 里的运行时配置就行。

在云端模式下，Cursor 给每个 Agent 分配独立的 VM，自动克隆仓库、跑完整的 dev 环境初始化，可以创建分支、推 PR、附带产物。即使中间网络断了 Agent 也能继续跑，跑完再把结果同步回来。这是最贴近"后台 Agent"使用场景的部分，CI/CD 流水线里用得上。

本地模式则适合两类场景：一是你在写脚本或者临时跑一些自动化任务，不想为每次执行起一个云端 VM；二是你的代码本身就敏感，不能离开本地环境。本地模式下 Agent 直接在你的 Node 进程里执行，文件读写、命令执行都在本地，相当于把 Cursor 的 Composer Agent 当成一个可编程的子进程来用。

需要注意的是，本地模式拿不到产物下载（downloadArtifact），这个能力是云端独有的。

配置体系是它真正的护城河

如果只看 Agent.create 这种基础 API，你可能会觉得"这不就是把 Cursor 的 Agent 包了一层 SDK"。但翻完文档以后会发现，真正复杂的部分在配置体系上。

MCP 服务器支持五个来源，按优先级合并：send() 内联定义、create() 内联定义、Cursor 插件、项目级 .cursor/mcp.json、用户级 ~/.cursor/mcp.json。值得提的是，send() 内联定义不是合并而是替换，写的时候要注意。云端 Agent 还能直接复用你在 cursor.com 上授权过的 OAuth token，省掉一次重新授权。

Skills 自动从 .cursor/skills/ 目录加载，Hooks 通过 .cursor/hooks.json 配置，Subagents 可以用 agents 字段嵌套定义。也就是说你在 Cursor IDE 里已经配置好的 Skills 和 Hooks，SDK Agent 能直接复用，不需要再搬一遍。

这一套东西堆在一起的意思是：Cursor 不是给你一个调用 LLM 的封装，而是把整个 Agent 运行时（包括上下文管理、工具调用、子任务委派、钩子）都打包出来了。如果你之前自己用 LangChain 之类的框架手写过 Agent，会知道把这些东西做完整有多少坑。

错误处理这块也做得比较细，所有异常继承自 CursorAgentError，带 isRetryable 布尔属性。具体类型分成 AuthenticationError、RateLimitError、ConfigurationError、NetworkError、UnknownAgentError。在调用某个操作前，可以用 run.supports(operation) 先检查兼容性，避免调到不支持的能力。

四个 Cookbook 项目分别能干什么

cursor/cookbook 这个仓库的定位是"build on top"，每个项目都是可以直接 clone 然后用 Cursor 改的。我快速过了一下：

Quickstart：最小的 Node.js 例子，演示怎么创建 Agent、怎么消费流式事件。代码非常短，用来对照着看 SDK 行为最方便。

Coding Agent CLI：终端交互式 Agent，类似 Claude Code 那种用法。但因为是开源的，你可以直接改 prompt、改默认模型、加自己团队的工具。如果你想给团队做一个内部 CLI，这个是最好的起点。

Prototyping Tool（app-builder）：一个 Web 应用，用来在云端 sandbox 里启动 Agent，专门做项目原型迭代。可以理解为一个简化版的 v0 / Bolt，但跑在 Cursor 自己的 Cloud Agent 上。

Agent Kanban：可视化看板，把 Cloud Agent 当成卡片管理，按状态、按仓库分组，能预览产物、直接创建新的 Cloud Agent。这个项目的设计思路挺有意思，把"派发 Agent"做成了一个团队协作产品，不是单人工具。

四个项目主要语言是 TypeScript（95.3%），CSS 和 JavaScript 占很少。对 Node.js 开发者来说，这几个项目本身就是不错的工程范例，看一遍就大致清楚社区怎么落地这个 SDK。

哪些场景值得现在就上？

结合官方公告和早期客户案例，目前看比较成熟的几个方向：

第一是 CI/CD 集成。在 PR 检查里挂一个 Agent，让它自动总结改动、定位 CI 失败的根因，甚至直接推一个修复 commit。这是 Faire 和一部分客户的主要用法，自我修复 codebase 的思路是这个意思。

第二是工单到 PR 的自动化。把 Bug 工单系统接进 SDK，工单创建后自动启动一个 Cloud Agent，让它读懂上下文、定位代码、写补丁、提 PR。Notion 和 Rippling 都在做类似的事。

第三是把 Agent 嵌进自有产品。Cursor 在博客里专门提了一句："有些客户把 Cursor 直接嵌进了面向终端用户的产品里"。也就是说，你的 SaaS 产品里那个"AI 助手"按钮，背后跑的可能就是一个 Cursor Agent。这种用法对 To B 产品来说是个新选项，省掉了自己搭 Agent 基建的成本。

第四是给非技术团队做 No-code Agent 平台。前端套一个表单或者拖拽界面，后端用 SDK 启动 Agent 帮 GTM、运营这些团队跑数据。这块从 LangChain 时代就有人做，但 Cursor SDK 的优势是它带完整的代码理解能力，能动你的产品代码，不只是查数据。

---

放到整个 AI 编程生态里看，Cursor 这次发布并不孤立。Anthropic 有 Claude Agent SDK，OpenAI 有 Agents SDK，Google 也在推自己的 Agent 框架。Cursor 进这个池子的差异点是：它不是把模型 API 包一层，而是把整个"在你代码上跑 Agent"的运行时商品化了。

代码理解、上下文索引、MCP 工具生态、Sandbox 隔离、PR 自动化，这些东西每一项单独做都不算难，难的是把它们整合到一个 SDK 里、做到生产可用、还要让本地和云端用同一套抽象。从文档的成熟度看，Cursor 在这块明显憋了很久。

但要不要现在就把 Cursor SDK 接进你的关键流程，还要看几个现实问题：你愿不愿意把代码绑定在 Cursor 这一家供应商上、token 成本能不能控制住、Composer 2 和你现在用的模型相比 ROI 怎么样。SDK 解决的是"能不能用"，"值不值得用"得自己跑一遍 benchmark。

对 Node.js 和 TypeScript 开发者来说，最务实的态度可能是：先 npm install @cursor/sdk 把 Quickstart 跑通，把 cookbook 那四个项目翻一遍，心里有个底。等下次你的项目里要做"自动总结 PR"、"自动写测试用例"、"接工单系统"这种 Agent 类需求的时候，至少多一个不用从零造轮子的选项。

Cursor 把工具钉在了 package.json 这一行上，剩下就看社区的反馈了。