今天 Cursor 推了一条消息，标题是 Cursor SDK: Custom Agents。推送文案里有几句很关键：可以从 CI/CD pipeline 里直接调用 agents，可以做自己的自动化，也可以把 Cursor 嵌到自己的产品里；SDK 用的是 Cursor 已经优化过的基础设施和 agent harness；Composer 2 通过 SDK 使用到 5 月 6 日前有 50% off。

我去读了官方的 TypeScript SDK 文档、发布公告、changelog、hooks 文档，以及官方示例仓库 cursor/cookbook。看上去很有意思，这件事可不简单的是“Cursor 多了一个 npm 包”而已。

如果说过去 Cursor 的核心入口是 IDE 里的交互式 Agent，那么 SDK 把同一套 agent 能力变成了一个可被代码调用的工程组件。它不再只是只能在编辑器里跟你交互，而是可以出现在 CI、内部平台、工单系统、看板、监控告警和业务产品里。

一句话理解：把 Cursor Agent 变成可编排的后台能力

官方文档里最小的例子很短：

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);
}

这段代码看起来只是“从 Node.js 调了一次 Cursor”。但真正有意思的是它背后的抽象：

• Agent 是一个持久化容器，保留对话状态、工作区配置和设置。
• Run 是一次提示词提交，有自己的状态、流、结果、取消控制和 git 元数据。
• SDKMessage 是标准化事件流，能拿到 assistant 文本、thinking、tool call、status 等事件。

也就是说，你可以像调一个后台任务系统一样调 Cursor Agent：创建、发送任务、订阅流、等待结果、取消、恢复、列出历史、下载 artifacts。这个抽象一旦稳定下来，就可以接进很多以前只能靠人工操作的流程。

它不是另一个 Chat API

很多人第一眼会把它理解成“Cursor 也出了一个 OpenAI SDK”。我觉得这会误读重点。

普通 Chat API 通常只负责模型输入输出。Cursor SDK 要暴露的是 coding agent runtime：它知道仓库、文件、终端、语义搜索、MCP、hooks、skills、subagents、artifacts，以及云端运行时里的分支和 PR。

官方公告里把这套能力称为 Cursor 的 harness：代码库索引、语义搜索、grep、MCP、skills、hooks、subagents 都能被 agents 使用。换句话说，SDK 的卖点不是“你可以发 prompt”，而是“你可以用代码启动一个和 Cursor IDE / CLI / Web App 同源的工程 agent”。

这也是为什么它的用法会天然偏工程自动化，而不是偏聊天机器人。

三种运行时：本地、Cursor Cloud、自托管

SDK 通过 Agent.create() 的参数选择运行时。传 local 就在本地 Node 进程里跑；传 cloud 就在 Cursor 托管的隔离 VM 里跑；如果团队有自托管用量池，也可以用类似 Cloud Agents 的形态把执行留在自己的环境里。

本地运行适合开发脚本和 CI 检查。比如仓库已经 checkout 到 runner 上，你只想让 agent 读当前工作树、分析失败日志、给出建议，或者跑一段轻量修改，本地模式就够了。

Cloud 运行适合更像“后台派工”的场景。调用方不一定有完整仓库，任务可能耗时较长，也可能要并行启动多个 agents。Cursor Cloud 会给每个 agent 一个隔离 VM，克隆仓库，任务可以在你断网或电脑睡眠后继续跑，结束后还能打开 PR、推分支或产出截图等 artifacts。

自托管池的意义则更偏企业：如果代码、凭据、构建产物不能离开自己的网络，仍然可以保留类似 Cloud Agent 的执行模型。这对金融、政企、医疗、硬件等行业很重要，因为真正卡住 AI 编程落地的往往不是模型能力，而是代码和环境能不能出门。

官方现在给了哪些积木

从文档和示例仓库看，Cursor 这次不是只发了 SDK API，还给了几块能直接参考的积木。

第一块是 @cursor/sdk。安装方式就是：

