Cursor 官方 SDK 上手指南：用 TypeScript 脚本调度 AI 编程 Agent

这东西是什么

Cursor 在 4 月底悄悄放出了 @cursor/sdk，一个 TypeScript 包。装上之后，你可以在自己的 Node.js 脚本里创建 Cursor Agent，发指令让它改代码、跑任务，结果以流式事件返回。

说白了：以前 Cursor 的 AI 能力只能在它的编辑器里用，现在可以从任何 TypeScript 程序里调。

官方还放了一个 cookbook 仓库（github.com/cursor/cookbook），5 天收了将近 3000 星。里面有五个示例项目：快速上手、原型构建器、看板、CLI、DAG 任务编排。我把这几个跑了一遍，下面是实测记录。

先装好环境

需要 Node.js 18+ 和一个 Cursor API Key。

拿 Key 的步骤：打开 cursor.com/dashboard/integrations，登录后点 Create API Key，复制保存。

# 创建项目
mkdir cursor-sdk-demo && cd cursor-sdk-demo
npm init -y
npm install @cursor/sdk typescript tsx

在终端设好环境变量：

export CURSOR_API_KEY="你的key"

最小可运行示例：10 行代码跑起来

新建 demo.ts：

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("列出当前目录的文件结构，用树状图表示");

for await (const event of run.stream()) {
  if (event.type === "text") {
    process.stdout.write(event.text);
  }
}

agent.close();

跑一下：

npx tsx demo.ts

Agent 会扫描当前目录，把文件树打印出来。整个过程走流式输出，打字机效果。

三种运行模式

SDK 支持三种 runtime，用 Agent.create() 的参数切换：

本地模式 — Agent 跑在你的 Node 进程里，直接读写磁盘文件。适合写脚本、跑 CI 检查。

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

云端模式（Cursor 托管） — Agent 跑在 Cursor 的隔离 VM 里，自动 clone 你的仓库。适合批量跑多个 Agent、或者调用方没有代码仓库的场景。

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: {
    repos: [{ 
      url: "https://github.com/your-org/your-repo", 
      startingRef: "main" 
    }],
    autoCreatePR: true,
  },
});

云端模式（自托管） — 同样的 API，但 VM 跑在你自己的机器上。代码和密钥不离开你的环境。

本地模式不需要额外配置，云端模式需要指定仓库地址。autoCreatePR: true 会让 Agent 改完代码后自动开 PR——这个功能在批量修 bug 的时候很好用。

实战：写一个代码审查脚本

下面这个脚本拿到 Git diff，丢给 Cursor Agent 做 code review：

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

async function reviewCode() {
  const diff = execSync("git diff HEAD~1").toString();

  if (!diff.trim()) {
    console.log("没有新的改动");
    return;
  }

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

  const prompt = `下面是最近一次 commit 的 diff，帮我做 code review。
指出潜在的 bug、性能问题和可读性问题。不用夸，直接说问题。

${diff}`;

  const run = await agent.send(prompt);

  let result = "";
  for await (const event of run.stream()) {
    if (event.type === "text") {
      result += event.text;
      process.stdout.write(event.text);
    }
  }

  agent.close();
}

reviewCode();

这里用了 model.params 设置 thinking 为 high，让 Agent 多想一会儿再回答。实测下来，审查结果比默认模式细致不少，会指出边界条件和并发问题。

实战：DAG 任务编排

cookbook 里最有意思的是 DAG task runner。把一个大任务拆成多个子任务，定义依赖关系，然后并行分发给多个 Agent 执行。

原理不复杂：

1. 你定义一个 JSON 格式的任务 DAG（有向无环图）
2. 脚本解析 DAG，找出没有前置依赖的任务
3. 每个任务启动一个独立的 Agent 执行
4. 任务完成后，检查哪些后续任务的依赖已满足，继续启动

interface Task {
  id: string;
  prompt: string;
  deps: string[];  // 依赖的任务 ID
}

const tasks: Task[] = [
  { id: "api",    prompt: "创建 REST API 路由文件，包含 /users 和 /posts 端点", deps: [] },
  { id: "db",     prompt: "创建数据库 schema，定义 users 和 posts 表",         deps: [] },
  { id: "tests",  prompt: "为 API 路由写单元测试",                              deps: ["api", "db"] },
  { id: "docs",   prompt: "根据 API 路由生成 OpenAPI 文档",                     deps: ["api"] },
];

api 和 db 没有依赖，会并行执行。tests 等 api 和 db 都完成后才开始。docs 只等 api。

跑起来后，四个任务可能只需要两轮就能全部完成，比串行快一倍。

踩坑记录

1. API Key 权限

SDK 支持两种 Key：个人 Key 和 Service Account Key。Team Admin Key 目前不支持。如果你在 CI 里用，建议创建 Service Account。

2. 云端 Agent 的环境变量

如果 Agent 需要访问第三方 API（比如数据库连接串），用 cloud.envVars 传进去，不要硬编码：

cloud: {
  repos: [{ url: "https://github.com/org/repo" }],
  envVars: {
    DATABASE_URL: process.env.DATABASE_URL!,
  },
}

这些变量加密存储，Agent 销毁后自动删除。变量名不能以 CURSOR_ 开头。

3. 流式事件的类型

run.stream() 返回的是 SDKMessage 联合类型，常用的几种：

• text — Agent 的文本输出
• tool_call — Agent 调用了工具（读文件、写文件、跑命令等）
• tool_result — 工具执行的结果
• error — 出错了

只想拿文本的话，过滤 event.type === "text" 就行。

4. 费用

SDK 调用的计费和 Cursor IDE 里用 Agent 一样，走你账号的请求池。在 cursor.com/dashboard/usage 能看到，会标注 SDK 来源。跑批量任务前先确认额度够。

5. 一次性调用的简写

如果只发一条指令、不需要多轮对话，用 Agent.prompt() 更简洁：

const result = await Agent.prompt({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
  message: "把所有 console.log 替换成 logger.info",
});

一行搞定创建、执行、销毁。

和 Codex CLI、Claude Code 的区别

这三个工具都能通过命令行调用 AI 写代码，但定位不同：

Cursor SDK 的核心是"可编程"。它不是给你一个终端 UI 让你打字聊天，而是给你一套 API 让你用代码控制 Agent。这意味着你可以把它嵌到 CI pipeline 里、写成定时任务、或者做成 Web 应用。

Codex CLI 更偏向交互式终端工具，适合个人在终端里快速改代码。Claude Code 也类似，但多了 --print 模式支持非交互调用。

如果你的需求是"自动化"——批量处理多个仓库、定时跑代码审查、构建一个内部的 AI 编程平台——Cursor SDK 目前是最合适的选择。

值得试的几个方向

1. CI 集成：在 GitHub Actions 里跑 code review，PR 提交后自动审查
2. 批量重构：同一个改动需要应用到 20 个微服务仓库，用云端 Agent 并行处理
3. 内部工具：搭一个 Web 界面，产品经理输入需求，后台 Agent 生成原型代码
4. 教学平台：学生提交代码后，Agent 自动给出反馈和改进建议

SDK 目前是 public beta，API 可能会变。但核心概念（Agent、Run、Stream）大概率会保留。

小结

@cursor/sdk 把 Cursor 的 AI 编程能力变成了一个可调用的 API。装包、拿 Key、写几行 TypeScript 就能跑起来。对于想在自己的工具链里集成 AI 编程能力的开发者来说，值得花一个下午试试。

仓库地址：github.com/cursor/cookbook 文档：cursor.com/docs/sdk/typescript