· 更新日誌

更新日誌

Cursor SDK 的自訂儲存體、自訂工具與自動審查

我們已在 TypeScript 與 Python SDK 中推出一批新功能。您現在可以選擇要如何儲存代理與執行的中繼資料、將自己的函式作為工具提供給代理使用、透過自動審查來處理本機工具呼叫，並以任意深度巢狀組合子代理。此次發佈也帶來一系列可靠性、效能與平台修正，讓本機與 Cloud SDK 代理更容易在正式環境的指令碼、CI 與自訂整合中執行。

自訂工具

你現在可以透過 local.customTools 傳入函式定義，在 Agent.create() 或每次 send() 時，將自己的工具交給本機代理。SDK 會透過一個名為 custom-user-tools 的內建 MCP 伺服器，將這些工具提供給代理，因此模型會透過與其他任何 MCP 工具相同的路徑和相同的權限機制來呼叫你的程式碼。

在此之前，若要提供自訂功能，你必須自行架設 stdio 或遠端 HTTP MCP 伺服器，並將其接入代理。現在只要有函式定義就夠了。父代理的每個子代理也都看得到自訂工具，因此工具只需定義一次，整個執行過程中都可使用。

自動審查

預設情況下，本機 SDK 代理會直接執行工具呼叫而不要求核准，因為在無頭執行時沒有人工介入。請設定 local.autoReview，改為讓這些呼叫透過 自動審查 處理。分類器會決定哪些呼叫可自動執行、哪些要先保留，而不是完全略過審查。

你可以在 permissions.json 中用自然語言指示來引導這個分類器。autoRun.allow_instructions 欄位用來描述傾向允許的呼叫模式，而 autoRun.block_instructions 則描述應暫停並等待審查的呼叫模式。舉例來說，你可以允許對建置產物進行唯讀檢查，同時對刪除這類破壞性操作一律暫停。

{
  "autoRun": {
    "allow_instructions": [
      "Read-only inspections of build artifacts under ./dist are fine."
    ],
    "block_instructions": [
      "Always pause delete operations so I get a chance to review them."
    ]
  }
}

JSONL 和自訂儲存體

兩個 SDK 都會儲存代理和執行的中繼資料，讓你可以在程序重啟後恢復代理。先前一直使用的是 SQLite。現在你也可以選擇改用 JSONL 儲存體，它會寫入純文字的追加式檔案，方便你讀取、查看差異，並提交到版本控制。SqliteLocalAgentStore 和 JsonlLocalAgentStore 都可直接匯出使用。

如果這兩種預設方式都不符合你的設定，請實作公開的 LocalAgentStore 介面，並透過 local.store 傳入。你可以為短暫的 CI 執行打造記憶體內儲存體；如果你希望代理狀態和其他應用程式資料存放在一起，也可以使用 Postgres 作為持久化後端。Python SDK 會透過 bridge 提供 host、JSONL 和 composed JSONL 儲存體。

巢狀子代理

子代理現在可以建立自己的子代理，依此類推。負責審查的子代理可以委派給撰寫測試的子代理，而後者還能再繼續委派；每一層都會保有自己的提示詞和模型。不需要啟用任何設定；子代理工作階段會註冊其呼叫 Task 所需的執行器，因此只要代理定義了子代理，就會自動支援巢狀結構。

可靠性、效能與平台改進

此版本也包含了一批涵蓋兩個 SDK 的體驗改進與修正。

  • 執行關聯：現在每次 send() 都會附帶由平台產生的 requestId，並可在 Run 和 RunResult 中取得，且會持久化儲存於記憶體內、SQLite 和 JSONL 儲存體。你可以將指令碼或 CI 執行與後端日誌、analytics 和支援討論串對應起來，而不必再從 agentId 推斷。
  • 本機執行的可靠 wait()：本機執行不再會在終端機結果寫入前就完成 wait()。Hydration 會持續重新整理，直到執行進入最終狀態，因此 automation 讀取到的會是完整結果。
  • dispose 時的安全檢查點：釋放本機代理時，即使缺少根參考，只要檢查點 blob 仍存在，就不再移除檢查點資料。只有在確實沒有任何需要保留的內容時，才會清除代理目錄。
  • 透過 HTTP/1.1 的雲端串流：雲端代理工作階段現在可在部分 proxy、較舊的 Node fetch 堆疊，以及某些 CI 映像使用的 HTTP/1.1 transport 上正確串流。HTTP/2 的行為維持不變。

  • 更輕量的匯入：匯入 @cursor/sdk 時，不再預先載入完整的本機代理堆疊。僅使用雲端功能或型別的使用者，在第一次本機呼叫前可略過本機 runtime 的成本，且不需要變更 API。第一次本機呼叫會支付一次性的匯入成本，之後則會維持快取。
  • 自含式 TypeScript 類型：發布的 .d.ts 檔案不再參照未發布的 workspace 套件。這修正了在 skipLibCheck: false 下的 TS2305 和 TS2307 錯誤，以及像 TurnEndedUpdate 這類串流型別悄悄變成 any 的情況。
  • 內建 ripgrep：本機 shell 執行會使用隨附的平台 rg 二進位檔，而不會修改你的全域 PATH。在 Windows 上，將 ripgrep 加到前面也不再覆寫 Path 變數。

  • Composer 2 會導向 Composer 2.5：仍固定使用已淘汰 composer-2 slug 的 SDK client，現在會自動導向 Composer 2.5，並保留快速變體，因此較舊的指令碼仍可繼續執行。

  • 以 workspace 為範圍的 list_runs：Client、AsyncClient 和 Agent.list_runs 現在接受可選的 cwd，而 bridge 會退回使用其啟動 workspace。這修正了當 bridge 以子程序執行時，偶爾出現的「找不到代理」結果。
  • 更清楚的找不到錯誤：查找不在已解析 workspace 內的代理時，現在會回傳明確的找不到錯誤，而不是模糊的內部錯誤。
  • 0.1.6 版本與 analytics：cursor-sdk 0.1.6 說明了 Buildkite 的發布路徑，並將 SDK 使用標記為 sdk-python-，讓 analytics 更清楚。

執行 npm install @cursor/sdk 或 pip install cursor-sdk 以升級。固定使用 composer-2 的指令碼會自動移轉至 Composer 2.5，而 requestId 也可安全加入你的執行中繼資料結構。完整資訊請參閱 TypeScript 和 Python 文件。