识图能力用户手册（视觉通道）

July 31, 2026 · View on GitHub

天枢什么时候能真的「看见」图片、看不见时会怎样、桌面端与 TUI 分别怎么配。

三种状态

图片能不能进模型，取决于主控模型的能力和有没有配识图桥：

状态	条件	行为
直接看图	主控模型声明 `supportsVision`	图片作为多模态消息追加到对话尾部，模型直接看
桥接描述	主控不支持 + 配了 `agent.visionModel`	图片先发给识图模型换成文字，只有描述进主对话
自动选桥	主控不支持 + 未配 `visionModel` + 开了 `agent.visionAutoBridge`	自动挑一个可用视觉模型做桥，行为同上
丢弃	以上都不成立	图片不发送

最后一种状态是会明说的：TUI 在消息气泡下方给出警告，截图工具的结果文字里也会写明"非视觉模型该附件会被自动丢弃，改用 observe / extract / eval 读 DOM"。早期版本静默丢弃，模型会凭"我截了图"断言渲染正常——截图是验证手段，能让模型声称验证过它没看见的东西，比没有这个工具更糟。

自动选桥默认关，而且是有意关的：它会把你的图片发给一个你从未为此选择过的 provider，那是成本与隐私决定，不该由默认值代做。关着的时候天枢不会闷声不响——如果仓里确实有能看图的模型，状态里会点名它并告诉你怎么启用：

未配置 agent.visionModel；检测到可用视觉模型 minimax/MiniMax-M3，在 /config → 识图模型 选定它，
或设 agent.visionAutoBridge=true 让它自动选（会把图片发给该 provider）

哪些内置模型能直接看图

Provider	模型
`glm`	`glm-5.2`
`minimax`	`MiniMax-M3`
`siliconflow`	`zai-org/GLM-5.2`
`codex`	`gpt-5.5`
`ccswitch`	`glm-5.2`（别名 `cc-glm`）

默认的 deepseek-v4-pro 不支持识图。 用 DeepSeek 当主控又要看图，就得配识图桥。

自定义 provider / 自己加的模型必须在那条 model 上手写 "supportsVision": true，否则天枢按纯文本模型对待。这个字段是按模型声明的，不是按 provider——同一个 provider 下文本模型和多模态模型混编是常态。

配识图桥

{
  "agent": {
    "visionModel": {
      "provider": "minimax",
      "model": "MiniMax-M3",
      "prompt": "请详细描述这张图片…",  // 可选，描述提示词
      "maxTokens": 1024,                // 可选，描述的输出上限
      "fallback": {                     // 可选，主视觉模型 5xx/超时时自动切
        "provider": "glm",
        "model": "glm-5.2"
      }
    },
    // 未配 visionModel 时是否自动挑一个可用视觉模型（默认 false）
    "visionAutoBridge": false
  }
}

两个前提：该 provider 已配好 key，且目标模型声明了 supportsVision。

fallback 是主备双桥：主视觉模型报 5xx / 超时才切备用（同 FallbackStreamClient 机制）。备桥起不来（缺 key、模型不存在）不致命，只在日志里点名并降级为单桥。

同一张图反复追问：`ask_image`

配了桥（或主控本身多模态）之后，模型可以用 ask_image 就同一张图反复追问，不需要你重发：

ask_image { question: "逐字念出红色报错那一行", imageId: "img_2" }

imageId 省略则用最近一张。图片 id 由天枢寄存时分配（img_1、img_2…），会出现在提示文本里。
寄存范围包括你附的图和 agent 自己截的图（browser_debug / computer_use 的截图），所以「截图 → 追问细节」是完整闭环。
主控多模态时直接把原图递回给主控看；text-only 时用你的问题定向问识图桥。
同一张图同一个问法重复问命中描述缓存，零额外调用。
寄存是纯内存的：不进对话历史、不落盘，按会话 LRU 上限（8 张 / 24MiB）淘汰。

描述提示词会自动分档

没显式配 prompt 时，天枢按随图文本挑模式：文本里出现报错、终端、代码、日志一类关键词 → OCR 级逐字转写（截图里关键常常就一行报错，泛泛描述会把它丢掉）；否则用通用结构化描述（文字内容 / 界面元素 / 可能意图三段）。显式配了 prompt 就永远用你的。

桌面端

Settings → 集成 → 识图模型。Provider / 模型下拉只列已配置且声明支持图片输入的组合，留空即关闭桥接。同一张卡里还有备用识图模型（主桥 5xx/超时时切）和未配置时自动选桥开关——桌面端与 TUI 面板功能对等，只装其中一个也能把识图配全。

