VISTA 双后端架构解析:Codex CLI 与 Claude Code 如何驱动同一个视觉 Agent

原创2026-11-13 09:00:541,878 阅读

VISTA 双后端架构解析:Codex CLI 与 Claude Code 如何驱动同一个视觉 Agent

VISTA 是面向多模态大模型的"视觉装置(visual harness)",让模型在长程任务中主动重组、反复检视自己的视觉输入,像玩家一样操作交互环境。本文拆解 VISTA 的双后端架构:Codex CLI 与 Claude Code 这两个编码智能体,如何通过 app-server 协议与原生 MCP 分别驱动同一个视觉 Agent,以及背后的共享工具核心与完全一致的系统提示词是如何做到的。

VISTA 视觉 Agent 在 ARC-AGI-3 与 GameWorld 等基准上玩游戏的画面

VISTA 把视觉观测保留为可检索的记忆:Agent 可以回溯早期的画面、放大检查选中的区域,还能读取像素数值。它提供了五个核心能力:

  • 用 play 执行游戏动作
  • 用 inspect 回看选定的画面帧与区域
  • 用 read_pixels 读取图像区域的像素数值
  • 用 history 回顾历史动作与环境反馈
  • 用 GUIDE.md(持久记忆)和 WORKING.md(工作记忆)沉淀对游戏的理解

效果相当惊人:在 25 个公开 ARC-AGI-3 游戏上,Codex CLI + GPT-5.6 Sol 拿到 RHAE 99 分,Claude Code + Opus 5.0 拿到满分 100 分(RHAE 是相对人类操作效率的得分)。

VISTA 双后端总体架构:一个核心,两个引擎

VISTA 的代码组织非常清晰地体现了"核心与传输分离"的思路:

src/vista/
├── core/        # 提供者中立的共享核心(工具、会话、提示词)
├── backends/
│   ├── codex/   # Codex CLI 适配器
│   └── claude/  # Claude Code 适配器
└── benchmarks/  # ARC-AGI-3 / GameWorld / AI GameStore / BabyVision
维度 Codex CLI 后端 Claude Code 后端
传输协议 app-server(stdio JSON-RPC) 原生 MCP + stream-json
工具注入方式 动态工具 game 命名空间 容器内 MCP Server 桥接
上下文压缩 preCompact 钩子 + 检查点工具 PreCompact 钩子阻塞至检查点保存
固定版本 0.145.0 2.1.220
玩家镜像 arc3-codex-player arc3-claude-player
代表成绩 RHAE 99(GPT-5.6 Sol) RHAE 100(Opus 5.0)

两种后端都由 CLI 的 --backend 参数一键切换(见 src/vista/cli.py),而命令的其余参数——--profile、--model、--effort——完全相同。这就是"同一个视觉 Agent"的含义:游戏逻辑、工具、提示词、评测协议全都不变,只换驱动它的"引擎"。

Codex CLI 后端:用 app-server 协议驱动视觉 Agent

Codex 后端的核心是 src/vista/backends/codex/runner.py 中的 DockerCodexRunner。它的运行方式很有特色:

  1. 启动强化容器:每次运行都 docker run 一个只读容器(--read-only、--cap-drop ALL、16GB 内存限制),Codex CLI 0.145.0 以 app-server --stdio 模式运行,VISTA 通过 stdin/stdout 的 JSON 消息与之对话。
  2. RPC 会话流:先 initialize 握手,然后 thread/start 创建线程,turn/start 下发任务输入(文本 + base64 图像块),之后循环接收事件直至回合完成。断线后可以用 thread/resume 精确恢复同一个会话。
  3. 工具即命名空间:play、inspect 等游戏工具以 direct_only_tool_namespaces = ["game"] 的形式注册为动态工具,容器内其他一切能力(shell、网络搜索、浏览器)全部在配置中显式关闭——模型只能"玩游戏"。
  4. 上下文压缩靠钩子:src/vista/backends/codex/lifecycle.py 会写入一个 preCompact 钩子。当 Codex 的上下文接近压缩阈值时,钩子会中断回合,要求模型先把完整续玩状态写进 WORKING.md(通过 save_compact_checkpoint 工具),随后 VISTA 用检查点内容开启全新会话继续游戏。这套"检查点交接"保证了长程游戏不会因上下文截断而失忆。

Claude Code 后端:用原生 MCP 接入游戏工具

