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.
TypeScript ai-agentsclaude-codeclaude-code-plugincodexcodex-plugincontext-managementdeveloper-toolsimage-generationmcpmultimodal
docs(v0.5): 规格、技术方案、README、CHANGELOG 和实测记录;补第二次压缩的测试
chipfighterd523971dd9c4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5355861..01289fa 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,24 @@When a version is released, its section here becomes the GitHub release notes.+## [0.5.0] - Unreleased++Your choice survives compaction in Claude Code.++### Features++- When Claude Code compacts a conversation (`/compact`, or on its own when the context fills up), it replaces the history with a summary and stops sending the images from before it. The plugin now keeps your selection: the images you checked still go to the model, right after the summary and marked with their IDs, and the ones you unchecked stay out, with a placeholder there. With Auto-select on, pinned images go out and the model fetches the others by ID when it needs them. Change the selection any time; it applies from the next message.+- The model is told which images came before the compaction and how to get one back (`need IMG-xxx`, or `cam_view_image` with Auto-select on), and that what it said about them while it could see them still stands.+- The panel marks these images *Before compaction*, counts the checked ones in the request estimate, and the last-request line says how many it sent again.+- The images come from Claude Code's own session record on your machine; nothing is copied.+- In Codex, the panel and the requests it sends work as in 0.4.0.++### Notes++- Tested on Windows in Claude Desktop with Claude Code 2.1.295 and Claude Haiku 5.5, in Chinese and English, in sessions compacted with `/compact`: after the compaction the model answered from the images sent again; with one unchecked, it said it could not see it now, kept its earlier answers and asked with `need IMG-xxx`; checked again, it answered from the image. With Auto-select on, images from before the compaction can be fetched; in our test session, which had asked with `need IMG-xxx` many times before, the model kept asking that way until told it could fetch. A newer account was simulated as in 0.4, and the conversation went on.+- Images sent again take up context like any other, and Claude Code's own context meter doesn't count them. If requests get large, uncheck some or switch on Auto-select: the plugin doesn't decide this for you. Anthropic limits each request to 100 images for models with a 200k-token context window (600 for others), each up to 8000 px (stricter with more than 20 images; under 2000 px is safe), and 32 MB in all.+- After an image is checked again, the model sometimes says that its earlier "I can't see it" was a mistake. Its answer is right; the remark isn't, since the image really was left out then.+## [0.4.0] - 2026-10-11Now in Claude Desktop too, under a new name: Context Attachment Manager.diff --git a/README.md b/README.mdindex 780c77e..61f1b32 100644--- a/README.md+++ b/README.md@@ -17,7 +17,7 @@<p align="center"><b>English</b> · <a href="README_CN.md">简体中文</a></p>-> **New in 0.4: it works in Claude Desktop too.** In the Code tab of Claude Desktop, install the plugin and type `/cam` in a session: the same panel opens in Claude Desktop's built-in browser, next to the conversation. Formerly *Codex Attachment Manager*; the project was renamed because it no longer works with Codex alone.+> **New in 0.5: your choice survives compaction in Claude Code.** When Claude Code compacts a conversation, it stops sending the images from before; the plugin keeps sending the ones you checked, right after the summary. **Since 0.4** it works in Claude Desktop: in the Code tab, install the plugin and type `/cam` in a session, and the same panel opens in the built-in browser, next to the conversation. Formerly *Codex Attachment Manager*; the project was renamed because it no longer works with Codex alone.<p align="center"><img src="docs/images/demo.gif" alt="The panel's filter shows only the PDF page, then every image again, and the uploads are unchecked a turn at a time. Asked about the chat button in the v1 desktop mockup, the model replies need IMG-001; the panel points to IMG-001, the user checks it, and the model answers from the image: orange." width="100%">@@ -38,6 +38,7 @@ So I wanted to keep the long conversation going and decide, turn by turn, which- **The model knows why**: a note tells the model the images were left out by you to save context, so its earlier answers still stand and it doesn't make up details it can't see.- **The model asks, you decide**: when it needs an image, it replies `need IMG-xxx`. The panel lists what it asked for and jumps to it in one click. A checked image goes back to its place in the conversation, marked with its ID.- **Or let the model pick** (new in 0.3): switch on *Auto-select* at the bottom of the panel, per task or session. Images from earlier turns are then left out by default, and the model fetches the ones it needs by ID, for that turn only. Images you check are pinned and go every turn. The panel shows what the model fetched in the latest turn.+- **Keeps your choice through compaction** (new in 0.5, Claude Code): when Claude Code compacts a conversation, it stops sending the images from before it. The plugin keeps sending the ones you checked, right after the summary and marked with their IDs, and tells the model about the others, so it can still ask for them or fetch them. The panel marks these images *Before compaction*.- **See the savings**: the panel estimates the size of the next request and how much you save compared with sending every image, and warns you when a request could not be rewritten.- **English and Simplified Chinese**: the panel, the tab name and the note for the model follow Codex's language, or your system's language when Codex isn't installed.- **Stays on your machine**: the plugin sends nothing anywhere besides the requests Codex and Claude Code already make to OpenAI and Anthropic.@@ -156,6 +157,7 @@ Your selections and logs stay in the data folder (see [Privacy](#privacy)); dele- Results of Codex's built-in image generation can't be unchecked.- With Auto-select on, each image the model fetches adds a request to that turn. Smaller models may misread small details in an image they fetched: in our tests GPT-6 Luna at low effort sometimes did, as it does with images opened with Codex's own image viewer, while GPT-6 Sol and Astra read them right. Pin an image whose details matter, or use a larger model.- **Claude accounts created on or after August 31, 2026** check the model's earlier thinking against the conversation before it. To leave an image out on such an account, the engine also leaves out the earlier thinking that no longer matches the conversation as sent, so the model may think again and use more tokens; the panel tells you each time. Thinking from after the change is kept, and checking the image again brings back the thinking from before. Older accounts aren't affected.+- **After a compaction in Claude Code**, the images you keep checked from before it go out with every request and take up context like any other, but Claude Code's own context meter doesn't count them. If requests get large or Claude Code compacts again soon, uncheck some or switch on Auto-select: the plugin doesn't decide this for you. Anthropic limits each request to 100 images for models with a 200k-token context window (600 for others), each up to 8000 px (with more than 20 images a stricter limit applies; under 2000 px is safe), and 32 MB in all.- In Claude Code, the main conversation is managed; subagents keep their own history as it is. Sessions that use another API address or a cloud provider (Bedrock, Vertex, Foundry) are left alone.- If you uncheck an image while a Codex turn is still running over WebSocket, the rest of that turn still carries the original. The panel tells you; the change applies from the next message.- In Codex, enabling, disabling and upgrading take effect after you restart Codex. In Claude Desktop, a new plugin version takes effect in new sessions: upgrade with `claude plugin marketplace update codex-attachment-manager`, then `claude plugin update codex-attachment-manager@codex-attachment-manager`.diff --git a/README_CN.md b/README_CN.mdindex c7561df..30896fd 100644--- a/README_CN.md+++ b/README_CN.md@@ -17,7 +17,7 @@<p align="center"><a href="README.md">English</a> · <b>简体中文</b></p>-> **0.4 新增:Claude 桌面版也能用了。** 在 Claude 桌面版的 Code 标签页装上插件,在会话里输入 `/cam`,同一个面板就在 Claude 桌面版自带的浏览器里打开,就在对话旁边。项目原名 *Codex Attachment Manager*,因为不再只给 Codex 用,改了名。+> **0.5 新增:Claude Code 压缩对话后,勾选照样有效。** Claude Code 压缩对话后不再发送之前的图;插件把你勾着的那些接着发出去,就放在摘要后面。**0.4 起**Claude 桌面版也能用:在 Code 标签页装上插件,在会话里输入 `/cam`,同一个面板就在自带的浏览器里打开,就在对话旁边。项目原名 *Codex Attachment Manager*,因为不再只给 Codex 用,改了名。<p align="center"><img src="docs/images/demo.gif" alt="面板的筛选先只显示 PDF 页面,再恢复显示全部,上传的图按整轮取消勾选。问起 v1 桌面版的聊天按钮,模型回复 need IMG-001;面板指出 IMG-001,用户勾上它,模型看图答出橙色。" width="100%">@@ -38,6 +38,7 @@- **模型知道原因**:一段说明告诉模型,这些图是你为了节省上下文省略的。它之前看着原图给出的回答仍然算数,也不会编造看不到的细节。- **模型要图,你来决定**:模型需要某张图时,会回复“需要 IMG-xxx”。面板列出它要的图,点一下就跳过去。重新勾上的图回到对话里原来的位置,并标着编号。- **也可以交给模型选**(0.3 新增):在面板底栏打开“自动选图”,每个任务或会话各开各的。之前各轮的图默认不发,模型需要哪张,就按编号取回,只在那一轮提供;勾上的图固定发送,每轮都发。面板会标出模型最近一轮取回了哪几张。+- **压缩对话后勾选照样有效**(0.5 新增,Claude Code):Claude Code 压缩对话后,不再发送之前的图。插件把你勾着的那些接着发出去,放在摘要后面、标着编号,并告诉模型还有哪些没发,它照样可以要图或取图。面板里这些图标着“压缩前”。- **看得见省了多少**:面板预估下一条请求的大小,以及比全部发送省了多少;请求没能改写时会提示。- **中英文界面**:面板、标签页名字和给模型的说明,都跟随 Codex 的界面语言(简体中文、英文);没装 Codex 时跟随系统语言。- **数据留在本机**:除了 Codex 和 Claude Code 本来就要发给 OpenAI、Anthropic 的请求,插件不向任何地方发送数据。@@ -156,6 +157,7 @@ curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/la- Codex 自带生图工具的结果不能取消。- 开着自动选图时,模型每取一张图,这一轮就多一次请求。小模型读取回的图可能读错小细节:测试里 GPT-6 Luna(低推理强度)偶尔会读错,用 Codex 自带的看图打开同一张图也一样;GPT-6 Sol 和 Astra 读得对。细节要紧的图可以固定发送,或者换用更大的模型。- **2026 年 8 月 31 日及以后注册的 Claude 账号**,会核对模型之前的思考记录和它前面的对话是否一致。在这样的账号上省略一张图时,引擎会一起去掉和实际发出的对话对不上的那部分旧思考,所以模型可能要重新思考、多用一些 token,面板每次都会提示。改动之后新产生的思考会保留;把图勾回来,之前的思考也会放回去。更早注册的账号不受影响。+- **Claude Code 压缩对话之后**,压缩前你勾着的图每次请求都会发出去,和别的图一样占上下文,但 Claude Code 自己显示的上下文用量不算它们。请求变大、或者 Claude Code 很快又要压缩时,少勾几张或打开自动选图:插件不替你做这个决定。Anthropic 对每个请求的限制:200k 上下文窗口的模型最多 100 张图(其他模型 600 张),每张不超过 8000 像素(超过 20 张时限制更严,边长不超过 2000 像素就没问题),整个请求不超过 32 MB。- 在 Claude Code 里只管理主对话,子代理的历史保持原样。改用了别的 API 地址或云服务(Bedrock、Vertex、Foundry)的会话不接管。- 取消勾选时,如果 Codex 这一轮还在进行,并且走的是 WebSocket,这一轮剩下的请求仍会带着原图。面板会提示,从下一条消息起生效。- 在 Codex 里,启用、停用和升级都要重启 Codex 才生效。在 Claude 桌面版里,新版本从新建的会话起生效;升级先运行 `claude plugin marketplace update codex-attachment-manager`,再运行 `claude plugin update codex-attachment-manager@codex-attachment-manager`。diff --git a/docs/design.md b/docs/design.mdindex 4ae9f3f..a9ab200 100644--- a/docs/design.md+++ b/docs/design.md@@ -1,7 +1,7 @@# 技术方案> 目标、约束和验收标准以 [spec.md](spec.md) 为准。本文件说明现在是怎么实现的、为什么这样做。-> 文中“已查证”的 Codex 行为,都针对桌面版 26.924(自带命令行 0.158),标着 v0.3 的针对 26.930(自带命令行 0.160);Codex 更新后可能变化。第 12 节的 Claude 行为(v0.4)针对 Claude 桌面应用 2.31226,自带 Claude Code 2.1.293;思考记录部分在 Claude Code 2.1.295 上查证。+> 文中“已查证”的 Codex 行为,都针对桌面版 26.924(自带命令行 0.158),标着 v0.3 的针对 26.930(自带命令行 0.160);Codex 更新后可能变化。第 12 节的 Claude 行为(v0.4)针对 Claude 桌面应用 2.31226,自带 Claude Code 2.1.293;思考记录部分和压缩之后(v0.5)在 Claude Code 2.1.295 上查证。> v0.1 开发过程中的调研和排错经过,归档在 [history/v0.1/](history/v0.1/),其中 plan.md 是当时逐步写成的完整方案。## 1. 总体结构@@ -209,7 +209,7 @@- v0.3 查证:GPT-6 Luna(low)读工具结果里的图,比读用户消息里的图差。同一张图放在消息里问,四次都读对;经 `cam_view_image` 或 Codex 自带的 `view_image` 送来,常把角落的小数字读错(5 读成 3,7 读成 2),有时说看不到数字。把取回的图挪进紧跟着的一条用户消息也没改善,问题在“先调用工具再看图”这个过程,不在图放在哪里。Sol、Astra 没有这个问题。README 和发布说明写明了这一点。- **桌面版的上下文比自测多**:桌面版每轮还带着电脑操作、浏览器等插件的工具说明(约 1 万 token)。自测为了不让测试模型操作用户的电脑,没开这些插件,所以个别只在桌面版出现的模型行为,自测复现不出来。-## 12. Claude Code 接入(v0.4)+## 12. Claude Code 接入(v0.4、v0.5)方案、关卡和任务见 [v0.4/plan.md](v0.4/plan.md)。做法是把上面的机制逐块移植,这里写对应的做法和平台逼迫的改动。@@ -228,6 +228,14 @@- 只改 `/v1/messages`:用户消息里和工具结果里的图换成占位符,文字和 Codex 版相同。- 说明是 `role: "system"` 消息,放在第一张被省略的图所在的那条消息之后;那里已经有系统消息时,并进去。每条含被省略图片的消息后面都跟一条简短说明(`rewrite.ts` 里的 `here`),从后往前插,勾选不变时位置不变。- 面板的“上一次请求”只记带工具的主对话请求。桌面版还会在会话里发附带请求(用户离开时的状态摘要、自动模式的安全检查):照样改写,但不记进这一行。+- **压缩之后**(v0.5,`claude-index.ts`、`claude-rewrite.ts` 的 `addCompacted`、`proxy.ts`;实测见 [v0.5/plan.md](v0.5/plan.md)):+ - Claude Code 2.1.295 压缩后的请求:第一条是用户消息,内容是整段摘要(等于会话记录里 `isCompactSummary` 那条的文字),接着常有一条它自己的系统消息(例如带 `output_config` 的空消息),然后是压缩前的最后一条回复,再往后是新的一轮;压缩前的图一张都没有。写摘要的那个请求和普通请求一样带着全部历史和图,照常改写。+ - 索引照常跨分界编号,压缩前的图标着 `compacted`,还记下摘要的文字(`summary`)。请求里找到这段摘要,才算压缩后的请求;找不到就不补。+ - 补在摘要文字后面,按编号:要发的(勾着的,自动选图时是固定发送的)是“已提供”标签加原图(`claudeImageData` 从会话记录读),其余是占位文字(手动和自动各用各的)。说明并进摘要后面的系统消息(没有就插一条):列出压缩前的全部图;有图没发时前面是完整说明,v0.4 的改写在后面的消息里就只加短说明(`noted`)。全部发出时说明里写明勾回的图回到这里、不会出现在新消息里,以及之前说看不到是因为当时被省略。勾选不变时这两条消息逐字节相同,提示缓存照常命中。+ - 先算好要补哪些,再跑 v0.4 的改写,最后补图;面板统计里 `compacted` 记下补了哪几张(`resent`),面板的“上一次请求”写“补回压缩前的图 N 张”。+ - 面板里压缩前的图照常可勾,标“压缩前”;请求预估把勾着的算作这次加上的。+ - 补图改的是摘要之后的内容,之后产生的思考按上面“思考记录”的做法处理;新账号(模拟)上实测对话不中断。+ - Claude Code 自己的上下文用量(输入框旁的显示)是它的估算,不含补回的图;Anthropic 返回、Claude Code 记进会话记录的用量含。- **思考记录**(`claude-thinking.ts`、`proxy.ts`):- Anthropic 给每段思考记下它前面的内容(系统提示、工具、消息),之后对不上就失效:2026-08-31 起注册的账号直接拒绝(400,`thinkingRejected`),更早的账号放行。思考可以去掉,只要留下的每一段前面都和它产生时一样。- 引擎第一次给一个会话发出改过的历史后,记下每个请求“Claude Code 给的历史”对应“实际发出的内容”(两条哈希链,存在数据目录的 `claude/thinking/<会话 id>.json`,只有哈希)。之后的请求里,一段思考前面要发的内容和它产生时发出的一样,才保留;查不到的算不知道,去掉。比较的是值,不看 JSON 写法、键的顺序和缓存断点,字符串内容等于同样文字的文本块(Claude Code 把末尾的系统消息在它是最后一条时写成带缓存断点的文本块,之后写成字符串)。@@ -249,7 +257,7 @@- Claude 桌面不带 Node。没装 Codex 时,启动脚本用 PATH 上 24 以上的 `node`,找不到就提示安装 Node 24。- **测试**:单元测试同第 10 节(`claude-*.test.ts`)。Mod 的界面和钩子用 Claude Code 自带的测试工具(`claude plugin test`)测。模型测试用真实的 Claude 桌面订阅会话,按 v0.4/plan.md 的约定用 Haiku 5.5,中英文都测。- **依赖的 Claude 行为**(都不是公开接口,Claude 更新后要重新验证):- - 会话记录的格式:`parentUuid`、`turnPosition`、压缩分界、并行工具结果的挂法;请求头 `x-claude-code-session-id`。+ - 会话记录的格式:`parentUuid`、`turnPosition`、压缩分界、并行工具结果的挂法;请求头 `x-claude-code-session-id`。v0.5:压缩后的请求以摘要开头,摘要文字和记录里 `isCompactSummary` 那条相同;会话记录只追加,压缩前的图一直在里面。- 桌面版启动会话的方式:启动时传入 `ANTHROPIC_BASE_URL`;新会话要到第一条输入才启动进程,所以 `/cam` 在那之前不在输入框的命令列表里。- `Claude_Browser` 浏览器工具;Mod 面板里的链接交给系统浏览器;桌面版在会话里发的附带请求。- 思考记录的前缀校验:替换历史里的一张图,之后的思考块就对不上了;2026-08-31 以后注册的账号直接拒绝。比较时不看 JSON 写法和键的顺序;去掉开头或末尾的思考可以,去掉中间的会让后面的失效,把去掉过的放回去,会让它不在期间产生的失效。diff --git a/docs/spec.md b/docs/spec.mdindex 2750c02..04401d2 100644--- a/docs/spec.md+++ b/docs/spec.md@@ -1,6 +1,6 @@# 规格:Context Attachment Manager(上下文素材管理器)-> 本文件是目标、范围、约束和验收标准的唯一事实来源(2026-09-24 经用户、Claude、Codex 三方确认),描述当前版本 v0.4.0,以后随版本更新。v0.4 加的 Claude 桌面 Code 接入,相关内容都标着“v0.4”;它的关卡、任务和验收步骤见 [v0.4/](v0.4/)。项目 2026-10-11 由 Codex Attachment Manager 改名,因为不再只给 Codex 用(用户定);安装用的标识(`codex-attachment-manager`)和数据目录不变,已装的用户照常升级。+> 本文件是目标、范围、约束和验收标准的唯一事实来源(2026-09-24 经用户、Claude、Codex 三方确认),描述当前版本 v0.5.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)。项目 2026-10-11 由 Codex Attachment Manager 改名,因为不再只给 Codex 用(用户定);安装用的标识(`codex-attachment-manager`)和数据目录不变,已装的用户照常升级。> 技术方案见 [design.md](design.md)。v0.1 的开发记录(原方案、任务记录、各阶段报告、最初的构想)归档在 [history/v0.1/](history/v0.1/),只作参考。## 1. 目标@@ -133,6 +133,11 @@ v0.4:同样的管理也用在 Claude 桌面应用的 Code 标签页里(本- 没有 Codex 特有的“启用插件 / 停用插件”按钮和新任务绑定。- 语言跟着插件,和发给模型的说明一致,不跟着浏览器。- **取图工具**:模型调用 `cam_view_image` 不弹权限确认,和 Codex 版的自动批准一样;用户自己的钩子或设置拒绝、或要求询问时,照旧按它们来(用户 2026-10-10 同意)。+- **压缩之后**(v0.5,用户 2026-10-12 定):Claude Code 压缩对话(手动 `/compact` 或自动压缩)时,把旧历史换成一段摘要,压缩前的图不再发给模型。Codex 没有这个问题,不变。+ - 压缩前的勾选照样有效:勾着的图(开着自动选图时是固定发送的图)照样发给模型,取消的照样不发;用户随时可以改,从下一条消息起生效。原图从本地会话记录里读,不另存一份。+ - 位置:压缩前的图按编号排在摘要后面(摘要所在的那条用户消息里):照样发的带“已提供”标签和原图,不发的是占位文字,和别处一样。勾选不变时这一段逐字节相同,缓存能续上。+ - 说明:摘要那条消息后面跟一条系统消息,列出压缩前的全部图片,说清哪些这次没发、怎么要回(手动时写“需要 IMG-xxx”,自动选图时用 `cam_view_image`);有图没发时,前面是完整的“上下文管理说明”,后面消息里的占位文字只再跟一段短说明。说明放在消息里面时模型不信,会收回之前看着原图做出的回答(2026-10-12 实测),所以和 v0.4 一样放在系统消息里。+ - 不替用户做决定:不做自动保护。补回的图太多、请求被拒或 Claude Code 又压缩时,由用户少勾几张或切到自动选图。Claude Code 自己的上下文用量显示不含补回的图,Anthropic 返回的用量含。### 为后续扩展预留@@ -154,6 +159,7 @@ v0.1 到 v0.3 都不做下面这些。其中音频和其他语言已确认是后- 修改或删除原生 Codex 任务里已有的历史;- 在 Codex 对话里把模型要的图的编号做成可点的引用,点了打开面板或原图(用户 2026-09-26 看过调研结果后决定不做,收益不值得;原因见 [history/v0.1/plan.md](history/v0.1/plan.md) 第 18 节)。- v0.4 也不做(用户 2026-10-10 确认的方案):其他模型供应商、云端会话、跨会话素材库、新的常驻系统服务;也不因为换了客户端,就把原生 PDF、文档、音频、视频和普通文本文件纳入管理。+- v0.5 也不做(用户 2026-10-12 定):补回的图太多时自动减少(由用户决定);`/clear` 或新会话带上过去的图(那是另一个会话);子代理的请求(仍只管主对话)。## 3. 硬约束@@ -166,7 +172,7 @@ v0.1 到 v0.3 都不做下面这些。其中音频和其他语言已确认是后- 真实数据不进仓库:从真实会话和用户素材里提取的图片、记录片段、日志和备份,只能放在本机,开发时放在 `local/` 目录(已被 git 忽略),装好的插件放在数据目录(Windows 是 `%USERPROFILE%\.codex-attachment-manager`,macOS 是 `~/Library/Application Support/codex-attachment-manager`,Linux 是 `~/.local/share/codex-attachment-manager`);任何时候都不提交。仓库里的样例数据只能是合成的或脱敏的。Windows 的数据目录 2026-09-25 从 `%LOCALAPPDATA%` 下挪出来(用户同意):Codex、Claude 这类微软商店应用启动的程序在 AppData 里新建的文件,会被转存到各应用的私有目录,插件服务、引擎和命令行看到的数据就不一样了。- 仓库里的文档和代码不写用户本机的具体路径(例如个人项目文件夹)。`~/.codex`、`%LOCALAPPDATA%` 这类通用位置可以写。本项目以后会开源。- 不改写原生任务的历史记录。-- 代理只替换用户取消的图片,连同 Codex 附在它前后的路径标签;自动选图开着时,还替换之前各轮没有固定发送的图(v0.3)。有图片被省略时,另外插入一条“上下文管理说明”开发者消息(用户 2026-09-25 要求告诉模型原因,见第 1 节“占位符”),并在仍发送的图前面加“已提供”标签(v0.1-25)。请求里的其他内容原样转发。v0.4:Claude 的请求里,说明是系统消息(位置见第 1 节“Claude Code(v0.4)”);思考块原样转发,只在账号拒绝时去掉对不上的那些,不关掉思考(用户 2026-10-11 定)。+- 代理只替换用户取消的图片,连同 Codex 附在它前后的路径标签;自动选图开着时,还替换之前各轮没有固定发送的图(v0.3)。有图片被省略时,另外插入一条“上下文管理说明”开发者消息(用户 2026-09-25 要求告诉模型原因,见第 1 节“占位符”),并在仍发送的图前面加“已提供”标签(v0.1-25)。请求里的其他内容原样转发。v0.4:Claude 的请求里,说明是系统消息(位置见第 1 节“Claude Code(v0.4)”);思考块原样转发,只在账号拒绝时去掉对不上的那些,不关掉思考(用户 2026-10-11 定)。v0.5:Claude Code 压缩之后,引擎还把压缩前的图从本地会话记录里取出来,补在摘要后面(用户勾选或固定发送的发原图,其余放占位文字),并跟一条说明(用户 2026-10-12 定,见第 1 节“压缩之后”)。这是唯一往请求里加图的地方,其余内容仍原样转发。- 选择权在用户:默认只由用户在面板里勾选决定,工具和模型都不能自动勾选或取消;模型只能按约定索要(例如回复“需要 IMG-004”),给不给由用户决定。用户给某个任务打开“自动选图”后,之前各轮的图默认不发,由模型用取图工具按编号取回需要的图,只在这一轮有效;模型不能改用户的勾选,也不能替用户开关自动选图(v0.3,用户 2026-10-06 定,取代原来的“选择权永远在用户”)。- 先在 Windows 上开发和测试。技术栈:TypeScript/Node。macOS、Linux 由 CI 验证能装上、能启动;这两个平台桌面版上的实测,等用户在 GitHub 上反馈(用户 2026-09-25 定)。- 交付形态:Codex 插件。插件带一个本地 MCP 服务,负责拉起引擎、提供面板;仓库根目录就是插件市场。面板位置见第 1 节“界面”。@@ -225,6 +231,18 @@ v0.1 之前的阶段验收(阶段 0 的重建路线、代理路线 P2)都已6. 账号拒绝改过历史之后的思考时,去掉对不上的思考记录后照样按勾选发出,取消之后新产生的思考保留,面板提示去掉了几段;还不行时原样发送并提示。对话不中断,全部勾回后也正常。用模拟的新账号(`prefix_mismatch_behavior: "error"`)实测。7. Codex 的功能没有退化。+### v0.5++> 用户 2026-10-12 定的规则,实测记录见 [v0.5/plan.md](v0.5/plan.md) 第 5 节。++1. Claude Code 压缩前勾着的图,压缩后下一条消息起照样发给模型,取消的不发;用户改勾选后从下一条消息起生效。+2. 压缩前的图在摘要后面,标着编号、名字和轮次;勾选不变时,连续两次请求的这一段逐字节相同。+3. 删减压缩前的图同样不诱发模型幻觉:不收回看着原图做出的回答,需要没发的图时按编号要;勾回后看图作答;开着自动选图时能取回并看图作答。+4. 面板正确显示压缩前的图会不会发送,请求预估包含它们。+5. 新账号(模拟)上补图后对话不中断。+6. Codex 的功能和请求不变。+7. 中英文都实测,真实桌面会话,Haiku 5.5。+## 5. 待定问题- 在插件页面移除或关掉插件、没先在面板里停用时,代理设置还在:diff --git a/docs/v0.5/plan.md b/docs/v0.5/plan.mdindex d0562ab..f789666 100644--- a/docs/v0.5/plan.md+++ b/docs/v0.5/plan.md@@ -1,6 +1,6 @@# v0.5 方案:Claude Code 压缩后保留图片-> 状态:用户 2026-10-12 确认,开发中。规则由用户 2026-10-12 定(见第 2 节)。当前正式规格仍是 [spec.md](../spec.md),现有实现见 [design.md](../design.md)。+> 状态:用户 2026-10-12 确认;开发和实测完成(第 5 节),等用户批准合并和发布。规则由用户 2026-10-12 定(见第 2 节)。规格已写进 [spec.md](../spec.md)(标着 v0.5),实现见 [design.md](../design.md) 第 12 节。## 1. 背景与目标@@ -13,8 +13,8 @@ Codex 不变:Codex 不会在压缩时丢图。## 2. 规则(用户 2026-10-12 定)1. **保留勾选**:压缩前勾着的图,压缩后照样发送;取消的照样不发。自动选图开着时,“固定发送”的图照样发送,其余的照旧由模型按需取回。用户在面板里随时可以改,从下一条消息起生效。-2. **补在哪**:照样发送的压缩前的图,放在压缩摘要后面,按编号排好、各自标上编号、名字和轮次。位置固定,勾选不变时请求逐字节相同,缓存能续上。-3. **告诉模型有哪些旧图**:压缩后在摘要后附一行压缩前的图片清单(编号和名字,不含图)。模型需要某张没发的图时照常写“需要 IMG-xxx”;开着自动选图时用 `cam_view_image` 取回(现在就能取,原图还在本地)。+2. **补在哪**:照样发送的压缩前的图,放在压缩摘要后面,按编号排好、各自标上编号、名字和轮次。位置固定,勾选不变时请求逐字节相同,缓存能续上。实测后(2026-10-12)不发的那些也在这里放占位文字,和别处一样(第 5 节)。+3. **告诉模型有哪些旧图**:压缩后附一份压缩前的图片清单(编号和名字,不含图)。模型需要某张没发的图时照常写“需要 IMG-xxx”;开着自动选图时用 `cam_view_image` 取回(现在就能取,原图还在本地)。实测后清单和说明放进摘要那条消息后面的系统消息,和 v0.4 的说明一样(第 5 节)。4. **不替用户做决定**:不做自动保护。补回的图太多、请求被拒绝或 Claude Code 又压缩时,由用户在面板里少勾几张或切到自动选图;面板照常显示请求大小的预估。5. **改一条硬约束**:现在引擎“只替换用户取消的图片”。v0.5 起,引擎也会把用户勾选、但 Claude Code 因压缩不再发送的图,从本地会话记录里取出来补进请求。其余内容仍原样转发。@@ -30,8 +30,8 @@ Codex 不变:Codex 不会在压缩时丢图。- **索引和勾选**(`claude-index.ts`、`selection.ts`):不变。压缩前后的图编号、键都不变,勾选按键保存,所以压缩后勾选自然还在。- **改写**(`claude-rewrite.ts`、`proxy.ts`):- - 认出压缩后的请求:第一条消息是压缩摘要(以 “This session is being continued from a previous conversation” 开头),并且会话记录里最近一次压缩之前有图。- - 在摘要后面插入,就在第一条消息里、摘要文字之后(实测见第 5 节):一行压缩前的图片清单(中英文两份,跟着现在的语言),然后是要照样发送的压缩前的图,每张前面一行标签。之后每次请求的第一条消息都一样,位置固定,不碰工具调用和结果的配对。+ - 认出压缩后的请求:请求里有一条用户消息的文字等于会话记录里最近一次摘要(`isCompactSummary`)的文字,并且最近一次压缩之前有图。+ - 在摘要后面插入,就在那条消息里、摘要文字之后(实测见第 5 节):压缩前的图按编号排开,照样发送的每张前面一行标签、后面是原图,不发的是占位文字。紧接着的系统消息里是说明:压缩前的图片清单(中英文两份,跟着现在的语言),这次没发哪些、怎么要回;有图没发时前面是完整的“上下文管理说明”,后面消息里的占位文字只再跟一段短说明。Claude Code 已在那里放了系统消息时并进去。勾选不变时这两条消息每次都一样,位置固定,不碰工具调用和结果的配对。- Claude Code 自己生成摘要的那个请求不用特别处理:它和普通请求一样带着全部历史和图,照常改写(第二次压缩时,里面同样补上第一次压缩前的图)。这样它的前缀和上一个请求一致,能命中缓存,写摘要的模型看到的图也和对话里一致。- 其余规则照旧:取消的图换占位符、说明消息、思考记录的处理。- **面板**(`panel-state.ts`、`panel.html`):压缩前的图照常可以勾选。勾着的显示为照样发送、计入请求预估;取消的显示“不发送”。行上加一个“压缩前”标记,说明它是补在摘要后面发的。界面改完截图给用户看。@@ -43,27 +43,41 @@ Codex 不变:Codex 不会在压缩时丢图。1. **压缩时的请求**:和普通请求一样带着系统提示、全部 177 个工具和思考设置,内容是到这时为止的历史,最后一条用户消息末尾加了一段 “CRITICAL: Respond with TEXT ONLY…” 的写摘要要求。三张图原样在里面,没有被换成 “[image]”(第三方资料说的去图,在这个版本上不成立);最后一条回复没带上。回复是 `<analysis>` 加 `<summary>` 的摘要。所以写摘要的模型看着图写,这个请求照常改写即可(第 4 节)。2. **压缩后的请求**:第一条是用户消息,内容是一整段字符串的摘要;接着一条空的系统消息;然后是压缩前的最后一条回复,原样保留;再往后是新的一轮。一张图都没有,模型凭摘要文字回答。补图的位置定在第一条消息里、摘要文字之后。-3. **还要在开发时观察**:补图之后,Claude Code 判断何时自动压缩是否把补回的图算在内(看它是否用 Anthropic 返回的用量)。只观察并写进文档,不加保护。-4. **写 README 时查**:一个请求里图多时 Anthropic 的限制(数量、尺寸),让用户知道被拒的原因。+3. **自动压缩算不算补回的图**(观察,不加保护):Claude Code 记进会话记录的用量是 Anthropic 返回的,含补回的图(英文测试会话最后一次 137,084 个输入 token,其中缓存读 135,621)。输入框旁的上下文用量是它自己的分类估算(172,023,其中“Messages”只有 125),不含补回的图。它按哪个数决定自动压缩没有查到,已写进 README:补回的图占上下文,Claude Code 的显示不算它们。+4. **Anthropic 对一个请求的限制**([官方文档](https://platform.claude.com/docs/en/build-with-claude/vision),2026-10-12 查):图片数 200k 上下文窗口的模型最多 100 张,其他模型 600 张;每张最大 8000×8000 像素,一个请求超过 20 张图时每张的尺寸限制更严(边长不超过 2000 像素就没问题),历史里重发的和工具结果里的图都算;每张 base64 后最大 10 MB;整个请求最大 32 MB。已写进 README。++开发后的实测(2026-10-12,开发引擎,Claude Code 2.1.295,Haiku 5.5;真实图片的尺寸由测试图的生成代码确定,模型给的数都和它一致):++5. **第一版的问题**:说明放在摘要那条用户消息里,没勾选的图直接不出现。补回过的图取消勾选后再问,模型说之前的数“没有依据,应当撤回”,并让用户重新提供图片;说明里点名“这次没提供”“不要收回”之后仍然这样。改成和 v0.4 一样:没勾选的放占位文字,说明作为系统消息跟在那条消息后面。在已经收回过的会话里复测仍然收回:模型照抄自己历史里的回复,那个会话测不出改动,只能在新压缩的会话里测。+6. **新压缩的会话**(中英文各一个,读三张图后用户输入 `/compact`):+ - 勾着时问红方块边长:中英文都答 240 像素(看图答对)。+ - 取消勾选后问没描述过的黑色小方块:都说现在看不到、之前的描述仍然有效,单独写一行“需要 IMG-001”/“need IMG-001”,不让用户重新上传。+ - 问 240 还算不算:都说算,是看着原图说的,没有收回。+ - 勾回后再问:中文第一次没看到补回的图,说“这次消息里没有附上”。全部勾回时不发完整说明,模型不知道勾回的图回到哪里;说明里加上“勾回的图回到这里,不会出现在新消息里”后,中英文都答 48 像素(对)。但两边都说自己之前那句“需要 IMG-001”是错的:图现在排在它之前的回复前面,它以为一直都在。说明里又加了一句“当时看不到是因为被省略了”,再改成讲清这一段每次请求重新放;复测(这时会话历史里已经有这种自我纠正)中英文仍然这样说。回答本身都对,只是这句话不对,写进了 CHANGELOG;新压缩的会话里还没测最后这句措辞。+ - 用另一张图(c-tri.png)再走一遍取消、勾回:取消时中英文都通过;勾回后答对(48 像素),仍有上面那句自我纠正。+7. **自动选图**(中文会话):压缩前的图都换成自动版占位文字,`cam_view_image` 在工具列表里。第一次问没测过的细节时,模型照会话里多次用过的方式写“需要 IMG-002”,没有取图;告诉它可以自己取之后,它调用 `cam_view_image` 取回 IMG-002,答对(48 像素)。下一轮取回的副本换成了“只在那一轮提供”的说明。固定发送 IMG-001 后,它在摘要后照样发出;模型又多取了一次这张已经在的图,答对。v0.4 的中文测试也有过一次多取。+8. **模拟新账号**(英文会话,推理强度 high,`CAM_EXPERIMENT_BLOCK_BINDING=error`):第一次被拒(400),引擎去掉 3 段对不上的旧思考后重发,接受;取消一张后直接去掉对不上的思考,第一次就接受;全部勾回后,勾选相同时产生的那段思考对得上、放回去,接受,缓存读 135,621、写 1,461。回答都对。+9. **请求逐字节相同**:勾选相同的三个请求,摘要那条消息和后面的系统消息哈希相同;取消一张时不同。+10. **Codex 回归**:全部单元测试通过(192 个);`v01-placeholder-selftest.ts` 中文、gpt-6-sol low 全部检查通过,测试任务已自动归档。v0.5 没有改 Codex 的措辞。## 6. 任务1. **实测请求结构**:已完成(第 5 节 1、2 项)。-2. **改写**:先写失败的单元测试(压缩一次、两次;勾选和取消;自动选图的固定发送;清单和标签的位置稳定;写摘要的请求照常改写;新账号的思考),再实现。-3. **面板**:压缩前图片的显示和预估,修掉 v0.4.0 的显示问题;截图给用户。-4. **发给模型的文字**:清单和标签的中英文措辞;用 Haiku 5.5 在桌面会话里中英文各测:压缩后模型能看着补回的图答对,没补的图会按编号要,不编造。-5. **桌面实测**:真实压缩前后取消、勾回、补回;模拟新账号;自动选图取回压缩前的图;Codex 回归(单元测试和一次 Codex 自测)。-6. **文档与发布**:spec(第 1 节和硬约束)、design、README 中英文、CHANGELOG;合并、发布 v0.5.0。+2. **改写**:已完成。单元测试覆盖压缩一次、两次,勾选和取消,自动选图的固定发送,标签、占位文字和说明的位置稳定,写摘要的请求照常改写;新账号的思考沿用 v0.4 的测试,另做了实测(第 5 节 8 项)。+3. **面板**:已完成,截图在验证机的 `local/v04/shots/`:`v050-panel-compacted.jpg`(手动,全部勾着,补回 3 张)、`v050-panel-auto.jpg`(自动选图,固定发送 1 张、占位 2 张,标出模型取回的图)。+4. **发给模型的文字**:已完成,中英文实测见第 5 节 5–7 项;勾回后的自我纠正还留着(第 5 节 6 项)。+5. **桌面实测**:已完成(第 5 节 6–10 项)。+6. **文档与发布**:spec、design、README 中英文、CHANGELOG(0.5.0 标着 Unreleased)已写好。合并、升版本号和发布等用户批准。## 7. 验收-1. 压缩前勾着的图,压缩后下一条消息起照样发给模型,取消的不发;用户改勾选后从下一条消息起生效。-2. 补回的图在摘要后面,标着编号、名字和轮次;勾选不变时,连续两次请求的这一段逐字节相同。-3. 模型知道压缩前有哪些图:需要没发的图时按编号要;开着自动选图时能取回并看图作答。-4. 面板正确显示压缩前图片会不会发送,请求预估包含它们。-5. 新账号(模拟)上补图后对话不中断。-6. Codex 的功能和请求不变。-7. 中英文都实测,真实桌面会话,Haiku 5.5。+1. 压缩前勾着的图,压缩后下一条消息起照样发给模型,取消的不发;用户改勾选后从下一条消息起生效。**通过**(第 5 节 6 项)。+2. 补回的图在摘要后面,标着编号、名字和轮次;勾选不变时,连续两次请求的这一段逐字节相同。**通过**(第 5 节 9 项)。+3. 模型知道压缩前有哪些图:需要没发的图时按编号要;开着自动选图时能取回并看图作答。**通过,有两点遗留**:勾回后模型有时说自己之前“看不到”是错的(回答本身对);手动用了很多次“需要 IMG-xxx”的会话切到自动选图后,模型先照旧要图,告诉它可以取之后才取(第 5 节 6、7 项)。+4. 面板正确显示压缩前图片会不会发送,请求预估包含它们。**通过**(截图见第 6 节 3 项)。+5. 新账号(模拟)上补图后对话不中断。**通过**(第 5 节 8 项)。+6. Codex 的功能和请求不变。**通过**(第 5 节 10 项)。+7. 中英文都实测,真实桌面会话,Haiku 5.5。**通过**。## 8. 不做diff --git a/spike/src/claude-fixtures.ts b/spike/src/claude-fixtures.tsindex 3e20baa..6b54b0c 100644--- a/spike/src/claude-fixtures.ts+++ b/spike/src/claude-fixtures.ts@@ -32,7 +32,7 @@ export function transcript() {toolResult: (toolUseId: string, content: Json[], extra: Json = {}, parent?: string | null) => add({ type: "user", message: { role: "user", content: [{ type: "tool_result", tool_use_id: toolUseId, content }] }, toolUseResult: {}, ...extra }, parent),attachment: () => add({ type: "attachment", attachment: { type: "x" } }),boundary: () => add({ type: "system", subtype: "compact_boundary", compactMetadata: {}, logicalParentUuid: last }, null),- summary: () => add({ type: "user", isCompactSummary: true, message: { role: "user", content: "summary" } }),+ summary: (content = "summary") => add({ type: "user", isCompactSummary: true, message: { role: "user", content } }),get last() { return last; },};}diff --git a/spike/src/proxy.test.ts b/spike/src/proxy.test.tsindex dde4f7a..9bf28af 100644--- a/spike/src/proxy.test.ts+++ b/spike/src/proxy.test.ts@@ -359,3 +359,49 @@ test("v0.5: after a compaction, the images from before it go back after the summassert.deepEqual(partsOf(sent(auto)[0]), ["summary", "omitted:IMG-001", "IMG-002", "image:C"]);assert.match(sent(auto)[0].content[1].text, /cam_view_image/);});++test("v0.5: the request writing a second summary is rewritten as usual; after it, the images from before both go back", async () => {+ const { image, pngA, pngB, text, transcript } = await import("./claude-fixtures.ts");+ const { rewriteClaudeBody } = await import("../../plugin/src/proxy.ts");+ const home = mkdtempSync(join(tmpdir(), "cam-claude-home-"));+ const dir = mkdtempSync(join(tmpdir(), "cam-claude-sel-"));+ const session = "11111111-2222-4333-8444-666666666666";+ mkdirSync(join(home, "projects", "D--work"), { recursive: true });+ const t = transcript();+ const save = () => writeFileSync(join(home, "projects", "D--work", `${session}.jsonl`), t.records.map((record) => JSON.stringify(record)).join("\n") + "\n");+ const body = (messages: any[]) => Buffer.from(JSON.stringify({ model: "claude-haiku-5-5", tools: [{ name: "Read", input_schema: { type: "object" } }], messages }));+ const sent = (out: any) => JSON.parse(out.body.toString("utf8")).messages;+ const partsOf = (message: any) => message.content.map((block: any) =>+ block.type === "image" ? `image:${block.source.data === pngA ? "A" : "B"}` : /^\[图片 (IMG-\d+) 已提供/.exec(block.text)?.[1] ?? block.text);+ t.prompt([image(pngA), text("first")]);+ t.assistant(text("A red square."));+ t.boundary();+ t.summary("first summary");+ t.prompt([image(pngB), text("second")]);+ t.assistant(text("A blue disc."));+ save();+ // Writing the second summary: the history since the first one, with B as Claude Code sends it; A goes back after the+ // first summary, so the model writing it sees what the conversation saw.+ const writing = rewriteClaudeBody(body([+ { role: "user", content: "first summary" },+ { role: "assistant", content: [text("A red square.")] },+ { role: "user", content: [image(pngB), text("second")] },+ { role: "assistant", content: [text("A blue disc.")] },+ { role: "user", content: [text("CRITICAL: Respond with TEXT ONLY.")] },+ ]), undefined, session, dir, home, {});+ assert.deepEqual(writing.report.compacted, { at: 0, listed: 1, resent: ["IMG-001"] });+ assert.deepEqual(partsOf(sent(writing)[0]), ["first summary", "IMG-001", "image:A"]);+ assert.deepEqual(partsOf(sent(writing)[3]), ["image:B", "second"]);+ // After the second compaction both are from before it: listed, and sent again after the new summary.+ t.boundary();+ t.summary("second summary");+ t.prompt("And now?");+ save();+ const after = rewriteClaudeBody(body([+ { role: "user", content: "second summary" },+ { role: "assistant", content: [text("A blue disc.")] },+ { role: "user", content: [text("And now?")] },+ ]), undefined, session, dir, home, {});+ assert.deepEqual(after.report.compacted, { at: 0, listed: 2, resent: ["IMG-001", "IMG-002"] });+ assert.deepEqual(partsOf(sent(after)[0]), ["second summary", "IMG-001", "image:A", "IMG-002", "image:B"]);+});