主题
AI 工具兼容
本文关注 Claude Code、Codex、OpenCode 一类现有 AI 工具如何接到 AaaS，而不是要求它们使用同一套内部代理循环。工具映射相关规范见 MCP Mapping、Runtime Session Protocol 和 Run。
为什么要兼容现有工具
很多团队已经在使用成熟的 AI coding tool 或终端代理工具。平台如果要求“先重写、再接入”，迁移成本会非常高，也会破坏工具本身已经验证过的人机协作体验。
因此，AaaS 更合理的方向是：
- 兼容现有工具的交互模型
- 托管现有工具的执行环境
- 收敛其运行事实、审计事实和治理能力
四种兼容模式
工具作为客户端
适合 CLI、IDE 扩展或 Web 前端直接触发任务的场景。
- 工具负责采集用户输入
- 平台负责创建
Run - 流式输出回到工具 UI
- 工具本身不需要成为平台 runtime
工具作为托管 runtime
适合 Claude Code、Codex、OpenCode 一类终端原生、文件系统原生、长会话原生的工具。
- 平台准备 Sandbox 或其他执行环境
- 工具进程在受控环境中运行
- 工具通过 Session 协议收输入、发输出、上报心跳
- 平台负责权限、网络、Secret、Checkpoint 和回收
工具作为 Tool Adapter
适合已有独立能力服务或 MCP Server 的场景。
- 平台 Agent 把某个外部 AI 工具当成一个 Tool
- Tool 调用结果回写到同一条 Run 事件流
- 外部工具不需要直接理解 Run 生命周期
工具作为 Session Peer
适合需要双向流式、长期连接、可恢复会话的高级集成。
- 工具实现平台 runtime session 能力
- 平台和工具共享心跳、恢复、KV、Config、Secrets 等语义
- 最终输出统一进入平台事件与 Trace 平面
常见 AI 工具的接入判断
不要先按品牌名判断，而应先按运行形态判断：
| 工具形态 | 典型例子 | 推荐模式 | 平台要重点补的能力 |
|---|---|---|---|
| 终端原生 coding tool | Claude Code、Codex、OpenCode | 托管 runtime 或 Session Peer | Sandbox、文件系统、PTY、Checkpoint、审计 |
| IDE / Web 交互工具 | IDE 扩展、聊天前端 | 工具作为客户端 | Run 创建、事件流、身份鉴权、会话继续 |
| MCP Server 或独立能力服务 | 搜索、浏览器、检索、代码分析服务 | Tool Adapter | Tool 治理、调用留痕、限流、权限边界 |
品牌只是入口，真正决定接入方式的是工具是否需要长期会话、是否直接操作本地工作区、以及是否需要被平台托管运行。
Claude Code、Codex、OpenCode 这类工具的共同特点
这类工具通常具备下面的运行特征：
- 强依赖终端、文件系统和进程执行
- 需要较长的交互会话，而不是一次无状态调用
- 常常会操作 Git、包管理器、测试框架和本地项目目录
- 既有自然语言输出，也有结构化动作，例如命令执行、文件修改和测试结果
这正是 AaaS 适合作为托管层的原因。平台可以在不改变工具核心交互体验的前提下，补齐这些工具本来欠缺的平台能力。
平台需要补上的能力
运行环境托管
- 为每次任务创建工作区或复用会话工作区
- 统一镜像、依赖缓存、网络边界和工具白名单
- 给运行进程分配 TTL、心跳和受控释放策略
事件归一化
- 把自然语言输出映射成消息事件
- 把命令执行、文件操作、测试结果映射成工具调用、Artifact 或活动消息
- 把关键状态变化映射到标准运行状态和 Span
安全与治理
- 统一 Secret 注入与最小权限控制
- 统一模型供应商访问策略和审计记录
- 统一输出留痕和内容捕获策略
继续执行与恢复
- 同一个 coding task 可以继续会话，而不是每次都冷启动
- 工具异常退出后，平台仍然保留 Run、Artifact、Checkpoint 和 Trace 事实
推荐的适配边界
不要试图把每个工具的内部动作完全重写为平台私有 API。更稳妥的方式是：
- 保留工具自己的 agent loop
- 只把平台需要治理的边界适配出来
- 让工具继续以它最擅长的交互方式工作
- 让平台统一负责生命周期、隔离、观测和审计
一个 coding agent 的典型接入形态
- 控制面选择某个 Agent 及其 execution profile
- Provider 创建 Sandbox，会话准备好工作区和依赖
- Claude Code、Codex 或 OpenCode 进程在其中启动
- runtime attach 到 Session，领取用户输入和上下文
- 工具运行期间持续输出消息、活动、Artifact 和 Trace
- 平台根据策略保留会话、生成 Checkpoint 或释放环境
兼容性边界
平台并不要求这些工具：
- 使用同一个模型供应商
- 使用同一种 Prompt 模板
- 使用同一种规划策略
- 使用同一套内部工具协议
平台真正要求的是：
- 能被纳入统一的 Run 生命周期
- 能提供可恢复的会话和可观测的执行事实
- 能接受受控的 Secret、Config、网络和工具边界