视觉 Agent 做还原对比，TaoToken Key 配合多模态模型路由

1. 视觉还原对比：多模态 Agent 最容易烧钱的环节

上周 visual-reviewer 子 Agent 在跑一次中等需求的视觉还原对比时，单轮 input token 冲到了 26 万，日志里最刺眼的是同一张 Figma 基准图在 8 轮修复循环中被反复上传。表面上是在做“视觉还原对比”，实际却变成了多模态模型的重复计费现场：基准图、候选截图、历史差异 JSON、CLI 日志全部堆在 context 里，visual-reviewer 每轮都要重新看一遍。我们排查后确认，问题不在 Agent 不会对比，而在于视觉 Agent 没有按角色做多模态路由——它和主 Agent 共用同一档大模型、同一套图片 detail 策略，导致规则性极强的像素级校验占用了最贵的推理资源。

这篇博客记录我们后来的改造路径：在 TaoToken 官网拿 Key（https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=visual_agent_key），把 Base URL 统一为https://taotoken.net/api，然后让 visual-reviewer 走低成本多模态模型，主 Agent 继续负责方案与调度。文末会给出可复现的多模态模型参数、视觉还原对比任务清单，以及 Claude Code、Codex、CC Switch 三种接入配置。目标很明确：让视觉还原对比从“多模态 token 黑洞”变成可度量、可路由、可回归的固定工序。

在 Multi-Agent 前后端协同开发里，视觉还原验证通常发生在自动化测试之后。tech-leader 拿到前端页面截图，visual-reviewer 拿到 Figma 设计稿截图，两者对比后输出差异清单，再交给 frontend-dev 修复。这个环节有三个天然成本放大器：

1. 图片 token 密度高：一张 1280px 长边的 UI 截图，在高 detail 模式下可能被切成多个 patch，单图消耗远高于同字数文本。
2. 修复循环轮次多：颜色、间距、字号、阴影、层级，每一类差异都可能触发一轮“截图—对比—修复—再截图”。
3. 历史重复打包：如果基准图不抽离、差异报告不压缩，每一轮模型调用都会把之前所有图片和历史消息重新计费一遍。

我们最初用 AgentLens 按 TraceId 和 SessionId 拆成本，发现视觉还原验证在整条工作流里调用次数不是最多，但单次 input token 排名靠前。原因很直接：visual-reviewer 默认继承了主 Agent 的多模态配置，模型贵、图片 detail 高、输出自由文本，导致 diff 结果无法被下游稳定消费，frontend-dev 还得再推理一次。

改造后的原则只有三句话：视觉 Agent 只看当前要判的区域，无关角色不共享图片上下文，同一张图不在多轮里重复上传。下面从多模态路由开始拆。

2. 多模态模型路由：先定义角色，再定义参数

多模态路由不是简单换一个模型名，而是把“角色—模型—参数—输出格式”绑定成配置。我们的 harness 里有 TL、backend-dev、frontend-dev、test-runner、visual-reviewer、code-reviewer 等角色。其中 visual-reviewer 的任务规则性强、推理深度低，但轮次最多，因此适合走低成本多模态模型。主 Agent 只在需要综合判断时调用高推理模型，视觉还原对比则固定路由到多模态低成本档。

我们参考了 GLM-5V 这类多模态模型的成本结构：在同等级别下，成本约为 Sonnet 的 36% 左右。视觉 Agent 的修复循环越多，这个比例带来的节省越明显。实测在测试与视觉校验角色上，整体成本下降约 64%。注意，这里不是说所有角色都换低价模型，而是按角色分层：

visual-reviewer 的多模态模型参数我们固定成一份 YAML，所有子 Agent 从同一份配置读取。这样做的好处是：换模型只改一处，度量口径一致，回归对比不会因为参数漂移而失真。

# multimodal-router.yaml roles: visual-reviewer: provider: taotoken base_url: https://taotoken.net/api model: glm-5v temperature: 0.1 top_p: 0.9 max_tokens: 2048 seed: 42 image: detail: high max_long_edge: 1280 max_bytes_per_image: 1048576 max_images_per_call: 4 output: format: json_object schema: visual_diff_v1

这份参数里几个关键点值得展开：

• temperature 0.1：视觉差异判定需要稳定，不希望模型自由发挥。颜色、间距、圆角这类判断必须可复现。
• top_p 0.9：保留少量候选，但不会让输出发散。
• max_tokens 2048：差异清单通常不会超过 2K token，设太大反而让模型输出冗余解释。
• seed 42：同一组输入尽量得到同一组输出，方便 A/B 对比。
• detail high：UI 还原对比需要看清文字和边框，low detail 会漏掉小图标差异。
• max_long_edge 1280：控制单图体积，避免 4K 截图直接进 context。
• max_images_per_call 4：一轮最多传基准图、候选图、局部裁剪图、差异热力图，超过就拆任务。
• response_format json_object：强制结构化输出，下游 frontend-dev 直接读 JSON，不再二次推理。

