SuperAPI AI 工具集

cursor-sdk

编程与开发

查看项目

更新于 10-16 07:16

技能介绍

Cursor TypeScript SDK(@cursor/sdk)用于以编程方式运行 Cursor 智能体。相同接口驱动两类运行时:本地运行时在调用者机器上针对其文件运行;云端运行时在 Cursor 托管或自托管基础设施上针对克隆的仓库运行并创建 PR。该技能用于快速搭建可工作的集成,并避免新手常见陷阱;完整文档见 https://cursor.com/docs/api/sdk/typescript。

主要调用模式有三种:Agent.prompt(...) 一次性执行,适合脚本、GitHub Actions 步骤等即发即弃流程;Agent.create(...) 加 agent.send(...) 支持流式输出、多轮对话与生命周期操作(取消、状态监听);Agent.resume(...) 用于跨进程边界继续已有智能体。

关键要点:本地与云端二选一时,若不显式传 cloud: { repos },会静默回退到本地运行时。失败分两类:抛出 CursorAgentError 表示运行未启动(认证、配置、网络问题);result.status === "error" 表示智能体已运行但中途失败,两者修复方式不同。务必在 finally 中调用 agentSymbol.asyncDispose 释放资源。run.stream() 用于观察,run.wait() 用于获取最终结果,几乎必须调用 wait()。并非每个运行操作在所有运行时都受支持,调用 cancel、conversation 前应先用 run.supports("...") 判断。

认证:设置 CURSOR_API_KEY 环境变量(用户 API key 或团队服务账号 key)即可,apiKey 未传时 SDK 会读取该变量。模型选择可用 Cursor.models.list(...);composer-2 是多数集成的默认,本地运行必须指定模型,云端可选。生产实践包括:始终用 try/finally 加 asyncDispose 包裹;区分启动失败(退出码 1)与运行失败(退出码 2);send() 后立即记录 run.id 与 agent.agentId;遵循 error.isRetryable;共享基础设施代码中显式传 apiKey;云端 CI 可设 skipReviewerRequest: true。

可稍后按 ID 查看未由自己启动的智能体/运行:云端以 bc- 开头的 ID 自动路由到云端 API,本地需提供 cwd。本技能不覆盖 Cloud Agents REST API、.cursor/hooks.json、私有 worker/自托管云及 Python 等非 TS SDK。