Cursor 凌晨開放 TypeScript SDK，一個 npm 包就能把 Composer Agent 嵌進你的項目

昨晚，Cursor 官方賬號發了一條推文，直接宣佈 Cursor SDK 開放使用。一句話總結：以前你只能在 Cursor 這個 IDE 裏用 Composer，現在可以把它當成一個 npm 包，裝到你自己的 Node.js 項目裏。

npm install @cursor/sdk

cursor/cookbook 這個新開的官方倉庫，幾個小時就拿到了 1.1k Star。對 Node.js 和 TypeScript 開發者來說，這是 2026 年到目前為止比較值得關注的一次發佈，因為它把"AI 編程"這個能力，從一個獨立的桌面工具，變成了你 package.json 裏的一行依賴。

下面把這次發佈拆開聊一下：它到底放出來了什麼，能用來幹什麼，以及現在上手大概是什麼手感。

這次到底放出來了什麼

官方一次性放了三樣東西：

第一，@cursor/sdk 這個 npm 包，TypeScript 原生，可以在 Node.js 進程裏直接 import { Agent } from "@cursor/sdk"。

第二，文檔站 cursor.com/docs/sdk/typescript，裏面寫清楚了 Agent 的生命週期、流式事件、MCP 接入、錯誤類型這些細節。

第三，開源 Cookbook 倉庫 github.com/cursor/cookbook，裏面塞了四個起手項目：一個 Quickstart、一個 Coding Agent CLI、一個 Web 端原型工具（app-builder）、一個 Agent 驅動的看板（agent-kanban）。這四個項目都是 TypeScript 寫的，可以直接 clone 下來改。

發佈的同時，官方還公佈了幾個早期客戶：Rippling、Notion、C3 AI、Faire。這幾家用 SDK 做的事情各不相同，有的拿來跑後台 Agent，有的把它接到 Bug 處理流程裏，從工單一路拉到可合併的 PR，還有的把它接進 CI/CD，讓 Agent 自己維護 codebase 的健康度。

定價上也沒繞彎子，沿用現有的 token 計費規則，跑在 SDK 上的用量會進團隊的統一 dashboard，帶一個 SDK 標籤做區分。

一段最小可跑的代碼

官方文檔裏給的 Hello World 長這樣：

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 repository");
for await (const event of run.stream()) {
  console.log(event);
}

幾個細節值得拎出來說一下。

Agent.create 是入口，決定了這個 Agent 要在哪裏跑。傳 local: { cwd } 就是本地模式，Agent 直接在你當前的 Node 進程裏讀寫文件；傳 cloud 配置就是雲端模式，Cursor 會在自己的隔離 VM 裏克隆倉庫、跑 Agent、推 PR。同一套 API，本地和雲端只差一個字段。

model.id 這一行直接選模型。現在能用的有 Composer 2、Claude 系列、GPT 系列。如果你想拿 thinking 模式跑，可以這樣寫：

model: { id: "composer-2", params: [{ id: "thinking", value: "high" }] }

具體哪些模型 ID 可用、每個模型支持什麼參數，可以通過 Cursor.models.list() 拿到，返回值是和你賬號綁定的，所以不需要手動維護一份模型列表。

run.stream() 是異步迭代器，吐出來的 event 是帶 discriminated union 的 SDKMessage，包含 system、user、assistant、thinking、tool_call、status、task、request 這幾種類型。如果你不想自己 switch case，可以直接 await run.wait()，一次性拿到最終結果、token 用量和 git 元數據。

如果只是臨時跑一個 prompt 不打算複用 Agent 實例，還有一個更短的寫法：

const result = await Agent.prompt("Your question", options);

整體 API 設計上能看出 Cursor 是認真做了 TypeScript 工程化的。資源管理用了 await using 這個 ES2024 特性，讓 Agent 在作用域結束時自動清理：

await using agent = await Agent.create({ /* ... */ });
// 塊結束時自動清理

這不是套殼 Python SDK 翻譯過來的，是按 Node.js 的寫法重新設計的。

Local 和 Cloud 是同一套架構

Cursor 在公告裏貼了一張架構圖，把整個 SDK 的能力棧畫得很清楚：

最下面是 Models 層，Composer、Claude、GPT、Other 並列。中間是 Harness 層，裏面是 Agent Loop 和 MCP/Tools。上面分兩條路：Managed Cloud 模式比 Local Workstation 多一層 Sandbox。

這張圖的關鍵點是：Local 和 Cloud 用的是同一個 Harness。也就是說你在本地調通的 Agent 邏輯，挪到雲端不需要改業務代碼，只改 Agent.create 裏的運行時配置就行。

在雲端模式下，Cursor 給每個 Agent 分配獨立的 VM，自動克隆倉庫、跑完整的 dev 環境初始化，可以創建分支、推 PR、附帶產物。即使中間網絡斷了 Agent 也能繼續跑，跑完再把結果同步回來。這是最貼近"後台 Agent"使用場景的部分，CI/CD 流水線裏用得上。

本地模式則適合兩類場景：一是你在寫腳本或者臨時跑一些自動化任務，不想為每次執行起一個雲端 VM；二是你的代碼本身就敏感，不能離開本地環境。本地模式下 Agent 直接在你的 Node 進程裏執行，文件讀寫、命令執行都在本地，相當於把 Cursor 的 Composer Agent 當成一個可編程的子進程來用。

需要注意的是，本地模式拿不到產物下載（downloadArtifact），這個能力是雲端獨有的。

配置體系是它真正的護城河

如果只看 Agent.create 這種基礎 API，你可能會覺得"這不就是把 Cursor 的 Agent 包了一層 SDK"。但翻完文檔以後會發現，真正複雜的部分在配置體系上。