模型路由配置好之后，视觉 Agent 调用多模态模型时就不需要每次问“用哪个模型”。visual-reviewer 的系统提示词里只写一句：按 multimodal-router.yaml 的 visual-reviewer 配置调用 TaoToken 多模态接口。这样派发提示词从十几行压缩到两行，稳定前缀更容易命中缓存。

Base URL 统一使用https://taotoken.net/api，不要在每个子 Agent 里散落不同地址。Key 统一用环境变量TAOTOKEN_API_KEY，占位符YOUR_API_KEY只出现在示例里，不要提交到仓库。如果你还没有 Key，可以在 TaoToken 官网获取：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=multimodal_router 。拿到 Key 后，下一步是把它接进 Claude Code、Codex 或 CC Switch。

3. 接入 TaoToken：Claude Code、Codex、CC Switch 三种配置

接入 TaoToken 的核心是三件事：Base URL、API Key、模型名。不同工具的叫法不同，但都围绕这三件套。注意不要把 Claude Code 的ANTHROPIC_*环境变量套到 Codex 上，Codex 走的是config.toml和model_providers。下面分别给出可复制配置。

3.1 Claude Code：settings.json + ANTHROPIC_*

Claude Code 用户可以在~/.claude/settings.json里配置环境变量。Base URL 填 TaoToken 的https://taotoken.net/api，认证 token 填你的YOUR_API_KEY。模型 ID 以 TaoToken 控制台展示为准，下面用占位模型名示意。

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "claude-sonnet-4-5", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5" } }

如果你用的是项目级配置，也可以放在项目根目录的.claude/settings.json。配置完成后，运行一次简单的模型对话验证连通性。视觉 Agent 的多模态调用不需要额外配置，只要模型 ID 支持图片输入即可。

3.2 Codex：config.toml + model_providers

Codex 的配置在~/.codex/config.toml。这里不要用ANTHROPIC_*，而是定义model_providers。Base URL 同样使用https://taotoken.net/api，环境变量名可以自定义为TAOTOKEN_API_KEY。

model = "YOUR_MODEL_ID" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"

然后在终端设置环境变量：

export TAOTOKEN_API_KEY="YOUR_API_KEY"

如果你的 Codex 版本要求/v1后缀，以 TaoToken 控制台文档为准；本文统一以产品给定的 Base URLhttps://taotoken.net/api为基准。配置完成后，Codex 的文本编码任务可以走 TaoToken，而 visual-reviewer 的多模态任务继续用同一 Key 和 Base URL，只是模型参数换成多模态档。

3.3 CC Switch 三件套：Base URL、API Key、Model

CC Switch 用户可以把 TaoToken 作为一个供应商配置。三件套如下：

在 CC Switch 里新增供应商时，名称可以写TaoToken，Base URL 不要带 UTM 参数，UTM 只用于官网访问统计。创建 Key 的入口在 TaoToken 控制台：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=visual_review_setup 。如果你还没有对应多模态模型的权限，可以在模型对话页先测试图片输入，再回到控制台确认模型 ID。

3.4 验证多模态调用

配置完成后，用一段最小 Python 代码验证 TaoToken 的多模态接口是否能读图。下面示例使用 OpenAI 兼容 SDK，Base URL 使用https://taotoken.net/api。如果你的 SDK 报 404，检查是否自动补了/v1，以实际控制台文档为准。

import base64 import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url="https://taotoken.net/api" ) def to_data_url(path: str) -> str: with open(path, "rb") as f: b64 = base64.b64encode(f.read()).decode() return f"data:image/png;base64,{b64}" resp = client.chat.completions.create( model="glm-5v", temperature=0.1, max_tokens=512, messages=[ { "role": "user", "content": [ {"type": "text", "text": "这张图里最显眼的颜色是什么？只输出 JSON。"}, {"type": "image_url", "image_url": {"url": to_data_url("screenshot.png"), "detail": "high"}} ] } ] ) print(resp.choices[0].message.content)

只要能稳定返回 JSON，就说明 Key、Base URL、多模态模型 ID 三件套已经打通。接下来是把 visual-reviewer 的任务清单固化下来。

4. visual-reviewer 的视觉还原对比任务清单

视觉还原对比最怕“让模型自由看”。模型每次关注的点不同，输出格式不同，下游修复成本就高。我们把 visual-reviewer 的任务拆成固定清单，每次对比按顺序执行。这份清单可以直接作为子 Agent 的系统提示词骨架，也可以放进references/visual-review-checklist.md，按需读取。

