AI SDK Cursor Harness 适配器全解析基于 Agent Client Protocol 集成 Cursor CLI【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读ai-sdk/harness-cursor是 AI SDK Harness 体系中专用于 Cursor 的适配器包它通过 Agent Client ProtocolACP将 Cursor CLI 接入HarnessAgent让 TypeScript 应用能够在受控沙箱中驱动 Cursor 完成代码库调研、工具调用与多轮 agent 任务。本文以 CHANGELOG.md 的版本演进为主线结合 09-cursor.mdx 官方文档、cursor-harness.ts 源码实现与测试用例完整覆盖安装配置、双层认证模型、内置工具清单、已知限制以及从 1.0.0 到 1.0.20 的关键能力变迁帮助你快速上手并在生产场景中正确选型。一、包定位Cursor CLI 的 AI SDK Harness 适配层ai-sdk/harness-cursor源码位于 packages/harness-cursor当前版本 1.0.20的作用是把 Cursor 的命令行形态——即 Cursor CLI——抽象成一个符合 AI SDK Harness V1 接口的适配器实例供上层HarnessAgent统一调用。从 cursor-harness.ts 的实现可以看到它本质上是对ai-sdk/harness-acp的createACP的一次“预配置化”包装固定了 Cursor 专属的 ACP 启动命令、安装来源、凭证环境变量、内置工具表与认证转发策略。ACP 会话管理、流式传输、工具中继、审批与生命周期逻辑全部委托给通用的 ACP harness 适配器详见 06-acp.mdx。关键实现事实可从源码确认安装来源source类型为install-command命令为curl https://cursor.com/install -fsS | bash即首个会话启动时在沙箱内用 Cursor 官方安装器安装 CLI启动命令executable为agent参数为[--disable-auto-update, acp]即以 ACP 模式启动并禁用自动更新凭证环境变量credentialEnv声明为[CURSOR_API_KEY]模型映射modelMapping采用session-config-option类型、路径为model意味着模型选择通过会话配置选项下发客户端能力声明parameterizedModelPicker: true表示支持参数化的模型选择客户端标识ACP 握手时上报ai-sdk/harness-cursor/VERSION。这些固定项由适配器直接决定不能通过createCursor()覆盖文档 09-cursor.mdx 明确说明。二、安装与基础用法2.1 安装依赖npm install ai-sdk/harness ai-sdk/harness-cursor ai-sdk/sandbox-vercel三个包各司其职ai-sdk/harness提供HarnessAgent与 Harness V1 抽象ai-sdk/harness-cursor提供 Cursor 适配器ai-sdk/sandbox-vercel提供满足 Cursor 运行条件的网络沙箱。包声明在 package.json 中运行时依赖ai-sdk/harness、ai-sdk/harness-acp、ai-sdk/provider-utilspeer 依赖zod并要求 Node.js 22。2.2 最小可运行示例import { HarnessAgent } from ai-sdk/harness/agent; import { cursor } from ai-sdk/harness-cursor; import { createVercelSandbox } from ai-sdk/sandbox-vercel; const agent new HarnessAgent({ harness: cursor, model: gpt-5.6-luna, sandbox: createVercelSandbox({ runtime: node24, ports: [4000], }), }); const session await agent.createSession(); try { const result await agent.generate({ session, prompt: Inspect this project and summarize its purpose., }); console.log(result.text); } finally { await session.destroy(); }要点说明cursor是包导出的默认实例等价于createCursor()的零参数调用见 index.ts使用 Vercel Sandbox 时宿主环境需要提供VERCEL_OIDC_TOKEN与CURSOR_API_KEY首次会话需要网络出口来执行 Cursor 官方安装器且沙箱必须暴露至少一个 TCP 端口供 ACP bridge 使用model是HarnessAgent层面的参数而非适配器构造参数这一设计源自 1.0.6 版本的调整详见后文版本演进章节。2.3 导入方式import { createCursor, cursor } from ai-sdk/harness-cursor;createCursor用于按需定制配置cursor是开箱即用的默认实例。三、Adapter 设置项全解使用createCursor()可以调整运行时行为文档给出的典型示例const harness createCursor({ auth: ai-gateway, port: 4001, startupTimeoutMs: 180_000, });各设置项说明类型定义见 cursor-harness.ts设置项作用默认/取值auth声明 Cursor 中配置的模型提供商认证方式或提供一个隔离的认证环境auto/direct/ai-gateway/ 形如{ CURSOR_API_KEY: ... }的记录不传时为autocredentialForwarding在每个凭证被转发进沙箱进程前对其做同步/异步定制可选只影响转发进沙箱的值不限制适配器在宿主进程中的读取范围port覆盖 ACP bridge 使用的沙箱端口可选portEndpoint覆盖连接沙箱 bridge 的宿主端点与port一起用于 basic sandbox session可选startupTimeoutMs等待 ACP bridge 启动的最大毫秒数可选mcpServers按服务器名组织的 MCP 服务器定义使用底层运行时的原生 MCP 配置格式可选mintBridgeToken生成沙箱 bridge 认证 token 的函数接收 sandbox id 返回 token默认为随机 32 字节十六进制 token自定义实现必须返回足够机密的 token测试 cursor-harness.test.ts 验证了这些设置会被原样透传给createACP包括自定义credentialForwarding、port: 4319、portEndpoint、startupTimeoutMs: 45_000、mcpServers与mintBridgeToken。四、双层认证模型CURSOR_API_KEY 与模型提供商路由Cursor 适配器存在两个相互独立的认证层这是理解auth语义的关键Cursor CLI 账号认证CURSOR_API_KEY负责让沙箱中的 Cursor CLI 登录 Cursor 账号。无论选择哪种auth模式该 key 都是必需的模型提供商认证Cursor 账号设置中配置的“如何向模型提供商认证”的方式。适配器无法读取也无法修改这项设置。4.1 auth 的三种共享 ACP 模式const automaticHarness createCursor({ auth: auto }); const directHarness createCursor({ auth: direct }); const gatewayHarness createCursor({ auth: ai-gateway });auto不声明预期路由不产生警告direct声明走 Cursor 直连模型提供商的路线。由于适配器无法改变 Cursor 的提供商路由会输出一条配置提醒console.warn提示在 Cursor 中配置直接路由ai-gateway声明走 AI Gateway 路线同样输出提醒并给出具体配置方式将 Cursor 的 OpenAI API key 配置为 AI Gateway key并在 Cursor 设置中把Override OpenAI Base URL设为https://ai-gateway.vercel.sh/cursor/v1。源码 cursor-harness.ts 与测试 cursor-harness.test.ts 确认direct与ai-gateway各触发一次包含auth: ...与CURSOR_API_KEY提示的警告而auto不触发。4.2 通过 auth 传递隔离的认证环境如果不想读写或修改process.env可以把凭证以对象形式传入const harness createCursor({ auth: { CURSOR_API_KEY: await resolveCursorToken() }, });该记录只配置 Cursor CLI 的账号认证模型提供商的转发路由仍由 Cursor 账号设置决定。4.3 本地订阅解析复用宿主机已有的 Cursor 登录态若宿主环境未提供任何适用的凭证变量适配器会尝试从宿主机解析 Cursor 的“原生订阅”AI Gateway 认证模式下除外。实现位于 cursor-subscription.ts解析顺序与细节为文件凭据按平台读取auth.jsonWindows%APPDATA%\Cursor\auth.json默认回退到AppData\RoamingLinux$XDG_CONFIG_HOME/cursor/auth.json默认~/.configmacOS/其他~/.cursor/auth.jsonmacOS 钥匙串若文件无凭据且不是 file 存储模式读取钥匙串中 service 为cursor-access-token、account 为cursor-user的密码JWT 过期检查若取到的 access token 是 JWT 且即将过期直接抛出错误提示Run Cursor login again.而不是尝试刷新。测试 cursor-subscription.test.ts 覆盖了三种场景Gateway 认证下不读取订阅、CURSOR_API_KEY优先于本地存储、平台路径解析正确性以及“过期 token 直接报错而非伪造刷新端点”的行为。五、凭证代理Credential Brokering的实现细节适配器通过credentialBrokering回调实现“宿主机持有真凭证、沙箱持有临时凭证”的安全模型源码 cursor-harness.ts 定义了两类出站请求变换Cursor 用户 API key 交换当宿主与沙箱都具备CURSOR_API_KEY时对发往api2.cursor.sh的POST /auth/exchange_user_api_key请求匹配沙箱凭据对应的Authorization: Bearer sandboxEnv.CURSOR_API_KEY头并将其替换为宿主真实凭据Bearer env.CURSOR_API_KEY自定义 headers 注入当推理请求携带自定义headers时根据auth模式选择匹配路由ai-gateway模式匹配ai-gateway.vercel.sh且路径以/cursor/v1开头其他模式匹配api2.cursor.sh随后将自定义 headers 变换进匹配到的请求。测试 cursor-harness.test.ts 验证了第一类变换的精确匹配与替换逻辑cursor-harness.test.ts 验证了ai-gateway与默认模式下 headers 分别应用到对应路由。值得一提自定义 headers 能力对应 1.0.15 版本的功能条目通过HarnessAgentSettings的headers属性传递且文档 09-cursor.mdx 指出——该能力并非 Cursor ACP 原生支持只能通过沙箱外请求变换实现若沙箱不具备该能力自定义 headers 会被忽略。六、沙箱要求Cursor 在沙箱内运行需要带网络访问且至少暴露一个 TCP 端口的沙箱官方推荐使用ai-sdk/sandbox-vercelconst sandbox createVercelSandbox({ runtime: node24, ports: [4000], });首次会话需要网络出口下载并安装 Cursor CLIACP bridge 通过暴露的端口通信port/portEndpoint/startupTimeoutMs等设置可调整 bridge 的启动行为。七、内置工具清单适配器将 Cursor 的终端、glob、grep 工具映射为 AI SDK 的公共bash、glob、grep工具同时以稳定名称暴露其余内置工具。完整清单定义于 cursor-harness.ts并被 cursor-harness.test.ts 的快照逐项断言工具名标题原生调用名类型bashTerminalshellToolCallbashdeleteDeletedeleteToolCalleditglobFindglobToolCallreadonlygrepgrepgrepToolCallreadonlyreadReadreadToolCallreadonlyupdateTodosUpdate TODOsupdateTodosToolCall—readTodosRead TODOsreadTodosToolCallreadonlyeditEditeditToolCalleditlsListlsToolCallreadonlyreadLintsRead LintsreadLintsToolCallreadonlysemanticSearchCodebase SearchsemSearchToolCallreadonlycreatePlanCreate PlancreatePlanToolCall—webSearchWeb SearchwebSearchToolCallreadonlytaskTasktaskToolCall—listMcpResourcesList MCP ResourceslistMcpResourcesToolCallreadonlyreadMcpResourceFetch MCP ResourcereadMcpResourceToolCallreadonlyapplyAgentDiffApply Agent DiffapplyAgentDiffToolCalleditfetchFetchfetchToolCallreadonlyswitchModeSwitch ModeswitchModeToolCall—generateImageGenerate ImagegenerateImageToolCall—recordScreenRecord ScreenrecordScreenToolCall—computerUseComputer UsecomputerUseToolCallbashwriteShellStdinWrite to stdinwriteShellStdinToolCallbashreflectReflectreflectToolCallreadonlysetupVmEnvironmentSetup VM EnvironmentsetupVmEnvironmentToolCallbashreplaceEnvReplace EnvironmentreplaceEnvToolCallbashstartGrindExecutionStart Grind ExecutionstartGrindExecutionToolCallbashstartGrindPlanningStart Grind PlanningstartGrindPlanningToolCallreadonlywebFetchWeb FetchwebFetchToolCallreadonlyreportBugfixResultsReport Bugfix ResultsreportBugfixResultsToolCall—两个动态工具未作为内置暴露mcpToolCall动态生成与truncatedToolCall传输层哨兵。Cursor 宿主工具调用走 ACP 的 MCP 传输适配器通过isMcpToolCall识别 Cursor 的 MCP 载荷rawInput 含providerIdentifier、toolName、args字段并与宿主侧工具执行相关联见 cursor-harness.ts 及对应测试。八、已知限制选型必读文档 09-cursor.mdx 明确列出了以下限制模型提供商路由不可编程切换必须在 Cursor 设置中配置auth无法改变它无模型步进边界与逐步用量ACP v1 不暴露这些信息适配器只能推断边界Cursor 未提供总量时报未知用量无便携的手动压缩与回合中转向 APIACP v1 限制无便携的内置工具过滤 API过滤宿主工具可行但过滤 Cursor 内置工具会抛出不支持能力错误不支持内置工具审批Cursor 当前不支持内置工具审批请求需要使用permissionMode: allow-all宿主执行的 AI SDK 工具审批仍可用不支持结构化输出Cursor ACP 未暴露结构化输出的元数据映射自定义 headers 依赖沙箱能力仅通过沙箱外请求变换生效沙箱不具备该能力时 headers 会被忽略。九、版本演进从 1.0.0 到 1.0.20CHANGELOG.md 记录了从首个正式版到当前 1.0.20 的全部发布历史。除大量仅升级底层依赖的 Patch 版本ai-sdk/harness、ai-sdk/provider-utils、ai-sdk/harness-acp的常规更新外以下条目反映了适配器能力的实质演进版本变更要点影响1.0.0feat(harness-cursor): implement Cursor harness adapter首个正式版完成 Cursor CLI 的 ACP 适配1.0.3feat(harness): harden credential brokering to only apply with correct ephemeral secret加固凭证代理仅当携带正确的临时密钥时才生效提升沙箱场景安全性1.0.5feat(harness): allow harness sessions to optionally authenticate from an isolated environment supplied through theauthoption移除旧版遗留 auth 选项类型支持auth传入隔离认证环境无需读写process.env1.0.6feat(harness): addmodelparameter toHarnessAgent模型参数上移到HarnessAgent构造层各 harness 适配器不再各自在构造函数支持1.0.7feat(harness): allow changingmodelbetween turns via call options支持在回合之间通过调用选项切换模型1.0.13fix(harness-acp): preserve terminal events replayed during ACP continuation startup修复 ACP 续接启动期间终端事件回放丢失的问题1.0.14feat(harness): supportaskUserQuestionstool with normalization across harness adapters新增向用户提问工具并支持跨 harness 适配器的归一化1.0.15feat(harness): allow passing arbitrary headers with inference requests viaheadersinHarnessAgentSettings推理请求可携带任意自定义 headers经凭证代理的请求变换落地1.0.17chore(harness): remove formerly deprecatedmodelandmodelIdconfig on harness adapter settings清理适配器设置中已废弃的model/modelId统一收敛到HarnessAgent在代码层面1.0.15 的 headers 能力体现为credentialBrokering回调接收headers参数并生成路由匹配变换1.0.6/1.0.7 的模型能力体现为modelMapping: { type: session-config-option, path: model }与会话配置选项下发模型的方式。十、总结ai-sdk/harness-cursor是 AI SDK Harness 体系中开箱即用的 Cursor 接入方案安装依赖、配置CURSOR_API_KEY、在 Vercel 沙箱中创建HarnessAgent即可用统一 API 驱动 Cursor CLI 执行代码库调研、工具调用等任务。理解其双层认证模型CLI 账号认证 Cursor 侧提供商路由、本地订阅解析机制、凭证代理实现以及文档明确列出的已知限制是避免踩坑的关键。若要深入底层可直接研读 cursor-harness.ts、cursor-subscription.ts 及其测试文件它们完整刻画了适配器的真实行为边界。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考