SDK 持久化与恢复

Agent.create 每次创建新会话，Agent.prompt 是一次性调用。要持续工作，保存 agent.agentId 后用 Agent.resume(agentId, options)；不能仅保存提示文本再重新 create。

恢复句柄

resume 根据 ID 前缀判断运行时：bc- 为云端，其他为本地。云端状态在服务端，本地状态来自 checkpoint store。除非再传 model，否则恢复句柄的 agent.model 为 undefined；inline MCP、tools、disallowedTools 和 systemPrompt 等选项需要重新提供。

已存在的 Run 可通过 Agent.getRun 获取。云端必须传父 agentId；调用 stream/wait/cancel/conversation 前用 supports 与 unsupportedReason 检查运行时能力。

默认 SQLite 与 JSONL

默认使用 node:sqlite 在磁盘持久化，本地 agent、checkpoint、run 和事件可跨进程保留。缺少 node:sqlite 会抛 ConfigurationError，不自动降级。

import { Agent, JsonlLocalAgentStore } from "@cursor/sdk";

const store = new JsonlLocalAgentStore("/var/lib/cursor-agents");
const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2.5" },
  local: { cwd: process.cwd(), store },
});

JSONL store 在指定目录写 agents.ndjson、runs.ndjson、run_events.ndjson、checkpoints.ndjson。resume、list/get 和 listRuns/getRun 应传相同 store，避免因 workspace 或 store 不同误判数据丢失。

全局默认与自定义后端

Cursor.configure 的 local.store 设置进程默认，单次调用优先；传 null 清除自定义默认。LocalAgentStore 由 agents、checkpoints、runs、runEvents 四个子 store 组成，可实现接口或通过 composeLocalAgentStore 组合。

目录记录用不透明 cursor/nextCursor 分页，事件日志用排他 afterOffset/nextOffset 续读。云端始终服务端持久化，local.store 不适用。

预热与配置新鲜度

createAgentPlatform().prewarmLocalWorkspace(options) 提前解析 rules、Skills、MCP 和 ignore files，只对 workspace options 匹配的 send 有效；关闭宿主时调用返回的 release。

workspaceScanCacheTtlMs 默认 20 秒，也可通过 CURSOR_RIPWALK_CACHE_TTL_MS 设置。增加缓存时间会延迟发现新规则。需要代理兼容时可设置 local.useHttp1ForAgent；Bun 因 HTTP/2 兼容问题默认走 HTTP/1.1。

云端生命周期

SDK 的 Agent.list({ runtime: "cloud" }) 默认隐藏归档任务，includeArchived: true 才显示。这与 REST v1 列表文档中默认包含归档不同，按所调用接口判断。

Agent.archive 保留可读会话，Agent.unarchive 恢复，Agent.delete 永久删除，后续读取返回 404。释放 SDK 句柄与删除云端资源是不同动作。

本地 listArtifacts 当前返回空数组，downloadArtifact 抛错；云端可列出 path 后下载。不要用本地产物列表为空推断 Agent 没有在 workspace 写文件。