4.1 输入准备清单

1. 基准图来源：从 Figma 导出，固定视口、DPR、字体渲染设置。不要用人工截图作为唯一基准。
2. 候选图来源：用 Playwright CLI 截图，视口与基准图一致，等待网络空闲，禁用动画。
3. 命名规范：{page}-{viewport}-{dpr}-{state}.png，例如home-1440x900-dpr2-default.png。
4. 图片预处理：长边缩放到 1280px 以内，单图不超过 1MB，格式统一为 PNG。
5. 区域裁剪：对 header、nav、hero、form、footer 分别裁剪局部图，减少无关区域干扰。
6. 差异热力图：先用本地像素 diff 生成热力图，再把基准图、候选图、热力图一起送入多模态模型。
7. 历史基线：已确认的差异写入 baseline，后续对比不再重复报告。

4.2 多模态对比任务项

visual-reviewer 每次只回答清单里的问题，输出固定 JSON。任务项包括：

• 布局：栅格、对齐、溢出、层级、定位。
• 颜色：主色、背景、边框、渐变、透明度。
• 字体：字号、字重、行高、字间距、截断。
• 间距：margin、padding、gap、圆角、阴影。
• 图标：尺寸、位置、颜色、状态。
• 响应式：断点切换、折叠、滚动条。
• 可访问性：对比度、焦点态、可点击区域。

每个任务项输出字段为：area、severity、expected、actual、bbox、suggestion。severity 只允许high、medium、low。high 进入人工复核，medium 和 low 进入自动修复候选。

4.3 输出 JSON Schema

{ "page": "home", "viewport": "1440x900", "dpr": 2, "diff_count": 3, "items": [ { "area": "header.login_button", "severity": "high", "expected": "背景色 #1677ff，圆角 6px", "actual": "背景色 #4096ff，圆角 4px", "bbox": [1180, 24, 96, 32], "suggestion": "将背景色改为 #1677ff，圆角改为 6px" } ] }

这个 JSON 直接交给 frontend-dev，避免再次调用多模态模型解释差异。visual-reviewer 跑完即销毁，图片上下文不进入主 Agent 会话。

4.4 完整调用示例

下面代码把任务清单和多模态参数串起来。注意截图和 diff 命令由本地或 CI 执行，不要让 Agent 直连生产环境。

