Skip to content

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.

docs(v0.11): plan the three-layer split and WorkBuddy support

chipfighter93342e2b48d1
diff --git a/AGENTS.md b/AGENTS.md
index 645bf42..3ae7a4b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,7 @@ Context Attachment Manager(上下文素材管理器,2026-10-11 前叫 Codex
- [docs/v0.7/plan.md](docs/v0.7/plan.md):v0.7 方案,Codex 的子代理和旁聊也自动选图(已发布 0.7.0)。
- [docs/v0.8/plan.md](docs/v0.8/plan.md):v0.8 方案,模型给每张图写特征行、压缩后照样拿对图,面板改成搜索加缩略图(已发布 0.8.0)。
- [docs/v0.10/plan.md](docs/v0.10/plan.md):v0.10 方案,压缩和续接之后照样拿回之前的图,编号不变(已发布 0.10.0;关卡结果见方案第 3 节)。
+- [docs/v0.11/plan.md](docs/v0.11/plan.md):v0.11 方案,把插件拆成接入层、核心层、面板层,并接入 WorkBuddy(进行中)。
- [docs/history/v0.1/](docs/history/v0.1/):v0.1 的开发记录(原方案、任务记录、各阶段报告、最初的构想),只作参考,不作依据。
- [CHANGELOG.md](CHANGELOG.md):每个版本的更新记录,发布时就是 Release 说明。
- [eval/README_CN.md](eval/README_CN.md):评测(英文版 [eval/README.md](eval/README.md)),装插件和不装插件的对比:方法、结果和复现步骤。这一份是 Codex 里的关键帧对话;Claude Code 里压缩两次再分叉的长任务在 [eval/long-task/](eval/long-task/README_CN.md)。
diff --git a/docs/spec.md b/docs/spec.md
index aceb03a..3461e34 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -1,6 +1,6 @@
# 规格:Context Attachment Manager(上下文素材管理器)
-> 本文件是目标、范围、约束和验收标准的唯一事实来源(2026-09-24 经用户、Claude、Codex 三方确认),描述当前版本 v0.10.0,以后随版本更新。v0.4 加的 Claude 桌面 Code 接入,相关内容都标着“v0.4”;它的关卡、任务和验收步骤见 [v0.4/](v0.4/)。v0.5 加的 Claude Code 压缩后保留图片标着“v0.5”,方案和实测见 [v0.5/plan.md](v0.5/plan.md)。v0.6 的默认开启自动选图和 Claude 桌面版自动打开面板标着“v0.6”,见 [v0.6/plan.md](v0.6/plan.md)。v0.7 的 Codex 子代理和旁聊也自动选图标着“v0.7”,见 [v0.7/plan.md](v0.7/plan.md)。v0.8 的特征行(压缩后照样拿对图)和重做的面板(凭印象找图)标着“v0.8”,见 [v0.8/plan.md](v0.8/plan.md)。v0.9 把两平台的服务线路分开,并接管兼容中转;技术做法见 [design.md](design.md) 第 2、5、12 节。v0.10 让两个平台在压缩之后(Claude 还包括续接之后)照样拿回之前的图,标着“v0.10”,见 [v0.10/plan.md](v0.10/plan.md)。项目 2026-10-11 由 Codex Attachment Manager 改名,因为不再只给 Codex 用(用户定);安装用的标识(`codex-attachment-manager`)和数据目录不变,已装的用户照常升级。
+> 本文件是目标、范围、约束和验收标准的唯一事实来源(2026-09-24 经用户、Claude、Codex 三方确认),描述当前版本 v0.10.0,以后随版本更新。v0.4 加的 Claude 桌面 Code 接入,相关内容都标着“v0.4”;它的关卡、任务和验收步骤见 [v0.4/](v0.4/)。v0.5 加的 Claude Code 压缩后保留图片标着“v0.5”,方案和实测见 [v0.5/plan.md](v0.5/plan.md)。v0.6 的默认开启自动选图和 Claude 桌面版自动打开面板标着“v0.6”,见 [v0.6/plan.md](v0.6/plan.md)。v0.7 的 Codex 子代理和旁聊也自动选图标着“v0.7”,见 [v0.7/plan.md](v0.7/plan.md)。v0.8 的特征行(压缩后照样拿对图)和重做的面板(凭印象找图)标着“v0.8”,见 [v0.8/plan.md](v0.8/plan.md)。v0.9 把两平台的服务线路分开,并接管兼容中转;技术做法见 [design.md](design.md) 第 2、5、12 节。v0.10 让两个平台在压缩之后(Claude 还包括续接之后)照样拿回之前的图,标着“v0.10”,见 [v0.10/plan.md](v0.10/plan.md)。项目 2026-10-11 由 Codex Attachment Manager 改名,因为不再只给 Codex 用(用户定);安装用的标识(`codex-attachment-manager`)和数据目录不变,已装的用户照常升级。v0.11(进行中)把插件拆成接入层、核心层、面板层,并接入 WorkBuddy,见 [v0.11/plan.md](v0.11/plan.md);做完之前,本文件描述的行为仍是 v0.10.0 的。
> 技术方案见 [design.md](design.md)。v0.1 的开发记录(原方案、任务记录、各阶段报告、最初的构想)归档在 [history/v0.1/](history/v0.1/),只作参考。
## 1. 目标
@@ -9,6 +9,8 @@
v0.4:同样的管理也用在 Claude 桌面应用的 Code 标签页里(本地会话、官方订阅登录)。做法是把现有插件的机制逐块移植过去,不另起架构、不削减功能,只在平台逼迫的地方改(用户 2026-10-10 定)。和 Codex 不同的地方见下面“Claude Code(v0.4)”一节。
+v0.11(用户 2026-10-31、11-02 定):做成所有 Agent 平台都能轻松接进来的多模态上下文管理工具。插件分三层:每个平台一份薄的接入层,核心层不认识任何平台,面板层只经核心的接口拿数据;核心层和面板层各自独立维护。第三方照对外的接口文档写自己平台的接入,跑契约测试证明能用,再提 PR。面板只在 Codex 桌面版和 Claude 桌面版,以后接的平台默认不带面板,除非用户主动要求。
+
### 用户场景
用户先上传参考图 A,Codex 生成图片 B,用户再引用 B 要求修改。面板按时间顺序列出 A、B,以及 B 再次出现的记录,默认全部勾选。用户取消 A 和 B 的再次出现,然后继续创作:A 换成占位符,B 的再次出现换成指向 B 的占位符。之后任何一轮,用户都可以重新勾选 A,让它从下一次请求起重新进入上下文。
@@ -212,10 +214,11 @@ v0.1 到 v0.3 都不做下面这些。其中音频和其他语言已确认是后
- 生成时交给生图工具哪些参考图:不归插件管;
- 改检索算法(独立的检索模块、字段化标签等):真实会话里模型按编号选图很准,先修压缩和续接,修完以后小规模回放,哪里错了再针对改;
- 浏览器和电脑操作截图的专门规则(例如同一轮只发最近几张):另议。
-- 所有 agent 平台通用的版本(用户 2026-10-18 定:先不做):只有自动选图、不带面板,任何多模态 agent 客户端都能装,压缩后也能准确找回图片。原因:
- - 省略旧图要让引擎站在客户端和模型 API 之间,只有允许改 API 地址的客户端接得进来,闭源客户端一般接不进。MCP 只能给模型加取图工具,不能从客户端发出的历史里删图。
- - 每接一个客户端,都要单独适配它的请求格式、分轮方式和本地记录;编号和压缩后准确找回都靠读它的本地记录。
- - 当时查到的需求集中在 Codex 和 Claude Code。
+- v0.11 也不做:
+ - 新平台的面板(用户 2026-11-02 定:默认不带,用户主动要求时再接);
+ - 让模型请求经过不了引擎的客户端:省略旧图要让引擎站在客户端和模型 API 之间,只有能改 API 地址或走代理的客户端接得进来;MCP 只能给模型加取图工具,不能从客户端发出的历史里删图;
+ - 跨请求格式的转换:翻译器只改图片相关的几处,请求照原格式发往原服务(v0.9 的规则不变);
+ - 拆成多个仓库(用户 2026-11-02 定;拆成多个包以后看情况)。
## 3. 硬约束
@@ -352,6 +355,15 @@ v0.1 之前的阶段验收(阶段 0 的重建路线、代理路线 P2)都已
5. 写错的特征行能更正;被打断那一轮里还没有特征行的图,下一轮再发一次让模型补写。
6. 原有测试和自测不退化(gpt-6-sol,中英文);Claude 桌面版用 `/compact` 再续接实测一次。
+### v0.11
+
+> 用户 2026-11-02 定,方案和步骤见 [v0.11/plan.md](v0.11/plan.md)。
+
+1. 代码分成接入层、核心层、面板层,分层检查测试通过:核心层不引用接入层和面板层,面板层只经核心的公开接口。
+2. Codex 和 Claude 的行为不变:原有单元测试和冒烟测试全过;各种勾选组合下改写结果和拆之前逐字节相同;模型自测不退化(gpt-6-sol,中英文)。
+3. 有对外的接入接口文档(英文)和契约测试;面板在文档里是可选的一节,新平台默认不接。
+4. WorkBuddy:装上后官方模型的请求经过引擎,之前各轮的图按自动选图省略,模型能按编号取回;不带面板。实跑一轮验证。
+
## 5. 待定问题
- 在插件页面移除或关掉插件、没先在面板里停用时,代理设置还在:
diff --git a/docs/v0.11/plan.md b/docs/v0.11/plan.md
new file mode 100644
index 0000000..995a518
--- /dev/null
+++ b/docs/v0.11/plan.md
@@ -0,0 +1,138 @@
+# v0.11 方案:拆成接入层、核心层、面板层,接入 WorkBuddy
+
+> 状态:用户 2026-11-02 确认方案(第 7 节),按第 5 节的步骤做。规格以 [spec.md](../spec.md) 为准,实现见 [design.md](../design.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 行。
+
+目标:
+
+1. **三层**:接入层(一个平台一份,尽量薄)、核心层(不认识任何平台)、面板层(只经核心接口拿数据)。以后调算法只改核心层;维护某个平台只看它的那一份。
+2. **Codex 和 Claude 的行为不变**:这次是重组,不改用户看得到的任何行为。
+3. **对外接口文档和契约测试**:第三方照文档写接入,跑契约测试证明能用。
+4. **用新结构接 WorkBuddy**,检验接入层是不是真的薄。
+
+## 2. 已定的规则(用户 2026-11-02 定)
+
+1. 三层的分工如第 1 节。一个仓库,不拆仓库;拆成多个包以后看情况。
+2. **面板只在 Codex 桌面版和 Claude 桌面版。** 以后接的平台默认都不带面板,除非用户主动要求。面板在接口文档里写成可选的一节;第三方想要面板,自己看这一层接。
+3. **翻译器只抽象操作,不抽象整份请求**(第 3.4 节):不把各家格式整个翻译成我们自己的格式再翻回去。
+4. **不受现有设计约束**:内部结构和机制可以重新设计;拆的过程中发现没用的、冗余的东西,直接清理。
+5. **顺序**:先拆和整理,抽象层在拆的过程中成形,每一步都测;再写接口文档和契约测试;最后接新平台来检验。
+
+## 3. 设计
+
+### 3.1 目录
+
+```
+plugin/src/
+ core/ 核心层:不认识任何平台、任何请求格式
+ engine/ 本机代理:监听、线路、HTTP 和 WebSocket 转发、系统代理、健康检查、退役
+ session/ 会话的图片清单和编号、勾选、自动选图、特征行和评价、压缩后放回的决定
+ text/ 发给模型的文字:占位符、说明、标签、清单(中英文)
+ tools/ 取图工具 cam_view_image 的逻辑
+ api.ts 给接入层和面板用的公开接口
+ panel/ 面板层:只用 core/api.ts
+ adapters/ 接入层
+ protocols/ 请求格式的翻译器:openai-responses、anthropic-messages,以后 openai-chat、gemini
+ codex/ common(config.toml、任务记录)、desktop、cli
+ claude/ common(会话记录)、desktop(Mod、面板自动打开)、code
+ workbuddy/
+```
+
+- 接入层按厂商分文件夹,里面按入口分。同一家的两个入口共用配置文件和本地记录,放在一起。
+- 宿主规定位置的文件(`.codex-plugin/`、`.claude-plugin/`、`hooks/`、`.mcp.json`、启动脚本)留在原处,只改它们指向的入口。
+- 上面是目标结构。具体文件怎么分,拆到那一步时按代码的实际情况定,不为了对齐这张图硬拆。
+
+### 3.2 三层各管什么
+
+- **核心层**:转发请求;决定每张图发不发、换成什么字;编号;勾选和自动选图;特征行;压缩后放回哪些图;取图工具按编号取图;统计和日志。核心只认会话、轮次、图片。
+- **面板层**:页面和面板工具,只通过核心的公开接口拿数据、改勾选。现在有两种宿主:MCP 应用(Codex 桌面版)和引擎提供的网页(Claude 桌面版)。
+- **接入层**:一个平台怎么接进来,见下面的契约。
+
+### 3.3 接入契约
+
+一个平台必须提供:
+
+1. **名字和格式**:平台编号,用哪个翻译器。
+2. **导流**:装上时让平台的模型请求经过引擎(改配置文件、写环境变量或用 Mod),卸载时只还原自己写的部分;注册 MCP 服务,让模型能用 `cam_view_image`。
+3. **认会话**:从请求里认出会话、轮次,以及它是主对话、子代理还是旁聊、来自哪个会话。
+4. **认取图的调用方**:`cam_view_image` 被调用时,是哪个会话在调(Codex 从调用的 `_meta` 拿,Claude 从 `CLAUDE_CODE_SESSION_ID` 拿)。
+
+可以提供:
+
+5. **会话历史**:读平台的本地记录,给出图片出现的顺序、来源和名字、模型回复的文字(核心从里面读特征行)、被打断的轮次、压缩信息、会话的开始时间和分叉关系、面板搜索用的每轮文字。不提供时由核心从请求里建(第 3.5 节)。
+6. **平台特有的处理**:例如 Codex 的 WebSocket 降级为 HTTP、API key 登录转去 OpenAI。
+7. **面板**:怎么在这个平台里打开面板。默认不提供(第 2 节第 2 条)。
+
+### 3.4 翻译器
+
+每种请求格式一个翻译器,提供三样:
+
+- **认路径**:哪些请求路径归它管。
+- **读**:把请求读成一份视图,内容是有哪些轮、每张图在哪一轮、是用户贴的还是工具返回的、内容哈希、能和本地记录对上的稳定标识、哪里能插说明、压缩项在哪。
+- **写**:把核心的决定落回原始请求。决定只有几种:把这张图换成这段字、在图前加标签、在某一轮前插一条说明、在压缩项后放回一些图。没动的部分原样保留;一张图都不换时原样转发原始字节。
+
+格式特有的麻烦归翻译器自己管,例如 Anthropic 的思考签名和提示缓存。参考项目印证了这个选择:new-api 把整份请求互相翻译,每多一种输入格式,每个渠道都要多实现一个转换方法。
+
+### 3.5 图片清单从哪来
+
+- 平台提供了会话历史(Codex、Claude),就用它,和现在一样。
+- 没提供的平台:核心从经过引擎的请求里建清单,图第一次出现时编号,原图存在数据目录,压缩以后从那里放回。这是新机制,分叉、撤回、多个会话共用引擎时编号怎么保持稳定,在第 5 节第 8 步单独设计,不影响 Codex 和 Claude。
+
+### 3.6 分层检查和契约测试
+
+- **分层检查**(单元测试):核心不引用 `adapters/` 和 `panel/`;面板只引用 `core/api.ts`;平台文件夹之间不互相引用(同一家的 `common` 除外),翻译器只被平台引用。参考项目 claude-code-router 的请求流水线直接引用了各智能体的特殊功能,平台的特殊处理漏进了核心;这条检查就是防这个。
+- **契约测试**:每个翻译器、每个平台带一组样例请求,跑同一套测试:不改时原样输出;换图后图不在了、字在对的位置;插说明的位置对;不认识的字段原样保留。
+
+### 3.7 发布
+
+- 仍是一个版本、一份内容。全机只有一个引擎,所有平台共用;各平台装不同版本时,引擎会互相请对方退役,Codex 和 Claude 两份副本之间已经出现过(design 第 5 节)。所以不按平台拆成不同的包。
+- 每个平台按它自己的方式装:Codex、Claude 照旧走各自的插件市场和安装命令;新平台在它那一步定(WorkBuddy 有和 Claude Code 几乎一样的插件市场)。
+- 面板文件随包一起发,只有 Codex 桌面版和 Claude 桌面版的接入打开它。
+- 拆的过程中插件版本号不动,免得 Codex 中途从工作区自动重装;全部做完再升到 0.11.0 发布。
+
+## 4. WorkBuddy 摸底(2026-11-02,本机 5.9.3,只看代码,没跑对话)
+
+- Electron 桌面应用,里面打包了腾讯的 CodeBuddy Code 智能体(`@genie/agent-cli` 2.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。
+- 要实跑确认:env 对桌面版的智能体进程是否生效;登录令牌经过本机代理会不会被拒;模型请求里带不带会话编号;图片是不是 `image_url` 的 data URL。跑对话会用掉 WorkBuddy 的额度。
+
+## 5. 步骤
+
+每一步一个短分支:跑全部单元测试和冒烟测试,再合并。动到引擎启动方式或安装的步骤,合并后重新安装,确认 Codex 和 Claude 都能连上(Codex 开着时不重装,等它关了再装)。
+
+1. 搭目录,加分层检查;搬不分平台的小文件(路径、语言、文字表、PNG、缩略图等),清理用不到的代码。行为不变。
+2. 拆改写:`rewrite.ts`、`claude-rewrite.ts` 里决定换哪张、写什么字的部分进核心,在请求里找图、改 JSON 的部分进两个翻译器。验收:各种勾选组合下改写结果和拆之前逐字节相同(对照测试)。
+3. 拆引擎:`proxy.ts` 的通用部分进核心;Codex 的部分(任务请求头、WebSocket 降级、API key 线路)和 Claude 的部分(会话请求头、思考记录重试、面板网页)进各自的接入。
+4. 拆找图:`thread-index.ts`、`claude-index.ts` 进各自的接入,实现核心的会话历史接口;`selection.ts` 里认分叉和子代理的部分交给接入。
+5. 拆面板:`panel-state.ts` 只读核心接口;插件服务里的面板工具和取图工具分开。
+6. 拆安装:Codex 的配置和命令行、Claude 的 Mod 进各自的接入。
+7. 写 `ADAPTERS.md`(英文,对外)和契约测试;在 Codex 和 Claude 里跑一遍模型自测(gpt-6-sol,中英文)。
+8. 接 WorkBuddy:先实跑抓包,核实第 4 节没确认的几点;写 openai-chat 翻译器;核心加从请求建清单;定安装方式。不带面板。
+
+## 6. 风险
+
+- 第 2、3 步动的是每个请求都经过的代码,最容易出回归。靠逐字节对照测试兜底。
+- 从请求建清单是新机制,第 8 步单独设计和测试。
+- WorkBuddy 第 4 节没确认的几点,第 8 步之前不对外承诺支持。
+- 文件搬家后,已安装的副本要靠 `cam install` 更新;启动脚本里的入口路径要一起改,不能让已安装的配置指向不存在的文件。
+
+## 7. 用户的决定(2026-11-02)
+
+1. 接入层做薄,核心层、面板层各自独立维护;以后调算法只改核心层。
+2. 面板只在 Codex 桌面版和 Claude 桌面版;以后接的平台默认不带面板,除非用户主动要求。
+3. 翻译器只抽象操作,不抽象整份请求。
+4. 一个仓库;拆包以后看情况;拆的过程中可以清理冗余。
+5. 按第 5 节的顺序做;不受现有设计约束。