MCP 服務器支持五個來源，按優先級合併：send() 內聯定義、create() 內聯定義、Cursor 插件、項目級 .cursor/mcp.json、用戶級 ~/.cursor/mcp.json。值得提的是，send() 內聯定義不是合併而是替換，寫的時候要注意。雲端 Agent 還能直接複用你在 cursor.com 上授權過的 OAuth token，省掉一次重新授權。

Skills 自動從 .cursor/skills/ 目錄加載，Hooks 通過 .cursor/hooks.json 配置，Subagents 可以用 agents 字段嵌套定義。也就是說你在 Cursor IDE 裏已經配置好的 Skills 和 Hooks，SDK Agent 能直接複用，不需要再搬一遍。

這一套東西堆在一起的意思是：Cursor 不是給你一個調用 LLM 的封裝，而是把整個 Agent 運行時（包括上下文管理、工具調用、子任務委派、鈎子）都打包出來了。如果你之前自己用 LangChain 之類的框架手寫過 Agent，會知道把這些東西做完整有多少坑。

錯誤處理這塊也做得比較細，所有異常繼承自 CursorAgentError，帶 isRetryable 布爾屬性。具體類型分成 AuthenticationError、RateLimitError、ConfigurationError、NetworkError、UnknownAgentError。在調用某個操作前，可以用 run.supports(operation) 先檢查兼容性，避免調到不支持的能力。

四個 Cookbook 項目分別能幹什麼

cursor/cookbook 這個倉庫的定位是"build on top"，每個項目都是可以直接 clone 然後用 Cursor 改的。我快速過了一下：

Quickstart：最小的 Node.js 例子，演示怎麼創建 Agent、怎麼消費流式事件。代碼非常短，用來對照着看 SDK 行為最方便。

Coding Agent CLI：終端交互式 Agent，類似 Claude Code 那種用法。但因為是開源的，你可以直接改 prompt、改默認模型、加自己團隊的工具。如果你想給團隊做一個內部 CLI，這個是最好的起點。

Prototyping Tool（app-builder）：一個 Web 應用，用來在雲端 sandbox 裏啓動 Agent，專門做項目原型迭代。可以理解為一個簡化版的 v0 / Bolt，但跑在 Cursor 自己的 Cloud Agent 上。

Agent Kanban：可視化看板，把 Cloud Agent 當成卡片管理，按狀態、按倉庫分組，能預覽產物、直接創建新的 Cloud Agent。這個項目的設計思路挺有意思，把"派發 Agent"做成了一個團隊協作產品，不是單人工具。

四個項目主要語言是 TypeScript（95.3%），CSS 和 JavaScript 佔很少。對 Node.js 開發者來說，這幾個項目本身就是不錯的工程範例，看一遍就大致清楚社區怎麼落地這個 SDK。

哪些場景值得現在就上？

結合官方公告和早期客戶案例，目前看比較成熟的幾個方向：

第一是 CI/CD 集成。在 PR 檢查裏掛一個 Agent，讓它自動總結改動、定位 CI 失敗的根因，甚至直接推一個修復 commit。這是 Faire 和一部分客戶的主要用法，自我修復 codebase 的思路是這個意思。

第二是工單到 PR 的自動化。把 Bug 工單系統接進 SDK，工單創建後自動啓動一個 Cloud Agent，讓它讀懂上下文、定位代碼、寫補丁、提 PR。Notion 和 Rippling 都在做類似的事。

第三是把 Agent 嵌進自有產品。Cursor 在博客裏專門提了一句："有些客戶把 Cursor 直接嵌進了面向終端用戶的產品裏"。也就是說，你的 SaaS 產品裏那個"AI 助手"按鈕，背後跑的可能就是一個 Cursor Agent。這種用法對 To B 產品來說是個新選項，省掉了自己搭 Agent 基建的成本。

第四是給非技術團隊做 No-code Agent 平台。前端套一個表單或者拖拽界面，後端用 SDK 啓動 Agent 幫 GTM、運營這些團隊跑數據。這塊從 LangChain 時代就有人做，但 Cursor SDK 的優勢是它帶完整的代碼理解能力，能動你的產品代碼，不只是查數據。

放到整個 AI 編程生態裏看，Cursor 這次發佈並不孤立。Anthropic 有 Claude Agent SDK，OpenAI 有 Agents SDK，Google 也在推自己的 Agent 框架。Cursor 進這個池子的差異點是：它不是把模型 API 包一層，而是把整個"在你代碼上跑 Agent"的運行時商品化了。

代碼理解、上下文索引、MCP 工具生態、Sandbox 隔離、PR 自動化，這些東西每一項單獨做都不算難，難的是把它們整合到一個 SDK 裏、做到生產可用、還要讓本地和雲端用同一套抽象。從文檔的成熟度看，Cursor 在這塊明顯憋了很久。

但要不要現在就把 Cursor SDK 接進你的關鍵流程，還要看幾個現實問題：你願不願意把代碼綁定在 Cursor 這一家供應商上、token 成本能不能控制住、Composer 2 和你現在用的模型相比 ROI 怎麼樣。SDK 解決的是"能不能用"，"值不值得用"得自己跑一遍 benchmark。

對 Node.js 和 TypeScript 開發者來說，最務實的態度可能是：先 npm install @cursor/sdk 把 Quickstart 跑通，把 cookbook 那四個項目翻一遍，心裏有個底。等下次你的項目裏要做"自動總結 PR"、"自動寫測試用例"、"接工單系統"這種 Agent 類需求的時候，至少多一個不用從零造輪子的選項。

Cursor 把工具釘在了 package.json 這一行上，剩下就看社區的反饋了。