AI 工具兼容

本文关注 Claude Code、Codex、OpenCode 一类现有 AI 工具如何接到 AaaS，而不是要求它们使用同一套内部代理循环。工具映射相关规范见 ACP Profile、AG-UI Profile、MCP Server Profile、Run 和 Interaction Request。

为什么要兼容现有工具

很多团队已经在使用成熟的 AI coding tool 或终端代理工具。平台如果要求“先重写、再接入”，迁移成本会非常高，也会破坏工具本身已经验证过的人机协作体验。

因此，AaaS 更合理的方向是：

• 兼容现有工具的交互模型
• 兼容现有工具已经广泛使用的协议面
• 托管现有工具的执行环境
• 收敛其运行事实、审计事实和治理能力

工具协议怎么选

对于现有 AI 工具，协议选择通常遵循下面的分工：

• ACP
  • 适合终端、文件系统、权限确认和长会话原生的工具
• AG-UI
  • 适合 Web、IDE 或聊天前端一类事件流界面
• A2A
  • 适合工具本身要作为远端 Agent 被发现、委派或协作
• MCP
  • 适合工具或能力服务以 McpServer 形式暴露能力目录、prompts/resources 和托管 session

一个成熟平台往往会同时支持多种协议面，但内部仍然共享同一套 Run 与 InteractionRequest 语义。

四种兼容模式

工具作为客户端

适合 CLI、IDE 扩展或 Web 前端直接触发任务的场景。

• 工具负责采集用户输入
• 平台负责创建 Run
• 流式输出回到工具 UI
• 工具本身不需要成为平台 runtime

工具作为托管 runtime

适合 Claude Code、Codex、OpenCode 一类终端原生、文件系统原生、长会话原生的工具。

• 平台准备 Sandbox 或其他执行环境
• 工具进程在受控环境中运行
• 工具通过 Runtime Connection 协议收输入、发输出、上报心跳
• 平台负责权限、网络、Secret、Checkpoint 和回收

工具作为 Tool Adapter

适合已有独立能力服务或 MCP Server 的场景。

• 平台 Agent 把某个外部 AI 工具当成一个 Tool
• Tool 调用结果回写到同一条 Run 事件流
• 外部工具不需要直接理解 Run 生命周期

工具作为 MCP Server

适合已有 MCP 目录、prompts/resources 语义，或希望以 server-first 方式接入平台的场景。

• 平台把外部能力注册为独立的 McpServer
• McpServerRevision 承载 tool catalog、运行画像和 MCP capability
• Agent 可通过引用 McpServer 暴露能力，或直接创建托管 MCP session run

工具作为 Runtime Connection Peer

适合需要双向流式、长期连接、可恢复会话的高级集成。

• 工具实现平台 runtime connection 能力
• 平台和工具共享心跳、恢复、KV、Config、Secrets 等语义
• 最终输出统一进入平台事件与 Trace 平面

常见 AI 工具的接入判断

不要先按品牌名判断，而应先按运行形态判断：

工具形态	典型例子	推荐模式	平台要重点补的能力
终端原生 coding tool	Claude Code、Codex、OpenCode	托管 runtime 或 Runtime Connection Peer	Sandbox、文件系统、PTY、Checkpoint、审计
IDE / Web 交互工具	IDE 扩展、聊天前端	工具作为客户端	Run 创建、事件流、身份鉴权、会话继续
MCP Server 或独立能力服务	搜索、浏览器、检索、代码分析服务	MCP Server 或 Tool Adapter	MCP server 治理、调用留痕、限流、权限边界

品牌只是入口，真正决定接入方式的是工具是否需要长期会话、是否直接操作本地工作区、以及是否需要被平台托管运行。

Claude Code、Codex、OpenCode 这类工具的共同特点

这类工具通常具备下面的运行特征：

• 强依赖终端、文件系统和进程执行
• 需要较长的交互会话，而不是一次无状态调用
• 常常会操作 Git、包管理器、测试框架和本地项目目录
• 既有自然语言输出，也有结构化动作，例如命令执行、文件修改和测试结果

这正是 AaaS 适合作为托管层的原因。平台可以在不改变工具核心交互体验的前提下，补齐这些工具本来欠缺的平台能力。

平台需要补上的能力

运行环境托管

• 为每次任务创建工作区或复用会话工作区
• 统一镜像、依赖缓存、网络边界和工具白名单
• 给运行进程分配 TTL、心跳和受控释放策略

事件归一化

• 把自然语言输出映射成消息事件
• 把命令执行、文件操作、测试结果映射成工具调用、Artifact 或活动消息
• 把关键状态变化映射到标准运行状态和 Span

安全与治理

• 统一 Secret 注入与最小权限控制
• 统一模型供应商访问策略和审计记录
• 统一输出留痕和内容捕获策略

统一交互阻塞

• 把权限确认、补充输入、继续执行确认统一映射为 InteractionRequest
• 让 CLI、IDE、Web UI 和审计系统看到同一个阻塞原因和同一份解决结果

继续执行与恢复

• 同一个 coding task 可以继续会话，而不是每次都冷启动
• 工具异常退出后，平台仍然保留 Run、Artifact、Checkpoint 和 Trace 事实

推荐的适配边界

不要试图把每个工具的内部动作完全重写为平台私有 API。更稳妥的方式是：

• 保留工具自己的 agent loop
• 只把平台需要治理的边界适配出来
• 让工具继续以它最擅长的交互方式工作
• 让平台统一负责生命周期、隔离、观测和审计

一个 coding agent 的典型接入形态

1. 控制面选择某个 Agent 或 Tool，并解析到确定 revision 与 execution profile
2. Provider 创建 Sandbox RunSpace，并由平台创建对应 Session，准备好工作区和依赖
3. Claude Code、Codex 或 OpenCode 进程在其中启动
4. runtime attach 到平台，建立 RuntimeConnection 并绑定当前 Session，领取用户输入和上下文
5. 工具运行期间持续输出消息、活动、Artifact 和 Trace
6. 平台根据策略保留会话、生成 Checkpoint 或释放环境

兼容性边界

平台并不要求这些工具：

• 使用同一个模型供应商
• 使用同一种 Prompt 模板
• 使用同一种规划策略
• 使用同一套内部工具协议

平台真正要求的是：

• 能被纳入统一的 Run 生命周期
• 能把审批、补充输入、鉴权和确认映射到统一交互模型
• 能提供可恢复的会话和可观测的执行事实
• 能接受受控的 Secret、Config、网络和工具边界

相关规范

• Run
• Session
• Tracing