Cursor SDK 的最新功能、改進和修復，涵蓋 npm 上的 @cursor/sdk 和 PyPI 上的 cursor-sdk。
1.0.27¶
- 限制智能體的工具集。
tools可將模型可用的內置工具限定在允許列表中 ([]表示僅文本) ，disallowedTools則會移除指定工具，同時保留其餘工具。兩者都接受"read"等公開名稱，以及"shell"和"mcp"等能力組；TypeScript 中使用tools、disallowedTools，Python 中使用tools、disallowed_tools。目前僅支持本地智能體，且不會在resume後保留。 - 在 TypeScript 中通過瀏覽器登錄。
Cursor.auth.login()會打開瀏覽器登錄流程、生成 API 密鑰，並將其存儲在~/.cursor/sdk/auth.json中；Cursor.auth.status()和Cursor.auth.logout()則提供其餘相關功能。登錄後，Agent.create()和Cursor.*的讀取操作無需apiKey或CURSOR_API_KEY。 - 本地智能體的用量和成本。 TypeScript 中的
agent.getUsage()和 Python 中的agent.get_usage()現也支持本地智能體，並返回按輪次細分的數據。傳入先前結果中的runId可將範圍縮小到單個輪次。 - 以 Cursor GitHub App 身份創建 PR。 TypeScript 中的
cloud.openAsCursorGithubApp和 Python 中的open_as_cursor_github_app用於控制 PR 的作者身份。服務賬戶密鑰默認使用該 App 身份；用戶密鑰默認使用密鑰所有者身份。 - 多根本地工作區。 傳入
local.dirs可從多個文件夾加載規則、技能和項目上下文；cwd仍是唯一的主工作目錄。這替代了cwd的數組形式，後者始終只使用第一項。 - 更清晰的 Python 錯誤。 先前僅顯示爲“內部錯誤”的失敗現在會包含底層消息和代碼。
- 管理員命令拒絕列表適用於本地運行。 與團隊管理員拒絕列表匹配的 shell 命令會在執行前被策略消息拒絕，包括會跳過批准提示的路徑。
1.0.26¶
- 首次發送前預熱本地工作區。
platform.prewarmLocalWorkspace(options)會預先解析規則、技能、MCP 服務器和忽略文件，因此首次對該工作區調用send()時可立即開始。它會返回一個可在關閉時調用的 release 函數。 - 控制工作區掃描的緩存時長。
configureCursorSdk({ local: { workspaceScanCacheTtlMs } })可設置工作區掃描的緩存時長，CURSOR_RIPWALK_CACHE_TTL_MS環境變量可爲託管部署設置相同的值。長期運行且使用穩定 checkout 的服務器現在可跳過重複掃描。 - 自定義工具無需批准提示即可運行。 通過
customTools傳入的主機定義工具，在沙盒化或 Auto-review 模式的本地運行中不再因交互式批准錯誤而失敗。拒絕規則和沙盒限額仍然適用。 - 已簽名的 macOS 二進制文件。
@cursor/sdk的 macOS 平臺包現在提供經過代碼簽名的二進制文件，因此不再被 Gatekeeper 和端點安全工具攔截。 - 更清晰的 Python 異常層級。
PermissionDeniedError、BadRequestError和InternalServerError現在直接繼承自CursorSDKError，而非AuthenticationError、ConfigurationError和NetworkError，因此except塊會捕獲名稱所對應的異常。 - 修復 Python 中偶發的啓動失敗。 大約每 64 次智能體啓動中就有 1 次會在首次發送前失敗。現在啓動已更加可靠。
1.0.25¶
- 按需獲取已計費用量和費用。 TypeScript 中的
agent.getUsage()和 Python 中的agent.get_usage()可返回雲端代理的 token 用量、已計費用及按每次運行劃分的明細，Agent.getUsage(agentId)無需 handle 即可使用。費用由服務器計算，包含折扣，並會在運行結束後不久結算。目前僅支持雲端；本地運行會拋出帶類型的配置錯誤。
1.0.24¶
- TypeScript 和 Python 現已同步發佈。 從 1.0.24 起，npm 上的
@cursor/sdk與 PyPI 上的cursor-sdk均從同一版本發佈，並使用相同的版本號。Python 版本不再落後於 TypeScript。 - 長時間運行的流更可靠。 高負載運行中的流式響應不再會在中途斷開；此前，這在長輪次中會表現爲 Python 客戶端的網絡錯誤。
1.0.23¶
- Cloud 運行中每次發送的環境變量。 傳入
send(prompt, { cloud: { envVars } })可將環境變量限定於單次運行，包括創建智能體時的首次發送。Agent.create({ cloud: { envVars } })仍會設置智能體級別的默認值。 - 失敗運行的錯誤詳情。 失敗的本地和 Cloud 運行現在會提供包含
message和code字段的結構化錯誤，無需解析日誌即可瞭解具體問題。run.wait()的行爲保持不變。 - Python 中的 token 用量。 運行流會發出包含每輪 token 計數的類型化
usage消息，累積總量可通過run.usage和RunResult.usage獲取，與 1.0.22 的 TypeScript 保持一致。 - 更可靠的本地運行歷史記錄。 磁盤上的運行歷史記錄現在可在寫入中斷後保持完整，修復了進程崩潰後導致運行無法恢復的一類問題。
- 修復 Bun 中的流式傳輸停滯問題。 Bun 下的運行流在長響應時不再停滯。
1.0.22¶
- 每次運行的 Token 用量。 本地運行會通過
run.stream()爲每輪發出usage事件，並通過run.wait()返回累計總量。雲端運行也會在其流和wait()結果中提供相同的用量；對於已分離的本地句柄，累計總量會持久保存，因此重新連接的進程仍可獲取這些數據。
1.0.21¶
- 支持在 Bun 下運行智能體。
agent.send()現可在 Bun 下運行，行爲與 Node 中一致。此更新還修復了新安裝的 Node 可能缺少必需依賴的問題。 - Python 中更易用的運行時名稱。 List API 和
get_run現支持runtime="cloud"、"local"和"auto"，與文檔中列出的值一致。
1.0.20¶
- SDK 現已可在 Bun 中正常導入。 在 Bun 中導入
@cursor/sdk不再會崩潰。Bun 中運行智能體將於 1.0.21 支持。
