ai-sdk/harness-grok-build 演进全解析AI SDK 中基于 ACP 的 Grok Build Harness 适配器【免费下载链接】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本篇文章以仓库中 packages/harness-grok-build/CHANGELOG.md 的版本记录为主线结合ai-sdk/harness-grok-build包的真实源码、测试与官方文档梳理该 Harness 适配器从 v1.0.0 诞生到 v1.0.44 的全部能力演进。读完本文你将理解Grok Build Harness 如何通过 Agent Client ProtocolACP把 Grok Build CLI 接入 AI SDK 的HarnessAgent每个版本引入的认证、沙箱、工具、结构化输出等能力是如何实现的以及如何在真实项目中完成安装、配置与调用。一、包定位Grok Build Harness 是什么ai-sdk/harness-grok-build是 AI SDK 中专门适配 Grok Build CLI 中的createACP({...})调用。从包的依赖关系package.json可以清晰看到这一分层运行时依赖ai-sdk/harnessHarness v1 抽象与内置工具定义、ai-sdk/harness-acpACP 协议实现、ai-sdk/provider-utils通用工具函数与 schema 解析对等依赖zod^3.25.76 || ^4.1.8用于工具输入 schema 的运行时校验引擎要求node 22。包入口src/index.ts导出了两个工厂形态import { createGrokBuild, grokBuild } from ai-sdk/harness-grok-build;其中grokBuild是默认实例等价于createGrokBuild()createGrokBuild(settings)用于按需定制运行时。VERSION通过构建期常量注入见 src/version.ts非构建环境回退为0.0.0-test测试快照亦验证了该回退行为。二、CHANGELOG 主线从 1.0.0 到 1.0.44 的能力演进CHANGELOG 记录了 44 个版本绝大多数是 Patch 级依赖同步跟随ai-sdk/harness与ai-sdk/harness-acp的版本推进但其中有若干带 commit 描述的行为变更构成了该适配器完整的能力时间线。下表按版本号汇总了所有非纯依赖同步的条目版本变更要点1.0.0首个 Major 版本基于 ACP 适配器新增 Grok Build Harness1.0.1支持按 Harness 独立配置 MCP servers新增可选mintBridgeToken(sandboxId)控制 bridge token1.0.2修复instructions 改为追加到 system/developer prompt而非用首条 user prompt 变通1.0.8网络沙箱支持请求变换并据此实现凭据代理credential brokering构建期注入 bridge 的package.json与pnpm-lock.yaml1.0.10HarnessAgent通过output属性支持结构化输出1.0.15HarnessAgentSession支持传入文件系统与进程受限的沙箱会话回退到网络沙箱方法1.0.24新增credentialForwarding设置细粒度控制转发进沙箱的凭据pnpm 11 沙箱引导时允许固定的 OpenCode 与 Grok Build 安装脚本1.0.27加固凭据代理仅在携带正确的一次性密钥ephemeral secret时才应用1.0.29auth选项支持从隔离环境认证会话移除废弃的 legacy auth 类型1.0.30Grok Build 适配器更新底层 SDK新增reasoningEffort控制model参数上移到HarnessAgent1.0.31支持通过 call options 在轮次之间切换model1.0.38支持askUserQuestions工具并在各 Harness 适配器间统一归一化1.0.39新增writeInstructions辅助函数ACP 类适配器支持基于文件系统的instructionsMappingHarnessAgentSettings新增headers属性透传任意请求头1.0.41移除废弃的model/modelId适配器配置这组条目恰好描绘出一个适配器从能用到生产可用的完整路径先是 ACP 协议打通1.0.0然后是 MCP、bridge token1.0.1与 prompt 注入方式修正1.0.2接着是沙箱凭据安全1.0.8/1.0.24/1.0.27再是结构化输出1.0.10、认证隔离1.0.29、推理强度控制与模型抽象1.0.30/1.0.31、用户提问工具1.0.38最后是指令映射与请求头透传1.0.39以及 API 清理1.0.41。三、v1.0.0 基础ACP 之上的固定实现在 grok-build-harness.ts 中createGrokBuild()通过createACP构造器注册了一系列不可覆盖的实现细节version: v1、harnessId: grok-buildsource: { type: npm-locked, ... }将 bridge/package.json、pnpm-lock.yaml、pnpm-workspace.yaml在构建期以字符串常量注入__GROK_BUILD_IMPLEMENTATION_PACKAGE_JSON__等声明固定锁定xai-official/grok1.0.5及其依赖agentclientprotocol/sdk1.4.0、modelcontextprotocol/sdk1.30.0、ws8.21.0、zod4.4.3executable: grok默认启动参数[agent, stdio]即通过 stdio 启动 Grok Build 的 ACP 服务clientApp: { name: ai-sdk/harness-grok-build, version: VERSION }用于向服务端标识客户端。之所以要把 bridge 的清单文件在构建期注入正是 CHANGELOG 1.0.8 中a72aca4修复的内容——此前在运行时读取这些文件会在某些环境下报错。测试 grok-build-harness.test.ts 通过快照验证了 npm-locked 来源、pnpm-workspace.yaml的allowBuilds白名单仅放行xai-official/grok1.0.5、可执行文件与启动参数等全部固定配置。四、工具体系内置工具映射与 MCP 扩展适配器把 Grok Build 的原生工具映射为 Harness v1 通用工具commonTool并统一以GROK_BUILD_BUILTIN_TOOLS注册同文件 86-288 行包括bash原生run_terminal_command输入含command、timeout0~36,000,000ms、description、backgroundedit原生search_replace输入含file_path、old_string、new_string、replace_allgrep原生grep支持pattern、path、glob、-B/-A/-C、-i、head_limit等webSearch原生web_search支持query与allowed_domainswrite原生write输入file_pathcontent。其余 Grok Build 工具保留原生名称直接暴露包括read_file、list_dir、todo_write、kill_command_or_subagent、get_command_or_subagent_output、spawn_subagent、scheduler_create/delete/list、monitor、search_tool、use_tool、workflow、enter_plan_mode/exit_plan_mode以及图像能力image_gen、image_edit、image_to_video、reference_to_video。MCP 工具通过isMcpToolCall识别检查工具调用的_meta[x.ai/tool].namespace mcp。自 v1.0.1 起可通过mcpServers配置项为 Harness 挂载独立的 MCP 服务器配置格式沿用底层运行时原生格式例如{ external: { command: external-mcp } }。测试用例专门验证了 MCP 命名空间与自定义命名空间的判别逻辑。五、认证与凭据安全direct、AI Gateway、原生订阅认证解析是 CHANGELOG 中出现最频繁的主题之一最终形态在 grok-build-harness.ts 与 grok-build-subscription.ts 中落地1. 三种认证模式authdirect直接使用XAI_API_KEYai-gateway将 Gateway 凭据作为XAI_API_KEY注入并把 Gateway Base URL确保以/v1结尾映射为GROK_XAI_API_BASE_URL与GROK_MODELS_BASE_URL同时设置GROK_CLIENT_NAME、GROK_CLIENT_VERSION做客户端归因见providerAuthentication.gateway.env映射auto默认存在 Gateway 凭据时选 Gateway否则退回 direct此外auth还可直接传入一个隔离的认证环境对象如{ AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL }该记录会整体替换宿主环境用于认证发现——这正是 v1.0.29 的能力。2. 凭据代理credential brokering当沙箱支持出站请求变换时v1.0.8 引入、v1.0.27 用 ephemeral secret 加固适配器不会把真实XAI_API_KEY明文送入沙箱而是沙箱内使用占位符适配器通过createCredentialRequestTransformation把匹配到GROK_XAI_API_BASE_URL默认https://api.x.ai/v1且携带Authorization: Bearer sandbox占位的出站请求重写为携带宿主真实密钥及自定义 headers的请求当使用 CLI Chat ProxyGROK_CLI_CHAT_PROXY_BASE_URL时还会追加X-XAI-Token-Auth: xai-grok-cli头。测试中对这两种场景直连 xAI 与 cli-chat-proxy的变换结果均有断言。3. 原生订阅解析native subscription若宿主环境未设置任何可用凭据且未强制 GatewayresolveGrokBuildSubscriptionEnvironment会尝试读取~/.grok/auth.json可用GROK_HOME覆盖提取匹配固定XAI_CLIENT_ID的 OAuth 记录若访问令牌即将过期则走 OIDC discovery refresh token 刷新流程并原子写入更新后的auth.json临时文件 rename权限0o600。成功后回填XAI_API_KEY与三个GROK_*_BASE_URL环境变量指向https://cli-chat-proxy.grok.com/v1。4. 凭据转发控制credentialForwardingv1.0.24该回调在凭据进入沙箱进程前对每个值做定制接收将转发的值——真实值或掩码值——及环境变量名。文档明确强调它只控制进入沙箱的值不限制适配器在宿主进程中发现、读取或访问凭据的能力。六、推理强度与模型抽象v1.0.30 / v1.0.31 / v1.0.41reasoningEffortv1.0.30对具备推理能力的模型控制推理强度可选none、minimal、low、medium、high、xhigh、max。实现上直接追加到 ACP 启动参数[agent, --reasoning-effort, value, stdio]未设置时保持默认[agent, stdio]。model上移v1.0.30模型选择从各适配器构造器收敛到HarnessAgent统一参数v1.0.31 进一步允许通过 call options 在轮次间切换模型。适配器通过modelMapping: { type: session-model, path: modelId }把模型映射到 ACP 会话的modelId字段。API 清理v1.0.41彻底移除适配器设置中已废弃的model/modelId配置避免双重入口造成歧义。七、指令、结构化输出与用户提问v1.0.2 / v1.0.10 / v1.0.38 / v1.0.39指令注入v1.0.2 修复后instructions 以追加到 system/developer prompt 的方式传递而不是用首条 user prompt 变通。v1.0.39 引入writeInstructions辅助函数并支持基于文件系统的instructionsMapping——Grok Build 的实现是{ type: filesystem, path: .grok/AGENTS.md }即把指令写入沙箱内的.grok/AGENTS.md由 Grok Build 原生读取。结构化输出v1.0.10 通过HarnessAgent的output属性支持 schema 化输出其 profile 把 JSON Schema 映射到 Grok Build 私有 ACP prompt 元数据outputSchemaMapping: { type: session-prompt-meta, path: [outputSchema] }由运行时经 provider 的结构化输出机制强制执行。askUserQuestionsv1.0.38适配器实现了 ACP 的提问工具归一化grok-build-question-tool.ts把 Grok 原生_x.ai/ask_user_question请求转换为 Harness v1 的askUserQuestions工具调用支持多选、自由填写、default/plan两种模式响应侧支持accepted、cancelled、declined、skip_interview、chat_about_this等结局并通过问题指纹判断是否为同一提问的延续请求。自定义请求头v1.0.39headers属性允许为推理请求附加任意头但实现仅通过沙箱外请求变换生效——若沙箱不支持该能力自定义头会被忽略见下文限制。八、快速上手安装、沙箱与会话安装见 README.md 与官方文档 07-grok-build.mdxnpm install ai-sdk/harness ai-sdk/harness-grok-build ai-sdk/sandbox-vercel一个完整的最小调用示例import { HarnessAgent } from ai-sdk/harness/agent; import { grokBuild } from ai-sdk/harness-grok-build; import { createVercelSandbox } from ai-sdk/sandbox-vercel; const agent new HarnessAgent({ harness: grokBuild, model: grok-build-0.1, sandbox: createVercelSandbox({ runtime: node24, ports: [4000], // 至少暴露一个 TCP 端口给 ACP bridge }), }); const session await agent.createSession(); try { const result await agent.stream({ session, prompt: Check the test failures and fix the production code., }); for await (const part of result.stream) { if (part.type text-delta) { process.stdout.write(part.text); } } } finally { await session.destroy(); }要点首个会话启动时 ACP harness 会在沙箱内安装锁定的xai-official/grok1.0.5因此沙箱必须有网络出口运行前需为 Vercel Sandbox 设置VERCEL_OIDC_TOKEN并按认证模式配置XAI_API_KEY或AI_GATEWAY_API_KEY/AI_GATEWAY_BASE_URL。九、设置项一览createGrokBuild(settings)设置说明默认/取值auth认证模式或隔离认证环境auto有 Gateway 凭据选 Gateway否则 direct可选direct、ai-gateway、环境对象credentialForwarding进入沙箱前的凭据值定制回调无原样转发/代理reasoningEffort推理强度不设置则沿用 Grok Build 默认none/minimal/low/medium/high/xhigh/maxmcpServers按名称组织的 MCP 服务器定义无portACP bridge 端口覆盖自动分配portEndpoint连接沙箱 bridge 的宿主端点与port在 basic sandbox 会话下需成对提供startupTimeoutMs等待 ACP bridge 启动的最大毫秒数视 ACP 实现mintBridgeToken生成 bridge 认证令牌的回调默认随机 32 字节十六进制令牌headers附加到推理请求的任意请求头依赖沙箱请求变换能力其中grokBuild默认实例与createGrokBuild()完全等价官方文档建议用createGrokBuild({ auth: direct })/createGrokBuild({ auth: ai-gateway })在双凭据环境下强制路由。十、已知限制来自官方文档ACP v1 不暴露模型步边界与逐步用量适配器只能推断边界Grok 不提供总量时按未知逐步用量上报ACP v1 无便携的手动压缩与轮次中转向 APIACP v1 无内置工具过滤 API过滤宿主工具可行但过滤 Grok 内置工具会抛不支持的能力错误Grok Build 目前不支持内置工具审批请求应配合permissionMode: allow-all使用宿主执行的 AI SDK 工具审批仍可用宿主工具目录变更后需 Grok Build 刷新 ACP MCP 工具列表若实现保留了陈旧工具该轮次会显式失败自定义headers仅通过沙箱外请求变换生效无该能力的沙箱下会被忽略。十一、总结CHANGELOG 之外的工程启示ai-sdk/harness-grok-build的 CHANGELOG 之所以值得精读是因为它完整记录了在统一抽象之上适配一个外部 CLI 智能体的典型工程路径协议先行ACP、实现锁定npm-locked 构建期注入、凭据安全代理 ephemeral secret、能力分层认证/沙箱/工具/输出各自演进、API 收敛废弃项移除。对照 grok-build-harness.ts、grok-build-subscription.ts、grok-build-question-tool.ts 及 grok-build-harness.test.ts 的快照断言可以看到每一个 CHANGELOG 条目背后都有明确的代码落点与测试守护——这也是在 AI SDK 生态中新增一个 Harness 适配器时可复用的最佳实践模板。【免费下载链接】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），仅供参考 @ai-sdk/harness-grok-build 演进全解析：AI SDK 中基于 ACP 的 Grok Build Harness 适配器
ai-sdk/harness-grok-build 演进全解析AI SDK 中基于 ACP 的 Grok Build Harness 适配器【免费下载链接】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本篇文章以仓库中 packages/harness-grok-build/CHANGELOG.md 的版本记录为主线结合ai-sdk/harness-grok-build包的真实源码、测试与官方文档梳理该 Harness 适配器从 v1.0.0 诞生到 v1.0.44 的全部能力演进。读完本文你将理解Grok Build Harness 如何通过 Agent Client ProtocolACP把 Grok Build CLI 接入 AI SDK 的HarnessAgent每个版本引入的认证、沙箱、工具、结构化输出等能力是如何实现的以及如何在真实项目中完成安装、配置与调用。一、包定位Grok Build Harness 是什么ai-sdk/harness-grok-build是 AI SDK 中专门适配 Grok Build CLI 中的createACP({...})调用。从包的依赖关系package.json可以清晰看到这一分层运行时依赖ai-sdk/harnessHarness v1 抽象与内置工具定义、ai-sdk/harness-acpACP 协议实现、ai-sdk/provider-utils通用工具函数与 schema 解析对等依赖zod^3.25.76 || ^4.1.8用于工具输入 schema 的运行时校验引擎要求node 22。包入口src/index.ts导出了两个工厂形态import { createGrokBuild, grokBuild } from ai-sdk/harness-grok-build;其中grokBuild是默认实例等价于createGrokBuild()createGrokBuild(settings)用于按需定制运行时。VERSION通过构建期常量注入见 src/version.ts非构建环境回退为0.0.0-test测试快照亦验证了该回退行为。二、CHANGELOG 主线从 1.0.0 到 1.0.44 的能力演进CHANGELOG 记录了 44 个版本绝大多数是 Patch 级依赖同步跟随ai-sdk/harness与ai-sdk/harness-acp的版本推进但其中有若干带 commit 描述的行为变更构成了该适配器完整的能力时间线。下表按版本号汇总了所有非纯依赖同步的条目版本变更要点1.0.0首个 Major 版本基于 ACP 适配器新增 Grok Build Harness1.0.1支持按 Harness 独立配置 MCP servers新增可选mintBridgeToken(sandboxId)控制 bridge token1.0.2修复instructions 改为追加到 system/developer prompt而非用首条 user prompt 变通1.0.8网络沙箱支持请求变换并据此实现凭据代理credential brokering构建期注入 bridge 的package.json与pnpm-lock.yaml1.0.10HarnessAgent通过output属性支持结构化输出1.0.15HarnessAgentSession支持传入文件系统与进程受限的沙箱会话回退到网络沙箱方法1.0.24新增credentialForwarding设置细粒度控制转发进沙箱的凭据pnpm 11 沙箱引导时允许固定的 OpenCode 与 Grok Build 安装脚本1.0.27加固凭据代理仅在携带正确的一次性密钥ephemeral secret时才应用1.0.29auth选项支持从隔离环境认证会话移除废弃的 legacy auth 类型1.0.30Grok Build 适配器更新底层 SDK新增reasoningEffort控制model参数上移到HarnessAgent1.0.31支持通过 call options 在轮次之间切换model1.0.38支持askUserQuestions工具并在各 Harness 适配器间统一归一化1.0.39新增writeInstructions辅助函数ACP 类适配器支持基于文件系统的instructionsMappingHarnessAgentSettings新增headers属性透传任意请求头1.0.41移除废弃的model/modelId适配器配置这组条目恰好描绘出一个适配器从能用到生产可用的完整路径先是 ACP 协议打通1.0.0然后是 MCP、bridge token1.0.1与 prompt 注入方式修正1.0.2接着是沙箱凭据安全1.0.8/1.0.24/1.0.27再是结构化输出1.0.10、认证隔离1.0.29、推理强度控制与模型抽象1.0.30/1.0.31、用户提问工具1.0.38最后是指令映射与请求头透传1.0.39以及 API 清理1.0.41。三、v1.0.0 基础ACP 之上的固定实现在 grok-build-harness.ts 中createGrokBuild()通过createACP构造器注册了一系列不可覆盖的实现细节version: v1、harnessId: grok-buildsource: { type: npm-locked, ... }将 bridge/package.json、pnpm-lock.yaml、pnpm-workspace.yaml在构建期以字符串常量注入__GROK_BUILD_IMPLEMENTATION_PACKAGE_JSON__等声明固定锁定xai-official/grok1.0.5及其依赖agentclientprotocol/sdk1.4.0、modelcontextprotocol/sdk1.30.0、ws8.21.0、zod4.4.3executable: grok默认启动参数[agent, stdio]即通过 stdio 启动 Grok Build 的 ACP 服务clientApp: { name: ai-sdk/harness-grok-build, version: VERSION }用于向服务端标识客户端。之所以要把 bridge 的清单文件在构建期注入正是 CHANGELOG 1.0.8 中a72aca4修复的内容——此前在运行时读取这些文件会在某些环境下报错。测试 grok-build-harness.test.ts 通过快照验证了 npm-locked 来源、pnpm-workspace.yaml的allowBuilds白名单仅放行xai-official/grok1.0.5、可执行文件与启动参数等全部固定配置。四、工具体系内置工具映射与 MCP 扩展适配器把 Grok Build 的原生工具映射为 Harness v1 通用工具commonTool并统一以GROK_BUILD_BUILTIN_TOOLS注册同文件 86-288 行包括bash原生run_terminal_command输入含command、timeout0~36,000,000ms、description、backgroundedit原生search_replace输入含file_path、old_string、new_string、replace_allgrep原生grep支持pattern、path、glob、-B/-A/-C、-i、head_limit等webSearch原生web_search支持query与allowed_domainswrite原生write输入file_pathcontent。其余 Grok Build 工具保留原生名称直接暴露包括read_file、list_dir、todo_write、kill_command_or_subagent、get_command_or_subagent_output、spawn_subagent、scheduler_create/delete/list、monitor、search_tool、use_tool、workflow、enter_plan_mode/exit_plan_mode以及图像能力image_gen、image_edit、image_to_video、reference_to_video。MCP 工具通过isMcpToolCall识别检查工具调用的_meta[x.ai/tool].namespace mcp。自 v1.0.1 起可通过mcpServers配置项为 Harness 挂载独立的 MCP 服务器配置格式沿用底层运行时原生格式例如{ external: { command: external-mcp } }。测试用例专门验证了 MCP 命名空间与自定义命名空间的判别逻辑。五、认证与凭据安全direct、AI Gateway、原生订阅认证解析是 CHANGELOG 中出现最频繁的主题之一最终形态在 grok-build-harness.ts 与 grok-build-subscription.ts 中落地1. 三种认证模式authdirect直接使用XAI_API_KEYai-gateway将 Gateway 凭据作为XAI_API_KEY注入并把 Gateway Base URL确保以/v1结尾映射为GROK_XAI_API_BASE_URL与GROK_MODELS_BASE_URL同时设置GROK_CLIENT_NAME、GROK_CLIENT_VERSION做客户端归因见providerAuthentication.gateway.env映射auto默认存在 Gateway 凭据时选 Gateway否则退回 direct此外auth还可直接传入一个隔离的认证环境对象如{ AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL }该记录会整体替换宿主环境用于认证发现——这正是 v1.0.29 的能力。2. 凭据代理credential brokering当沙箱支持出站请求变换时v1.0.8 引入、v1.0.27 用 ephemeral secret 加固适配器不会把真实XAI_API_KEY明文送入沙箱而是沙箱内使用占位符适配器通过createCredentialRequestTransformation把匹配到GROK_XAI_API_BASE_URL默认https://api.x.ai/v1且携带Authorization: Bearer sandbox占位的出站请求重写为携带宿主真实密钥及自定义 headers的请求当使用 CLI Chat ProxyGROK_CLI_CHAT_PROXY_BASE_URL时还会追加X-XAI-Token-Auth: xai-grok-cli头。测试中对这两种场景直连 xAI 与 cli-chat-proxy的变换结果均有断言。3. 原生订阅解析native subscription若宿主环境未设置任何可用凭据且未强制 GatewayresolveGrokBuildSubscriptionEnvironment会尝试读取~/.grok/auth.json可用GROK_HOME覆盖提取匹配固定XAI_CLIENT_ID的 OAuth 记录若访问令牌即将过期则走 OIDC discovery refresh token 刷新流程并原子写入更新后的auth.json临时文件 rename权限0o600。成功后回填XAI_API_KEY与三个GROK_*_BASE_URL环境变量指向https://cli-chat-proxy.grok.com/v1。4. 凭据转发控制credentialForwardingv1.0.24该回调在凭据进入沙箱进程前对每个值做定制接收将转发的值——真实值或掩码值——及环境变量名。文档明确强调它只控制进入沙箱的值不限制适配器在宿主进程中发现、读取或访问凭据的能力。六、推理强度与模型抽象v1.0.30 / v1.0.31 / v1.0.41reasoningEffortv1.0.30对具备推理能力的模型控制推理强度可选none、minimal、low、medium、high、xhigh、max。实现上直接追加到 ACP 启动参数[agent, --reasoning-effort, value, stdio]未设置时保持默认[agent, stdio]。model上移v1.0.30模型选择从各适配器构造器收敛到HarnessAgent统一参数v1.0.31 进一步允许通过 call options 在轮次间切换模型。适配器通过modelMapping: { type: session-model, path: modelId }把模型映射到 ACP 会话的modelId字段。API 清理v1.0.41彻底移除适配器设置中已废弃的model/modelId配置避免双重入口造成歧义。七、指令、结构化输出与用户提问v1.0.2 / v1.0.10 / v1.0.38 / v1.0.39指令注入v1.0.2 修复后instructions 以追加到 system/developer prompt 的方式传递而不是用首条 user prompt 变通。v1.0.39 引入writeInstructions辅助函数并支持基于文件系统的instructionsMapping——Grok Build 的实现是{ type: filesystem, path: .grok/AGENTS.md }即把指令写入沙箱内的.grok/AGENTS.md由 Grok Build 原生读取。结构化输出v1.0.10 通过HarnessAgent的output属性支持 schema 化输出其 profile 把 JSON Schema 映射到 Grok Build 私有 ACP prompt 元数据outputSchemaMapping: { type: session-prompt-meta, path: [outputSchema] }由运行时经 provider 的结构化输出机制强制执行。askUserQuestionsv1.0.38适配器实现了 ACP 的提问工具归一化grok-build-question-tool.ts把 Grok 原生_x.ai/ask_user_question请求转换为 Harness v1 的askUserQuestions工具调用支持多选、自由填写、default/plan两种模式响应侧支持accepted、cancelled、declined、skip_interview、chat_about_this等结局并通过问题指纹判断是否为同一提问的延续请求。自定义请求头v1.0.39headers属性允许为推理请求附加任意头但实现仅通过沙箱外请求变换生效——若沙箱不支持该能力自定义头会被忽略见下文限制。八、快速上手安装、沙箱与会话安装见 README.md 与官方文档 07-grok-build.mdxnpm install ai-sdk/harness ai-sdk/harness-grok-build ai-sdk/sandbox-vercel一个完整的最小调用示例import { HarnessAgent } from ai-sdk/harness/agent; import { grokBuild } from ai-sdk/harness-grok-build; import { createVercelSandbox } from ai-sdk/sandbox-vercel; const agent new HarnessAgent({ harness: grokBuild, model: grok-build-0.1, sandbox: createVercelSandbox({ runtime: node24, ports: [4000], // 至少暴露一个 TCP 端口给 ACP bridge }), }); const session await agent.createSession(); try { const result await agent.stream({ session, prompt: Check the test failures and fix the production code., }); for await (const part of result.stream) { if (part.type text-delta) { process.stdout.write(part.text); } } } finally { await session.destroy(); }要点首个会话启动时 ACP harness 会在沙箱内安装锁定的xai-official/grok1.0.5因此沙箱必须有网络出口运行前需为 Vercel Sandbox 设置VERCEL_OIDC_TOKEN并按认证模式配置XAI_API_KEY或AI_GATEWAY_API_KEY/AI_GATEWAY_BASE_URL。九、设置项一览createGrokBuild(settings)设置说明默认/取值auth认证模式或隔离认证环境auto有 Gateway 凭据选 Gateway否则 direct可选direct、ai-gateway、环境对象credentialForwarding进入沙箱前的凭据值定制回调无原样转发/代理reasoningEffort推理强度不设置则沿用 Grok Build 默认none/minimal/low/medium/high/xhigh/maxmcpServers按名称组织的 MCP 服务器定义无portACP bridge 端口覆盖自动分配portEndpoint连接沙箱 bridge 的宿主端点与port在 basic sandbox 会话下需成对提供startupTimeoutMs等待 ACP bridge 启动的最大毫秒数视 ACP 实现mintBridgeToken生成 bridge 认证令牌的回调默认随机 32 字节十六进制令牌headers附加到推理请求的任意请求头依赖沙箱请求变换能力其中grokBuild默认实例与createGrokBuild()完全等价官方文档建议用createGrokBuild({ auth: direct })/createGrokBuild({ auth: ai-gateway })在双凭据环境下强制路由。十、已知限制来自官方文档ACP v1 不暴露模型步边界与逐步用量适配器只能推断边界Grok 不提供总量时按未知逐步用量上报ACP v1 无便携的手动压缩与轮次中转向 APIACP v1 无内置工具过滤 API过滤宿主工具可行但过滤 Grok 内置工具会抛不支持的能力错误Grok Build 目前不支持内置工具审批请求应配合permissionMode: allow-all使用宿主执行的 AI SDK 工具审批仍可用宿主工具目录变更后需 Grok Build 刷新 ACP MCP 工具列表若实现保留了陈旧工具该轮次会显式失败自定义headers仅通过沙箱外请求变换生效无该能力的沙箱下会被忽略。十一、总结CHANGELOG 之外的工程启示ai-sdk/harness-grok-build的 CHANGELOG 之所以值得精读是因为它完整记录了在统一抽象之上适配一个外部 CLI 智能体的典型工程路径协议先行ACP、实现锁定npm-locked 构建期注入、凭据安全代理 ephemeral secret、能力分层认证/沙箱/工具/输出各自演进、API 收敛废弃项移除。对照 grok-build-harness.ts、grok-build-subscription.ts、grok-build-question-tool.ts 及 grok-build-harness.test.ts 的快照断言可以看到每一个 CHANGELOG 条目背后都有明确的代码落点与测试守护——这也是在 AI SDK 生态中新增一个 Harness 适配器时可复用的最佳实践模板。【免费下载链接】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），仅供参考