A local plugin for image-heavy chats in Codex, Claude Code and other agents: earlier images stop going out with every message, and the model fetches the one it needs by its ID, also after compaction.
v0.11 方案:拆成接入层、核心层、面板层,接入其他 Agent 平台
状态:用户 2026-11-02 确认方案(第 7 节)。第 1–9 步已做完:Codex 自测和 Claude 桌面版实测通过(压缩自测里两张图没认出名字,0.10.0 一样),2026-11-02 发布 0.11.0。接下来改 README、定仓库名字、简介、标签,做视频和图片(第 7 节)。规格以 spec.md 为准,实现见 design.md,对外的接入说明是 ADAPTERS.md。本机的摸底记录和参考项目的笔记只在
local/,不进仓库。
1. 背景与目标
2026-10-31 用户定了新方向:从解决一个具体问题的工具,扩展成所有 Agent 平台都能轻松接进来的多模态上下文管理工具。别人让自己的 AI 写一层接入,就能提 PR 接自己的平台。
现在的代码做不到这一点:Codex 和 Claude 的逻辑缠在一起。
proxy.ts(约 1100 行)里,通用的转发、Codex 的改写、Claude 的改写、给 Claude 面板供数据的接口混在一起,靠platform === "codex"/"claude"分支。panel-state.ts、selection.ts、plugin-server.ts直接引用两个平台的会话索引。routes.ts里平台类型写死成两种。- 接一个平台大约要写一千多行:Claude 的会话索引、改写、思考记录、缓存加起来约 1200 行。
目标:
- 三层:接入层(一个平台一份,尽量薄)、核心层(不认识任何平台)、面板层(只经核心接口拿数据)。以后调算法只改核心层;维护某个平台只看它的那一份。
- Codex 和 Claude 的行为不变:这次是重组,不改用户看得到的任何行为。
- 对外接口文档和契约测试:第三方照文档写接入,跑契约测试证明能用。
- 用新结构接其他平台:WorkBuddy、OpenCode、Gemini CLI、pi、DeepSeek Harness,再加 Qwen Code、Cline、Kilo Code、goose、Cherry Studio,只接核心,不带面板,检验接入层是不是真的薄。
2. 已定的规则(用户 2026-11-02 定)
- 三层的分工如第 1 节。一个仓库,不拆仓库;拆成多个包以后看情况。
- 面板只在 Codex 桌面版和 Claude 桌面版。 以后接的平台默认都不带面板,除非用户主动要求。面板在接口文档里写成可选的一节;第三方想要面板,自己看这一层接。
- 翻译器只抽象操作,不抽象整份请求(第 3.4 节):不把各家格式整个翻译成我们自己的格式再翻回去。
- 不受现有设计约束:内部结构和机制可以重新设计;拆的过程中发现没用的、冗余的东西,直接清理。
- 顺序:先拆和整理,抽象层在拆的过程中成形,每一步都测;再写接口文档和契约测试;最后接新平台来检验。
3. 设计
3.1 目录
做完后的结构(文件清单见 design.md):
plugin/src/
proxy.ts、plugin-server.ts、cam.ts、engine.ts、platforms.ts 入口、引擎生命周期、平台登记表
core/ 核心层:不认识任何平台、任何请求格式(engine/transport.ts 是通往服务的路)
panel/ 面板层:只用核心
adapters/ 接入层
protocols/ 请求格式的翻译器:openai-responses、anthropic-messages、openai-chat、gemini;any.ts 给只接核心的平台用
codex/、claude/ 带面板的两个平台,各自读本地记录、改配置、开面板
workbuddy/、opencode/、gemini-cli/、pi/、qwen-code/、cline/、kilo-code/、goose/、cherry-studio/ 只接核心的平台,每个一个 platform.ts(pi 另有扩展)
dsh/ DeepSeek Harness 的 dsh 插件包(index.js、offload.js、package.json、cordis.patch.yml)
- 宿主规定位置的文件(
.codex-plugin/、.claude-plugin/、hooks/、.mcp.json、启动脚本)留在原处,只改它们指向的入口。 - 原先画的目标结构(core 下再分 session/、text/、tools/,加一个 api.ts)没有照搬:拆到那一步时按代码的实际情况定,核心是平铺的小文件。
3.2 三层各管什么
- 核心层:转发请求;决定每张图发不发、换成什么字;编号;勾选和自动选图;特征行;压缩后放回哪些图;取图工具按编号取图;统计和日志。核心只认会话、轮次、图片。
- 面板层:页面和面板工具,只通过核心的公开接口拿数据、改勾选。现在有两种宿主:MCP 应用(Codex 桌面版)和引擎提供的网页(Claude 桌面版)。
- 接入层:一个平台怎么接进来,见下面的契约。
3.3 接入契约
平台分两种:
带面板的平台(Codex、Claude Code):接入层读平台自己的本地记录(任务记录、会话记录),认会话、轮次、子代理和旁聊、压缩,改平台的配置,打开面板,还有平台特有的处理(Codex 的 WebSocket 降级、API key 线路;Claude 的思考签名重试、提示缓存)。这两份接入是厚的,因为面板要用这些信息。
只接核心的平台(其余所有平台):接入层只填一个条目(
core/platform.ts的CorePlatform):- 名字;
- 原地址:它的模型请求本来发去哪(按服务商填地址的平台,从它的设置里读,或用户在
cam connect时给出); - 认会话(可选):哪个请求头是会话编号;
- 旁路请求(可选):哪些请求不改(起标题、润色提示之类);
- 认平台:平台给它跑的命令设的环境变量(
cam detect用); - 装法:要改哪些设置文件、改成什么(
cam connect --apply照着写),以及给人看的步骤。
平台加一行进
platforms.ts就接上了。请求格式、哪几张图、省略哪些,都由核心和翻译器从请求本身算出来(第 3.8 节)。
3.4 翻译器
每种请求格式一个翻译器,提供三样:
- 认路径:哪些请求路径归它管。
- 读:把请求读成一份视图,内容是有哪些轮、每张图在哪一轮、是用户贴的还是工具返回的、内容哈希、能和本地记录对上的稳定标识、哪里能插说明、压缩项在哪。
- 写:把核心的决定落回原始请求。决定只有几种:把这张图换成这段字、在图前加标签、在某一轮前插一条说明、在压缩项后放回一些图。没动的部分原样保留;一张图都不换时原样转发原始字节。
格式特有的麻烦归翻译器自己管,例如 Anthropic 的思考签名和提示缓存。参考项目印证了这个选择:new-api 把整份请求互相翻译,每多一种输入格式,每个渠道都要多实现一个转换方法。
3.5 图片清单从哪来
- 平台提供了会话历史(Codex、Claude),就用它,和现在一样。
- 只接核心的平台:核心从经过引擎的请求里建清单(
core/request-index.ts,第 3.8 节)。
3.6 分层检查和契约测试
- 分层检查(单元测试):核心不引用
adapters/和panel/;面板只引用核心;平台文件夹之间不互相引用,翻译器只引用核心和别的翻译器。参考项目 claude-code-router 的请求流水线直接引用了各智能体的特殊功能,平台的特殊处理漏进了核心;这条检查就是防这个。 - 契约测试:每个翻译器、每个平台带一组样例请求,跑同一套测试:不改时原样输出;换图后图不在了、字在对的位置;插说明的位置对;不认识的字段原样保留。
3.7 发布
- 仍是一个版本、一份内容。全机只有一个引擎,所有平台共用;各平台装不同版本时,引擎会互相请对方退役,Codex 和 Claude 两份副本之间已经出现过(design 第 5 节)。所以不按平台拆成不同的包。
- 每个平台按它自己的方式装:Codex、Claude 照旧走各自的插件市场和安装命令;只接核心的平台把仓库克隆到一个固定的文件夹,
cam detect认出平台,cam connect <平台> --apply登记线路并改好平台的设置,cam disconnect撤回;DeepSeek Harness 用dsh plugin add装 dsh 包。 - 用户 2026-11-02 定:用户把一句话发给自己的 Agent,Agent 看仓库就能在对应的平台上装好,而且不会装错(例如 WorkBuddy 里的 DeepSeek 模型要装 WorkBuddy 的那一份)。所以平台由各平台给命令设的环境变量来认,不靠模型自己猜;改设置由命令来做,不让模型手改:记下改了哪几项、原来是什么(不复制整个文件:设置文件和 .env 里常有 API key),
cam disconnect只撤回还保持原样的设置。带注释的 JSON 不改,只打出步骤。 - 面板文件随包一起发,只有 Codex 桌面版和 Claude 桌面版的接入打开它。
- 拆的过程中插件版本号不动,免得 Codex 中途从工作区自动重装;全部做完再升到 0.11.0 发布。
3.8 只接核心的平台(用户 2026-11-02 定:除 Codex 和 Claude 桌面版外,都不接面板)
- 导流:平台的服务地址改成引擎的一条线路(
/__cam/routes/<编号>),线路记着原地址。请求原样转去原地址,只有图片相关的几处被改;引擎自己的请求头(x-cam-*)不往外发,其余请求头照转。 - 格式:按路径认:
/chat/completions、/responses、/messages、:generateContent/:streamGenerateContent(Gemini CLI 用 Google 账号登录时,内容包在request里)。四种格式各有翻译器,adapters/protocols/any.ts把它们串起来。 - 轮次:每条用户自己写了字的消息开始新的一轮;工具结果、只有图的消息算在当前轮。
- 自动选图一直开着:之前各轮的图换成占位文字,本轮的图照发;模型用
cam_view_image取回的图只在那一轮发,下一轮换成一句短说明。特征行不开:模型写的记录行在终端里会原样显示出来。 - 编号:按内容编号,同一张图在哪都是同一个编号;第一次见到时编号,原图存进数据目录(
platforms/<平台>/)。不读平台自己的记录。 - 认会话:平台请求头里的会话编号;没有就用我们的扩展加的
x-cam-session(pi);再没有就按第一条提问区分(同一平台、同样开头的两个会话会合成一个,编号仍按内容,不会拿错图)。 - 取图:平台的 MCP 服务(
plugin-server.ts,CAM_HOST=<平台>)只有cam_view_image,从最近一次发出带工具的请求的那个会话里取。 - 引擎保活:MCP 服务每几秒探一次引擎,引擎看到有平台在探就不退出(不再只认 Codex 和 Claude 的进程)。
- 不做:压缩后放回、面板、手动勾选、固定发送。
3.9 DeepSeek Harness(用户 2026-11-02 定:在接入层里顶替它官方的插件)
DSH 的请求可能用 DeepSeek 的文件模式发图(请求里是文件引用,不是图片数据),走引擎改不了,所以做成 dsh 插件包(adapters/dsh/),用 dsh plugin --profile <配置档> add 装。包里的补丁按 id 把官方底包的 image-offload 行停掉(两者注册同一个消息投影,只能留一个),再插上我们的(用户 2026-11-02 问能不能直接停掉官方的:能,装包时自动停):
- 保留官方插件做的事:服务因图片超预算拒绝请求时,标记最旧的几张卸载,然后重试。
- 加上自动选图:新一轮开始时(
agent/pre-step里轮次变了),把之前各轮还留着的图全部标记卸载。 - 官方的超预算卸载留在我们的插件里当兜底:一轮里就可能超预算(一步一张截图地控制浏览器),没有它请求会报错、这一轮结束。
- 卸载是 DSH 自己的机制:写进会话日志、永不撤回,模型看到的是写着附件名和只读路径的文字,需要时自己读回原图。所以不需要我们的取图工具,提示缓存的前缀也只往前走。
4. WorkBuddy 摸底(2026-11-02,本机 5.9.3,只看代码,没跑对话)
- Electron 桌面应用,里面打包了腾讯的 CodeBuddy Code 智能体(
@genie/agent-cli2.165.0)。 - 登录后的官方模型发到
https://www.workbuddy.cn加/v2/chat/completions,是 OpenAI Chat Completions 格式,带 Bearer 令牌。自定义模型写在~/.workbuddy/models.json,每个模型自己填url,个别可选 OpenAI Responses 格式。 - 导流:环境变量
CODEBUDDY_BASE_URL改官方地址;~/.workbuddy/settings.json的env会被写进智能体进程的环境变量。设了自定义地址后不再 gzip 压缩请求。也认HTTPS_PROXY。 - 插件:和 Claude Code 几乎一样的插件市场,插件目录里是
.codebuddy-plugin/plugin.json、.mcp.json,有 hooks。内置插件里有mcp-app类别(带 HTML 页面)。 - 会话:代码里有
X-Conversation-ID请求头,对话记录看起来是 jsonl。 - 11-02 抓包(只记请求的形状,不记内容和令牌):请求头里有
x-conversation-id(UUIDv7)和x-agent-type(润色提示这类旁路请求是auxiliary)。CODEBUDDY_BASE_URL要带/v2:那次没带,请求发到/chat/completions,服务回 405,看起来像“连不上”。 - 用户 11-02 定:不再实跑,按上面的结论写接入,等用户反馈。图片是不是
image_url的 data URL、登录令牌经过本机代理会不会被拒,没有实测。
5. 步骤
每一步一个短分支:跑全部单元测试和冒烟测试,再合并。动到引擎启动方式或安装的步骤,合并后重新安装,确认 Codex 和 Claude 都能连上(Codex 开着时不重装,等它关了再装)。
- 搭目录,加分层检查;搬不分平台的小文件(路径、语言、文字表、PNG、缩略图等),清理用不到的代码。行为不变。
- 拆改写:
rewrite.ts、claude-rewrite.ts里决定换哪张、写什么字的部分进核心,在请求里找图、改 JSON 的部分进两个翻译器。验收:各种勾选组合下改写结果和拆之前逐字节相同(对照测试)。 - 拆引擎:
proxy.ts的通用部分进核心;Codex 的部分(任务请求头、WebSocket 降级、API key 线路)和 Claude 的部分(会话请求头、思考记录重试、面板网页)进各自的接入。 - 拆找图:
thread-index.ts、claude-index.ts进各自的接入,实现核心的会话历史接口;selection.ts里认分叉和子代理的部分交给接入。 - 拆面板:
panel-state.ts只读核心接口;插件服务里的面板工具和取图工具分开。 - 拆安装:Codex 的配置和命令行、Claude 的 Mod 进各自的接入。
- 写
ADAPTERS.md(英文,对外)和契约测试;在 Codex 和 Claude 里跑一遍模型自测(gpt-6-sol,中英文)。 - 接其他平台:平台登记表(自动选图的规则收进核心、会话编号不限 UUID、引擎认所有平台的探活);openai-chat、gemini 两个翻译器;核心从请求建清单;WorkBuddy、OpenCode、Gemini CLI、pi 的条目,pi 的扩展,DSH 的插件包;
cam detect、cam connect --apply、cam disconnect;INSTALL.md 按平台写;Codex 在 cc-switch 切换后自动接回;README 底部的平台表;再接 Qwen Code、Cline、Kilo Code、goose、Cherry Studio(goose 的设置是 YAML、Cherry Studio 的在应用里,这两个只打出步骤)。不带面板,不实跑(第 7 节)。 - Claude 桌面版实跑一轮,然后推送、发 0.11.0。
6. 风险
- 第 2、3 步动的是每个请求都经过的代码,最容易出回归。靠逐字节对照测试兜底。
- 只接核心的五个平台都没实跑过,只有合成请求的测试。README 的平台表写明“新接入,欢迎反馈”,和实测过的 Codex、Claude 分开。
- cc-switch(切换 Claude Code、Codex 等的服务地址)每次切 Codex 的服务商,会删掉顶层的
openai_base_url、重写[model_providers.custom],把插件对 Codex 的接管抹掉。用户 2026-11-02 定:用户要能随便换模型,插件也照样起作用。所以引擎盯着 config.toml,一被改写就重新接上,线路指向用户刚选的服务商,切换照样生效(adapters/codex/setup.ts的keepRouted)。只在用户想用引擎(启用过、没停用,记在数据目录,不看 config.toml)且插件还在时做;十分钟里被改回三次就停手,免得和别的工具来回改。Codex 关着时切换的,下次启动先直连一次,再下次才经过引擎。Claude Code 不受影响:插件每个会话开始时重新读地址。没和真的 cc-switch 一起跑过。 - 文件搬家后,已安装的副本要靠
cam install更新;启动脚本里的入口路径要一起改,不能让已安装的配置指向不存在的文件。
7. 用户的决定(2026-11-02)
- 接入层做薄,核心层、面板层各自独立维护;以后调算法只改核心层。
- 面板只在 Codex 桌面版和 Claude 桌面版;以后接的平台默认不带面板,除非用户主动要求。
- 翻译器只抽象操作,不抽象整份请求。
- 一个仓库;拆包以后看情况;拆的过程中可以清理冗余。
- 按第 5 节的顺序做;不受现有设计约束。
- WorkBuddy 不再测;其余平台也不在本机实跑,按代码和文档写接入,对外展示,等别人提 issue 和 PR。
- 接入的平台:WorkBuddy、OpenCode、Gemini CLI、pi 写进接入层;DeepSeek Harness 在接入层里顶替它官方的插件,接不进就先不要;Antigravity 不写。
- README:删掉“为什么做这个”;开头改成多模态税的口径(多模态上下文的自动管理工具,装上就不用管),场景写短;最底下放平台表(各平台的简介和接入情况),不挡上面的展示内容,用来和其他平台双向引流。
- 用户换模型(cc-switch 等)后插件要照样起作用(第 6 节)。
- 安装:Agent 看仓库就能在所在平台装对,平台靠环境变量认,设置由命令改(第 3.7 节)。
- DeepSeek Harness 直接停掉官方的图片卸载,用我们的(第 3.9 节)。
- 这几个平台接完以后,再改 README、定新的仓库名字、简介、标签,做新的视频和图片,调整宣传口径。
- 再接的平台只接开源、用户多、用途多的:Qwen Code、Cline、Kilo Code、goose、Cherry Studio(Roo Code 的仓库已归档,不接)。闭源平台暂时不支持。测试只在 Codex 和 Claude 上实跑,其余平台不测(11-02 晚)。