Cursor SDK 的最新功能、改進和修復，涵蓋 npm 上的 @cursor/sdk 和 PyPI 上的 cursor-sdk。
1.0.31¶
- 替換系統提示詞。
Agent.create()上的systemPrompt會用你自己的文本替換 Cursor 爲主 agent loop 內置的系統提示詞。規則、技能和工具 schema 仍會加載，subagents 保留各自的提示詞。僅支持 TypeScript 本地智能體；在Agent.resume()時需再次傳入，且訪問權限按賬戶啓用。 - 在運行過程中引導運行。
run.steer(text)會向進行中的輪次注入一條消息，並解析爲complete_delivered；當你應改爲以普通後續消息發送時，則解析爲revert_to_followup。它可在前臺 subagent 運行時使用，該 subagent 會轉入後臺並繼續運行。僅支持 TypeScript 本地運行；雲端運行會解析爲revert_to_followup。 - 後臺 subagents 會回傳結果。 當智能體在後臺運行 subagent 時，其結果現在會作爲同一次運行中的後續輪次返回給 parent，而不再在 parent 輪次結束時被丟棄。
run.stream()會持續產出這些輪次的內容，run.wait()會在這些輪次之後完成。支持本地智能體，TypeScript 和 Python 均可用。 - 爲自定義工具添加註解。
local.customTools條目上的annotations會將 MCP 工具註解 (title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint) 傳遞給模型。它們僅爲描述性提示；SDK 不會強制執行。僅支持 TypeScript。
1.0.30¶
- 長時間運行的本地智能體會保持憑據有效。 TypeScript 和 Python 中的本地運行會在短期訪問令牌過期前刷新令牌，因此運行超過一小時的智能體不再因身份驗證錯誤而失敗。Cloud 運行不受影響。
1.0.29¶
- 自定義工具的輸出 schema。 TypeScript 中的
outputSchema和 Python 中的output_schema可爲自定義工具的結構化結果聲明 JSON Schema，並作爲該工具的 MCP 輸出 schema 告知模型。結果不會依據它進行校驗。僅支持本地智能體。
1.0.28¶
- 以單文件形式上線 SDK。 在 Bun 下，
@cursor/sdk現在會解析爲扁平的單文件 bundle，因此bun build --compile無需更改導入即可使用，也不會再出現Cannot find module './986.js'。@cursor/sdk/bundled和@cursor/sdk/bundled/sqlite以顯式入口的形式暴露相同的構建產物，供 esbuild 等其他單文件 bundler 使用。僅限 TypeScript。
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 支持。
