AI SDK 集成 Claude Codeai-sdk/harness-claude-code 适配器实战指南【免费下载链接】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/aiai-sdk/harness-claude-code是 AI SDKThe AI Toolkit for TypeScript中的HarnessV1适配器它基于anthropic-ai/claude-agent-sdk驱动claudeCLI将 Claude Code 完整的工作能力文件读写、Shell 执行、子代理、任务管理等封装进 AI SDK 的 HarnessAgent 统一接口。阅读本文后你将掌握该适配器的安装、会话管理、全量配置项认证、思考模式、环境变量、端口等、沙箱桥接架构与断线恢复机制并能在自己的 TypeScript 项目中用统一 API 编排 Claude Code。适配器定位把 Claude Code 变成可编程的 Harness在 AI SDK 的架构中ai-sdk/harness定义了HarnessV1接口与HarnessAgent用于把各类编码 Agent如 Claude Code、其他 CLI 工具接入统一的 Agent 编排体系。ai-sdk/harness-claude-code正是这个体系的 Claude Code 实现提供createClaudeCode()工厂函数返回符合HarnessV1协议的适配器实例内部依赖anthropic-ai/claude-agent-sdk通过它驱动claudeCLI适配器附带一个bridge桥接进程该进程运行在沙箱Sandbox内部与沙箱外的宿主进程通过 WebSocket 通信连接建立在沙箱代理sandbox-proxied的 loopback 端口上。这种桥接进程 WebSocket 沙箱的架构让 Claude Code 的执行环境文件系统、Shell、凭据被严格隔离在沙箱中而宿主应用通过统一的会话 API 驱动它无需直接管理claudeCLI 的子进程生命周期。桥接进程与通用传输协议WebSocket 服务、令牌鉴权、事件日志、断线重连位于共享运行时ai-sdk/harness/bridge中本包只负责 Claude 特定的回合驱动逻辑见 bridge 入口。安装与依赖在项目中安装适配器及其配套包npm i ai-sdk/harness-claude-code ai-sdk/harness ai-sdk/sandbox-vercel三个包的职责如下包作用ai-sdk/harness-claude-codeClaude Code 的HarnessV1适配器本主题核心ai-sdk/harnessHarnessAgent、HarnessV1接口与通用工具ai-sdk/sandbox-vercel提供支持端口的HarnessV1SandboxProvider沙箱实现从 package.json 可以看到该包的运行时依赖为ai-sdk/harness、ai-sdk/provider-utils和wsWebSocket 客户端zod作为 peer 依赖^3.25.76 || ^4.1.8并要求 Node.js22。一个关键机制是bridge 所需的第三方依赖anthropic-ai/claude-agent-sdk、anthropic-ai/claude-code并不会打进编译产物而是在会话首次启动时由 bridge 在沙箱内部根据src/bridge/package.json及固定的pnpm-lock.yaml自行安装。因此沙箱需要具备安装依赖的能力且沙箱内的依赖清单才是这些包的真正版本来源——发布到 npm 的宿主包不负责在运行时提供它们。源码注释对这一约束有明确说明参见 bridge/index.ts。快速开始一个完整的 HarnessAgent 示例下面的示例来自 README它演示了最典型的用法创建沙箱、注入自定义 Skills、注册业务工具然后让 Claude Code 执行一次任务import { HarnessAgent } from ai-sdk/harness/agent; import { createClaudeCode } from ai-sdk/harness-claude-code; import { createVercelSandbox } from ai-sdk/sandbox-vercel; import { tool } from ai; import { z } from zod/v4; const agent new HarnessAgent({ harness: createClaudeCode({ skills: [ { name: careful-refactors, description: Make minimal diffs and keep tests green., content: Prefer changes that touch the fewest files possible., }, ], }), id: demo, sandbox: createVercelSandbox({ runtime: node24, ports: [4000], }), tools: { deploy: tool({ description: Deploy a service., inputSchema: z.object({ env: z.enum([staging, production]) }), execute: async ({ env }) ({ url: https://${env}.example.com }), }), }, harnessOptions: { claude-code: { thinking: { type: adaptive, display: summarized }, }, }, }); const session await agent.createSession(); try { const result await agent.generate({ session, prompt: Read README.md and summarise the goals., }); console.log(result.text); } finally { await session.destroy(); }要点拆解skills向 Claude Code 注入自定义技能。每个 Skill 包含name、description和content三要素name用于激活description帮助模型判断何时使用content是技能的具体指令内容。源码中writeSkills负责将 Skill 落盘供 CLI 读取见 claude-code-harness.ts 的导入。sandboxcreateVercelSandbox必须声明至少一个端口ports: [4000]因为 bridge 需要在该端口上监听 WebSocket。如果沙箱未暴露端口适配器会抛出HarnessCapabilityUnsupportedError提示需要沙箱暴露 TCP 端口请用ports: [...]创建沙箱或传createClaudeCode({ port })见 resolveBridgePort 实现。tools通过HarnessAgent的tools选项注册业务工具如deploy。这些工具会通过mcp__harness-tools__*命名的 MCP 通道暴露给沙箱内的 Claude Code适配器特意过滤掉这些工具名避免与原生 MCP 调用混淆见 claude-code-harness.ts 的注释。harnessOptions按 harness id此处为claude-code传递适配器专属配置例如扩展思考模式thinking: { type: adaptive, display: summarized }。资源释放使用finally块确保会话销毁避免沙箱与桥接进程泄漏。会话生命周期创建、生成与清理适配器要求HarnessV1SandboxProvider的句柄至少暴露一个端口当前受支持的实现是ai-sdk/sandbox-vercel。会话开始后Agent 会调用provider.createSession()创建沙箱会话。方法行为agent.createSession()创建会话触发沙箱创建与 bridge 首次启动agent.generate({ session, prompt })提交提示词并流式生成结果返回result.textsession.detach()将 bridge 与沙箱停靠park保留运行状态之后可通过 bridge 坐标重新挂载attachsession.stop()保存状态并停止沙箱doStop生命周期状态数据在结构上为空对象{}框架通过provider.resumeSession({ sessionId })恢复session.destroy()彻底清理不保留任何可恢复状态这里的关键区别是stop与detach都会写入生命周期状态数据但只有detach会携带 bridge 坐标端口、令牌、事件游标从而支持跨进程的attach重连而stop之后需要重新启动 bridge由 Claude SDK 通过continue: true从工作目录快照恢复对话线程。这一语义在生命周期状态 Schema 的注释中有明确说明见 claude-code-harness.ts。配置项全解ClaudeCodeHarnessSettingscreateClaudeCode(settings)接收ClaudeCodeHarnessSettings类型源码定义位于 claude-code-harness.ts各配置项如下配置项类型默认值说明authClaudeCodeAuthenticationMode即HarnessV1Authentication自动探测指定认证模式直连 Anthropic 或走 Vercel AI Gateway未指定时从宿主进程环境自动探测credentialForwardingHarnessV1CredentialForwarding无在凭据转发进沙箱前定制每个凭据值。注意它只影响转发值不限制适配器在宿主进程中的发现与读取范围mcpServersRecordstring, unknown无按服务器名定义的 MCP 服务器使用底层运行时Claude Code原生 MCP 配置格式maxTurnsnumberCLI 默认CLI 内部可执行的回合数硬上限达到后让出控制权给调用方envReadonlyRecordstring, string无注入 Claude Code 进程的环境变量合并覆盖沙箱 bridge 进程继承的环境thinkingClaudeCodeThinkingConfig{ type: adaptive, display: summarized }扩展思考行为控制type为adaptive \| enabled \| disableddisplay为summarized \| omitteddisabled时无display见 claude-code-thinking.tseffortlow \| medium \| high \| xhigh \| maxClaude Agent SDK 默认启用 adaptive thinking 时控制 Claude 投入的努力程度portnumber沙箱sandbox.ports第一个端口覆盖 bridge 在沙箱内绑定的端口。仅当沙箱声明多个端口且第一个端口被占用时建议设置portEndpointHarnessV1PortEndpoint无覆盖宿主连接沙箱 bridge 的端点与port配合用于 basic sandbox 会话startupTimeoutMsnumber120000等待 bridge 通告端口的最大毫秒数mintBridgeTokenHarnessV1MintBridgeTokenCallback随机 32 字节十六进制令牌创建沙箱 bridge 使用的认证令牌。注意使用该回调要求沙箱会话暴露id否则抛出HarnessCapabilityUnsupportedError其中thinking的默认值在createClaudeCode入口处显式落地为{ type: adaptive, display: summarized }见 claude-code-harness.ts这与 README 示例中harnessOptions里的配置一致——后者是 HarnessAgent 层面的透传写法二者效果相同。运行时环境变量与认证env向 Claude Code 注入环境变量createClaudeCode({ env })中配置的值会覆盖override从沙箱 bridge 进程继承的变量。典型用法const harness createClaudeCode({ env: { DEPLOYMENT_ENV: staging, }, });从源码看最终注入 Claude Code 进程的环境是三层合并的结果认证解析出的环境 →settings.env→ 宿主传入的请求头转换ANTHROPIC_CUSTOM_HEADERS见 claude-code-harness.ts。认证模式与凭据转发认证解析逻辑位于 claude-code-auth.ts支持的凭据环境变量为AI_GATEWAY_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN。认证模式的优先级为显式指定的auth模式自动探测宿主进程环境优先 AI GatewayAI_GATEWAY_API_KEY/VERCEL_OIDC_TOKEN其次直连 Anthropic。createClaudeCodeRequestTransformations会为x-api-keyANTHROPIC_API_KEY和Authorization: BearerANTHROPIC_AUTH_TOKEN分别生成请求变换当沙箱内凭据与宿主凭据不同时在请求出站前把沙箱凭据替换为宿主凭据见 claude-code-auth.ts。若沙箱会话不支持addRequestTransformations则回退为直接向沙箱环境注入凭据并发出warnCredentialBrokeringUnavailable警告。此外当走 AI Gateway 时适配器会通过CLAUDE_AGENT_SDK_CLIENT_APP环境变量设置客户端标识ai-sdk/harness-claude-code/version用于请求归属与网关计费追踪见 claude-code-harness.ts。内置工具Claude Code 原生能力一览适配器将 Claude Code CLI 的全部原生工具声明为ToolSet键名为 bridge 在线路上发出的toolNamecommonName ?? nativeName。工具 Schema 转录自固定版本 Claude Code 可执行文件中生成/注册的工具定义完整清单见 CLAUDE_CODE_BUILTIN_TOOLS核心类别包括类别工具文件操作read读文本/图片/PDF/Notebook支持 offset/limit/pages、write、edit精确字符串替换支持 replace_all、glob、grepripgrep 正则搜索含 output_mode、-A/-B/-C、multiline 等参数Shell 执行bash可后台运行、可传 timeout、Monitor运行并监控 Shell/WebSocket 命令、PowerShell网页webSearch可限定/排除域名、WebFetch抓取 URL 并对内容提问子代理与任务Agent衍生子代理可选 sonnet/opus/haiku 模型与 plan/auto 等模式、TaskCreate/Get/Update/List/Stop/Output会话内任务列表与后台任务管理计划与权限EnterPlanMode、ExitPlanMode可批量批准 Bash 提示、AskUserQuestion向用户提问工作区EnterWorktree/ExitWorktreegit worktree 隔离、TodoWriteMCPListMcpResources、ReadMcpResource、RefreshMcpTools、ToolSearch按需加载延迟工具、Skill按名激活技能、WaitForMcpServers协作文档NotebookEdit、Artifact、DesignSync、SendUserFile、SendMessage多 Agent 消息含结构化团队消息、ShareOnboardingGuide、PushNotification、RemoteTrigger、ScheduleWakeup其他LSP语言服务器代码智能、ReportFindings代码审查发现、CronCreate/Delete/List定时任务、Workflow动态多 Agent 工作流值得注意的实现细节泛型代理工具MCP被有意排除在清单之外——bridge 会先过滤mcp__harness-tools__*工具名再发出事件其余 MCP 调用则以各自的 server-tool 名透传而非字面的Mcp标记见 claude-code-harness.ts。另外mcpServers配置中不允许使用harness-tools作为服务器名——该名称被保留用于 HarnessAgent 工具通道违规会在createClaudeCode时直接抛错见 claude-code-harness.ts。底层原理bridge 连接与恢复策略从 doStart 实现 可以还原完整的启动流程它按rung台阶分三档处理Rung 1 — ATTACH挂载若生命周期状态携带 bridge 坐标端口、令牌、lastSeenEventId游标先尝试复用仍在运行的 bridge——直接重开 WebSocket 并带上事件游标恢复不重新派生进程。continueFrom场景下会以resume: true打开通道。若 bridge 已不可达则落入下一档。Rung 2/3 — REPLAY vs RERUN重放/重跑需要重新派生 bridge。replay只对continueFrom成立因为其坐标含磁盘事件日志的重放游标BRIDGE_REPLAY_FROM_DISK1从event-log.ndjson重放尾部直至finishresumeFrom这类回合间恢复即使携带坐标也总是rerun避免把上一回合的过期事件重新投递进新回合——此时 Claude SDK 靠continue: true从工作目录快照继续自己的线程。全新启动在沙箱中创建workdir与 bridge 状态目录${defaultWorkingDirectory}/.agent-runs/${sessionId}/bridge派生node bridge.mjs等待 bridge 就绪默认 120 秒超时再建立通道。每次启动BRIDGE_CHANNEL_TOKEN都会轮换。从 bridge/index.ts 可以看到通用传输层WebSocket 服务、令牌鉴权、single-flight 重连、内存事件日志与seq序号、resume 重放、生命周期元文件全部由ai-sdk/harness/bridge运行时提供本包只实现 Claude 特有的回合驱动、工具过滤、系统提示与问题交互question-tool、tool-filtering、claude-code-system-prompt等模块。桥接进程内部还通过compaction-latch处理长会话的压缩协调并用json-schema-to-zod把 CLI 下发的 JSON Schema 转成 zod 校验。测试与验证本包使用 Vitest 进行单元与集成测试配置见 vitest.node.config.js测试覆盖claude-code-harness.test.ts用 Fake WebSocket 与模拟沙箱验证doStart的 attach/重连、消息发送、错误处理等核心路径bridge/index.test.ts 及claude-skills-option.test.ts、tool-filtering.test.ts、question-tool.test.ts、compaction-latch.test.ts、create-emit-stream-event.test.ts等分别覆盖桥接回合驱动、Skills 选项转换、工具过滤、提问工具、压缩锁存与流事件生成。运行测试pnpm --filter ai-sdk/harness-claude-code test使用前提与注意事项沙箱必须暴露端口bridge 需要 TCP 端口承载 WebSocketcreateVercelSandbox({ ports: [...] })是当前受支持的选择Node.js 版本包要求 22首次启动耗时bridge 首次启动需在沙箱内安装anthropic-ai/claude-agent-sdk与anthropic-ai/claude-code可用startupTimeoutMs调整等待上限默认 120 秒凭据安全宿主 API Key 通过请求变换机制注入优先使用支持addRequestTransformations的沙箱会话以避免把真实凭据写入沙箱环境保留名称mcpServers中不得使用harness-tools作为服务器名。借助ai-sdk/harness-claude-code你可以用统一的HarnessAgent接口将 Claude Code 作为沙箱化的可编程 Agent 使用——注入自定义 Skills、注册业务工具、控制思考模式与回合数并利用 attach/replay/rerun 三档恢复策略获得健壮的断线续跑能力。【免费下载链接】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），仅供参考
