Stop paying the multimodal tax. Your AI agent keeps every image it has seen but only sends the ones it needs: lighter chats, no endless reconnecting, no starting over. Works with Codex, Claude Code, Cline, Gemini CLI, OpenCode, WorkBuddy and more. Install once, forget it.
v0.4 变更方案:Claude 桌面 Code 接入
状态:随 v0.4.0 发布(2026-10-11)。2026-10-09 按用户要求整理;2026-10-10 用户确认:按现有插件的机制逐块移植,只在平台逼迫时改动(见第 1 节);2026-10-11 用户定:新账号校验思考记录时,由引擎去掉对不上的思考(D04-03),并授权不等审核直接发布。 当前版本的唯一规格仍是 spec.md,现有实现见 design.md。本目录记录 v0.4 的增量变更、关卡和开发任务,不另复制一套现行规格。 执行顺序:本方案 → 任务清单 → 验收标准。每个任务都要有对应验收和证据;通过路由实验不等于通过完整迁移。
1. 目标与范围
用户已明确的目标:在 Claude 桌面应用的 Code 标签页、本地会话、官方订阅登录 下使用当前素材管理能力。继续在同一个会话逐轮取消和恢复图片,原始对话与素材只读。只支持 API key、只支持终端,或只能转发文字,都不能满足该目标。
v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独立选择、重复关系、整轮勾选、来源筛选、发送预览、模型要图定位、自动选图和按需取回、中英文、面板与安装启停。各项详细行为引用现行规格,不在此重写。Claude 没有的 Codex 专属来源不伪造;只识别有可靠依据的来源。
按现有插件的机制逐块移植到 Claude(用户 2026-10-10 定):同仓新增 Claude 接入、保留 Codex 实现,不另起架构,不削减 v0.3 的功能。只有平台逼迫的地方才改,并写明原因;对应关系见下表。正式实现前由规格维护者将确认内容写回现有规格和方案。已有 Codex 功能保持可用是本方案的回归要求。
| 现有机制(见 design.md) | Claude 上的对应 |
|---|---|
| 本机引擎改写请求,同一个任务,历史不动 | 同一个引擎增加 /v1/messages 转发,上游固定为 api.anthropic.com |
config.toml 里带标记的 openai_base_url |
平台逼迫:桌面版不认 settings 里的地址,由插件里的 Mod 用 $.env.set 切换(D04-01) |
| 插件的 MCP 服务拉起、看守引擎,给面板提供数据 | Claude 插件同样带这个 MCP 服务拉起、看守引擎;面板的数据改由引擎的本机接口提供(D04-04);Mod 负责切地址和 /cam(D04-01、D04-04) |
请求头 x-codex-turn-metadata 认出任务 |
请求头 x-claude-code-session-id(D04-02) |
| 从本地记录只读编号,只追加;引擎和插件服务各自计算,不共享状态 | 从 Claude Code 的本地会话记录只读编号,做法相同(D04-02) |
按条目 id 对齐请求和记录,没有就用 call_id,再没有就用类型、轮次和内容哈希 |
消息块没有 id:工具图用 tool_use_id,用户图用最后一档(D04-02) |
| 占位符、重复占位符、“已提供”标签;勾选不变时逐字节相同 | 照搬(D04-03) |
| “上下文管理说明”开发者消息,插在第一张被省略的图所在那一轮的用户消息之前 | 平台逼迫:改用 role: "system" 消息,放在那条用户消息之后(D04-03) |
| WebSocket 握手回 426,让 Codex 改走 HTTP | 不需要:Claude Code 本来就走 HTTP 和 SSE |
| 改写不了就原样发送,面板提示原因 | 照搬;账号拒绝改过历史之后的思考时,先去掉对不上的思考记录、照样按勾选发送,还不行才原样发送(D04-03) |
| 面板是 MCP 应用,用户自己打开,不经过模型 | 平台逼迫:用户打不开插件的 MCP 应用,Mod 面板放不进网页。同一份 panel.html 改由引擎作为本机页面提供,用户输入 /cam 后在 Claude 桌面自带的浏览器里打开,仍不经过模型(D04-04) |
自动选图:cam_view_image 按编号取图,取回的图放在本轮末尾,副本下一轮换成说明 |
照搬,取图工具由同一个 MCP 服务提供(D04-05) |
本轮不扩大素材范围:原生 PDF/document、音频、视频和普通文本文件不因为换客户端就自动进入管理范围。工具渲染出的图片仍按图片处理。暂不增加其他模型供应商、云端会话、跨会话素材库或新的常驻系统服务。
2. 事实、证据与未知项
2.1 已实测
验证环境:Windows;Claude 桌面应用 2.26454.2.0,自带 Claude Code 2.1.293。结论只覆盖该环境,更新后需重跑相关验证。
- 项目 settings 中的
ANTHROPIC_BASE_URL不能覆盖桌面宿主启动时传入的同名变量。 - Mod 的
$.env.set()可以在会话运行时切换地址。真实桌面 Code 会话经过本机透明探针,保留 Bearer/OAuth capability、无 API key,请求带x-claude-code-session-id,Anthropic 返回 HTTP 200,主回复流完整结束。 - 用户实际执行开启、发送消息、关闭命令,并确认了可见回复和恢复提示。
- 本机探针的透明转发、认证头、SSE、取消和恢复共 9 项回归测试通过;桌面自带命令行校验实际安装副本通过。这些是实验工具证据,不是正式 v0.4 功能验收。
- 只写
enabledPlugins不完成安装;必须实际登记并安装插件,再加载到目标会话。首次命令缺失由漏安装造成,补安装后已解决。 - 面板(2026-10-10 桌面实测):Mod 面板只能画 Claude 自带的元素,放不进网页;Claude Code 不登记只给应用调用的工具,用户打不开插件的 MCP 应用。Mod 面板里的链接,点开交给系统默认浏览器。Mod 用
$.mcp.call("Claude_Browser", "preview_start", { url })能在桌面自带的浏览器里打开本机页面,默认权限模式下也不弹确认;这是桌面版给模型用的工具,不是公开给插件的接口,终端和 VS Code 里没有。 - 桌面版的新会话,发出第一条输入时才启动 Claude Code 进程。Mod 注册的命令在那之前不在输入框的命令列表里:输入时提示命令不存在,发出后照常执行。插件自带的命令文件一律带插件名前缀(
/codex-attachment-manager:cam)。 - 图片与思考(2026-10-10,T04-01,Haiku 5.5,推理强度 low,桌面订阅会话,工具查看的图,中英各 3 次):用户自己的账号接受改过的历史连同思考记录(全部 200)。全部省略后,模型不收回之前的描述、不猜新细节、不自己重读文件,勾回后看图答对;逐条说明写明何时写“需要 IMG-xxx”后,中英都 3/3 按编号要图。模拟新账号(
CAM_EXPERIMENT_BLOCK_BINDING=error)时,改写后的请求得到 400,引擎改发原始请求得到 200,对话不断,面板提示。自动选图:需要看图时都用cam_view_image取回并答对;不需要时,中文有 1 次多取,英文都不取;取回的副本下一轮换回说明。 - 新账号的思考校验(2026-10-10 至 11,Claude Code 2.1.295,Haiku 5.5,推理强度 high 和 max,模拟新账号):
- 引擎去掉对不上的思考(D04-03 现行做法):取消勾选后的第一个请求被拒,去掉 1 段对不上的思考后重发成功,之后同一会话直接这样发、不再被拒;取消之后新产生的思考在后面的请求里保留并被接受;全部勾回后,取消之前的思考放回去、取消期间产生的去掉,被接受。回答全部正确。面板提示去掉了几段(最终实测截图在验证机的
local/v04/shots/)。 - 实验中发现并修好两个问题:比较历史时把字符串内容和同样文字的文本块当成不同(Claude Code 的末尾系统消息就是这样变的),多去掉了本该保留的思考;记录不全时(换了哈希写法)把取消期间产生的思考当成对得上,请求被拒,最后的原样请求在真正的新账号上也会被拒,会话会卡住。现在记录不全时宁可多去掉。旧做法(被拒就原样发送)也有这个卡住的问题:新账号上改过的请求成功过一次,之后全部勾回,原样请求就被拒。
- 对照组
drop_block(服务端丢掉对不上的思考):只丢对不上的那段,之后新产生的思考保留。效果和引擎自己去掉相同,但要在正式请求里带 beta 请求头,有些思考设置下不能用,没采用。 - 代价:丢掉旧思路后模型要重新想。同一个追问,旧思考在时用 29 个思考 token,被去掉后用 2,422 个;推理强度 low 时模型很少在看图之后思考,这个问题很少触发。
- 引擎去掉对不上的思考(D04-03 现行做法):取消勾选后的第一个请求被拒,去掉 1 段对不上的思考后重发成功,之后同一会话直接这样发、不再被拒;取消之后新产生的思考在后面的请求里保留并被接受;全部勾回后,取消之前的思考放回去、取消期间产生的去掉,被接受。回答全部正确。面板提示去掉了几段(最终实测截图在验证机的
- 并行调用工具时,Claude Code 把除最后一个以外的结果挂在各自的调用记录下面,不在沿父记录回溯出的链上(2026-10-10 在测试中发现并修复)。
- 安装(2026-10-10,在隔离的配置目录里):从仓库导出的插件市场添加、安装到用户范围后,插件服务能起来;用 Codex 带的 Node,或只有系统的 Node 24,都能运行。
私有实验记录位于验证机的 local/claude-live-routing/;不得把原始记录、凭据、图片或本机路径复制到提交中。仓库只保留上述脱敏结论和实验方法。该目录被忽略,克隆仓库后无需存在。
2.2 已查证的平台约束,仍需在订阅链路实测
2026-10-09 查官方文档(链接见第 8 节)和桌面自带 Claude Code 2.1.293 的 Mod 类型定义。文档说的是 API 行为,订阅链路的实际表现以实测为准。
- 桌面启动的环境变量过滤,与 Mod 运行时设置是不同入口;正式生命周期是否一直保持有效,不能从一次文本请求推断。
- 思考签名:Fable 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5 做前缀校验。替换历史里的一张图、缩短一个工具结果,或增删
tools里的工具,都会让之后所有的思考块失效。2026-08-31 起注册的账号默认返回 400;更早的账号照样校验,但放行给模型。加 beta 头thinking-binding-controls-2026-08-01并设thinking.block_binding.prefix_mismatch_behavior: "error",老账号也按新账号拒绝,可用于实验;只加 beta 头、不设该字段,响应会列出放行的失效块。文档明说代理自己的改写也算编辑。服务端上下文编辑只能按规则清掉最早的工具结果,不能指定某张图,也碰不到用户消息里的图。2026-10-10 实测(见 2.1):订阅链路接受该 beta 头;400 由引擎接住,Claude Code 看不到;用户自己的账号是放行的那种。2026-10-11 查证:比较的是值,不看 JSON 写法和键的顺序;400 写明第一个失效的块和前面第一处不同的位置;去掉开头或末尾的思考可以,去掉中间的会让后面的失效,把去掉过的放回去,会让它不在期间产生的失效;文档要求代理去掉思考重试时不要藏起来。 - 说明消息的位置:对话中途可以放
role: "system"消息,不需要 beta 头,但它必须紧跟在用户消息之后,后面是助手消息或已是最后一条。所以 Codex 的位置(那一轮用户消息之前)在 Claude 上不合法。2026-10-10 实测:订阅链路接受,效果见 2.1。 turn.step只能改模型和推理强度,不是历史消息改写接口,不能替代请求改写引擎。
2.3 尚未通过
带思考记录的图片取消/恢复、历史与请求中的图片出现记录对齐、完整桌面内面板、自动取图、续聊/分叉/多会话隔离、登录刷新、免配置安装及失败恢复。目前均不得标记为完成。其中取消/恢复、对齐和自动取图已有 G04-1 的实测证据(见 2.1),正式验收还没做。
3. 变更要求与追踪
| 编号 | v0.4 增量要求 | 设计边界 | 任务 | 验收 |
|---|---|---|---|---|
| R04-01 | 桌面本地 Code 保留官方订阅接入,免手改配置 | D04-01、D04-06 | T04-00、T04-03、T04-09 | A04-01、A04-10 |
| R04-02 | 同一会话逐轮取消、恢复;原始记录与素材只读 | D04-02、D04-03 | T04-01、T04-04、T04-05 | A04-02、A04-03、A04-04、A04-09 |
| R04-03 | 稳定编号、重复关系、可靠来源与会话隔离 | D04-02、D04-04 | T04-04、T04-06 | A04-05、A04-10 |
| R04-04 | Code 桌面内的完整图片管理面板 | D04-04 | T04-02、T04-07 | A04-06、A04-07 |
| R04-05 | 保持 v0.3 自动选图、固定发送、按需取回语义 | D04-03、D04-05 | T04-01、T04-08 | A04-04、A04-08 |
| R04-06 | 双语、隐私、原样转发和无法改写的可见提示 | D04-03、D04-04、D04-06 | T04-05、T04-07、T04-09 | A04-02、A04-07、A04-09、A04-10 |
| R04-07 | Codex 无退化,验证后再发布 | D04-01、D04-06 | T04-03、T04-10、T04-11 | A04-11、A04-12 |
4. 设计边界
D04-01 接入与透明转发
沿用已验证的会话内 Mod 接入路径:先确认本机引擎就绪,再切换当前 Code 进程地址;保存原值,停用时恢复。Mod 负责切地址,以及 /cam 打开面板(D04-04)。只绑定本机地址,保留系统代理和用户已有的 NO_PROXY 设置。引擎就是现有引擎,增加 /v1/messages 转发,固定官方 Anthropic 上游,不提供任意目的地转发。
照原机制,由插件的 MCP 服务拉起并看守引擎(见 design.md 第 5 节)。Codex 与 Claude 共用这个引擎,引擎的退出条件和替换规则改为同时考虑两边(现在只看有没有 Codex 进程)。OAuth、版本、beta 和会话相关请求头需要透传,认证值不得进入日志。查询串、错误响应和 SSE 都须保留;客户端取消时关闭上游请求。正文无需改写时保留原始字节。MCP 服务在 Claude 下的 Node 运行环境在 T04-03 中确定,不把实验端口或本机安装路径写死进正式安装包。
D04-02 Claude 图片与会话适配
照原机制新增 Claude 的会话读取:从 Claude Code 的本地会话记录只读、增量地找图和编号,只追加,已有编号不变;引擎和插件服务各自计算,不共享状态。Mod 的读取接口只在 Claude Code 进程里,引擎拿不到,不作为编号依据。不写回原始会话。
区分直接图片块和嵌套工具结果中的图片;原生 document 等未知结构保留。编号对应每次出现,不能把图片哈希当作唯一出现编号。相同内容、不同出现、工具取回副本需要分别处理。对齐沿用原机制的顺序:消息块没有条目 id,工具结果里的图用 tool_use_id(相当于 call_id),用户消息里的图用类型、轮次和内容哈希。历史存储与发出请求可能有预处理差异,必须用实验确定匹配方式,无法可靠对应就原样放行并提示。
会话按每个请求的 x-claude-code-session-id 认出,不只在插件加载时缓存。Codex 与 Claude 的状态隔离;并行会话、续聊、分叉和子代理不能误用另一会话的选择。压缩(/compact 与自动压缩)和 /rewind 回退之后,已有编号不变、选择不串。
D04-03 Claude 请求改写与思考兼容
单独适配 Anthropic Messages。只修改确定的目标图片块及必要的占位说明,保留工具容器、调用配对、消息顺序和未触碰字段。不得把整份请求转成 OpenAI Responses 再转回来。上下文管理说明改用 role: "system" 消息,放在第一张被省略的图所在那条用户消息之后(Anthropic 不允许放在用户消息之前);它和改图在同一处,不扩大思考失效的范围。订阅链路是否接受、Claude 模型的效果在 T04-01 中验证。
保留现行选择与占位语义,Claude 措辞需分别跑中英文模型验收。选择不变时输出稳定;自动取图不能反复修改前面的占位文本。
思考块原样转发,不关思考。账号放行时效果与 Codex 相同。账号拒绝改过历史之后的思考时(2026-08-31 起注册的账号),引擎去掉和实际发出的历史对不上的思考记录,照样按勾选发出;之后新产生的思考保留;面板提示去掉了几段。这是用户 2026-10-11 看过实验证据(见 2.1)后选定的降级:模型少了被改位置之后的那部分旧思路。还不行时才按“改写不了就原样发送”处理,面板提示,这一次不计作取消成功。服务端上下文编辑不能指定某张图,drop_block 要在正式请求里带 beta 头,都不采用。做法见 design.md 第 12 节。
D04-04 面板与业务规则复用
面板与 Codex 一致(用户 2026-10-10 要求):复用同一份 panel.html 和面板数据,用户自己打开,不经过模型。平台逼迫的改动(见 2.1):用户打不开插件的 MCP 应用,Mod 面板放不进网页,所以由引擎在本机提供面板页(/__cam/panel?session=<会话 id>),页面前加一段桥接脚本代替 MCP 应用宿主,把面板的调用转成引擎的本机接口;Codex 特有的启用、停用和新任务绑定不出现。页面和接口只接受用本机名字访问、不来自其他网站的请求。
用户输入 /cam,面板就在 Claude 桌面自带的浏览器里打开,在对话旁边(用户 2026-10-10 选定)。只有两种情况弹出 Mod 小面板:自带浏览器打不开(终端、VS Code 或调用失败)时,给出面板链接和复制按钮;本会话的请求没经过引擎、勾选不会生效时,提醒用户。新会话的第一条输入就是 /cam 时,输入框会提示命令不存在,发出后照常打开;保持现状,在用户文档里写明(用户 2026-10-10 定)。
复用候选包括选择状态、图片指纹、重复关系、缩略图处理、编号识别和面板数据字段。先做单图,再做多图的桌面内面板实验,验证缩略图、放大预览、勾选、状态保存与当前会话绑定。验收在 Claude 桌面里用 /cam 打开的面板上做;在外部浏览器里打开同一页面只用于调试。关键界面节点按 AGENTS.md 截图给用户,等待反馈后继续界面开发。
D04-05 自动取图
先完成手动闭环,再接自动模式。保留当前默认关闭、手动与固定发送分开、当前轮新图照常发送、历史未固定图省略、取回只用于本轮、下一轮省略副本的规则。取图工具照原机制由插件的 MCP 服务提供,始终注册、不随开关增删:增删 tools 里的工具也会让之后的思考失效。
工具注册成功不代表图片已到模型。必须检查模型实际看到原图中的合成标记,并检查下一轮请求。思考兼容关卡也覆盖工具图及副本省略。模型无权修改用户选择或开关。
D04-06 安装、恢复与回归
Claude 插件入口与 Codex 入口分别安装;只提取确实需要共享的规则,不先重构为通用供应商框架。Claude 插件的内容是 MCP 服务(与 Codex 共用 plugin/src 的运行代码)加一个 Mod(切地址、/cam 打开面板)。运行代码在 plugin/src,测试与实验在 spike,安装脚本在 scripts;Claude 插件的目录与清单由 T04-03 确定。
安装必须校验实际安装副本和目标会话加载,不能只写启用配置。恢复只影响工具自管的地址/设置,不覆盖用户的其他配置。验证卸载、重载、桌面重启、引擎失败、登录刷新和版本更新;不新增系统计划任务等常驻机制。
Codex 现有自测、安装和卸载保持可用;共享运行代码变化后重新运行 cam install。不因新文档提前修改插件版本、README 支持声明或 Release。
5. 实施关卡
| 关卡 | 进入条件 | 工作 | 退出条件 |
|---|---|---|---|
| G04-0 路由入口 | 真实桌面官方订阅 | 最小透明转发实验 | 已通过 T04-00;仅证明入口 |
| G04-1 核心可行性 | G04-0;T04-01 用 Haiku 5.5(用户 2026-10-10 定),运行次数在开始前与用户确认 | T04-02 面板实验(面板形式见 D04-04),T04-01 图片/思考闭环及最小取回副本实验 | A04-04 的前置子集及面板实验有实测证据;界面经用户反馈;没有未确认的降级 |
| G04-2 正式适配 | G04-1 通过,规格维护者将目标与采用方案写回现有文档 | T04-03–T04-07 | 手动模式与完整面板通过对应验收 |
| G04-3 自动模式 | 手动模式稳定;核心关卡覆盖取图副本 | T04-08 | 自动取图语义和模型行为通过 |
| G04-4 交付 | 前述功能通过 | T04-09–T04-11 | 全部验收、回归、安装检查通过,用户确认后再发布(2026-10-11 用户授权不等审核直接发布,之后自己验收) |
G04-1 任一核心能力失败时,不跳过关卡开发完整面板或宣称 v0.4 可用。先追溯原因、记录可行选项;涉及官方订阅、同会话连续性、桌面内交互或思考能力的取舍,由用户确认后更新规格。
6. 文档与开发纪律
docs/spec.md、docs/design.md按 AGENTS.md 继续由 Claude 维护。正式实现前将确认的 v0.4 增量写回原文;未发布时清楚区分当前已实现与计划内容,不另保存 old/new 两套规格。- 任务按顺序执行,每项标明依赖、验收与证据。可自动化的行为按 TDD;未知原因的失败先按 systematic-debugging 复现和定位。
- 完成前按 verify-before-done 核验证据;跨模块、认证与服务边界按 code-review 审阅。文档改动只检查结构、链接、事实与状态,不为文档造运行测试。
- 在短分支工作;提交、合并和发布遵循 AGENTS.md。未验收的项目不勾完成。
- Codex 模型自测继续遵守 AGENTS.md 的模型、推理强度和双语矩阵。Claude 专项验收必须使用真实 Claude 桌面订阅模型;自动化前需确定模型范围和成本上限,不能用 GPT 自测替代,也不要求 API key。
- 真实证据只在
local/或工具数据目录;可提交测试样例必须合成或脱敏。Windows 优先,其他平台的 CI 与桌面实测范围分别说明。
7. 开始正式实现前需确定
- 正式专项验收的模型范围与成本上限(G04-1 用 Haiku 5.5),以及要覆盖的账号差异(2026-08-31 前后注册)。
G04-1 的实测结论见 2.1;Claude 插件的目录、清单和 Node 运行环境见 design.md 第 12 节;确认的内容已写回 spec.md、design.md(2026-10-10)。
8. 资料依据
- 订阅与网关:仅切换地址不等于切换凭据,OAuth capability 需要透传。
- Mod API、Mod 参考:环境、命令、工具和界面能力;以安装版本接口和真实桌面实验为准。
- Preserved thinking:做前缀校验的模型、按账号注册时间的处理、实验用的 beta 头;订阅链路的表现尚待验证。
- Mid-conversation system messages:对话中途
role: "system"消息的位置规则。 - Context editing:服务端清理只按规则清最早的工具结果或思考,不能指定某张图。
- 插件安装:安装、启用和会话加载是不同步骤。