卡片顶部那一行是当前会话的真实桥状态（读 GET /sessions/:id/vision-bridge），不是"配置里有没有这个键"：显示「主控模型原生支持识图」/「识图桥已生效」/「图片不会被看到（附原因）」。没有打开会话时它会明说状态未知，而不是拿配置冒充运行时事实。

附图时如果这个会话的图片不会被看到，Composer 会在缩略图下方直接警告并给一个「去配置识图模型」按钮——不再默默收下一张没人看的图。桥状态未知时不警告（假警告只会训练你忽略所有警告）。

/config 打开设置面板 → 左栏选识图模型 → Enter 选模型 → S 保存。候选同桌面端：只列已配置且声明 supportsVision 的 provider/模型组合，选第一项「（关闭）」即关掉桥接；prompt、maxTokens、以及「未配置时自动选桥」开关都在同一分类里改。面板写的是用户级 ~/.rivet/config.json，下次会话生效（会话模型在首个请求前就钉住了，中途换会碎前缀缓存）。

/settings、/setup 是同一面板的别名。

手改配置文件

~/.rivet/config.json（全局）或项目根的 .rivet-config.json（只作用于本项目，优先级更高）。字段名两处相同。注意面板只写用户级——项目级文件里的同名字段优先级更高，会盖掉面板里看到的值。

图片从哪来

用户附图：TUI 里粘贴图片的文件路径（终端只能粘贴文本），或直接 Ctrl+V 读系统剪贴板里的图；桌面端用 Composer 的附件按钮。每条消息最多 4 张，单张解码后 1.5MB，超了会按长边 1568px 自动缩。

agent 自己截的：browser_debug screenshot（frontend / full preset）和 computer_use screenshot（full preset）。单张 PNG 超 3.5MB 不附图，只留文字说明——这时缩小视口重截，或用 eval 量 DOM。

browser_debug 需要 chromium（约 150MB，不随包分发）。两条入口都能装，各自独立可用：

CLI：rivet browser status 查状态、rivet browser install 一键装（自动带国内镜像，--no-mirror 走官方源）。含 browser_debug 的 preset 下启动还会自动体检，缺失时在首屏给出安装入口。
桌面端：Settings → 集成 → 浏览器（截图）——就绪状态、一键安装（镜像 / 官方源两个按钮）、实时安装日志都在这张卡里。只装桌面端的用户不需要终端。

playwright-core 模块本身缺失时（打包残缺）两边都不会给安装按钮：那不是"浏览器没下载"，装浏览器解决不了。

每轮工具批次最多带最近 2 张截图进上下文：一批里连拍多张时，不让百万像素的 base64 灌满窗口。

成本与缓存

图片走对话尾部追加，不重写历史，所以不打断前缀缓存。

token 按分辨率估算（OpenAI 分块规则，实现在 `src/context/image-tokens.ts$），别按"每张固定"心算：

尺寸	估算 \text{token}
1024 \times 1024	765
1280 \times 800（默认视口）	1105
1280 \times 4000（整页长图）	1445

桥接路径下主历史里只留一份文字描述，识图模型自身的调用成本单独记在侧路（会话目录的 $cache-log.jsonl`）。

排查

桥配了却不生效时，先看 sidecar / 终端日志里的这一行，它会点名原因：

[vision] 识图桥未启用：<原因>（图片仍会被丢弃）

常见原因与对策：

原因	对策
provider 不在已配置列表里	先 `rivet config setup <provider>` 或在桌面端 Settings → Providers 里加
模型不在该 provider 的 `models` 里	补一条 model，或换成上表里的模型
该模型没声明 `supportsVision`	自定义模型手写 `"supportsVision": true`
没有可用的 key	最常见：key 只存在环境变量里，而 GUI / Dock 启动的桌面端没继承到 shell profile。把 key 写进配置，或从终端启动。（`config.env` 那套只作用于命令执行，不改进程自身环境）

桌面端不用去翻日志：识图卡顶部那一行就是同一份 detail（无活会话时会明说未知）。

两端分开部署时配置互不打扰：agent.visionModel.fallback 现在是"省略即保留"——桌面端保存主识图模型不会抹掉你手写的备用桥，TUI 面板也一样；要清掉备用桥就在界面里选「不设备用」（走显式清除）。旧行为是整体替换，任何不带该字段的写入都会吞掉它。

如果某个内置模型的 supportsVision 看起来"丢了"：旧版本在 UI 里编辑上下文窗口会连带抹掉这个字段。2026-07-29 起写入改为逐字段合并，且加载时会按预设补回缺失的 supportsVision / tier / pricing，不需要手动修配置文件。详见 docs/changelog/2026-07-29-vision-channel-honesty-and-test-entry-hardening.md。