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.10): token numbers calibrated on the desktop test; compaction passed
chipfighterb8571ee70381
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 32a478c..c0f552f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,7 +9,7 @@ Earlier images come back after compaction and resume, with the same IDs, in Code### Features- After Codex compacts a task, the images that tools viewed, generated or returned before the compaction go back into the request right after it: pinned images as originals, the others one line each with the model's feature line and ratings. Previously only uploaded images survived a Codex compaction. The panel marks these images as from before the compaction.-- Images put back after a compaction are now one compact list, one line per image (ID, name, source, turn, feature line, ratings), instead of a placeholder each, on both platforms. In a real session with 127 earlier images this is an estimated 5–7K tokens per request instead of 13–19K.+- Images put back after a compaction are now one compact list, one line per image (ID, name, source, turn, feature line, ratings), instead of a placeholder each, on both platforms. In a real session with 127 earlier images this is an estimated 7–9K tokens per request instead of 17–20K.- The model can correct a wrong feature line by writing it again with "corrected:".- When the user stops a turn before the model writes the feature lines for its new images, those images are sent once more in the next turn, labelled as still missing a feature line.@@ -25,7 +25,7 @@ Earlier images come back after compaction and resume, with the same IDs, in Code- After updating, reopen Claude sessions that were open: their image tool still runs the earlier code and numbering until then.- Earlier transcripts are read only up to the compaction, and their image data stays on disk until needed: for the longest real session tested (9 transcripts, 210 images), the engine uses about 60 MB more memory and the first index takes under 2 seconds.-- Verified so far with 282 unit tests and read-only replays of real Codex and Claude sessions. The model self-tests and a live Claude Desktop compaction test are still to run.+- Verified so far with 282 unit tests, read-only replays of real Codex and Claude sessions, and a live compaction in Claude Desktop. Resuming in Claude Desktop and the model self-tests are still to run.## [0.9.1] - 2026-10-29diff --git a/docs/spec.md b/docs/spec.mdindex 6ea016b..b8fc942 100644--- a/docs/spec.md+++ b/docs/spec.md@@ -81,7 +81,7 @@ v0.9(用户 2026-10-23 定):两平台使用兼容中转时,图片照样- **为什么放在开发者消息里**:用户 2026-09-25 发现,占位符放在原图的位置,模型会以为自己从没看过那张图,于是收回之前看着原图做出的正确回答。把这些说明写在占位符里也没用:占位符属于用户内容,模型不把它当成证据。改成开发者消息后,两次自测都不再收回(见 [history/v0.1/tasks.md](history/v0.1/tasks.md))。- **重复占位符**:包含编号、名称、来源、所在轮次和尺寸,说明它和哪一条(编号、名称、轮次)内容完全相同,那一条照常提供,请参考那一条。内容仍然看得到,不需要上面的说明。- **“已提供”标签**:一次请求里只要有图被换掉,每张仍在发送、有编号的图前面都加一行标签,写法和占位符的第一行一样,状态是“已提供”,例如“[图片 IMG-002([Image #2]) 已提供|名称|来源|第 1 轮|尺寸]”。原因:用户 2026-09-28 发现,重新勾选的图回到原来的位置、夹在占位符中间,而 Codex 自己的“[Image #2]”在每条消息里都从 1 开始,模型对不上编号,就说看不到。没有图被换掉时不加,请求照旧原样转发。v0.8:写特征行的任务里,每张发送的图都带这个标签,这一轮的新图也带,模型才能当场对上编号;新图在它那一轮的第一个请求里就已经有编号(Codex 和 Claude 都先把新图写进本机记录,再发请求,2026-10-19 实测)。这一轮新图的标签只影响请求的末尾,不弄断缓存。-- **压缩后放回的清单**(v0.10):压缩之后放回请求、又不发原图的图,不再一张一个占位,而是合成一份清单,一张一行,例如“IMG-101|alley_v2.png|查看|第 66 轮|雨后小巷|路面反光局部|评价:第 70 轮“太空了””(没有名字的写“-”),清单第一行说明这是压缩之前的图、这次没有附原图,以及各列是什么。怎么取回只在说明里讲一次,说明里也不再把这些图列一遍。原因:一个有 127 张压缩前图片的真实会话,照原来每张一个占位、说明里再列一遍的写法,每条请求多 1.3–1.9 万 token;清单加说明约 0.5–0.7 万(用户 2026-10-31 定)。+- **压缩后放回的清单**(v0.10):压缩之后放回请求、又不发原图的图,不再一张一个占位,而是合成一份清单,一张一行,例如“IMG-101|alley_v2.png|查看|第 66 轮|雨后小巷|路面反光局部|评价:第 70 轮“太空了””(没有名字的写“-”),清单第一行说明这是压缩之前的图、这次没有附原图,以及各列是什么。怎么取回只在说明里讲一次,说明里也不再把这些图列一遍。原因:一个有 127 张压缩前图片的真实会话,照原来每张一个占位、说明里再列一遍的写法,每条请求多约 1.7–2.0 万 token;清单加说明约 0.7–0.9 万(按 Claude 桌面实测校准的系数估;用户 2026-10-31 定)。- **“已提供,还没有特征行”标签**(v0.10):被打断那一轮里还没有特征行、这一轮再发一次的图,标签的状态写“已提供,还没有特征行”(英文 “included, no feature line yet”),特征行说明里告诉模型给它补一行。- 占位符里不写本地路径。Codex 附在上传图片前后的路径标签,也一起换掉。- PDF 页面和网页截图被取消时,占位符和用户上传的图一样,来源写“用户上传”;Codex 写在图前面的那句说明原样保留,模型仍然知道那是哪一页(v0.2,用户 2026-09-29 定:不改发给模型的文字)。@@ -347,7 +347,7 @@ v0.1 之前的阶段验收(阶段 0 的重建路线、代理路线 P2)都已1. Claude:压缩当场和续接之后(包括多次续接、分叉),压缩前的图都放回在摘要后面,编号和续接前一样;老会话里按重排编号写下的特征行和评价,换算后落在对的图上。用户的真实会话只读回放验证。2. Claude:续接和分叉出来的会话沿用上一个会话的勾选。3. Codex:压缩之后,工具查看、生成的图带着编号、特征行和评价回到请求里,模型能靠清单拿对,要看原图时按编号取对。-4. 压缩后放回的那一段用紧凑清单:130 张图的 Claude 会话、33 张图的 Codex 任务,多出的都不超过请求的约 7%(原定 6% 和 3%;用户看了估算后放宽,准确度和信息别丢太多更要紧);往回读旧记录时,最长的真实会话引擎堆内存多不超过 80 MB,第一次建索引不超过 2 秒。+4. 压缩后放回的那一段用紧凑清单:130 张图的 Claude 会话、33 张图的 Codex 任务,多出的不超过请求的约 7%,Claude 压缩后的头几条请求(请求还小的时候)可到约 9%(原定 6% 和 3%;用户看了估算后放宽,准确度和信息别丢太多更要紧);往回读旧记录时,最长的真实会话引擎堆内存多不超过 80 MB,第一次建索引不超过 2 秒。5. 写错的特征行能更正;被打断那一轮里还没有特征行的图,下一轮再发一次让模型补写。6. 原有测试和自测不退化(gpt-6-sol,中英文);Claude 桌面版用 `/compact` 再续接实测一次。diff --git a/docs/v0.10/plan.md b/docs/v0.10/plan.mdindex ffa56eb..d86eda9 100644--- a/docs/v0.10/plan.md+++ b/docs/v0.10/plan.md@@ -1,6 +1,6 @@# v0.10 方案:压缩和续接之后,照样拿回之前的图-> 状态:用户 2026-10-31 确认方案,让 Claude 按自己的安排做完(第 8 节)。代码和单元测试已完成,spec 和 design 已改;关卡 1–4 用本机回放验证通过,关卡 6 只有估算,关卡 5、7 的模型自测因为 Codex 用量到了上限没跑成,Claude 桌面的 `/compact` 实测要用户手动触发。这几项通过之前不发布。起因是用 5 个真实会话评估图片检索(会话内容只在本机,不进仓库)。规格以 [spec.md](../spec.md) 为准,实现见 [design.md](../design.md)。+> 状态:用户 2026-10-31 确认方案,让 Claude 按自己的安排做完(第 8 节)。代码和单元测试已完成,spec 和 design 已改;关卡 1–4 用本机回放验证通过,关卡 6 的大会话只有估算(系数按桌面实测校准过),关卡 5、7 的模型自测因为 Codex 用量到了上限没跑成;Claude 桌面实测压缩当场已通过,续接还没测。这几项通过之前不发布。起因是用 5 个真实会话评估图片检索(会话内容只在本机,不进仓库)。规格以 [spec.md](../spec.md) 为准,实现见 [design.md](../design.md)。## 1. 背景与目标@@ -49,13 +49,13 @@### 两边6. **紧凑写法**(只用于压缩后放回的那一段):一张图一行,写编号、名称、来源、轮次、特征行和最近 3 条评价,例如“IMG-041|exec-….png|查看|第 28 轮|海边栈道|半身中景,白衬衫,回头|评价:第 29 轮“光太硬了””,没有名字的写“-”,清单第一行说明各列;怎么取图在说明里讲一次,说明里不再把图列第二遍。- - 原因:原来每个占位都重复一句“需要原图时调用 cam_view_image…”,说明里又把全部图列一遍。一个有 127 张压缩前图片的真实会话,照原写法每条请求要多 1.3–1.9 万 token(约占请求的 15%–20%);紧凑写法加说明约 0.5–0.7 万(见关卡 6)。+ - 原因:原来每个占位都重复一句“需要原图时调用 cam_view_image…”,说明里又把全部图列一遍。一个有 127 张压缩前图片的真实会话,照原写法每条请求要多约 1.7–2.0 万 token(压缩后第一条请求的约 16%–18%);紧凑写法加说明约 0.7–0.9 万(按桌面实测校准的系数估,见关卡 6)。- 别处的占位(图在原位被省略的)不变。7. **补写和更正特征行**(用户 2026-10-31 采纳了方向,做法见第 8 节):- 补写:被打断的那一轮,新图没写上特征行。被打断那一轮里还没有特征行的图,下一轮再发一次,标签写“已提供,还没有特征行”。- 更正:模型发现特征行写错了(比如用户指出),写一行 `[//]: # (cam IMG-005 更正:…)`,替换原来的特征行。- 这一条改的是特征行说明,按 AGENTS.md 跑自测。-8. **截断按宽度算**(做的时候回放发现,Claude 定):特征行和评价超长时,原来按界面语言数字符截断(中文 30、英文 100),中文界面里模型写的英文特征行被截到只剩地点。第 6 条那个会话的 180 条特征行里 91 条是英文,全被截成“cafe storefront morning |…”这样,51 条截完和别的行一模一样;压缩之后清单是模型看到这些特征的唯一地方,它就分不清这些图。改成按宽度算,和界面语言无关:中日韩文字一个算 1,其他字符算 0.3,特征 30、评价 15,也就是 30 个汉字或 100 个字母。截完相同的从 51 条降到 6 条(127 张里能分开的特征行从 76 条升到 105 条),放回的一段多约 0.13–0.15 万 token。原位的占位用的是同一个截断,也跟着变。+8. **截断按宽度算**(做的时候回放发现,Claude 定):特征行和评价超长时,原来按界面语言数字符截断(中文 30、英文 100),中文界面里模型写的英文特征行被截到只剩地点。第 6 条那个会话的 180 条特征行里 91 条是英文,全被截成“cafe storefront morning |…”这样,51 条截完和别的行一模一样;压缩之后清单是模型看到这些特征的唯一地方,它就分不清这些图。改成按宽度算,和界面语言无关:中日韩文字一个算 1,其他字符算 0.3,特征 30、评价 15,也就是 30 个汉字或 100 个字母。截完相同的从 51 条降到 6 条(127 张里能分开的特征行从 76 条升到 105 条),放回的一段多约 0.2–0.28 万 token(按校准后的系数)。原位的占位用的是同一个截断,也跟着变。## 3. 要先验证的事(关卡)@@ -75,10 +75,10 @@- 结果:通过。旧文件只留压缩点之前带 uuid 的记录,图片数据留在磁盘上、用到时再读:堆内存 83 → 145 MB(多 62 MB),第一次建索引 1.8 秒;每条请求重建约 10 毫秒,同一请求里再读走缓存,约 0.5 毫秒(现在是每次都建,3 次共约 6 毫秒)。5. **Codex 放回的位置**:压缩项后面能不能插;插成开发者消息还是用户消息,模型才把它当真;连续两次请求里这一段逐字节相同,缓存接得上。用 app-server 的 `thread/compact/start` 做探针验证。- 结果:未完成。按真实压缩记录重建的请求(本机回放)和单元测试里,放回的一段在压缩项后面(说明是开发者消息,原图在后面一条用户消息里),两次请求逐字节相同。探针(`spike/src/v10-compaction-selftest.ts`)没跑成:Codex 用量到了上限,2026-11-04 15:35 恢复。-6. **token**:实测压缩后的请求,按 API 返回的用量算,不按估算。130 张图的 Claude 会话、33 张图的 Codex 任务,多出的都不超过请求的约 7%(原定 6% 和 3%;用户看了估算后放宽,准确度和信息别丢太多更要紧,见第 8 节)。- - 结果:只有估算(按字数估的 token,不是 API 返回的用量)。Claude 那个 127 张的会话,放回的一段约 5.4–7.3 千 token(清单 4.4–5.8 千、说明 1.0–1.5 千),约占请求的 6%–8%,上半段可能超过 7%,比原定 6% 多出的部分来自第 2 节第 8 条(英文特征行不再截短)。Codex 那个 33 张的任务约 1.2–1.7 千(说明 0.24–0.34 千、清单 0.98–1.33 千),压缩后第一条真实请求是 44,893 token,约占 2.7%–3.7%,其中编号式的文件名约 0.2–0.3 千(第 8 节第 5 条)。实测用量等桌面实测和自测。+6. **token**:实测压缩后的请求,按 API 返回的用量算,不按估算。130 张图的 Claude 会话、33 张图的 Codex 任务,多出的不超过请求的约 7%,Claude 压缩后的头几条请求可到约 9%(原定 6% 和 3%;用户看了估算后放宽,准确度和信息别丢太多更要紧,见第 8 节)。+ - 结果:大的会话只有估算,系数用 Claude 桌面实测校准过:拿模型回复的长度对照 API 报的 output token,汉字一个约 1.25–1.35 token,其他字符约 0.36–0.5(原来按 1.0–1.5、0.25–0.3 估,非汉字偏低;整条请求按原系数估 5.4–6.5 万,API 报 7.5 万)。Claude 那个 127 张的会话,放回的一段约 7.3–9.1 千 token(清单 6.0–7.7 千、说明 1.3–1.4 千),原写法约 1.7–2.0 万;这个会话续接后第一条请求是 9.1 万 token,这时约占 7%–9%,对话变长后下降,请求到 15 万时约 5%–6%,到中位数 31 万时约 2%–3%。比原定 6% 多出的部分主要来自第 2 节第 8 条(英文特征行不再截短)。Codex 那个 33 张的任务约 1.2–1.7 千(说明 0.24–0.34 千、清单 0.98–1.33 千),压缩后第一条真实请求是 44,893 token,约占 2.7%–3.7%,其中编号式的文件名约 0.2–0.3 千(第 8 节第 5 条);Codex 的分词不同,没有校准,按偏高的系数算也不到 4.5%。桌面实测的小会话(4 张图):压缩后第一条请求 75,099 token,放回的一段约 1.2–1.8 千。7. **模型照样会取、取对**:改成紧凑写法、放回之后,Codex 自测(gpt-6-sol,推理强度 low),Claude 桌面测试会话(Haiku 5.5),中英文都测。- - 结果:未完成。10 组自测(新的 v10-compaction 和 v08-features、v01-placeholder、v01-needs、v03-auto,各中英文)都因 Codex 用量上限(HTTP 429)没跑成,建的测试任务都已归档;Claude 桌面实测要用户在测试会话里手打 `/compact`。第一次桌面实测发现,v0.9.0 起 Claude Code 2.1.309 不加载插件的 mod(它用变量传环境变量的名字),Claude 会话的请求根本不经过插件;已修好,在修好的版本上重测。+ - 结果:未完成。10 组自测(新的 v10-compaction 和 v08-features、v01-placeholder、v01-needs、v03-auto,各中英文)都因 Codex 用量上限(HTTP 429)没跑成,建的测试任务都已归档;Claude 桌面实测要用户在测试会话里手打 `/compact`。第一次桌面实测发现,v0.9.0 起 Claude Code 2.1.309 不加载插件的 mod(它用变量传环境变量的名字),Claude 会话的请求根本不经过插件;已修好,在修好的版本上重测。重测(Haiku 5.5,推理强度 low):压缩当场通过,摘要后面放回了 4 张图的清单,特征行都在,模型按编号取回 IMG-002 并答对细节;续接还没测。## 4. 做法@@ -133,3 +133,5 @@5. 关卡 6 的 Codex 部分:估算 2.7%–3.7%,超过原定的约 3%。多出的主要是 15 行里 `exec-<uuid>.png` 这样由一串编号组成的文件名(9 个不同的名字),约 0.17–0.34 千 token;压缩后保留的对话里这些名字一个都没再出现。用户选了名字照留;另一个办法是清单里把这类名字写成“-”(约 2.3%–3.3%),没有采用。随后用户补充(同一天):两边放回的一段占请求约 7% 以内都能接受,更要紧的是准确度和信息别丢太多。关卡 6 的上限照此定为约 7%。++6. 按桌面实测校准系数以后,Claude 那个 127 张的会话在压缩后的头几条请求里约占 7%–9%,超过 7%;对话变长后降到 7% 以下。要一直压在 7% 以下,就得截短特征行或去掉文件名。用户选择保持现状。