深入 VISTA 源码:core 核心模块架构设计与代码实现原理全景图
深入 VISTA 源码:core 核心模块架构设计与代码实现原理全景图
VISTA 是一个视觉推理执行框架(Visual Harness),它让多模态大模型能在长程交互式任务中主动重组视觉输入——保存无损视觉记忆、按需回看历史帧、裁剪区域检查像素。本文将带你深入 VISTA 的 core 核心模块,完整拆解它的架构设计、状态机循环与代码实现原理,帮你快速读懂这套"视觉 Harness"的骨架。
一、3 层架构:core 引擎如何与后端、基准解耦 🧱
VISTA 的源码分为三层,core 是中间那颗"不依赖任何人"的心脏:
| 层级 | 目录 | 职责 |
|---|---|---|
| 核心引擎 | src/vista/core/ | 任务执行、工具契约、预算控制、视觉证据,不依赖任何基准 SDK 或模型供应商 |
| 后端适配 | src/vista/backends/ | 适配 Codex CLI 与 Claude Code 两条隔离的 CLI 传输通道 |
| 基准接入 | src/vista/benchmarks/ | ARC-AGI-3、GameWorld、AI GameStore、BabyVision 各自的 profile 与运行器 |
core 的模块文档字符串写得非常直白:"Task execution without benchmark SDK or provider dependencies."(见 init.py)。这意味着:新增一个基准或换一个模型 CLI,都只需要写适配层,引擎本体一行不用改。
core 内部 14 个文件的分工如下:
- contracts.py:公共证据与工具契约(数据模型层)
- profiles.py:实验身份定义、阶段提示词
- runtime.py:
TaskRuntime状态机(执行心脏) - episode.py:
run_episode主循环 - session.py / support.py:视觉记忆与检查点恢复
- dispatcher.py / tools.py / player.py:工具分发与 Schema
- artifacts.py / json.py / io.py / timeouts.py:证据存档、不可变 JSON、IO 与超时兜底
- prompts/:VISTA 方法论提示词(claude.md、codex.md)
二、契约层:contracts.py 如何定义"模型能看到什么" 🔐
contracts.py 的第一行注释就点出了设计哲学:"Public evidence and tool contracts. Evaluator state is deliberately absent."——模型只能看到被显式放行的公共证据,评测器内部状态刻意缺席。
核心数据模型是一条清晰的证据链:
PublicTask → ObservationBundle → Observation → Visual
- Visual:不是文件路径,而是"被适配器批准的显示字节"。构造时会用 PIL 实际打开图片,校验尺寸、MIME 类型、禁止动画帧(contracts.py),任何不符都直接抛异常。
- Observation:一个"时刻(moment)"下的多个视图,分为
current/historical/derived三类证据,派生视图必须声明来源。 - ObservationBundle:规定"同一时刻只能有一个当前状态",
display字段精确控制哪些观察真正展示给模型。
工具侧的契约同样严格:ToolSpec 在 post_init 中强制校验工具命名规则、JSON Schema、以及"能力(Capability)↔ 副作用(Effect)"的合法组合——例如只有 ACTION 能力才能改环境,INSPECTION 能力必须是只读的。这种"契约即防线"的设计,让模型行为在入口就被数学化约束。
三、实验身份:profiles.py 的"无预设"显式化 🧪
profiles.py 拒绝任何隐式默认值。一次运行的完整身份由 Experiment 显式声明:基准、基准版本、协议、模型、effort、预算、评测器……最终通过 canonical() 生成规范化 JSON 再取 SHA-256,得到全局唯一的 identity(profiles.py)。
两个关键抽象值得新手注意:
- Phase 阶段提示词:PromptBundle 为
initial / step / retry / checkpoint / compact / recovery六个阶段各备一份提示词,系统提示词必填。VISTA 方法论本体就藏在这里的公共提示词里,例如 claude.md 要求模型"构建一个紧凑、可修订的游戏模型,行动前预测、行动后复述可见变化"。 - SessionPolicy 会话策略:上下文模式(连续 / 全新)、交互模式(原生工具 / 最终回答 / 结构化回复)、压缩模式(原生 / 检查点交接),每个 profile 必须与解析出的工具集合精确匹配,否则启动即报错(validate_tools)。
四、状态机心脏:TaskRuntime 的序列化执行 ⚙️
TaskRuntime 是两条 CLI 传输通道共享的"序列化、白名单化"执行器,所有公共方法都握着一把 threading.RLock,保证任意时刻只有一个动作在推进任务。
它最核心的执行入口 execute() 依次做了 6 道关卡:
- 终态检查:会话已结束则直接拒绝;
- 去重:相同
call_id的请求"什么都没执行",防重复扣费; - 预算扣费:
tool_calls等计量器超额时返回"预算耗尽"的正常停止,而非崩溃; - 确认门:若上一次带副作用/图片的工具调用还未被
acknowledge()确认,则拒绝新动作——"先观察结果,再改变状态"; - JSON Schema 校验:用
Draft202012Validator验证参数合法性,非法参数按工具声明决定是否转交环境语义处理; - 边界断言:图片数量不得超过声明上限,
decision_complete边界只允许来自 ACTION 工具。
预算机制的精妙之处在于 BudgetExhausted 被定义为"正常停止条件,而非失败的后端调用"——tool_calls、backend_segments、final_answers 三个内置计量器加上工具自定义的 costs,构成一套确定性的资源会计(_charge())。跑满预算 = 任务体面收工,评测结果依然可信。
五、主循环:run_episode 为什么"绝不发明续集" 🔁
run_episode() 只有 40 来行,却是理解整个框架的最佳入口:
prepare_input(Phase.INITIAL) → while not terminal:
backend.run(task_input) # 模型跑一段
→ 若出现 decision_complete 边界,交给基准决策循环
→ runtime.submit(final_message) # 否则提交最终回答
→ prepare_input(Phase.STEP) # 拼上工具回复,进入下一轮
finally: runtime.close()
模块注释写道:"Run an explicitly bounded task; never invent a continuation or recovery prompt."——引擎只在显式边界处停下,绝不自造"继续吧"之类的提示词。续命、重试、上下文压缩的决策权全部交给后端生命周期层(见 backends/session.py 中 "provider lifecycles own recovery decisions" 的注释),这保证了每一步都是可审计的显式事件。
六、视觉记忆与恢复:session.py + support.py 的双层结构 📸
VISTA 最有辨识度的能力是"无损视觉记忆 + 模型主导的检查",实现分两层:
底层 SessionController(约 864 行)管理三种恢复快照数据类 CompactRecovery / RetryRecovery / RuntimeRecovery,分别对应:上下文压缩前的检查点、非法动作重试边界、运行时崩溃后的权威状态快照。每个快照都包含边界步号、当前观察、最后一次动作结果、目标历史和帧图片路径——恢复时按图索骥,不靠模型"回忆"。
上层 TaskContext 继承它,把公共任务证据绑定到 VISTA 的记忆与视觉操作上:bind() 在运行目录里落盘 GUIDE.md(持久游戏模型,上限 64KB)、WORKING.md(工作草稿,上限 16KB)与 visuals/ 帧存档目录,并放置各种检查点标记文件。像素读取还支持 4-bit 量化调色板(quantize_rgb),把 JPEG 噪声折叠进有限色阶,用紧凑的符号行字符串返回精确像素读数。
七、工具分发:dispatcher.py 与 tools.py 的白名单模式 🛠️
GameToolDispatcher 以"Provider 中立"的方式执行公共视觉游戏工具:
read_guide / read_working / write_guide / write_working由分发器直接落盘完成,写操作走 atomic_write_text(临时文件 + 原子替换,防半截写入);inspect / read_pixels / history / play / save_compact_checkpoint统一包装成{method, request_id, arguments}请求转发给私有 controller;- 检查点门控:当压缩标记文件存在时,分发器只放行检查点相关工具,其他调用一律被拒并提示"先保存检查点"(dispatcher.py)——用文件标记做状态机,简单而可靠。
所有工具的 JSON Schema 集中在 tools.py 的 build_tools() 中构建:inspect 最多 16 个视图、read_pixels 最多 64 个视图 4096 个采样点、统一的 1024×1024 标准坐标系——这些数字既是安全边界,也是模型可预期行为的一部分。player.py 则定义了 ToolExecutor 协议与 ToolInterface 数据类,把"定义 + 执行器 + 动作工具集合"打包成一个可替换的端口。
八、证据存档:artifacts.py 的不可变审计链 🗂️
ArtifactStore 是"仅主机可见、白名单化"的尝试记录器,权限收得很紧(目录 0700、文件 0600/0400):
manifest.json:实验配置 + 任务 + 证据协议,一次性写入("x"模式防覆盖);events.jsonl:每个事件(model_input、tool_started、tool_result、budget_exhausted……)以 canonical() 规范化后追加,形成可回放的时间线;evidence/:图片字节按 SHA-256 去重存档(artifacts.py),同名文件内容不一致时直接抛"证据被篡改"异常。
配合 json.py 的 freeze/thaw(把任意输入冻结成只读 MappingProxyType/tuple,只允许有限 JSON 值),整个系统实现了"配置只读、状态可回放、证据不可变"三位一体的可复现性。
九、设计哲学小结 + 上手阅读路线 📌
| 设计点 | 落地手段 |
|---|---|
| 供应商无关 | core 零依赖后端,backends/session.py 的 BackendSession 做任务绑定与预检 |
| 公共/私有严格隔离 | 契约层"评测状态缺席",ArtifactStore 仅主机可见 |
| 确定性 | 预算会计 + 去重 + Schema 校验 + 规范化哈希身份 |
| 可审计 | events.jsonl 时间线 + SHA-256 证据存档 |
| 显式边界 | run_episode 绝不发明续集,恢复决策归后端生命周期 |
建议的阅读顺序(新手友好):
- episode.py —— 40 行主循环,先建立全局观;
- runtime.py 的
execute()—— 理解六道执行关卡; - contracts.py —— 吃透证据链数据模型;
- session.py + support.py —— 视觉记忆与恢复协议;
- dispatcher.py + tools.py —— 工具面与门控。
读完这条线,你就掌握了 VISTA core 的全部主干:一个以"契约 + 预算 + 不可变证据"为三根支柱、把多模态 Agent 的每一步行为都变成可审计显式事件的执行引擎。想扩展新基准时,参照 benchmarks/ 下任一子目录,只需实现 TaskSession 协议并提供 profile,即可接入这套引擎。
