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): record the eval, the Codex self-tests and the user's decisions
chipfighter724cbb2492a6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b6b9988..84085d7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -30,7 +30,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 300 unit tests, read-only replays of real Codex and Claude sessions, a live test in Claude Desktop (a compaction, a restart of the session, and an edited earlier message that moved the session to a new transcript), and a long real session replayed turn by turn into a test session with two compactions, where the model picked the right image for all 12 questions asked after them. The model self-tests are still to run.+- Verified so far with 300 unit tests, read-only replays of real Codex and Claude sessions, a live test in Claude Desktop (a compaction, a restart of the session, and an edited earlier message that moved the session to a new transcript), and a long real session replayed turn by turn into a test session with two compactions, where the model picked the right image for all 12 questions asked after them. The Codex self-tests ran on gpt-6-sol at low effort, in Chinese and English; three checks failed, none because of this version's changes (the model misread a faint digit, the model said it could not see an image that was sent, and an image viewed through a path built in code gets no name, as before). A long task in Claude Code, compacted twice and then forked, is measured in the [long-task eval](https://github.com/chipfighter/context-attachment-manager/blob/main/eval/long-task/README.md).## [0.9.1] - 2026-10-29diff --git a/docs/v0.10/plan.md b/docs/v0.10/plan.mdindex ffef90c..3dfd3b7 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 桌面实测(压缩、重启、改消息分叉)和长会话回放(关卡 8)已通过,回放发现的三处(第 2 节第 9 到 11 条)已修。公开评测(第 6 节)2026-11-01 跑过一次,评测里又发现并修了两处(第 2 节第 12、13 条);报告先留在本机,等 Claude 会话的提示缓存命中问题改好、重跑之后再发布(第 8 节第 7 条)。这几项通过之前不发布。起因是用 5 个真实会话评估图片检索(会话内容只在本机,不进仓库)。规格以 [spec.md](../spec.md) 为准,实现见 [design.md](../design.md)。+> 状态:用户 2026-10-31 确认方案,让 Claude 按自己的安排做完(第 8 节)。代码和单元测试已完成,spec 和 design 已改;关卡 1–4 用本机回放验证通过,关卡 6 的大会话只有估算(系数按桌面实测校准过),小会话的实测见公开评测;关卡 5、7 的 Codex 自测 2026-11-01 跑完,10 组里 3 组有检查没过,原因都查清了、不是这个版本改出来的,用户定记为已知问题(第 8 节第 9 条);Claude 桌面实测(压缩、重启、改消息分叉)和长会话回放(关卡 8)已通过,回放发现的三处(第 2 节第 9 到 11 条)已修。公开评测(第 6 节)2026-11-01 跑完,评测里发现并修了三处(第 2 节第 12 到 14 条),报告在 [eval/long-task/](../../eval/long-task/README_CN.md)。还没发布。起因是用 5 个真实会话评估图片检索(会话内容只在本机,不进仓库)。规格以 [spec.md](../spec.md) 为准,实现见 [design.md](../design.md)。## 1. 背景与目标@@ -63,11 +63,11 @@10. **评价和特征行一样长**:评价原来截到 15 个汉字,长会话测试里一条 18 个字的评价在清单里只剩前半句,压缩后模型看不到后半句说的问题。评价是用户的原话,一个会话没几条,上限改成和特征行一样,30 个汉字或 100 个字母。11. **清单里标出同一张图**:用户重发同一张图时,插件已经认得出是同一张,但清单列成两行、各写各的特征。改成后面那行写“同 IMG-108”,不再重复特征。12. **等记录文件写完再改写**(公开评测试跑时发现):Claude Code 有时在把这一轮刚读的图写进记录文件之前就发出请求,插件认不出这几张图,原样发出、不带编号,模型这一轮没法给它们写特征行(试跑里一轮 3 张;用户本机日志 8904 次请求里有 119 次,下一次请求才认出)。改成:请求里模型最近一次回复之后有认不出的图时,引擎每 100 毫秒重读一次记录文件,最多 1.5 秒;认出了就照常改写。一张一直认不出的图只让一次请求多等这一下。-13. **压缩后照常看新图**(公开评测发现):说明里“不要用其他工具去读取图片文件”本意是被省略的图要用 `cam_view_image` 取。评测第一次跑 0.10 时(Haiku 5.5,推理强度 low),压缩后模型把它当成所有图,用户后面 5 轮让它看的图一张都没读。改成只说被省略的(Codex 的压缩说明里是清单里的)图,并写明用户新让它看的图照常去看;重跑后每轮都照常读图。这是发给模型的措辞,按 AGENTS.md 要跑 Codex 的 `v01-placeholder`、`v01-needs`、`v03-auto` 自测。+13. **压缩后照常看新图**(公开评测发现):说明里“不要用其他工具去读取图片文件”本意是被省略的图要用 `cam_view_image` 取。评测第一次跑 0.10 时(Haiku 5.5,推理强度 low),压缩后模型把它当成所有图,用户后面 5 轮让它看的图一张都没读。改成只说被省略的(Codex 的压缩说明里是清单里的)图,并写明用户新让它看的图照常去看;重跑后每轮都照常读图。这是发给模型的措辞,按 AGENTS.md 要跑 Codex 的 `v01-placeholder`、`v01-needs`、`v03-auto` 自测;改的也有压缩后放回的说明,还要跑 `v10-compaction`(结果见关卡 5、7)。14. **Claude 的提示缓存接得上**(公开评测发现,用户 2026-11-01 定先修再发 0.10):装插件的 Claude 会话按 API 价格折算约是不装的两倍($0.069 对 $0.036),多在写缓存上:每组 7 到 9 次请求只命中系统提示,整段对话重写。用评测留下的请求逐个对比查到两个原因:- **断点位置**:Claude Code 只在最后两条消息上放断点,插件换掉上一轮的图后,这两个断点都在改动之后;Anthropic 往回找之前的缓存,评测里往回 6 个位置的也没找到。改成引擎自己放消息里的断点(`claude-cache.ts`,design.md 的“提示缓存”):在之前请求放过断点、又在这次第一处改动之前的最后一个位置放一个(读),在第一张以后会换掉的原图前面放一个(备),Claude Code 最末那个尽量留着。- **占位符和清单后来又变**:用户隔几轮才评价一张图时,那张图的占位符(或压缩后的清单)里多出这条评价,从它起整段缓存重写。改成占位符只带这张图出现那一轮及以前记下的评价,清单用压缩那一刻的特征和评价;之后记下的在模型自己的回复里,下一次压缩再进清单(spec 的占位符和清单两条)。- - 结果(Haiku 5.5,推理强度 low,每组一次):只改第一条的第一版 $0.047、从缓存读 86%;改成记最近 4 次请求后 $0.065、78%,那一组模型每轮都晚一轮才写特征行,图在下一轮中间才换掉,之前的断点都用不上,于是加了“备”。最后这一版还没跑成:那次在 5 小时额度暂停之后上游连不上,36 步都是 502(评测脚本已改成连着两次出错就停),之后测试账号一周额度用到 95%,等 11 月 6 日重置后再跑,每组至少两次。按评测留下的请求离线模拟(断点处的缓存才算读到,往回找 20 个位置),这一版从缓存读的比例比只用 Claude Code 的断点高十几个百分点,读不到几乎任何东西的请求从 14–17 次降到 3–5 次。+ - 结果(Haiku 5.5,推理强度 low,每组一次):只改第一条的第一版 $0.047、从缓存读 86%;改成记最近 4 次请求后 $0.065、78%,那一组模型每轮都晚一轮才写特征行,图在下一轮中间才换掉,之前的断点都用不上,于是加了“备”。最后这一版第一次跑时,在 5 小时额度暂停之后上游连不上,36 步都是 502(评测脚本已改成连着两次出错就停);2026-11-01 晚换了一个账号再跑一次(用户为省额度定只跑这一次,第 8 节第 8 条):58 次请求全部正常返回,新的断点放法没被 API 拒;$0.047、从缓存读 87%,只命中系统提示的请求 1 次(不装插件 $0.036、91%、1 次)。没走缓存的输入比其他组多约 2.4 万 token,原因还没查。按评测留下的请求离线模拟(断点处的缓存才算读到,往回找 20 个位置),这一版从缓存读的比例比只用 Claude Code 的断点高十几个百分点,读不到几乎任何东西的请求从 14–17 次降到 3–5 次。## 3. 要先验证的事(关卡)@@ -86,11 +86,14 @@- 原型照原样读:堆内存从 83 MB 到 268 MB,多出的几乎都是旧文件里的图片数据,所以要改成用到时再从文件读(发原图、取图、面板缩略图时)。第一次建索引 1.7 秒,之后每条请求 9–12 毫秒(现在 6 毫秒)。- 结果:通过。旧文件只留压缩点之前带 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 恢复。+ - 结果:通过。按真实压缩记录重建的请求(本机回放)和单元测试里,放回的一段在压缩项后面(说明是开发者消息,原图在后面一条用户消息里),两次请求逐字节相同。探针(`spike/src/v10-compaction-selftest.ts`,2026-11-01,gpt-6-sol,推理强度 low):中英文都压缩成功,两张查看的图都放回在压缩项后面,带着特征行和评价;模型照清单答对了用户说好的是哪一张,没调用工具。英文那次按名字的检查没过,原因见关卡 7。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 千。+ - 结果:大的会话只有估算,系数用 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 千。公开评测(第 6 节,Claude Code,按 API 实测的请求):放回的清单 33 张约 1.6 千、51 张约 2.4 千 token,占压缩后第一条请求的 10.3% 和 13.2%,因为对话短、请求只有 1.5–1.8 万 token。大会话没有实测,按估算和第 8 节第 4 到 6 条的决定算通过(第 8 节第 9 条)。7. **模型照样会取、取对**:改成紧凑写法、放回之后,Codex 自测(gpt-6-sol,推理强度 low),Claude 桌面测试会话(Haiku 5.5),中英文都测。- - 结果:Codex 部分未完成,10 组自测(新的 v10-compaction 和 v08-features、v01-placeholder、v01-needs、v03-auto,各中英文)都因 Codex 用量上限(HTTP 429)没跑成,建的测试任务都已归档。+ - 结果:Codex 部分 2026-11-01 跑完(gpt-6-sol,推理强度 low,5 个自测各中英文;2026-10-31 那批因用量上限全部失败)。`v03-auto` 中英文 20/20,`v08-features` 中英文 18/18,`v01-needs` 中英文都按编号要对了图,`v01-placeholder` 中文 8/8;测试任务都已归档。3 组有检查没过,原因都查清了,不是这个版本改出来的,用户定记为已知问题(第 8 节第 9 条):+ - `v10-compaction` 中文:问角落数字时,模型照自己的特征行答“是问号,不是数字”,没去取原图。它第一次看图时就把淡淡的 7 认成了问号。+ - `v10-compaction` 英文:模型用代码模式看图(`tools.view_image({path: p + "a.png"})`),路径是拼出来的,插件只认得写死的路径,两张图没有名字,按名字的检查都没过;模型其实按清单挑对了图、取了原图、答对了数字。这个限制在这个版本之前就有。+ - `v01-placeholder` 英文:重新勾上的图已经发了原图,模型还说看不到。这个测试关着自动选图;这个版本改的措辞只在自动选图的说明和压缩后的说明里,关着时的说明没动。和 2026-09-28 GPT-6 Luna 的情况一样。- Claude 部分通过(2026-10-31,桌面测试会话,Haiku 5.5,推理强度 low,用户手打 `/compact`、手动回退)。第一次桌面实测发现,v0.9.0 起 Claude Code 2.1.309 不加载插件的 mod(它用变量传环境变量的名字),Claude 会话的请求根本不经过插件;修好后重测:- 压缩当场:摘要后面放回了 4 张图的清单,特征行都在;模型按编号取回 IMG-002,答对细节。- 归档再恢复(只重启进程,还是原来的记录文件):请求照样经过插件,清单和编号不变,这一段走缓存。@@ -128,7 +131,7 @@修完以后,在 `eval/` 加一个长任务的评测。现有的关键帧评测只有 9 张图、Codex 一个平台,它的“局限”一节里写着长任务没测,这次补上。用合成的会话和图片,谁都能复现,不用用户的真实会话。这一轮只测 Claude Code(用户 2026-11-01 定);Codex 由用户自己上手体验,评测里只写测了什么。- **怎么跑**:命令行版 Claude Code,脚本驱动,一个会话一个进程,像桌面版那样一条条发消息。用评测自己的配置文件夹(`CLAUDE_CONFIG_DIR`),用户的技能、设置、记录都不混进来;插件用 `--plugin-dir` 加载,各组各用自己的引擎端口和数据文件夹。自动压缩关掉,脚本在两个固定位置发 `/compact`(和用户手打一样),三组都在同一处压缩;每次压缩后接着问题。-- **三组**:不装插件、0.9.1、0.10。0.9.1 的 mod 在 Claude Code 2.1.309 起不加载,对照组用只换上修好的 `register.js` 的 0.9.1(两个版本的 mod 只差这一处),比出来的才是压缩修复本身的效果。+- **三组**:不装插件、0.9.1、0.10(报告里另列缓存修复之前的 0.10,见第 2 节第 14 条)。0.9.1 的 mod 在 Claude Code 2.1.309 起不加载,对照组用只换上修好的 `register.js` 的 0.9.1(两个版本的 mod 只差这一处),比出来的才是压缩修复本身的效果。- **模型**:Haiku 5.5,推理强度 low,每组跑一次。原来打算再加 Sonnet,以及 300 张、600 张两档看全量清单从多大规模开始不准;试跑算下来要用掉测试账号一周额度的大半,用户定先做简单的一版(2026-11-01),规模的问题以后需要时再测。- **场景**:在关键帧评测的基础上加长。51 张合成图、16 轮,有用户直接发的(简笔画、重发的同一张),也有工具查看的(代替生成的,省掉生图费用);有同一镜头的几个版本、几乎一样的抽帧、三视图、一批设置页截图、一次并行读的一批;中间评价几张,有说好的、说差的、改主意的、只说局部的。- **题目**照真实会话里用户的说法设计:一批里的哪一张、按版本、按内容、按评价(含改了主意的)、按文件名;另有只看原图才答得出的细节题(角落里的数字)、不需要看图的题。压缩后在原会话里接着问,最后再分叉一次问几题。@@ -162,3 +165,6 @@2026-11-01:7. 公开评测按简单的一版跑(Haiku,一个场景,第 6 节)。跑完后发现装插件的 Claude 会话提示缓存命中有问题,用户定:报告先存在本机的 `local/`,不进 git;等缓存的问题改好、重跑以后再发布。评测脚本留在仓库里,改完用它重跑。+8. 同一天晚上,为省额度:评测只给缓存修复的最终版补跑一次(Haiku 5.5,推理强度 low);不装插件、0.9.1、修复前的 0.10 用同一天跑过的结果(同一场景、同一模型、同一版 Claude Code 2.1.314);不加 Sonnet,也不重复跑。报告写明每组只跑了一次。+9. 同一天:关卡 7 里 Codex 自测没过的 3 组不重跑,记为已知问题,照样发布;关卡 6 的大会话按估算、小会话按评测实测,算通过。+10. 同一天:第 5 节的 Codex 桌面实测不做,自测也不补跑 `gpt-6-luna`、`gpt-6-astra`;Codex 这次只有 sol 的自测。