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: README 加上自动选图和 Luna 的局限;CHANGELOG 加 0.3.0 一节
chipfighter5b0eb046571d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3f0de0c..778cd80 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,23 @@When a version is released, its section here becomes the GitHub release notes.+## [0.3.0] - 2026-10-06++Let the model pick the images it needs.++### Features++- An *Auto-select* switch at the bottom of the panel, for each task. With it on, images from earlier turns are left out by default, even one generated a turn ago, and the model fetches the ones it needs by ID with the plugin's `cam_view_image` tool, for that turn only. The placeholders before a fetched image stay as they were, so the cached part of the request isn't broken.+- Check an image to pin it: pinned images go every turn. Pins are kept apart from your own checks, which come back as they were when you switch Auto-select off.+- The panel lists what the model fetched in the latest turn and marks those rows; click an ID to jump to one. The request estimate becomes a minimum, since what the model will fetch isn't known beforehand.+- With Auto-select off, everything works as in 0.2.0, and the requests sent are byte-identical. Codex doesn't list plugin tools to the model, so the model only learns about the tool from the note it gets with Auto-select on.++### Notes++- Tested with three GPT-6 models at low effort, in Chinese and English. GPT-6 Sol and Astra fetched the images they needed, left the rest alone, and read what they fetched correctly. GPT-6 Luna mostly decided right but sometimes misread small details in a fetched image, as it does with images opened with Codex's own image viewer. Pin an image whose details matter, or use a larger model.+- Each image the model fetches adds a request to that turn.+- Platforms are the same as in 0.2.0: tested on Windows with the Codex desktop app 26.930; CI checks that the plugin installs and starts on macOS and Linux.+## [0.2.0] - 2026-09-29Filter the panel's list by where each image came from.diff --git a/README.md b/README.mdindex c5921c1..94fc516 100644--- a/README.md+++ b/README.md@@ -34,6 +34,7 @@ So I wanted to keep the long conversation going and decide, turn by turn, which- **Duplicates handled**: when an identical image is still being sent, the placeholder points to it.- **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. 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.- **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.- **Stays on your machine**: the plugin sends nothing anywhere besides the requests Codex already makes to OpenAI.@@ -41,7 +42,8 @@ So I wanted to keep the long conversation going and decide, turn by turn, which## How it works- The plugin runs a small local proxy, the engine, between Codex and OpenAI. Before a request goes out, the engine swaps unchecked images for placeholders and adds the note; everything else is forwarded as is.-- Selections are saved per task. Only you can change them, not the model.+- With Auto-select on, the engine does the same for the images of earlier turns you haven't pinned, and the plugin gives the model one tool, `cam_view_image`, to fetch an image back into the current turn. The placeholders before it stay as they were, so the cached part of the request isn't broken.+- Selections and the Auto-select switch are saved per task. Only you can change them; the model can only fetch an image for one turn, and only with Auto-select on.- The panel is an MCP app you open from the side panel. It doesn't go through the model and costs no tokens.## Requirements@@ -87,6 +89,7 @@ The command installs the plugin with Codex's own CLI and sets up the proxy. Rest2. Uncheck the images you don't want to send anymore. Each change is saved at once and applies from the next message.3. When the model replies `need IMG-xxx` for an unchecked image, a bar at the top of the panel lists it. Click the ID to jump to the image and check it.4. With many images, click the filter button next to refresh and pick the sources to show. A turn's checkbox then covers only the images shown.+5. To let the model pick, switch on **Auto-select** at the bottom of the panel. Check the images that should go every turn, such as a reference image; the model fetches the others when it needs them. Switch it off to get your own checks back.## Uninstall@@ -114,6 +117,7 @@ Your selections and logs stay in the data folder (see [Privacy](#privacy)); dele- Only images are managed, because they are the only files that reach the model as they are. Codex doesn't send PDFs or videos themselves, only text the model extracts from them or images it makes of them, and those images are listed like any other. Audio waits for a Codex model that accepts it: until then, Codex replaces audio with a short note before sending.- 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.- If you uncheck an image while a 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.- Enabling, disabling and upgrading take effect after you restart Codex.- After you switch Codex's language, the panel changes right away and the note for the model changes from the next message, but the tab name in the side panel changes only after a restart.@@ -132,7 +136,7 @@ Your selections and logs stay in the data folder (see [Privacy](#privacy)); dele- Install from source into your Codex: quit Codex, run `cam install` in the repository (`./cam install` on macOS and Linux), then start Codex. `cam status` shows the installation, `cam uninstall` removes it.- Run the tests with Node 24 or later: `cd spike && node --test`. CI runs them on Windows, macOS and Linux, then installs the plugin with Codex's CLI and runs the install and uninstall scripts.- Work on the panel without Codex: `node spike/scripts/panel-dev.ts`, then open `http://127.0.0.1:17895/?solo=1`. The page uses synthetic images and a temporary Codex folder, so your real data is never read or changed.-- When you change the text the model sees (`plugin/src/rewrite.ts`), run the self-tests in `spike/src/v01-placeholder-selftest.ts` and `spike/src/v01-needs-selftest.ts`, in Chinese and with `--lang en`. They start their own engine and app-server, use your Codex account, and archive the test tasks they create.+- When you change the text the model sees (`plugin/src/rewrite.ts`), run the self-tests in `spike/src/v01-placeholder-selftest.ts` and `spike/src/v01-needs-selftest.ts`, and for Auto-select's wording `spike/src/v03-auto-selftest.ts`, in Chinese and with `--lang en`. They start their own engine and app-server, use your Codex account, and archive the test tasks they create.- Release notes: [CHANGELOG.md](CHANGELOG.md).## Licensediff --git a/README_CN.md b/README_CN.mdindex 2a2809b..fc54290 100644--- a/README_CN.md+++ b/README_CN.md@@ -34,6 +34,7 @@- **重复的图自动处理**:有内容相同的图还在发送时,占位文字指向那一张。- **模型知道原因**:一段说明告诉模型,这些图是你为了节省上下文省略的。它之前看着原图给出的回答仍然算数,也不会编造看不到的细节。- **模型要图,你来决定**:模型需要某张图时,会回复“需要 IMG-xxx”。面板列出它要的图,点一下就跳过去。重新勾上的图回到对话里原来的位置,并标着编号。+- **也可以交给模型选**(0.3 新增):在面板底栏打开“自动选图”,每个任务各开各的。之前各轮的图默认不发,模型需要哪张,就按编号取回,只在那一轮提供;勾上的图固定发送,每轮都发。面板会标出模型最近一轮取回了哪几张。- **看得见省了多少**:面板预估下一条请求的大小,以及比全部发送省了多少;请求没能改写时会提示。- **中英文界面**:面板、标签页名字和给模型的说明,都跟随 Codex 的界面语言(简体中文、英文)。- **数据留在本机**:除了 Codex 本来就要发给 OpenAI 的请求,插件不向任何地方发送数据。@@ -41,7 +42,8 @@## 工作原理- 插件在本机启动一个小代理(引擎),位于 Codex 和 OpenAI 之间。请求发出前,引擎把取消勾选的图换成占位文字,并加上那段说明;其余内容原样转发。-- 勾选状态按任务分别保存,只有你能改,模型不能。+- 开着自动选图时,引擎对之前各轮没有固定发送的图也这样处理;插件给模型一个工具 `cam_view_image`,用来把某张图取回到当前这一轮。前面的占位文字保持不变,请求里已经缓存的部分不受影响。+- 勾选状态和自动选图开关按任务分别保存,只有你能改;模型只能在开着自动选图时,取回某张图在那一轮看。- 面板是一个 MCP 应用,从侧边面板打开,不经过模型,也不花 token。## 环境要求@@ -87,6 +89,7 @@ curl -fsSL https://github.com/chipfighter/codex-attachment-manager/releases/late2. 取消勾选不想再发送的图。每次改动立刻保存,从下一条消息起生效。3. 模型回复“需要 IMG-xxx”、而那张图没有勾上时,面板顶部会列出它。点编号跳到那张图,勾上即可。4. 图多的时候,点刷新旁边的筛选按钮,选要看的来源。这时整轮勾选只管显示出来的图。+5. 想交给模型选,就打开面板底栏的**自动选图**。勾上每轮都要发的图,比如一直要对照的参考图;其余的由模型需要时自己取回。关掉开关,你原来的勾选原样回来。## 卸载@@ -114,6 +117,7 @@ curl -fsSL https://github.com/chipfighter/codex-attachment-manager/releases/late- 只管理图片,因为只有图片会原样发给模型。Codex 不发送 PDF 和视频文件本身,只发送模型从中提取的文字或转成的图片,这些图片会和其他图一起列出来。音频要等 Codex 上有能直接听音频的模型:在那之前,Codex 会在发送前把音频换成一句说明。- Codex 自带生图工具的结果不能取消。+- 开着自动选图时,模型每取一张图,这一轮就多一次请求。小模型读取回的图可能读错小细节:测试里 GPT-6 Luna(低推理强度)偶尔会读错,用 Codex 自带的看图打开同一张图也一样;GPT-6 Sol 和 Astra 读得对。细节要紧的图可以固定发送,或者换用更大的模型。- 取消勾选时,如果这一轮还在进行,并且走的是 WebSocket,这一轮剩下的请求仍会带着原图。面板会提示,从下一条消息起生效。- 启用、停用和升级,都要重启 Codex 才生效。- 切换 Codex 的界面语言后,面板立刻跟着换,给模型的说明从下一条消息起换;侧边面板里标签页的名字要重启 Codex 才换。@@ -132,7 +136,7 @@ curl -fsSL https://github.com/chipfighter/codex-attachment-manager/releases/late- 从源码装进自己的 Codex:先退出 Codex,在仓库里运行 `cam install`(macOS、Linux 上是 `./cam install`),再启动 Codex。`cam status` 查看安装状态,`cam uninstall` 卸载。- 运行测试(需要 Node 24 及以上):`cd spike && node --test`。CI 在 Windows、macOS、Linux 上跑全部单元测试,再用 Codex 的命令行装一遍插件,跑一遍安装和卸载脚本。- 不开 Codex 调面板:运行 `node spike/scripts/panel-dev.ts`,然后打开 `http://127.0.0.1:17895/?solo=1`。页面用合成的测试图和一个临时的 Codex 目录,不读取、不修改你的真实数据。-- 改了发给模型的文字(`plugin/src/rewrite.ts`)后,要跑 `spike/src/v01-placeholder-selftest.ts` 和 `spike/src/v01-needs-selftest.ts` 两个自测,中文、英文(`--lang en`)各一次。它们会自己启动引擎和 app-server,使用你的 Codex 账号,测完把建的测试任务归档。+- 改了发给模型的文字(`plugin/src/rewrite.ts`)后,要跑 `spike/src/v01-placeholder-selftest.ts` 和 `spike/src/v01-needs-selftest.ts` 两个自测,改的是自动选图的文字时再跑 `spike/src/v03-auto-selftest.ts`,中文、英文(`--lang en`)各一次。它们会自己启动引擎和 app-server,使用你的 Codex 账号,测完把建的测试任务归档。- 更新记录见 [CHANGELOG.md](CHANGELOG.md)。## 许可证