npm install @cursor/sdk

认证使用 CURSOR_API_KEY，可以从 Cursor Dashboard 的 Integrations 里创建用户 API key，也可以使用团队的 service account API key。文档里明确说目前不支持 team admin API key。SDK 用量会进入团队用量仪表盘，并标记为 SDK。

第二块是 Cloud Agents API v1。changelog 里提到 v1 把 API 拆成持久化 agent 和每次 prompt 对应的 run，状态、流式输出、取消和 follow-up 都变成 run 级别。REST API 还支持 SSE 流、Last-Event-ID 重连、archive / unarchive / delete，以及更标准的响应和错误结构。

第三块是 hooks。hooks 是放在 .cursor/hooks.json 里的项目策略边界，可以在 agent loop 的多个阶段运行脚本或 prompt-based 检查。比如 beforeShellExecution 拦截危险命令，afterFileEdit 自动格式化，beforeMCPExecution 审计外部工具调用，beforeSubmitPrompt 检查 prompt，stop 做结束处理。官方文档说 hooks 同时支持 Agent 和 Tab，只是事件类型不同；Cloud Agents 也会运行仓库里的 hooks，企业版还会跑团队和企业托管 hooks。

第四块是 MCP、skills 和 subagents。SDK 里可以内联传 mcpServers，也可以让本地 agent 读取项目或用户的 .cursor/mcp.json。子智能体既可以通过 agents 参数内联定义，也可以读取仓库里的 .cursor/agents/*.md。这意味着你可以把“代码审查员”“测试作者”“迁移专家”这样的角色固化下来，让主 agent 在合适的时候派发子任务。

第五块是官方 cookbook。目前里面有四个 SDK 示例：Quickstart、Prototyping tool、Kanban board、Coding agent CLI。Quickstart 只是本地 agent 的最小例子；Kanban board 更有意思，它把 Cloud Agents 看板化，按状态或仓库分组，能预览 artifacts，也能从仓库和 prompt 创建新的 cloud agent。

能拿来做什么

最直接的用途是把 Cursor 接进 CI/CD。比如测试失败后，不只是发一封“CI failed”的通知，而是让 agent 读失败日志、读 PR diff、定位可能的根因、提出最小修复，并在满足条件时推一个分支或创建 PR。这个方向很容易想象，也最符合 SDK 的发布文案。

第二类是内部研发平台。很多公司都有工单、需求看板、发布系统、质量看板、知识库和告警平台。以前这些系统最多把链接甩给开发者，现在可以在某些动作后直接启动 agent：拖动一张看板卡片，后台创建一个 Cloud Agent；告警里出现重复错误，agent 先查最近变更和日志；需求进入“技术评审”，agent 先扫一遍影响面和缺失测试。

第三类是产品内嵌。官方公告里提到，有客户把 Cursor 直接嵌到面向客户的产品里，让最终用户不离开宿主应用也能获得 agent 体验。这件事要谨慎，但方向很清楚：如果你的产品本身有“项目、配置、脚本、数据管道、集成代码”这些可操作对象，SDK 可以让 agent 成为产品功能的一部分，而不是另开一个聊天窗口。

第四类是长期维护任务。比如每周自动检查依赖升级、找 flaky tests、扫 TODO、同步文档、补 changelog、迁移过时 API、做小范围安全修复。过去这类活要么没人做，要么靠脚本只能做机械部分。Agent 的价值在于它能读上下文、做判断、写解释，最后把结果交给人审。

第五类是批量探索。Cloud runtime 支持更适合并行的工作方式。你可以对多个仓库、多个模块、多个备选方案启动 agents，让它们各自输出结果，再由人或另一个汇总 agent 归纳。这个方向有点像“研发组织里的小型自动化劳动力池”。

一个实用例子：CI 失败后让 agent 准备一个可审查修复

我认为第一版不要做成“CI 失败自动改完直接合并”。那太激进，也容易把责任边界搞乱。

更稳的版本是：CI 失败后，启动一个 agent，让它只做三件事：定位原因、尝试最小修复、把验证结果和改动说明交给人审。能推分支就推分支，不能推就发评论。人仍然是最终合并者。

一个简化的脚本大概长这样：

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

const prUrl = process.env.PR_URL!;
const repoUrl = process.env.REPO_URL!;
const failingJobUrl = process.env.FAILING_JOB_URL!;

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  name: `ci-fix: ${prUrl}`,
  model: { id: "composer-2" },
  cloud: {
    repos: [{ url: repoUrl, prUrl }],
    autoCreatePR: false,
  },
});

const run = await agent.send(`
You are helping with a failing pull request.

PR: ${prUrl}
Failing CI job: ${failingJobUrl}

Please:
1. Inspect the failing checks and the PR diff.
2. Identify the smallest likely root cause.
3. If the fix is low risk, apply it on the PR branch.
4. Run the focused test or lint command.
5. Return a concise summary with files changed, commands run, and remaining risk.

Do not make broad refactors. Do not touch unrelated files.
`);

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

  if (event.type === "tool_call") {
    console.log(`[tool] ${event.name}: ${event.status}`);
  }
}

const result = await run.wait();
console.log(result.status);
console.log(result.git?.branches?.[0]?.prUrl);

真正接进 GitHub Actions 时，还要补几件事。

首先是权限。CURSOR_API_KEY 应该用 service account 或专门的低权限 key，GitHub token 也要最小化。能只评论就不要给写权限；需要推分支时，也尽量只允许写当前 PR 分支。

其次是触发条件。不要所有失败都启动 agent。比如只对 lint、unit test、typecheck、文档构建这类可局部修复的问题开启；部署失败、权限失败、生产环境操作失败，先只让 agent 做诊断，不让它改代码。

再次是 hooks。可以在仓库里放 .cursor/hooks.json，对 shell 和文件编辑做限制。比如禁止 rm -rf、禁止改 .env、禁止触碰迁移文件以外的生产配置，或者在 afterFileEdit 后自动跑 formatter。hooks 不是单次 prompt 的装饰，而是项目级策略边界，这点很关键。

最后是审计。SDK 会流出 tool call、status、assistant 文本，Cloud Agents API 也有 run、agent、artifacts 这些对象。把这些记录保存下来，至少要能回答：它为什么被触发、看了什么、改了什么、跑了什么、谁最后批准。

hooks 是这件事能不能进生产的关键

官方推送标题里写的是 Custom Agents，但我觉得真正适合和 SDK 一起看的，是 hooks。

没有 hooks 的 agent 自动化很容易变成“给一个很长的 prompt，祈祷它听话”。这在本地试验可以，在组织级流程里不够。生产里需要的是明确边界：哪些命令不能跑，哪些文件不能改，哪些外部 MCP 调用要审计，哪些输出必须附带验证证据。

Cursor hooks 的模型比较工程化。命令型 hook 通过 stdin 收 JSON，通过 stdout 返回 JSON；退出码 2 可以阻断动作，其他失败默认 fail-open。Prompt-based hook 则可以用一个快模型判断自然语言条件，例如“这个命令是否只读”。这两种方式可以混用：明确规则用脚本，不好写死的策略用 prompt。

这意味着一个团队可以把自己的 Cursor 使用规范变成仓库资产。人打开 Cursor IDE 时生效，SDK 启动 Cloud Agent 时也生效。对比只靠口头约定，这才像能进团队流程的东西。

现在不适合拿它做什么

SDK 目前还是 public beta。官方文档也写得很直白：正式发布前 API 可能变化。所以不建议一上来就把关键生产链路绑死在某个具体事件结构或内部 tool payload 上。

还有一个小坑：tool_call 事件的外层结构相对稳定，但工具调用里的 args 和 result 负载并不稳定，文档明确建议把它们当作 unknown 防御式解析。也就是说，别写那种强依赖某个内部 shell 输出 JSON 结构的业务逻辑。

本地运行时目前也不支持下载 artifacts，listArtifacts() 会返回空列表，downloadArtifact() 会抛错。需要产物、截图、演示文件的场景，应该优先考虑 cloud runtime。

内联 mcpServers 在 Agent.resume() 后不会保留。这个设计是合理的，因为它们经常带机密信息，但工程上要记得恢复 agent 时重新传入，或者改用文件配置。

另外，文档写明 hooks 只支持文件配置，没有“每次 SDK 调用临时传一个 hook 回调”的编程接口。这反而是个好事：hooks 是仓库或组织策略，不应该被某个调用方轻易绕过。

对 Cursor 的意义：它正在从 IDE 往 agent 平台挪

我之前写 Cursor 和 Claude Code 的对比时，一直强调一个判断：AI 编程的重心正在从“编辑器里补代码”转向“代理跑流程”。这次 SDK 发布，基本就是 Cursor 对这个趋势的正面回应。

如果 Cursor 只停留在 IDE 里，它会一直被拿来和 Claude Code、Codex、Copilot 做入口之争。谁的模型强，谁的 CLI 顺，谁的 IDE 补全快，用户就会来回摇摆。

但 SDK 把问题换了一个层次：Cursor 不只是一个人机交互界面，而是一个可以被组织调用的 agent runtime。IDE、CLI、Web App、Cloud Agents、SDK、MCP、hooks、skills、subagents 组合起来，Cursor 想卖的不只是“一个好用编辑器”，而是“把代码任务交给 agent 的基础设施”。

这也解释了为什么官方文案会强调 CI/CD、自定义自动化、嵌入产品、production quickly，而不是只强调“模型更强”。模型当然重要，Composer 2 的折扣也会刺激大家试用，但真正长期的价值在于：当 agent 能被程序调用、被 hooks 约束、被平台记录、被 PR 流程接住，它才有机会从个人效率工具变成组织生产系统的一部分。

我会怎么开始试

如果你想动手，我建议不要先做“大而全的自动程序员”。从一个窄任务开始：

• 本地脚本：对当前仓库生成一份架构摘要，或者找出最近 PR 里缺失的测试。
• CI 辅助：只在 typecheck 或 lint 失败时启动 agent，输出诊断和建议，不自动改代码。
• PR 评论：让 agent 读取 diff，总结风险点和建议补测点，然后把评论发回 PR。
• 依赖维护：每周启动一次 agent，尝试升级一个小依赖，并附上测试结果。
• 文档同步：代码变更后检查对应 README、API 文档或 changelog 是否需要更新。

等这些低风险场景跑顺，再考虑让 agent 推分支、开 PR、下载 artifacts 或接入内部平台。不要一开始就把“自动合并”当目标。真正有价值的自动化，往往是先把人最烦的 70% 准备工作做好，而不是抢最后那个批准按钮。

结尾

Cursor SDK 这次发布，最值得注意的不是几行 TypeScript，而是 Cursor 把自己的 agent 能力从产品界面里拿出来，交给开发者和团队编排。

它让 Cursor 进入了一个新的比较维度：不是“我在 IDE 里能不能聊得更舒服”，而是“我能不能把 agent 安全地接进真实工程流程”。这件事一旦跑通，CI、看板、告警、内部平台、产品内嵌都会变成入口。

当然，它还在 public beta，API 会变，成本要算，权限和 hooks 要认真设计。但方向已经很清楚：AI 编程工具正在从“开发者打开一个窗口”变成“系统在合适时机召唤一个 agent”。Cursor SDK 就是 Cursor 给这个方向递出来的一把钥匙。

---

参考

• Cursor TypeScript SDK 文档
• Cursor 发布公告：Build programmatic agents with the Cursor SDK
• Cursor changelog：SDK release
• Cursor Hooks 文档
• Cloud Agents API v1
• 官方示例仓库 cursor/cookbook