AI SDK Harness 依赖更新指南掌握 harness 包 SDK 依赖的升级、桥接同步与一致性校验【免费下载链接】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 SDKThe AI Toolkit for TypeScript仓库的维护者与贡献者系统讲解如何安全、规范地更新packages/harness-*系列包所依赖的第三方 Agent SDK如 Claude Code、Codex、ACP、Pi 等。你将掌握两套更新命令的适用场景workspace 内更新 vs. bridge 独立目录更新、minimumReleaseAge发布年龄门槛的约束逻辑、需要同步维护的allowBuilds与示例工程依赖以及如何用仓库自带的验证脚本一次跑通全部一致性检查。一、为什么要维护 harness 依赖适配器与主 SDK 的关系在 AI SDK 仓库中packages/harness-*目录下的包统称为 harness 适配器harness adapter它们把各类外部 Agent 工具Claude Code、Codex、OpenCode、Pi、GitHub Copilot、Grok Build 等封装成统一的ai-sdk/harness抽象供上层应用以一致的接口调用。每个适配器都直接依赖对应 Agent 的主 SDKprimary SDKharness-claude-code→anthropic-ai/claude-agent-sdkharness-codex→openai/codex-sdkharness-cline→cline/agentsharness-pi→earendil-works/pi-coding-agentharness-github-copilot→github/copilotharness-grok-build→xai-official/grokharness-opencode→opencode-ai/sdk这些主 SDK 上游迭代频繁适配器必须紧跟版本才能兼容新能力并修复缺陷。仓库通过 pnpm-workspace.yaml 中的minimumReleaseAge: 4320即 4320 分钟 3 天来约束依赖包发布未满 3 天时禁止升级避免把刚发布、尚未充分验证的版本引入仓库。从 packages/harness-pi/package.json 可以看出非 bridge 适配器的典型结构earendil-works/pi-coding-agent与pi-mcp-adapter等直接声明在dependencies中而 packages/harness-claude-code/package.json 中anthropic-ai/claude-agent-sdk和modelcontextprotocol/sdk则出现在devDependencies——这正体现了bridge 型适配器与非 bridge 型适配器的关键区别下一节展开。二、两种更新模式workspace 包 vs. bridge 独立包1. 为什么 bridge 需要单独处理一部分 harness 适配器如 Claude Code、Codex、ACP、OpenCode、Deep Agents 等采用bridge桥接架构适配器本体通过进程桥接方式启动外部 Agent CLI而 bridge 子目录如packages/harness-claude-code/src/bridge是独立的最小 pnpm 工程拥有自己的package.json和pnpm-lock.yaml用于精确锁定运行时实际加载的 SDK 版本。因此更新逻辑分两层适配器包本体bridge 型适配器把主 SDK 放在devDependencies编译期类型与测试用真正对运行时生效的版本由 bridge 自己决定非 bridge 型适配器如 Pi则直接把主 SDK 放在dependencies由 workspace 统一解析。bridge 子工程必须单独在src/bridge或src/v1/bridge目录下执行pnpm update且由于该目录不在 workspace 配置的packages列表内需要--ignore-workspace标志绕过 workspace 校验并手动指定与仓库一致的minimumReleaseAge。2. 第一步更新 workspace 内的 harness 主 SDK在仓库根目录按以下命令逐个更新务必原样执行--latest升到最新版本--lockfile-only只改 lockfile 不动 node_modules# ACP pnpm --filter harness-acp update agentclientprotocol/sdk modelcontextprotocol/sdk --latest --lockfile-only # Claude Code pnpm --filter harness-claude-code update anthropic-ai/claude-agent-sdk modelcontextprotocol/sdk --latest --lockfile-only # Cline pnpm --filter harness-cline update cline/agents --latest --lockfile-only # Codex pnpm --filter harness-codex update openai/codex-sdk --latest --lockfile-only # Deep Agents pnpm --filter harness-deepagents update langchain/core langchain/langgraph deepagents langchain langsmith --latest --lockfile-only # GitHub Copilot pnpm --filter harness-github-copilot update github/copilot --latest --lockfile-only # Grok Build pnpm --filter harness-grok-build update xai-official/grok --latest --lockfile-only # OpenCode pnpm --filter harness-opencode update opencode-ai/sdk --latest --lockfile-only # Pi pnpm --filter harness-pi update earendil-works/pi-coding-agent --latest --lockfile-only要点说明--filter harness-acp等过滤词对应各包的目录名即packages/harness-acppnpm 会自动映射Deep Agents 一次更新 5 个 LangChain 系包因为它们彼此存在 peer 约束必须同步升级此阶段 workspace 内minimumReleaseAge: 4320会自动生效无需手动传参。3. 第二步更新 bridge 子工程的依赖bridge 型适配器需要额外在 bridge 目录内执行更新。此时必须显式传入--config.minimumReleaseAge4320与 pnpm-workspace.yaml 中定义的 4320 保持一致因为--ignore-workspace会使 workspace 配置失效# ACP pnpm --dir packages/harness-acp/src/v1/bridge update agentclientprotocol/sdk modelcontextprotocol/sdk --latest --ignore-workspace --config.minimumReleaseAge4320 # Claude Code pnpm --dir packages/harness-claude-code/src/bridge update anthropic-ai/claude-agent-sdk anthropic-ai/claude-code modelcontextprotocol/sdk --latest --ignore-workspace --config.minimumReleaseAge4320 # Codex pnpm --dir packages/harness-codex/src/bridge update openai/codex-sdk --latest --ignore-workspace --config.minimumReleaseAge4320 # Deep Agents pnpm --dir packages/harness-deepagents/src/bridge update langchain/anthropic langchain/core langchain/langgraph deepagents langchain langsmith --latest --ignore-workspace --config.minimumReleaseAge4320 # GitHub Copilot pnpm --dir packages/harness-github-copilot/src/bridge update github/copilot --latest --ignore-workspace --config.minimumReleaseAge4320 # Grok Build pnpm --dir packages/harness-grok-build/src/bridge update agentclientprotocol/sdk modelcontextprotocol/sdk xai-official/grok --latest --ignore-workspace --config.minimumReleaseAge4320 # OpenCode pnpm --dir packages/harness-opencode/src/bridge update opencode-ai/sdk opencode-ai --latest --ignore-workspace --config.minimumReleaseAge4320注意与第一步的差异命令以--dir packages/.../bridge而非--filter定位工程--ignore-workspace跳过 workspace 校验因此必须手动带--config.minimumReleaseAge4320维持发布年龄门槛Claude Code 额外包含anthropic-ai/claude-codeCLI 包OpenCode 额外包含opencode-aiCLI 包Grok Build 的 bridge 还引入了agentclientprotocol/sdk与modelcontextprotocol/sdk。以 packages/harness-claude-code/src/bridge/package.json 为例更新后anthropic-ai/claude-agent-sdk、anthropic-ai/claude-code、modelcontextprotocol/sdk三个版本号应保持一致并写入dependencies。三、同步维护 allowBuilds 白名单某些 bridge CLI 包Claude Code、GitHub Copilot、Grok Build、OpenCode安装时依赖 install scripts 编译/下载二进制而仓库根 pnpm-workspace.yaml 默认通过allowBuilds控制构建脚本白名单。bridge 子工程有自己的pnpm-workspace.yaml必须以精确版本exact version同步更新allowBuilds条目否则升级后 pnpm 会因安全策略拒绝执行安装脚本导致 CLI 无法运行packages/harness-claude-code/src/bridge/pnpm-workspace.yamlpackages/harness-github-copilot/src/bridge/pnpm-workspace.yamlpackages/harness-grok-build/src/bridge/pnpm-workspace.yamlpackages/harness-opencode/src/bridge/pnpm-workspace.yaml例如 Claude Code 的 bridge 文件中当前为allowBuilds: anthropic-ai/claude-code2.1.245: true当 bridge 的package.json中anthropic-ai/claude-code升到新版本时这里的2.1.245必须同步替换为相同的新版本号注意allowBuilds键中带版本号的精确匹配写法与根 workspace 中按包名声明的方式不同。另外有两个适配器可以跳过全部更新流程packages/harness-cursor和packages/harness-fx使用无版本号的安装脚本unversioned installer script而不是 NPM 包作为其 SDK/CLI不存在可更新的依赖声明。四、示例工程的依赖对齐仓库中的端到端示例工程直接引用了部分主 SDK其版本必须与各 harness 包中实际使用的版本保持一致否则示例运行时会与适配器产生版本错位examples/harness-e2e-next/package.json声明了cline/agents、earendil-works/pi-coding-agent、xai-official/grok、agentclientprotocol/claude-agent-acp、agentclientprotocol/codex-acp等多个 SDKexamples/harness-e2e-tui/package.json声明了earendil-works/pi-coding-agent。检查这两个package.json中与上述 SDK 相关的依赖项将版本号更新为与对应 harness 包使用一致的精确版本。五、验证运行一致性校验脚本完成所有更新后运行仓库自带的验证脚本./tools/verify-harness-adapter-deps.mjs该脚本tools/verify-harness-adapter-deps.mjs基于adapterConfigs配置表自动完成四类检查配置完整性遍历packages/harness-*/package.json若存在未在adapterConfigs中登记配置的适配器包则直接报错防止新增适配器漏配主 SDK 声明检查每个配置了primarySdk的适配器必须在dependencies/devDependencies/optionalDependencies中声明该 SDK且已安装版本必须满足声明范围使用 semver 校验peer 兼容性校验读取已安装主 SDK 的peerDependencies逐一比对适配器包本体与 bridge 子工程声明的 SDK 范围semver.subset确保声明的版本范围是主 SDK 支持范围的子集版本对齐校验对存在 bridge 清单的适配器比对适配器包与 bridge 中主 SDK 的版本是否完全一致避免两侧漂移。若脚本输出错误以✖开头分组列出必须逐条修复后重跑直到输出✓ Verified SDK peer compatibility for N harness adapter manifest(s).与✓ Verified primary SDK versions match across bridge manifests.两条成功信息为止。六、完整更新流程速查一次完整的 harness 依赖升级可以归纳为以下五步在仓库根目录执行第一步的 9 条pnpm --filter ... update命令更新各适配器主 SDK--lockfile-onlyworkspace 内自动受minimumReleaseAge4320约束对 bridge 型适配器在其src/bridge或src/v1/bridge目录执行第二步的命令带--ignore-workspace --config.minimumReleaseAge4320更新运行时依赖对需要 install scripts 的 bridge CLI 包同步更新对应src/bridge/pnpm-workspace.yaml中allowBuilds的精确版本号检查 examples/harness-e2e-next/package.json 与 examples/harness-e2e-tui/package.json把示例工程中的 SDK 版本对齐到各包实际版本运行./tools/verify-harness-adapter-deps.mjs直至全部校验通过。这套流程既保证了 workspace 层 lockfile 的版本记录又让 bridge 运行时使用的 SDK 版本精确可控同时通过minimumReleaseAge守住了“新版本至少发布 3 天”的稳定性底线是维护 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），仅供参考