用途:帮助用户基于 Cursor TypeScript SDK(@cursor/sdk)快速搭建可运行的集成,避免新手常见陷阱。官方文档见 https://cursor.com/docs/api/sdk/typescript,本技能补充决策、故障预防与可扩展模式。
主要能力:同一套接口驱动本地运行时(智能体在用户机器上针对本地文件运行)与云端运行时(在 Cursor 托管或自托管基础设施上针对克隆仓库运行并开 PR)。
三种调用模式:Agent.prompt(...) 一次性调用,适合脚本、GitHub Actions 步骤;Agent.create(...) 加 agent.send(...) 支持流式、多轮对话与生命周期操作;Agent.resume(...) 跨进程恢复已有智能体。
必要用法:设置 CURSOR_API_KEY 环境变量(用户 API key 或团队服务账号 key),或在代码中显式传 apiKey。模型可用 Cursor.models.list 查询,composer-2 为常见默认,{ id: "auto" } 由服务端选择;本地运行必须指定模型,云端可选。
常见陷阱:想要云端却漏写 cloud: { repos } 会静默回退本地;CursorAgentError 表示未启动(鉴权、配置、网络),result.status === "error" 表示已运行但失败,二者修复方式不同;忘记 await agentSymbol.asyncDispose 会泄漏资源;run.wait() 几乎必须调用;调用 stream、wait、cancel、conversation 前应先用 run.supports(...) 判断运行时是否支持。
适用场景:CI 评审机器人、定时任务、聊天、Webhook、PR 自动化等。
限制:不覆盖 Cloud Agents REST API、.cursor/hooks.json、私有 worker 及非 TS SDK;resume 不会保留内联 mcpServers,需重新传入。