在AI SDK harness层中使用兼容ACP的harness
内容提要
AI SDK新增@ai-sdk/harness-acp包，支持任何兼容Agent Client Protocol（ACP）的harness。该包作为元适配器，通过createACP配置harness映射，实现如Codex等ACP兼容包的无缝集成。但建议Claude Code和Codex优先使用直接适配器，仅在无直接适配器时使用ACP方案。
延伸解读
元适配器的定位
该包不是直接适配某个具体工具，而是包装ACP协议本身，因此任何提供ACP兼容包的harness都能通过createACP快速接入。这种设计减少了为每个工具单独编写适配器的工作量，但同时也意味着集成深度取决于ACP协议对工具内部行为的暴露程度。
适用场景与选择建议
文章明确指出，对于Claude Code和Codex这类已有直接适配器的工具，应优先使用直接适配器，因为直接适配能更紧密地集成工具的内部特性。ACP方案更适合那些没有直接适配器但提供ACP兼容包的harness，此时它提供了一种标准化的接入途径。
配置要点
实现ACP harness时，需要配置harnessId、npm包来源、可执行文件、环境变量转发、权限模式映射和认证方式。这些配置项直接对应ACP协议的要求，确保harness能正确启动和通信。示例中展示了如何为Codex配置API密钥认证和权限模式，但实际使用时需根据目标harness的ACP包文档调整。
Q&A
AI SDK的harness层如何支持ACP兼容的harness？
AI SDK通过新增的@ai-sdk/harness-acp包支持任何兼容Agent Client Protocol（ACP）的harness。该包是一个元适配器，通过createACP函数配置harness映射，将ACP兼容包集成到HarnessAgent中。
如何使用@ai-sdk/harness-acp包实现一个自定义的ACP harness？
首先导入createACP，然后传入harnessId、source（指定npm包）、executable、forwardEnv、permissionModeMapping和authentication等配置，最后将返回的harness传递给HarnessAgent。
为什么建议Claude Code和Codex优先使用直接适配器而不是ACP方案？
因为ACP是编码harness的抽象，但AI SDK的harness层刻意与其解耦。并非所有harness都支持ACP，且ACP可能限制或改变harness内部行为的暴露方式，直接适配器能提供更紧密的集成。
在什么情况下应该使用@ai-sdk/harness-acp包？
当某个harness没有直接适配器，但提供了ACP兼容包时，应使用@ai-sdk/harness-acp包。
createACP函数中的permissionModeMapping配置有什么作用？
permissionModeMapping用于将harness的权限模式映射到ACP的会话模式，例如将'allow-all'映射为'session-mode'的'agent-full-access'，以控制harness的权限级别。
AI SDK的harness层与ACP的关系是什么？
AI SDK的harness层刻意与ACP解耦，不直接依赖ACP。它通过@ai-sdk/harness-acp包作为元适配器，将ACP兼容的harness集成到HarnessAgent中，但并非所有harness都支持ACP。
