SuperAPI AI 工具集

cursor-sdk

编程与开发

查看项目

更新于 11-19 03:05

技能介绍

用途

Cursor SDK(包名 @cursor/sdk)是 Cursor 提供的 TypeScript SDK,用于以编程方式运行 Cursor 智能体。同一套接口可驱动两种运行时:本地运行时在调用方机器上、针对当前工作目录和本地文件运行;云端运行时在 Cursor 托管或自托管的云基础设施上,针对新克隆的仓库运行,并可自动创建 PR。该技能面向希望基于 SDK 构建应用、脚本、CI 流水线或自动化的开发者,重点在于集成决策、常见失败模式规避和可扩展的实现模式。

主要能力

  • 三种调用模式:Agent.prompt(...) 一次性调用;Agent.create(...) 加 agent.send(...) 支持流式输出、多轮对话与生命周期操作;Agent.resume(...) 跨进程恢复已有智能体。
  • 运行观测:run.stream() 获取事件流,run.wait() 获取最终结果;通过 run.supports(...) 判断当前运行时是否支持某项操作。
  • 认证:通过 CURSOR_API_KEY 环境变量或显式传入 apiKey,支持用户 API Key 和团队服务账号 Key。
  • 模型选择:可用 Cursor.models.list() 查询可用模型,composer-2 为多数集成的默认模型,auto 由服务端选择。
  • 运行查询:可通过 Agent.get、Agent.getRun、Agent.list 按 ID 或运行时查询智能体与运行信息。
  • MCP 服务器配置:支持 HTTP、stdio 等传输方式及本地/云端差异。

使用方式

基本流程为:设置 CURSOR_API_KEY,按需选择 Agent.prompt、Agent.create 加 send、或 Agent.resume,指定模型与运行时(本地用 local: { cwd },云端用 cloud: { repos }),然后消费流式事件并调用 wait() 获取终态。生产环境中应在 try/finally 中调用 [Symbol.asyncDispose]() 释放资源,或使用 await using 语法;应区分启动失败(CursorAgentError)与运行失败(result.status === "error"),并遵循 error.isRetryable 决定是否重试。

适用场景

适合构建代码审查机器人、定时巡检、聊天式代码问答、webhook 触发的自动化,以及本地开发循环和已有代码检出的 CI 流水线;云运行时更适合长时间任务、免值守自动化和自动创建 PR。

限制

该技能不涵盖 Cloud Agents REST API、.cursor/hooks.json 钩子、私有 worker/自托管云,以及其他语言的 SDK(目前没有官方非 TypeScript SDK,REST 是跨语言方案)。当前已文档化的差异包括:分离或重新加载的运行可能不支持 stream(),conversation() 可能为空;本地运行时中模型为必填,云端为可选;内联 mcpServers 在 resume 时不会持久化,需要再次传入。