企业官网建设流程全解析

@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 Protocol（ACP）把 Grok Build CLI 接入 AI SDK 的HarnessAgent，每个版本引入的认证、沙箱、工具、结构化输出等能力是如何实现的，以及如何在真实项目中完成安装、配置与调用。

一、包定位：Grok Build Harness 是什么

@ai-sdk/harness-grok-build是 AI SDK 中专门适配 Grok Build CLI 中的createACP({...})调用）。

从包的依赖关系（package.json）可以清晰看到这一分层：

• 运行时依赖：@ai-sdk/harness（Harness v1 抽象与内置工具定义）、@ai-sdk/harness-acp（ACP 协议实现）、@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 描述的行为变更，构成了该适配器完整的能力时间线。下表按版本号汇总了所有非纯依赖同步的条目：

这组条目恰好描绘出一个适配器从"能用"到"生产可用"的完整路径：先是 ACP 协议打通（1.0.0），然后是 MCP、bridge token（1.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-build'；
• source: { type: 'npm-locked', ... }：将 bridge/package.json、pnpm-lock.yaml、pnpm-workspace.yaml在构建期以字符串常量注入（__GROK_BUILD_IMPLEMENTATION_PACKAGE_JSON__等声明），固定锁定@xai-official/grok@1.0.5及其依赖（@agentclientprotocol/sdk@1.4.0、@modelcontextprotocol/sdk@1.30.0、ws@8.21.0、zod@4.4.3）；
• executable: '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/grok@1.0.5）、可执行文件与启动参数等全部固定配置。

四、工具体系：内置工具映射与 MCP 扩展

适配器把 Grok Build 的原生工具映射为 Harness v1 通用工具（commonTool），并统一以GROK_BUILD_BUILTIN_TOOLS注册（同文件 86-288 行），包括：

• bash（原生run_terminal_command，输入含command、timeout（0~36,000,000ms）、description、background）；
• edit（原生search_replace，输入含file_path、old_string、new_string、replace_all）；
• grep（原生grep，支持pattern、path、glob、-B/-A/-C、-i、head_limit等）；
• webSearch（原生web_search，支持query与allowed_domains）；
• write（原生write，输入file_path+content）。

其余 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. 三种认证模式（auth）

• direct：直接使用XAI_API_KEY；
• ai-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 Proxy（GROK_CLI_CHAT_PROXY_BASE_URL）时，还会追加X-XAI-Token-Auth: xai-grok-cli头。测试中对这两种场景（直连 xAI 与 cli-chat-proxy）的变换结果均有断言。

3. 原生订阅解析（native subscription）

若宿主环境未设置任何可用凭据且未强制 Gateway，resolveGrokBuildSubscriptionEnvironment会尝试读取~/.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. 凭据转发控制（credentialForwarding，v1.0.24）

该回调在凭据进入沙箱进程前对每个值做定制（接收将转发的值——真实值或掩码值——及环境变量名）。文档明确强调：它只控制进入沙箱的值，不限制适配器在宿主进程中发现、读取或访问凭据的能力。

六、推理强度与模型抽象（v1.0.30 / v1.0.31 / v1.0.41）

• reasoningEffort（v1.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 的结构化输出机制强制执行。
• askUserQuestions（v1.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.39）：headers属性允许为推理请求附加任意头，但实现仅通过沙箱外请求变换生效——若沙箱不支持该能力，自定义头会被忽略（见下文限制）。

八、快速上手：安装、沙箱与会话

安装（见 README.md 与官方文档 07-grok-build.mdx）：

npm 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/grok@1.0.5，因此沙箱必须有网络出口；运行前需为 Vercel Sandbox 设置VERCEL_OIDC_TOKEN，并按认证模式配置XAI_API_KEY或AI_GATEWAY_API_KEY/AI_GATEWAY_BASE_URL。

九、设置项一览（createGrokBuild(settings)）

其中grokBuild（默认实例）与createGrokBuild()完全等价；官方文档建议用createGrokBuild({ auth: 'direct' })/createGrokBuild({ auth: 'ai-gateway' })在双凭据环境下强制路由。

十、已知限制（来自官方文档）

• ACP v1 不暴露模型步边界与逐步用量，适配器只能推断边界，Grok 不提供总量时按未知逐步用量上报；
• ACP v1 无便携的手动压缩与轮次中转向 API；
• ACP 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