import base64 import json import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url="https://taotoken.net/api" ) def img(path: str) -> dict: with open(path, "rb") as f: b64 = base64.b64encode(f.read()).decode() return {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}", "detail": "high"}} prompt = """ 你是 visual-reviewer。只对比基准图和候选图，按以下任务项输出 JSON： 布局、颜色、字体、间距、图标、响应式。 每项包含 area、severity、expected、actual、bbox、suggestion。 severity 只能是 high/medium/low。不要输出 JSON 以外的内容。 """ resp = client.chat.completions.create( model="glm-5v", temperature=0.1, top_p=0.9, max_tokens=2048, seed=42, response_format={"type": "json_object"}, messages=[ { "role": "user", "content": [ {"type": "text", "text": prompt}, img("baseline/home-1440x900-dpr2-default.png"), img("actual/home-1440x900-dpr2-default.png"), img("diff/home-1440x900-dpr2-default-heatmap.png") ] } ] ) result = json.loads(resp.choices[0].message.content) print(json.dumps(result, ensure_ascii=False, indent=2))

这份代码就是可复现产出的一部分：多模态模型参数固定、任务清单固定、输出 Schema 固定。接下来要把它接进 harness，而不是每次临时手写提示词。

5. 把视觉对比接进 Harness：子 Agent、稳定前缀、并行截图

视觉还原对比不能只当一次脚本调用，要作为 visual-reviewer 子 Agent 的标准能力接进 tech-leader 工作流。我们做了四件事：

5.1 visual-reviewer 子 Agent 化

以前主 Agent 自己调用多模态模型看截图，原始图片和历史差异永久留在最长生命周期的 context 里。改法是给 visual-reviewer 单独建一个自定义子 Agent，只携带多模态工具和白名单，跑完即销毁。它只返回结构化摘要：差异数量、high 项、修复建议。主 Agent 不需要看到图片本身，只需要读 JSON。

这一步和 TAPD/Figma 数据获取子 Agent 化是同一个思路：原始 payload 不进主上下文，只让结构化摘要回流。实测同一工作流改造前后，单轮会话 input token 从 1,030,000 降到 634,905，降幅约 38.4%。视觉场景同理，基准图和候选图不再跟着主 Agent 跑几十轮。

5.2 稳定前缀设计

多模态模型的 prompt cache 同样吃前缀稳定性。我们把 visual-reviewer 的提示词拆成两段：

• 静态前缀：角色说明、任务清单、输出 Schema、严重级别定义。这段每次完全一致，放在最前面。
• 动态内容：基准图、候选图、热力图、页面元数据。这段统一后置。

不要在前缀里插入“本次是 home 页面”“本次视口 1440”这类动态文本，否则前缀每次都变，缓存命中不了。页面元数据可以放进动态内容的第一条文本里，或者放在图片之后。

5.3 并行截图与批量对比

视觉还原对比天然可以并行：多视口、多页面、多状态之间没有数据依赖。我们用 Playwright CLI 一次接收多个 spec 文件，内置多 worker 并行截图。截图完成后，visual-reviewer 一次调用最多传 4 张图，按区域或页面分批对比。

不要用 MCP 控制浏览器逐步点击截图。每次点击都是一次模型推理轮次，10 步操作就是 10 轮对话。把“理解用例并翻译为 Playwright spec”和“实际执行截图”拆成两步：大模型生成 spec，Playwright CLI 批量执行。LLM 侧只调用一次，读汇总结果，不随用例数线性增加推理轮次。

5.4 压缩 CLI 输出

Playwright CLI 的原始输出、git diff、测试日志夹带大量噪音。我们接入了 rtk 这类 CLI 代理，在命令执行前拦截并重写为压缩版本。官方实测降幅 60%~90%，但幅度因命令而异。全局配置一次，所有子 Agent 自动获得压缩效果。注意字段名转换：有些工具输出updatedInput，而 CodeBuddy 要求modifiedInput，不转换会静默失效。

视觉 Agent 的 context 里只应该出现：压缩后的 CLI 摘要、基准图、候选图、热力图、任务清单。其他都不进。

6. 度量与回归：视觉还原对比的验收指标

改造之后必须度量，否则不知道省下来的 token 是不是以漏报差异为代价。我们关注五个指标：

回归方法不要用“同一需求跑两遍，开/关多模态路由各一次”的粗放对比。大模型执行路径不确定，噪声可能比效果还大。更可靠的方式是固定输入集：同一批基准图、候选图、任务清单，分别用旧配置和新配置跑，比较 JSON 输出和 token 统计。图片 token 是确定性的，路由参数也是确定性的，这样对比才可复现。

落地优先级建议：

1. 先给 visual-reviewer 建独立子 Agent，固定多模态参数和输出 Schema。
2. 把任务清单外置到references/visual-review-checklist.md，正文只留骨架。
3. 接入 TaoToken Key 和 Base URLhttps://taotoken.net/api，统一环境变量。
4. 用 Playwright CLI 替代 MCP 逐步点击截图，批量并行执行。
5. 接入 rtk 压缩 CLI 输出，减少修复循环噪音。
6. 最后做固定输入集的回归对比，确认召回率和误报率。

如果你还没有配置 Key，可以在 TaoToken 官网完成：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=visual_review_regression 。创建 Key 后，把YOUR_API_KEY放进环境变量，Base URL 保持https://taotoken.net/api，不要在每个子 Agent 里重复硬编码。

7. 总结与 CTA

这次视觉还原对比改造，我们沉淀了四条经验：

1. 多模态路由要按角色分：visual-reviewer 规则性强、轮次多，走低成本多模态模型；主 Agent 继续做高推理调度。
2. 图片上下文要短生命周期：基准图、候选图、热力图只进 visual-reviewer 子 Agent，跑完即销毁，结构化 JSON 回流。
3. 任务清单和输出 Schema 要固定：不要让模型自由看、自由写，固定任务项和 JSON 字段，下游才能稳定消费。
4. 能并行就不要串行：多视口、多页面、多状态截图并行执行，批量送入多模态模型，减少历史重复打包。

现在 visual-reviewer 的视觉还原对比已经变成 harness 里的固定工序：TaoToken Key 统一管理，Base URL 统一为https://taotoken.net/api，多模态参数从multimodal-router.yaml读取，任务清单从 references 按需加载。下一步我们会把这份清单沉淀成团队 checklist，应用到更多前端项目的视觉回归中。

如果你也在做 Multi-Agent 工作流的成本治理，或者正在为 visual-reviewer 的多模态调用找更稳的路由方式，可以按下面路径开始：

1. 先到模型对话页测试多模态模型是否支持图片输入：
   https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=visual_chat

2. 如果准备把 Coding Agent 和视觉 Agent 一起接入，可以看 Coding Plan：
   https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=visual_plan

3. 创建 API Key，填入YOUR_API_KEY：
   https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=visual_keys

4. Claude Code 用户可参考官方文档完成settings.json配置：
   https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=visual_claudecode

把 Base URL 换成https://taotoken.net/api，让 visual-reviewer 走多模态低成本路由，视觉还原对比的 token 成本就会从“不可控”变成“可预算”。