Claude 后端(src/vista/backends/claude/runner.py)走的是另一条技术路线,核心组件是三件套:

  • ClaudeGameMcpHost(mcp_host.py):运行在宿主机上的 Unix socket 服务,负责把 Claude 的工具调用转发给共享的游戏控制器,并带随机 token 鉴权。
  • MCP 桥(mcp_bridge.py):一个运行在容器内的最小 stdio MCP Server,把 play、inspect 等工具暴露给 Claude Code。它还被特意剥离了所有凭据环境变量——容器里的桥进程碰不到任何 token。
  • 压缩钩子(compact_hook.py):拦截 Claude 的 PreCompact 事件,在模型把 WORKING.md 更新为完整检查点之前阻止压缩发生(返回 decision: "block")。

此外,provider.py 做了一个精妙的抽象:Claude Code 只是"传输层",模型是可以替换的。原生 Anthropic 走订阅 OAuth token;任何实现了 /v1/messages 的 Anthropic 兼容端点,只需通过环境变量(ANTHROPIC_BASE_URL 等)即可接入,传输层代码一行不改。

同一个 Agent 的关键:共享工具、相同提示词

双后端"看起来一样聪明"的秘密,在于共享核心(src/vista/core/):

  • 同一套工具执行器:GameToolDispatcher(dispatcher.py)是"提供者中立"的——无论工具调用来自 Codex 的 RPC 还是 Claude 的 MCP,最终都落到同一个控制器上执行。
  • 完全相同的系统提示词:core/prompts/codex.md 与 core/prompts/claude.md 内容逐字一致,都要求模型"为游戏构建紧凑、可修订的模型"、"每个动作前陈述预期、动作后陈述变化",并维护 GUIDE.md/WORKING.md。
  • 统一的任务绑定:binding.py 里的 prepare_player 把同一份系统提示词写成 AGENTS.md、创建 screenshots/ 目录,两个后端共用同一套 ToolInterface 与恢复提示词模板。
  • 差异被隔离在"内容层":content.py 的 ordered_content 把同一份任务输入转成各后端的图像格式(Codex 用 data-URL,Claude 用 base64 source),保证文本与图像的顺序在两种协议下严格一致。
  • 统一会话包装:session.py 的 BackendSession 对上层暴露相同的 run() 接口,内部按 kind 分派到 Codex 的"检查点循环"或 Claude 的"原生上下文循环",并负责会话 ID 校验、用量统计、限流退避(如 serverOverloaded 时按 10s/20s/40s 递增重试)。

换句话说,后端只负责"怎么把工具调用和图像送进 CLI",所有游戏智能都沉淀在共享核心里——这正是双后端可以公平对比、未来还能轻松接入第三个编码智能体的原因。

三步跑通 VISTA:环境配置完整指南

1️⃣ 安装 Python 包

git clone https://gitcode.com/gh_mirrors/vista14/VISTA
cd VISTA
python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .
cp .env.example .env && chmod 600 .env

2️⃣ 安装固定版本的 CLI 与 Docker 镜像

两个后端各需安装精确版本的 CLI(Codex CLI 0.145.0 / Claude Code 2.1.220),并分别构建 Dockerfile.codex-player 与 Dockerfile.claude-player 镜像。凭据分别写入 ~/.codex/auth.json 和 .env 的 CLAUDE_CODE_OAUTH_TOKEN。

3️⃣ 一行命令切换后端

# Codex CLI 驱动
.venv/bin/vista --profile arc3 --backend codex \
  --game-id s5i5 --operation-mode online --model gpt-5.6-sol --effort max

# Claude Code 驱动(其余参数完全一致)
.venv/bin/vista --profile arc3 --backend claude \
  --game-id s5i5 --operation-mode online --model opus --effort xhigh

批量评测还有现成脚本:scripts/run_batch.sh、scripts/run_gameworld_batch.sh 等,用 --backend codex|claude 即可整批切换。

为什么这套双后端架构值得学习 🧠

  1. 公平对比:提示词逐字一致、工具同一份、图像顺序同一套转换,模型间的成绩差异真正反映模型能力,而非工程差异。
  2. 传输可插拔:新增一个编码智能体,只需实现一个 Runner + factory(约 1400 行内聚代码),核心零改动。
  3. 上下文压缩工程化:preCompact 钩子 + WORKING.md 检查点 + 全新会话恢复,是把"上下文会爆"这个 Agent 通病变成可控流程的范本。
  4. 安全姿态严格:只读容器、能力全部丢弃、凭据不进桥进程、每次运行独立状态目录——多 Agent 长程运行时的安全基线。

VISTA 的完整实现可以从 pyproject.toml 起的 Python 包直接安装,架构入口在 src/vista/backends/。想研究"如何让同一个 Agent 大脑插到不同编码 CLI 上",这个仓库是最直接的一手材料。

登录后查看全文
VISTA