粘贴截图致Claude Code对话崩溃？开源项目填坑了

为什么需要本项目？

先说一个核心判断：当AI CLI工具配上第三方模型，图片理解这件事几乎就是一块真空地带。

用过Claude Code、OpenCode这类工具，再搭配DeepSeek等不支持多模态的模型时，这个问题简直让人抓狂。你辛辛苦苦贴了张截图上去，结果模型要么直接报错，要么给出离谱的分析，整段对话就这么毁了。

传统方案为啥走不通？

常见的做法，是在全局CLAUDE.md里写规则，强制要求系统调用某个Skill或MCP去处理图片。听起来很有道理，但实操中有一个绕不开的坑。

Claude Code在系统层面把指令写死了——只要粘贴图片，它就必定调用read工具，直接把图片数据发给模型。这个系统指令的优先级高于CLAUDE.md，所以你写的规则根本拦不住它。

结果是什么？Ctrl+V一张截图，模型收到base64数据，直接宕机或者胡说八道。对话就此烂尾，毫无挽回余地。

更麻烦的是，调试阶段我们几乎不会先把截图存成本地文件再上传——直接截图、复制到剪贴板、粘贴，这才是最自然的工作流。传统方案只适用于"先保存文件，再给路径"的场景，跟实际使用习惯完全对不上。

本项目的解法：两层防线

思路很直接：图片整流器 + 图片分析技能，分两层应对。

两层防线怎么分工？

1. 图片整流器（袋里层） — 在请求发出前拦截。检测messages中的base64图片块，移除原始数据，替换为文本提示，引导模型调用Skill。这一步在模型看到请求之前就已经完成了。

2. 图片分析技能（CLI工具） — 被模型调用后，智能判断图片来源：传了本地路径就读文件，没传路径就从系统剪贴板直接读取。兼容Claude Code（粘贴生成临时文件）和OpenCode（粘贴不生成临时文件）两种行为。

原项目简介

CC Switch是一款管理AI CLI工具（Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes）的桌面应用，提供供应商管理、袋里/故障转移、MCP/Skills管理和用量统计等功能。

本分支在此基础上新增了针对图片输入处理的功能，核心解决了大量第三方API供应商不支持多模态（视觉理解）的问题。

本分支新增功能

1. 图片整流器

这个功能要解决的问题非常明确：大量第三方API供应商（中转站、非官方接口）不支持多模态输入。当请求的messages数组中间出现type: "image"的base64图片块时，这些供应商会直接报错或行为异常。

它的工作原理是作为袋里层的拦截器，在请求转发之前运行。整流器扫描messages[*].content，检测type: "image"块，移除base64数据（通常有几MB），然后替换为文本提示，引导模型调用指定的skill来处理图片。

几个关键特性：

• 自动检测并替换messages中的type: "image"块
• 存在图片缓存引用时自动提取文件路径拼入提示
• 可配置调用的skill名称（默认：image-analysis）
• 与下方的图片分析技能无缝配合

配置起来很简单：路由设置 → 整流器区域 → 图片整流器，打开开关，按需修改skill名称即可。

2. 图片分析技能

这是一个独立的Python命令行图片视觉识别工具，兼容任何能执行Shell命令的AI CLI。

核心能力包括：

• 支持本地图片（jpg/png/gif/webp/bmp）、网络图片URL、系统剪贴板（macOS AppleScript）
• 多图对比（多次--image）
• Fallback机制：按配置顺序依次尝试所有provider，失败自动切换，第一个成功的结果标注[provider名]后返回

预置了30+ AI Provider：

它与图片整流器的联动逻辑是这样的：当某模型不支持图片时，整流器会将图片块替换为文本提示，引导模型调用Skill，模型自动通过CLI完成实际视觉分析。整个过程对用户透明，不需要手动执行Python脚本。

3. dev.sh — 开发启动脚本

封装了pnpm tauri dev / pnpm tauri build的便捷脚本：

./dev.sh # Debug模式（默认）
./dev.sh debug # Debug模式（含请求体打印）
./dev.sh release # Release模式
./dev.sh build # Release编译

预置了CARGO_HTTP_PROXY，方便国内网络环境下编译Rust依赖。

安装

从源码编译：

git clone https://github.com/piaomiaoguying/cc-switch.git
cd cc-switch
./dev.sh build

使用流程

第一步：注册AI Provider并获取API Key

本Skill预置了多个平台的视觉模型，均有免费额度，挑一个自己习惯的平台注册即可：

注册后获取API Key，填入Skill配置文件：

cp skills/image-analysis/scripts/config.example.json skills/image-analysis/scripts/config.json
# 编辑config.json，将各个平台的API Key填入对应字段

第二步：配置全局CLAUDE.md

在你的全局CLAUDE.md（~/.claude/CLAUDE.md）中加入以下规则，禁止直接使用read工具读取图片：

## 图片处理规范
禁止使用 `read` 工具读取任何图片文件（如.png, .jpg, .jpeg）
必须使用 image-analysis 这个 skill 来分析图片
当模型返回不支持直接接收图片输入时，自动调用 image-analysis 这个 skill 来分析图片

第三步：导入Skill到AI CLI

推荐通过CC Switch统一管理Skill，避免手动复制文件夹：

1. 将skills/image-analysis配置文件夹放在CC Switch目录下
2. 打开CC Switch → Skills管理
3. 在Claude Code和OpenCode对应的Skill开关处，开启image-analysis

这样CC Switch会自动将Skill同步到各CLI的Skill目录。

第四步：配置CC Switch路由与整流器

这一步最关键，需要打开三层开关：

① 打开本地路由

进入CC Switch → 路由设置：

• 打开本地路由总开关
• 打开Claude Code的路由开关（常见漏掉：总开关开了但Claude Code开关没开）

② 配置图片整流器

在路由设置界面往下滑，找到整流器区域：

• 打开整流器总开关
• 打开图片整流器开关
• 在Skill名称输入框中填入image-analysis

完成

以上配置完成后，正常的Claude Code实例通常会立即生效。如果老的实例没有生效，重启一个新的Claude Code实例即可。此时模型的网络请求会经过CC Switch袋里，CC Switch会对会话数据进行拦截修改：

之后的整体流程为：

Ctrl+V粘贴图片 → CC Switch袋里拦截 → 移除base64，替换为文本提示
→ 模型收到文本，调用image-analysis Skill → Skill读取图片并返回分析结果