Stop paying the multimodal tax. Your AI agent keeps every image it has seen but only sends the ones it needs: lighter chats, no endless reconnecting, no starting over. Works with Codex, Claude Code, Cline, Gemini CLI, OpenCode, WorkBuddy and more. Install once, forget it.
TypeScript ai-agentsai-imageclaude-codeclaude-code-pluginclinecodexcodex-plugincomputer-usecontext-engineeringcontext-managementdeveloper-toolsgemini-cliimage-generationmcpmultimodalmultimodal-aiopencodeqwen-codetoken-optimizationvision-language-model
docs(readme): README 改成面向普通用户的短版,安装和开发内容拆到 INSTALL.md、CONTRIBUTING.md
chipfightera9e2da22dc64
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlindex f451342..84e9530 100644--- a/.github/ISSUE_TEMPLATE/bug_report.yml+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -8,8 +8,8 @@ body:谢谢反馈。macOS 和 Linux 还没有人实测过,这两个平台上的任何问题都很有用。Thanks! macOS and Linux have not been tested by hand yet, so reports from them help a lot.- **Codex 连不上时 / If Codex cannot connect:** 先运行卸载命令恢复直连(见 README 的“卸载”),再来提问题。- Run the uninstall command from the README first to restore the direct connection.+ **Codex 连不上时 / If Codex cannot connect:** 先运行卸载命令恢复直连(见 INSTALL.md 的 Uninstall),再来提问题。+ Run the uninstall command from INSTALL.md first to restore the direct connection.**Claude 连不上时 / If Claude Code cannot connect:** 卸载 Claude 插件后,新会话会直接连接。Uninstall the Claude plugin; new sessions then connect directly.- type: dropdowndiff --git a/AGENTS.md b/AGENTS.mdindex 91af78e..0404559 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -21,7 +21,7 @@ Context Attachment Manager(上下文素材管理器,2026-10-11 前叫 Codex- 插件本体在 `plugin/`(`plugin/src` 是运行代码),测试和实验脚本在 `spike/`,一行命令用的安装、卸载脚本在 `scripts/`。改动运行代码后,要重新运行 `cam install`,Codex 缓存里的插件副本才会更新;不要让已安装的配置指向不存在的文件。- `scripts/*.ps1` 只用 ASCII 字符:Windows PowerShell 5.1 用 `irm … | iex` 下载时按 Latin-1 解码,中文会乱码。- 仓库里的文档和代码不写用户本机的具体路径;通用位置(如 `~/.codex`、`%LOCALAPPDATA%`)可以写。-- 对外的信息以英文为主:README.md、仓库简介、CHANGELOG.md(发布时就是 Release 说明)用英文,README_CN.md 是中文版;`docs/` 下的规格、方案和开发记录,以及本文件,保持中文(用户 2026-09-28 定)。+- 对外的信息以英文为主:README.md、INSTALL.md、CONTRIBUTING.md、仓库简介、CHANGELOG.md(发布时就是 Release 说明)用英文,README_CN.md 是中文版;`docs/` 下的规格、方案和开发记录,以及本文件,保持中文(用户 2026-09-28 定)。- 先在 Windows 上开发和测试。技术栈用 TypeScript/Node。- 界面开发:Claude 自己截图检查效果;做到界面的关键节点时,截图给用户看,停下来等反馈再继续(用户 2026-09-24 确认)。- 测试时调用模型一律用 `gpt-6-sol`,推理强度 `low`,包括脚本自测和桌面版测试,为了省 token(用户 2026-09-24 要求)。diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..05de541--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,33 @@+# Contributing++Bug reports, ideas and pull requests are all welcome. For a bug, an [issue](https://github.com/chipfighter/context-attachment-manager/issues) with what you did and what you saw is enough. For security problems, see [SECURITY.md](SECURITY.md).++## How it works++- The plugin runs a small local proxy, the engine, between Codex and OpenAI, and between Claude Code and Anthropic. Before a request goes out, the engine swaps the images that shouldn't go for placeholders and adds a note for the model; everything else is forwarded as is, including the sign-in.+- In Codex, installing points Codex at the engine. In Claude Desktop, the plugin points each Claude Code session at the engine when the session starts, and puts it back when the session ends.+- With Auto-select on, images from earlier turns become placeholders unless they are set to send every turn, and the model gets 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.+- The engine labels each image with its ID in the turn it appears and asks the model to note what each image shows and what the user said about it. The model writes these notes as Markdown link definitions at the start of its reply, which the apps don't display; the placeholders carry them. The plugin reads them from the conversation records on the machine; nothing is stored separately.+- Selections and the Auto-select switch are saved per task or session. Only the user can change them; the model can only fetch an image for one turn.+- The panel doesn't go through the model. In Codex it's an MCP app in the side panel; in Claude Desktop the engine serves the same page to the built-in browser, on the local machine only.++## Repository layout++- `plugin/` is the plugin itself: the MCP server, the engine, the panel and the `cam` command line (runtime code in `plugin/src`).+- `.claude-plugin/` plus the mod in `hooks/` make the Claude plugin.+- `spike/` holds the tests and experiments, `scripts/` the one-line install and uninstall scripts.+- `docs/` holds the spec and the technical design, in Chinese: start with [docs/spec.md](docs/spec.md), then [docs/design.md](docs/design.md). Release notes are in [CHANGELOG.md](CHANGELOG.md).++## Develop++- 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 `cam install` again after changing runtime code, so Codex's copy of the plugin is updated.+- 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`, or `?solo=1&thread=v08` for a task with the model's notes (add `&lang=en` for English). The page uses synthetic images and a temporary Codex folder, so your real data is never read or changed.+- Text in the panel and the command line comes in English and Simplified Chinese: the panel's in the string table of `plugin/src/panel.html`, the rest in `plugin/src/messages.ts`. Change both; a unit test checks that they match.+- 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`; `spike/src/v07-children-selftest.ts` covers subagents and side chats, and `spike/src/v08-features-selftest.ts` the model's notes, including after a compaction. They start their own engine and app-server, use your Codex account, and archive the test tasks they create.++## Pull requests++- Open pull requests against `main`. They need CI to pass on Windows, macOS and Linux, and a review from the maintainer.+- Keep `scripts/*.ps1` ASCII only: Windows PowerShell 5.1 decodes a downloaded script as Latin-1.+- Real conversation data and user images never go into the repository.diff --git a/INSTALL.md b/INSTALL.mdnew file mode 100644index 0000000..97c3122--- /dev/null+++ b/INSTALL.md@@ -0,0 +1,99 @@+# Install++The easy way: paste this to Codex, or to Claude in Claude Desktop's Code tab, and let it do the steps below for you.++```text+Install the Context Attachment Manager plugin for me, following https://github.com/chipfighter/context-attachment-manager/blob/main/INSTALL.md+```++## For AI assistants++- Install for the app the user is talking to you in: the Codex desktop app, or Claude Desktop's Code tab. Install for both only if the user asks.+- Follow that app's section below and run the commands yourself.+- When you are done, tell the user the one step left for them: restart Codex, or start a new session in Claude Desktop's Code tab. Then tell them how to open the panel (see [Open the panel](#open-the-panel)).++## Codex++### One command++Windows (PowerShell):++```powershell+irm https://github.com/chipfighter/context-attachment-manager/releases/latest/download/install.ps1 | iex+```++macOS and Linux:++```bash+curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/latest/download/install.sh | sh+```++The command installs the plugin with Codex's own command line and points Codex at the plugin's local engine. Restart Codex afterwards. Run it again later to upgrade.++What it changes in Codex:++- Adds a marked proxy block to `~/.codex/config.toml`, after backing the file up.+- If a proxy is set in your environment variables, adds a marked `NO_PROXY` block with local addresses only to `~/.codex/.env`.+- Nothing else. If you have set `openai_base_url` yourself, it stops without writing anything.++### Without a terminal++1. On Codex's **Plugins** page, click **Add a marketplace**, enter `chipfighter/context-attachment-manager` as the **Source**, leave the rest empty, and click **Add marketplace**.+2. Install **Context Attachment Manager** from the list.+3. Open the panel (see below). It says the plugin is not enabled yet: click **Enable plugin**, then restart Codex.++## Claude Desktop++Claude Desktop installs plugins only from marketplaces you have added, and adding one from GitHub takes the `claude` command, Claude Code's command line ([setup guide](https://code.claude.com/docs/en/setup)). Without Codex installed, the plugin also needs [Node 24 or later](https://nodejs.org).++```bash+claude plugin marketplace add chipfighter/context-attachment-manager+```++```bash+claude plugin install codex-attachment-manager@codex-attachment-manager+```++Instead of the second command, you can also install it in the Code tab: click **+** next to the prompt box, choose **Plugins**, then **Add plugin**, pick **Context Attachment Manager**, and install it for your user account. The install ID keeps the project's old name.++Then start a new session in the Code tab. There is nothing to set up: the plugin doesn't edit any settings, and only points that session's own Claude Code process at the engine while it runs.++## Open the panel++- **Codex**: open a task, click **Toggle side panel** at the top right, open a new tab with **+**, and choose **Context Assets** under **Plugins and MCPs**. If it isn't there, restart Codex once.+- **Claude Desktop**: once a session in the Code tab has images, the panel opens by itself in the built-in browser, next to the conversation. Type `/cam` and send it to open it any time. If `/cam` is your first message in a new session, the prompt box may say the command doesn't exist: send it anyway.++## Update++- **Codex**: run the one command again, then restart Codex.+- **Claude Desktop**: run `claude plugin marketplace update codex-attachment-manager`, then `claude plugin update codex-attachment-manager@codex-attachment-manager`. New sessions use the new version.++## Uninstall++### Codex++Disable first, then remove: click **Disable plugin** in the panel, remove the plugin on the **Plugins** page, and restart Codex.++Or run the uninstall command. It restores the direct connection and removes the plugin, and it works even when the plugin files are gone:++Windows (PowerShell):++```powershell+irm https://github.com/chipfighter/context-attachment-manager/releases/latest/download/uninstall.ps1 | iex+```++macOS and Linux:++```bash+curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/latest/download/uninstall.sh | sh+```++**If Codex can't connect** and its errors mention `localhost:17891` (for example, the plugin was removed without disabling it first), run the uninstall command above and restart Codex.++### Claude Desktop++Uninstall it with **Manage plugins** under **+** → **Plugins** in the Code tab, or with `claude plugin uninstall codex-attachment-manager@codex-attachment-manager`. New sessions then connect directly; there is nothing to restore.++### Your data++Your selections and logs stay in the data folder: `%USERPROFILE%\.codex-attachment-manager` on Windows, `~/Library/Application Support/codex-attachment-manager` on macOS, `~/.local/share/codex-attachment-manager` on Linux. It holds selections, request statistics (sizes and counts, never content), logs (no conversation content or credentials) and the backup of `config.toml`. Delete it if you don't need it.diff --git a/README.md b/README.mdindex 7cf8fa6..dc06c85 100644--- a/README.md+++ b/README.md@@ -4,7 +4,7 @@<h1 align="center">Context Attachment Manager</h1>-<p align="center">Choose which past images go to the model with your next message, in Codex and in Claude Desktop, without leaving the conversation.</p>+<p align="center"><b>Keep long image chats in Codex and Claude light and fast.</b><br>Iterate on images in one conversation as long as you like. Old images stop riding along with every message, and the model still finds the right one when it needs it.</p><p align="center"><a href="https://github.com/chipfighter/context-attachment-manager/actions/workflows/ci.yml"><img src="https://github.com/chipfighter/context-attachment-manager/actions/workflows/ci.yml/badge.svg" alt="CI"></a>@@ -17,180 +17,42 @@<p align="center"><b>English</b> · <a href="README_CN.md">简体中文</a></p>-> **New in 0.8: the model keeps notes on your images, and the panel finds them by what you remember.** In lines you don't see, the model notes what each new image shows and what you said about it ("too dark", "best face"). The placeholders carry these notes, so after a compaction the model still picks the right image. The panel is redone: search by what an image shows or by what you said back then, filter by scene, browse thumbnails by turn, and preview an image across the whole panel. **Earlier:** since 0.7 subagents and side chats in Codex follow Auto-select, since 0.6 Auto-select is on by default and the panel opens by itself in Claude Desktop, since 0.5 your selection survives compaction in Claude Code, and since 0.4 it works in Claude Desktop. Formerly *Codex Attachment Manager*; the project was renamed because it no longer works with Codex alone.-<p align="center">- <img src="docs/images/panel.png" alt="Three views of the panel on a task of rainy-night keyframes. Left: the request card, the search box, filters for uploads, generated images and scenes, and the thumbnails by turn, the hand sketch marked Every turn and two images Just fetched. Middle: a search for best face finds the close-up the user called the best face and the turn in which they said it. Right: that close-up previewed across the panel, with its Send every turn checkbox." width="100%">+ <img src="docs/images/panel.png" alt="Three views of the panel on a task of rainy-night keyframes. Left: the request card, the search box, filters for uploads, generated images and scenes, and the thumbnails by turn. Middle: a search for best face finds the close-up the user called the best face. Right: that close-up previewed across the panel, with its Send every turn checkbox." width="100%"></p>-<p align="center"><sub>The panel on a synthetic task from the development page: the images by turn, a search for what you said, and a preview.</sub></p>--## Why I built this--I was iterating on image generation with GPT in Codex. After a dozen or so images, the task started failing: the connection kept dropping, and the retries every few minutes never went through. Digging into it, I found that Codex sends every image in the task's history again with every request, and each request had grown to about 44 MB. The only way out was a new task, which meant losing the conversation.-So I wanted to keep the long conversation going and decide, turn by turn, which images the model still gets. Uncheck the ones you no longer need: from the next message on they become short placeholders, and the task and the conversation stay the same. Claude Code also sends the whole history with every request, so 0.4 brings the same panel to Claude Desktop.+## Why I made this-Later I ran into the next problem. In a long task, a face close-up from the middle of the conversation came out best, but after a compaction the model took the half-length shot from the start as its face reference: the placeholders said nothing about what each image showed. So in 0.8 the model keeps notes on each image, and the panel lets you find one by what you remember.+I was iterating on images with GPT in Codex. After a dozen or so, the chat started failing: it kept reconnecting and never got through. Every message was sending every image in the conversation again, about 44 MB each time. The only way out was a new chat, and with it, losing everything we had built up.-## Features+So I made a panel that keeps the conversation and drops the weight.-- **Every image at a glance**: the panel shows every image in the task (in Codex) or session (in Claude Code) as thumbnails grouped by turn, newest first: the ones you uploaded and the ones the model viewed or generated. Small marks show which go every turn, which the model just fetched and which can't be turned off, and images that won't be sent are gray. Click one to preview it across the panel, with its ID, turn, source and size. In Codex it's a *Context Assets* tab in the side panel; in Claude Desktop it opens in the built-in browser.-- **Find an image by what you remember** (new in 0.8): type what an image shows or what you said back then ("best face"), or pick a filter: *Uploaded*, *Generated*, or a scene such as *rainy blue night*. PDF pages you commented on in Codex and web page screenshots count as uploads and carry a small corner mark. Searching and filtering change what you see, never what is sent.-- **The model keeps notes** (new in 0.8): for each new image, the model writes a short line on what it shows, scene first; when you rate an image ("the first one is too dark", even turns later), it notes your words under that image. It writes these lines at the start of its reply as Markdown link definitions, which Codex and Claude Desktop don't display, and doesn't mention them. The placeholders carry the notes, so after a compaction, or many turns later, the model can still tell the images apart and pick the right one. The panel uses them for its search and scenes, and never shows them.-- **One click to leave an image out**: with Auto-select off, every image is sent until you uncheck *Send* in its preview, or a whole turn with the box at the end of the turn's line. From the next message on, it becomes a short placeholder.-- **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`. A bar at the top of the panel lists what it asked for; click an ID to jump to the image. A checked image goes back to its place in the conversation, marked with its ID.-- **Or let the model pick** (new in 0.3, on by default since 0.6): *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, several at once if it needs several. Images you set to *Send every turn*, such as a reference image, go with every message. New tasks and sessions start with it on; switch it off to choose yourself. The panel marks what the model fetched in the latest turn.-- **Subagents and side chats too** (new in 0.7, Codex): a side chat you open in a task carries the task's whole history, images included; it goes out with those images as placeholders, except the ones you send every turn, and the model fetches one from the task when the answer needs it. Subagents the model starts without the task's history leave out the images of their own earlier turns and fetch them back the same way. Since 0.8 this is always on; the panel's details show what they saved.-- **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 card at the top estimates the size of the next request and how much you save compared with sending every image; *Show details* adds the last request, the images the model fetched, and subagents and side chats. The panel 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.+## What it does-## How it works+- **Your chat stays light.** Earlier images stop going out with every message. In a 15-image task, a request that carried 24.9 MB went out at 212 KB.+- **The model fetches what it needs.** When it needs an earlier image, it pulls that one back by itself. Pin the ones that matter, like a character reference, and they go with every message.+- **It remembers every image.** The model quietly notes what each image shows and what you said about it ("too dark", "best face"). Even far into a long chat, or after the chat is compacted, it picks the right one.+- **Find any image by what you remember.** Search "best face" or "rainy night", filter by scene, or browse by turn. Click one to see it full size.-- The plugin runs a small local proxy, the engine, between Codex and OpenAI, and between Claude Code and Anthropic. Before a request goes out, the engine swaps unchecked images for placeholders and adds the note; everything else is forwarded as is, including your sign-in.-- In Codex, installing points Codex at the engine. In Claude Desktop, the plugin points each Claude Code session at the engine when the session starts, and puts it back when the session ends.-- With Auto-select on, the engine does the same for the images of earlier turns you haven't set to send every turn, 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.-- Since 0.8 the engine also labels each image with its ID in the turn it appears, adds a short note asking the model to keep its notes on images, and puts those notes in the placeholders. The plugin reads the notes from the conversation records on your machine; nothing is stored separately.-- Selections and the Auto-select switch are saved per task or session. Only you can change them; the model can only fetch an image for one turn, and only with Auto-select on.-- Codex sends the task a side chat or subagent came from with each of its requests, so the engine leaves out their images as Auto-select does; a side chat's images are looked up in the task it came from.-- The panel doesn't go through the model and costs no tokens. In Codex it's an MCP app in the side panel; in Claude Desktop the engine serves the same page to the built-in browser, on your machine only.+## How to use-## Requirements+- **Codex**: open **Context Assets** in a task's side panel.+- **Claude Desktop**: in the Code tab, the panel opens by itself next to your conversation once there are images. Type `/cam` to bring it back.-- **Codex**: the Codex desktop app. Tested on Windows with Codex 26.1013.-- **Claude Desktop**: the Code tab, local sessions, signed in with your Claude subscription. Tested on Windows with the Claude Code 2.1.299 that Claude Desktop runs.-- **Other agent apps**: not planned for now. Leaving images out needs the engine between the app and the model API, which only apps that let you change the API address allow, and each app builds its requests and stores its conversation records in its own way, so each would need its own support.-- macOS and Linux: CI installs the plugin with Codex's own CLI, starts it, and runs the install and uninstall scripts, but nobody has tried it in the desktop apps on these platforms yet. [Issues](https://github.com/chipfighter/context-attachment-manager/issues) welcome.-- Node: the plugin uses the Node 24 that ships with Codex, and falls back to `node` 24 or later on your PATH. Claude Desktop doesn't ship Node, so without Codex, install [Node 24 or later](https://nodejs.org).+Then just keep chatting. From the start, the model picks earlier images on its own; to pin one, click it and check **Send every turn**. To choose yourself, turn off **Auto-select** at the bottom of the panel.## Install-### In Codex, no terminal--1. On Codex's **Plugins** page, click **Add a marketplace**, enter `chipfighter/context-attachment-manager` as the **Source**, leave the rest empty, and click **Add marketplace**.-2. Install **Context Attachment Manager** from the list.-3. Open a task, click **Toggle side panel** at the top right, open a new tab with **+**, and choose **Context Assets** under **Plugins and MCPs**. If it isn't there, restart Codex once.-4. The panel says the plugin is not enabled yet. Click **Enable plugin**, then restart Codex.--### In Codex, one command--Windows (PowerShell):--```powershell-irm https://github.com/chipfighter/context-attachment-manager/releases/latest/download/install.ps1 | iex-```--macOS and Linux:--```bash-curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/latest/download/install.sh | sh-```--The command installs the plugin with Codex's own CLI and sets up the proxy. Restart Codex afterwards. Run it again later to upgrade.--What installing changes in Codex:--- Adds a marked proxy block to `~/.codex/config.toml`, after backing the file up.-- If a proxy is set in your environment variables, adds a marked `NO_PROXY` block with local addresses only to `~/.codex/.env`.-- Nothing else. If you have set `openai_base_url` yourself, installing stops without writing anything.--### In Claude Desktop--Claude Desktop installs plugins only from marketplaces you have added, and adding one from GitHub takes the `claude` command, Claude Code's command line ([setup guide](https://code.claude.com/docs/en/setup)). Once:--```bash-claude plugin marketplace add chipfighter/context-attachment-manager-```--```bash-claude plugin install codex-attachment-manager@codex-attachment-manager-```--Instead of the second command, you can also install it in the Code tab: click **+** next to the prompt box, choose **Plugins**, then **Add plugin**, pick **Context Attachment Manager**, and install it for your user account. The install ID keeps the project's old name.--Then start a new session in the Code tab. There is nothing to set up: the plugin doesn't edit any settings, and only points that session's own Claude Code process at the engine while it runs.+Paste this to Codex, or to Claude in Claude Desktop's Code tab:-## Usage--### In Codex--1. Open **Context Assets** in the side panel of a task. On a new chat you can open it before the first message; it switches to the task once you send.-2. New tasks start with **Auto-select** on (at the bottom of the panel): images from earlier turns are left out, and the model fetches the ones it needs. For an image that should go every turn, such as a reference image, click it and check **Send every turn** in the preview; the box at the end of a turn's line does this for the whole turn. Each change is saved at once and applies from the next message.-3. To choose yourself, switch Auto-select off: every image then goes unless you uncheck **Send** in its preview, or a turn's box. Images that won't be sent are gray. When the model replies `need IMG-xxx` for one of them, a bar at the top of the panel lists it; click the ID to jump to the image, open it and check **Send**. Switching Auto-select on again brings back your send-every-turn choices, and off again your own checks.-4. To find an image, type in the search box what it shows or what you said in that turn, or pick a filter: **Uploaded**, **Generated** or a scene. A turn's box then covers only the images shown.-5. The card at the top estimates the next request. **Show details** adds the last request, the images the model fetched in the latest turn and, once there are any, how much the task's subagents and side chats saved.-6. Tasks you had before installing 0.6 keep their own Auto-select setting.--### In Claude Desktop--1. Once a session in the Code tab has images, the panel opens by itself in Claude Desktop's built-in browser, next to the conversation. When you have been away from a session for about 30 minutes, Claude Desktop closes its built-in browser; the panel opens again with your next message. If you close it yourself, it stays closed in that session until you type `/cam` and send it, which opens it any time. If `/cam` is your first message in a new session, the prompt box may say the command doesn't exist: send it anyway. Claude Desktop starts the session when you send your first message, and the plugin adds `/cam` then.-2. From there it works as in Codex: new sessions start with **Auto-select** on; send images every turn, search and filter, or switch it off to leave images out yourself and answer `need IMG-xxx`. Changes apply from the next message.-3. With Auto-select on, the model's `cam_view_image` calls don't ask for your permission, unless your own Claude Code settings or hooks say otherwise.--If the built-in browser can't be used (in the terminal, for example), `/cam` shows a small pane with a link to the panel instead.--## Uninstall--### Codex--Disable first, then remove: click **Disable plugin** in the panel, remove the plugin on the **Plugins** page, and restart Codex.--Or run the uninstall command. It restores the direct connection and removes the plugin, and it works even when the plugin files are gone:--Windows (PowerShell):--```powershell-irm https://github.com/chipfighter/context-attachment-manager/releases/latest/download/uninstall.ps1 | iex+```text+Install the Context Attachment Manager plugin for me, following https://github.com/chipfighter/context-attachment-manager/blob/main/INSTALL.md```-macOS and Linux:--```bash-curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/latest/download/uninstall.sh | sh-```--**If Codex can't connect** and its errors mention `localhost:17891` (for example, the plugin was removed without disabling it first), run the uninstall command above and restart Codex. On macOS and Linux the engine also restores the direct connection by itself once the plugin is removed or turned off, from the next start of Codex.--### Claude Desktop--Uninstall it with **Manage plugins** under **+** → **Plugins** in the Code tab, or with `claude plugin uninstall codex-attachment-manager@codex-attachment-manager`. New sessions then connect directly; there is nothing to restore.--Your selections and logs stay in the data folder (see [Privacy](#privacy)); delete it if you don't need them.--## Good to know--- 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 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. Set an image whose details matter to send every turn, or use a larger model.-- **The model's notes** are lines like `[//]: # (cam IMG-015 rainy blue night | close-up, facing the camera)` at the start of its reply. Codex and Claude Desktop don't display them; a place that shows the raw reply may (Claude Code in a terminal is not checked yet). In Codex with Auto-select off, notes start once you uncheck an image: until then the plugin leaves the task's requests alone, so they stay on WebSocket. Images from before 0.8 get no notes, and neither do subagents and side chats. Smaller models sometimes miss a rating: in our tests GPT-6 Luna at low effort did, more often in English.-- **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. Since 0.8 this also happens once in the turn where a session's first image comes in, because the engine adds its note for the model there. 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.-- In Codex, a subagent started with the task's history follows the task's checks, as a forked task does. Images a subagent reads during one long turn all stay in that turn, as Auto-select keeps the current turn's images; they are left out from its next turn.-- 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`.-- 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.-- Right after Codex starts, the engine may restart a few times and you may see "Reconnecting" once.-- The engine goes through your system proxy: on Windows it reads the system setting, on macOS it supports HTTP(S) proxies only (no PAC or SOCKS), and on Linux it reads `HTTPS_PROXY` and similar variables.+Then restart Codex, or start a new session in Claude. To install or uninstall it yourself, see [INSTALL.md](INSTALL.md).## Privacy-- All data stays in a local folder: `%USERPROFILE%\.codex-attachment-manager` on Windows, `~/Library/Application Support/codex-attachment-manager` on macOS, `~/.local/share/codex-attachment-manager` on Linux. It holds your selections, request statistics (sizes and counts only, never content), hashes the engine uses to tell which thinking still matches (never content), logs (no conversation content or credentials) and the backup of `config.toml`.-- Besides the requests Codex and Claude Code already send to OpenAI and Anthropic, the plugin sends nothing anywhere.-- The conversation records of Codex and Claude Code are only read, never modified.--## Development--- `plugin/` is the plugin itself: the MCP server, the engine, the panel and the `cam` command line (runtime code in `plugin/src`). The Claude plugin is `.claude-plugin/` plus the mod in `hooks/`. `spike/` holds the tests and experiments, `scripts/` the one-line install and uninstall scripts, and `docs/` the spec and the technical design (in Chinese; start with [docs/spec.md](docs/spec.md)). The development records of v0.1 are in `docs/history/v0.1/`.-- 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`, or `?solo=1&thread=v08` for a task with the model's notes (add `&lang=en` for English). 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`, and for Auto-select's wording `spike/src/v03-auto-selftest.ts`, in Chinese and with `--lang en`; `spike/src/v07-children-selftest.ts` covers subagents and side chats, and `spike/src/v08-features-selftest.ts` the model's notes, including after a compaction. 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).--## License+Everything stays on your computer. The plugin sends nothing anywhere beyond the requests Codex and Claude already make.-[MIT](LICENSE)+<p align="center"><sub><a href="CHANGELOG.md">Changelog</a> · <a href="CONTRIBUTING.md">Contributing</a> · <a href="LICENSE">MIT License</a></sub></p>diff --git a/README_CN.md b/README_CN.mdindex 80a99f4..5aa6036 100644--- a/README_CN.md+++ b/README_CN.md@@ -4,7 +4,7 @@<h1 align="center">Context Attachment Manager</h1>-<p align="center">在 Codex 和 Claude 桌面版里,不换对话,决定哪些历史图片随下一条消息发给模型。</p>+<p align="center"><b>在 Codex 和 Claude 里跟 AI 改图,聊再久也不卡。</b><br>同一个对话,想改多少轮就改多少轮。旧图不再跟着每条消息重发,模型要用哪张,照样找得到。</p><p align="center"><a href="https://github.com/chipfighter/context-attachment-manager/actions/workflows/ci.yml"><img src="https://github.com/chipfighter/context-attachment-manager/actions/workflows/ci.yml/badge.svg" alt="CI"></a>@@ -17,180 +17,42 @@<p align="center"><a href="README.md">English</a> · <b>简体中文</b></p>-> **0.8 新增:模型给每张图记笔记,面板里凭印象就能找到图。** 模型在你看不到的行里,记下每张新图画的是什么,以及你对它的评价(“太暗”“脸最好”)。占位文字带着这些笔记,所以压缩对话之后,模型照样能拿对图。面板也重做了:按画面或你当时说过的话搜索,按场景筛选,按轮浏览缩略图,点开的图占满整个面板。**之前的版本:** 0.7 起 Codex 的子代理和旁聊也按自动选图来,0.6 起默认开启自动选图、Claude 桌面版里面板自己打开,0.5 起 Claude Code 压缩对话后勾选照样有效,0.4 起 Claude 桌面版也能用。项目原名 *Codex Attachment Manager*,因为不再只给 Codex 用,改了名。-<p align="center">- <img src="docs/images/panel-zh.png" alt="面板的三个画面,任务是人物雨夜关键帧。左边:请求占用卡片、搜索框、上传、生成和各个场景的筛选按钮,以及按轮分组的缩略图,手绘草图标着每轮都发,两张标着刚取回。中间:搜索“最好”,找到用户说脸最好的那张特写,以及说这句话的那一轮。右边:这张特写占满面板的预览,右下角是“每轮都发”的勾选框。" width="100%">+ <img src="docs/images/panel-zh.png" alt="面板的三个画面,任务是人物雨夜关键帧。左边:请求占用卡片、搜索框、上传、生成和各个场景的筛选按钮,以及按轮分组的缩略图。中间:搜索“最好”,找到用户说脸最好的那张特写。右边:这张特写占满面板的预览,右下角是“每轮都发”的勾选框。" width="100%"></p>-<p align="center"><sub>开发页上的合成任务:按轮分组的图、按你说过的话搜索,以及预览。</sub></p>## 为什么做这个-我在 Codex 里用 GPT 反复生图、改图。图攒到十几张以后,这个任务开始出问题:连接一直断,每隔几分钟自动重试一次,始终发不出去。查下去发现,Codex 每次请求都会把任务历史里的图全部重新发一遍,一次请求已经涨到约 44 MB。想去掉旧图只能新开任务,前面的对话就接不上了。--所以我想要的是:长对话照常继续,每一轮自己决定模型还能看到哪些图。不再需要的图取消勾选,从下一条消息起换成一小段占位文字,任务不换,对话连续。Claude Code 每次请求也会把整段历史发一遍,所以 0.4 把同一个面板带到了 Claude 桌面版。--后来又碰到下一个问题。一个长任务里,对话中间那张人物近景效果最好;压缩一次之后,模型拿五官参考时,却去取了对话开头那张人物中景:占位文字里看不出每张图画的是什么。所以 0.8 让模型给每张图记笔记,面板里也能凭印象把图找出来。+我在 Codex 里用 GPT 反复生图、改图。图攒到十几张以后,对话开始出问题:一直在重连,怎么都发不出去。原来每发一条消息,对话里所有的图都要重新上传一遍,一次就是约 44 MB。唯一的办法是新开对话,前面攒下的东西也就全没了。-## 功能+所以我做了这个面板:对话留着,负担卸掉。-- **所有图片一眼看全**:面板把任务(Codex)或会话(Claude Code)里的每张图做成缩略图,按轮分组,最新一轮在最上面,包括你上传的,以及模型查看、生成的。缩略图上的小标记标出哪些每轮都发、哪些模型刚取回、哪些无法取消;不发送的图是灰色。点开一张,大图占满面板,还能看到编号、轮次、来源和大小。在 Codex 里,它是侧边面板里的“上下文素材”标签页;在 Claude 桌面版里,它在自带的浏览器里打开。-- **凭印象找图**(0.8 新增):在搜索框里输入画面内容,或者你当时说过的话(“脸最好”),也可以点筛选按钮:“上传”“生成”,或者某个场景,比如“深蓝雨夜”。在 Codex 里批注 PDF 时附上的页面和网页截图算作上传,角上有小标记。搜索和筛选只改变面板里显示哪些,不影响发送。-- **模型记笔记**(0.8 新增):每张新图,模型都写一行简短的特征,先写场景;你评价某张图时(“第一张太暗”,隔了几轮再说也行),它照你的原话记在那张图下面。这些行写在回复开头,是 Markdown 的链接定义,Codex 和 Claude 桌面版都不显示,模型在正文里也不提。占位文字带着这些笔记,所以压缩对话之后、或者隔了很多轮,模型照样分得清每张图,拿得对。面板用它们来搜索和分场景,但不显示这些文字。-- **点一下就不再发送**:关掉自动选图时,所有图都照常发送;在预览里取消“发送”,或者取消一轮标题线末尾的方框,这张或这一轮的图就从下一条消息起换成一小段占位文字。-- **重复的图自动处理**:有内容相同的图还在发送时,占位文字指向那一张。-- **模型知道原因**:一段说明告诉模型,这些图是你为了节省上下文省略的。它之前看着原图给出的回答仍然算数,也不会编造看不到的细节。-- **模型要图,你来决定**:模型需要某张图时,会回复“需要 IMG-xxx”。面板顶部列出它要的图,点编号就跳过去。重新勾上的图回到对话里原来的位置,并标着编号。-- **也可以交给模型选**(0.3 新增,0.6 起默认开启):面板底栏的“自动选图”,每个任务或会话各开各的。之前各轮的图默认不发,模型需要哪张,就按编号取回,只在那一轮提供,要几张就一次取几张;设成“每轮都发”的图(比如参考图)每条消息都带上。新任务和新会话一开始就开着,想自己选就关掉。面板会标出模型最近一轮取回了哪几张。-- **子代理和旁聊也管**(0.7 新增,Codex):在任务里开的旁聊带着任务的全部历史,图也在里面;发出去时这些图换成占位文字(每轮都发的照发),回答需要时,模型从任务里取回那张图。模型开的、不带任务历史的子代理,也省掉它自己前几轮的图,同样按需取回。0.8 起一直这样,不再有开关;面板的详情里能看到它们省了多少。-- **压缩对话后勾选照样有效**(0.5 新增,Claude Code):Claude Code 压缩对话后,不再发送之前的图。插件把你勾着的那些接着发出去,放在摘要后面、标着编号,并告诉模型还有哪些没发,它照样可以要图或取图。面板里这些图标着“压缩前”。-- **看得见省了多少**:顶部的卡片预估下一条请求的大小,以及比全部发送省了多少;“展开详情”里还有上一次请求、模型取回的图,以及子代理和旁聊。请求没能改写时会提示。-- **中英文界面**:面板、标签页名字和给模型的说明,都跟随 Codex 的界面语言(简体中文、英文);没装 Codex 时跟随系统语言。-- **数据留在本机**:除了 Codex 和 Claude Code 本来就要发给 OpenAI、Anthropic 的请求,插件不向任何地方发送数据。+## 能做什么-## 工作原理+- **对话一直轻快。** 之前的图不再跟着每条消息重发。一个 15 张图的任务里,原本 24.9 MB 的请求,发出去只有 212 KB。+- **模型自己取图。** 要用之前哪张图,模型自己把那一张取回来。要紧的图,比如角色参考图,可以固定成每条消息都带上。+- **每张图它都记得。** 模型会悄悄记下每张图画的是什么,以及你对它说过什么(“太暗”“这张脸最好”)。聊得再久,对话压缩过,它照样拿对图。+- **凭印象找图。** 搜“脸最好”或者“雨夜”,按场景筛选,或者按轮翻看,点开就是大图。-- 插件在本机启动一个小代理(引擎),位于 Codex 和 OpenAI、Claude Code 和 Anthropic 之间。请求发出前,引擎把取消勾选的图换成占位文字,并加上那段说明;其余内容原样转发,登录凭据也原样转发。-- 在 Codex 里,安装时把 Codex 指向引擎。在 Claude 桌面版里,插件在每个 Claude Code 会话启动时把它指向引擎,会话结束时还原。-- 开着自动选图时,引擎对之前各轮没有设成每轮都发的图也这样处理;插件给模型一个工具 `cam_view_image`,用来把某张图取回到当前这一轮。前面的占位文字保持不变,请求里已经缓存的部分不受影响。-- 0.8 起,引擎还在每张图出现的那一轮就标上编号,加一段说明请模型给图记笔记,并把这些笔记放进占位文字。插件从本机的对话记录里读出笔记,不另外保存。-- 勾选状态和自动选图开关按任务或会话分别保存,只有你能改;模型只能在开着自动选图时,取回某张图在那一轮看。-- Codex 发出旁聊和子代理的每个请求时,都带着它来自哪个任务,所以引擎像自动选图那样省掉它们的图;旁聊的图到它来自的任务里去找。-- 面板不经过模型,也不花 token。在 Codex 里它是侧边面板里的 MCP 应用;在 Claude 桌面版里,由引擎把同一个页面提供给自带的浏览器,只在本机访问。+## 怎么用-## 环境要求+- **Codex**:在任务的侧边面板里打开**上下文素材**。+- **Claude 桌面版**:在 Code 标签页里,对话里有了图,面板就自己在对话旁边打开。输入 `/cam` 可以随时再打开。-- **Codex**:Codex 桌面版。在 Windows 上用 Codex 26.1013 实测过。-- **Claude 桌面版**:Code 标签页里的本地会话,用你的 Claude 订阅登录。在 Windows 上实测过,Claude 桌面版运行的是 Claude Code 2.1.299。-- **其他 agent 应用**:暂时不做。省略图片要让引擎站在应用和模型 API 之间,只有允许改 API 地址的应用接得进来;而且每个应用组装请求、保存对话记录的方式都不一样,要逐个适配。-- macOS、Linux:CI 会用 Codex 自己的命令行装上插件、启动插件,并跑一遍安装和卸载脚本;但还没有人在这两个平台的桌面版上实际用过。遇到问题欢迎[提 issue](https://github.com/chipfighter/context-attachment-manager/issues)。-- Node:插件使用 Codex 自带的 Node 24;找不到时,才用 PATH 里 24 及以上版本的 `node`。Claude 桌面版不带 Node,没装 Codex 的话,请装 [Node 24 或更新版本](https://nodejs.org)。+然后照常聊天就行。一开始,模型就会自己挑之前的图;想固定某张,点开它,勾上**每轮都发**。想自己选,就关掉面板底部的**自动选图**。## 安装-### 在 Codex 里安装,不用开终端--1. 在 Codex 的**插件**页面点**添加插件市场**,**来源**填 `chipfighter/context-attachment-manager`,其余留空,点**添加市场**。-2. 在列表里找到 **Context Attachment Manager**,安装。-3. 打开一个任务,点右上角的**显示/隐藏侧边面板**,用 **+** 新建一个标签页,在**插件和 MCP**下选**上下文素材**。找不到的话,先重启一次 Codex。-4. 面板提示插件还没有启用。点**启用插件**,然后重启 Codex。--### 在 Codex 里用一行命令安装--Windows(PowerShell):--```powershell-irm https://github.com/chipfighter/context-attachment-manager/releases/latest/download/install.ps1 | iex-```--macOS、Linux:--```bash-curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/latest/download/install.sh | sh-```--命令会用 Codex 自己的命令行装好插件,并写好代理设置。装完重启 Codex。以后再运行一次,就是升级到最新版本。--安装会在 Codex 里改这些:--- 在 `~/.codex/config.toml` 里写一段带标记的代理设置,改之前先备份。-- 如果环境变量里设了代理,再在 `~/.codex/.env` 里写一段带标记的 `NO_PROXY`,只包含本机地址。-- 别的一概不动。如果你自己设了 `openai_base_url`,安装会停下来,什么都不写。--### 在 Claude 桌面版里安装--Claude 桌面版只能从已经添加的插件市场安装插件,而从 GitHub 添加插件市场要用 Claude Code 的命令行 `claude`([安装说明](https://code.claude.com/docs/en/setup))。只需要做一次:--```bash-claude plugin marketplace add chipfighter/context-attachment-manager-```--```bash-claude plugin install codex-attachment-manager@codex-attachment-manager-```--第二条命令也可以换成在 Code 标签页里装:点输入框旁边的 **+**,选**插件**,再选**添加插件**,找到 **Context Attachment Manager**,装到你的用户账户下。安装用的标识还是项目原来的名字。--然后在 Code 标签页里新建一个会话。不用做任何设置:插件不改任何设置,只在会话运行期间把这个会话自己的 Claude Code 进程指向引擎。+把这句话发给 Codex,或者 Claude 桌面版 Code 标签页里的 Claude:-## 使用--### 在 Codex 里--1. 在任务的侧边面板里打开**上下文素材**。新任务也可以在发第一条消息之前打开:发出消息后,面板会自动切到这个任务。-2. 新任务一开始就开着**自动选图**(在面板底栏):之前各轮的图默认不发,模型需要时自己取回。有的图每轮都要发,比如一直要对照的参考图:点开它,在预览里勾上**每轮都发**;一轮标题线末尾的方框可以把这一轮的图一起勾上。每次改动立刻保存,从下一条消息起生效。-3. 想自己选,就关掉自动选图:所有图照常发送,在预览里取消**发送**,或者取消一轮的方框,才不发。不发送的图是灰色。模型回复“需要 IMG-xxx”、而那张图没有发送时,面板顶部会列出它;点编号跳到那张图,点开勾上**发送**即可。再打开自动选图,每轮都发的勾选原样回来;再关掉,你自己的勾选也原样回来。-4. 找图时,在搜索框里输入画面内容,或者你在那一轮说过的话,也可以点筛选按钮:**上传**、**生成**或者某个场景。这时一轮的方框只管显示出来的图。-5. 顶部的卡片预估下一条请求的大小。**展开详情**里还有上一次请求、模型最近一轮取回的图;模型开过子代理、或者你在任务里开过旁聊之后,还有它们省了多少。-6. 装 0.6 之前就有的任务,自动选图保持原来的设置。--### 在 Claude 桌面版里--1. Code 标签页的会话里有了图,面板就自己在 Claude 桌面版自带的浏览器里打开,就在对话旁边。你离开一个会话约 30 分钟(期间没有新消息),Claude 桌面版会关掉它的自带浏览器;你再发消息时,面板会重新打开。你自己关掉的,这个会话里不再自动打开,直到你输入 `/cam` 并发送(随时都可以用它打开)。如果 `/cam` 是新会话的第一条消息,输入框可能提示命令不存在:照样发出去就行。Claude 桌面版在你发出第一条消息时才启动会话,插件这时才加上 `/cam`。-2. 之后的用法和 Codex 一样:新会话一开始就开着**自动选图**;可以把图设成每轮都发、搜索和筛选,或者关掉自动选图,自己决定哪些不发、按“需要 IMG-xxx”找图。改动从下一条消息起生效。-3. 开着自动选图时,模型调用 `cam_view_image` 不会弹权限确认;你自己的 Claude Code 设置或钩子另有规定时,照它们的来。--用不了自带浏览器时(比如在终端里),`/cam` 会弹出一个小面板,给出面板的链接。--## 卸载--### Codex--先停用,再移除:在面板里点**停用插件**,在**插件**页面移除插件,然后重启 Codex。--也可以运行卸载命令。它会恢复直连并移除插件,插件文件已经删掉时也能用:--Windows(PowerShell):--```powershell-irm https://github.com/chipfighter/context-attachment-manager/releases/latest/download/uninstall.ps1 | iex+```text+帮我安装 Context Attachment Manager 插件,按这里的说明来:https://github.com/chipfighter/context-attachment-manager/blob/main/INSTALL.md```-macOS、Linux:--```bash-curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/latest/download/uninstall.sh | sh-```--**Codex 连不上时**:如果 Codex 的报错里带着 `localhost:17891`(比如没先停用就移除了插件),运行上面的卸载命令,再重启 Codex。macOS、Linux 上,插件被移除或关掉后,引擎也会自己恢复直连,下次启动 Codex 时生效。--### Claude 桌面版--在 Code 标签页里点 **+** → **插件** → **管理插件** 卸载,或者运行 `claude plugin uninstall codex-attachment-manager@codex-attachment-manager`。之后新建的会话直接连接,不用恢复什么。--勾选记录和日志留在数据目录里(见[隐私](#隐私)),不需要可以删掉。--## 一点补充--- 只管理图片,因为只有图片会原样发给模型。Codex 不发送 PDF 和视频文件本身,只发送模型从中提取的文字或转成的图片,这些图片会和其他图一起列出来。音频要等有能直接听音频的模型:在那之前,Codex 会在发送前把音频换成一句说明。-- Codex 自带生图工具的结果不能取消。-- 开着自动选图时,模型每取一张图,这一轮就多一次请求。小模型读取回的图可能读错小细节:测试里 GPT-6 Luna(低推理强度)偶尔会读错,用 Codex 自带的看图打开同一张图也一样;GPT-6 Sol 和 Astra 读得对。细节要紧的图可以设成每轮都发,或者换用更大的模型。-- **模型的笔记**是写在回复开头的这种行:`[//]: # (cam IMG-015 深蓝雨夜|近景,正脸,霓虹反光)`。Codex 和 Claude 桌面版都不显示;直接显示回复原文的地方可能会显示(终端里的 Claude Code 还没看过)。在 Codex 里关着自动选图时,要等你第一次取消勾选,模型才开始记:在那之前插件不碰这个任务的请求,请求照旧走 WebSocket。0.8 之前就有的图不补记,子代理和旁聊也不记。小模型偶尔漏记评价:测试里 GPT-6 Luna(低推理强度)漏记过,英文时更常见。-- **2026 年 8 月 31 日及以后注册的 Claude 账号**,会核对模型之前的思考记录和它前面的对话是否一致。在这样的账号上省略一张图时,引擎会一起去掉和实际发出的对话对不上的那部分旧思考,所以模型可能要重新思考、多用一些 token,面板每次都会提示。改动之后新产生的思考会保留;把图勾回来,之前的思考也会放回去。0.8 起,会话里出现第一张图的那一轮也会这样去掉一次,因为引擎在那里加上给模型的说明。更早注册的账号不受影响。-- **Claude Code 压缩对话之后**,压缩前你勾着的图每次请求都会发出去,和别的图一样占上下文,但 Claude Code 自己显示的上下文用量不算它们。请求变大、或者 Claude Code 很快又要压缩时,少勾几张或打开自动选图:插件不替你做这个决定。Anthropic 对每个请求的限制:200k 上下文窗口的模型最多 100 张图(其他模型 600 张),每张不超过 8000 像素(超过 20 张时限制更严,边长不超过 2000 像素就没问题),整个请求不超过 32 MB。-- 在 Claude Code 里只管理主对话,子代理的历史保持原样。改用了别的 API 地址或云服务(Bedrock、Vertex、Foundry)的会话不接管。-- 在 Codex 里,带着任务历史启动的子代理,和分叉出来的任务一样沿用任务的勾选。子代理在同一轮里读的图都留在那一轮(自动选图本来就照发这一轮的图),从它的下一轮起才省掉。-- 取消勾选时,如果 Codex 这一轮还在进行,并且走的是 WebSocket,这一轮剩下的请求仍会带着原图。面板会提示,从下一条消息起生效。-- 在 Codex 里,启用、停用和升级都要重启 Codex 才生效。在 Claude 桌面版里,新版本从新建的会话起生效;升级先运行 `claude plugin marketplace update codex-attachment-manager`,再运行 `claude plugin update codex-attachment-manager@codex-attachment-manager`。-- 切换 Codex 的界面语言后,面板立刻跟着换,给模型的说明从下一条消息起换;侧边面板里标签页的名字要重启 Codex 才换。-- Codex 刚启动时,引擎可能会重启几次,偶尔会看到一次“正在重新连接”。-- 引擎沿用系统代理:Windows 读系统设置;macOS 只支持 HTTP(S) 代理,不支持 PAC 和 SOCKS;Linux 读 `HTTPS_PROXY` 等环境变量。+装好后重启 Codex,或者在 Claude 里新建一个会话。想自己动手安装或卸载,看 [INSTALL.md](INSTALL.md)(英文)。## 隐私-- 所有数据只留在本机的数据目录:Windows 是 `%USERPROFILE%\.codex-attachment-manager`,macOS 是 `~/Library/Application Support/codex-attachment-manager`,Linux 是 `~/.local/share/codex-attachment-manager`。里面有勾选记录、请求统计(只记大小和数量,不记内容)、引擎用来判断哪些思考还对得上的哈希(不记内容)、日志(不记对话内容和凭据),以及 `config.toml` 的备份。-- 除了 Codex 和 Claude Code 本来就要发给 OpenAI、Anthropic 的请求,插件不向任何地方发送数据。-- Codex 和 Claude Code 的原始对话记录只读,不修改。--## 开发--- `plugin/` 是插件本体:MCP 服务、引擎、面板和 `cam` 命令行,运行代码在 `plugin/src`。Claude 插件是 `.claude-plugin/` 加上 `hooks/` 里的 Mod。`spike/` 是测试和实验脚本,`scripts/` 是一行命令用的安装、卸载脚本,`docs/` 是规格和技术方案,从 [docs/spec.md](docs/spec.md) 读起;v0.1 的开发记录在 `docs/history/v0.1/`。-- 从源码装进自己的 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`;带模型笔记的任务用 `?solo=1&thread=v08`(加 `&lang=en` 是英文)。页面用合成的测试图和一个临时的 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`)各一次;子代理和旁聊用 `spike/src/v07-children-selftest.ts` 测,模型的笔记(包括压缩之后)用 `spike/src/v08-features-selftest.ts` 测。它们会自己启动引擎和 app-server,使用你的 Codex 账号,测完把建的测试任务归档。-- 更新记录见 [CHANGELOG.md](CHANGELOG.md)。--## 许可证+所有东西都留在你自己的电脑上。除了 Codex 和 Claude 本来就要发的请求,插件不往任何地方发数据。-[MIT](LICENSE)+<p align="center"><sub><a href="CHANGELOG.md">更新记录</a> · <a href="CONTRIBUTING.md">参与开发</a> · <a href="LICENSE">MIT 许可证</a></sub></p>diff --git a/SECURITY.md b/SECURITY.mdindex 3f7b651..1854e31 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -16,4 +16,4 @@ The plugin runs a local proxy (the engine) between Codex and OpenAI, and on inst- The engine accepts connections from other machines, or forwards requests anywhere other than OpenAI.- Credentials or conversation content end up in logs or in the data directory.-- The install or uninstall scripts change more than the README says.+- The install or uninstall scripts change more than INSTALL.md says.diff --git a/docs/design.md b/docs/design.mdindex a820191..8d487fd 100644--- a/docs/design.md+++ b/docs/design.md@@ -122,7 +122,7 @@- **跟着 Codex**:插件服务启动时确保引擎在运行,之后每隔几秒检查一次,崩了就重新拉起。Codex 全部退出后,引擎自己退出;v0.4 起 Claude Code 也用这个引擎,要等 Codex 和 Claude 的进程都没有了才退出。- **Windows 的 Job**:插件服务在一个“关闭即结束、不许脱离”的 Job 里,它拉起的引擎随它一起结束,其他会话的插件服务会在几秒内重新拉起。macOS、Linux 上引擎用 `setsid` 脱离进程组。- **升级时替换**:插件服务发现运行中的引擎版本比自己低,就请旧引擎退役(`/__cam/retire`):旧引擎立刻停止监听,把正在进行的请求和 WebSocket 这一轮做完再退出,新引擎马上接手端口。版本相同、代码不同时不替换,只有安装命令(`cam install`)强制替换:v0.4 起 Codex 和 Claude 各有一份插件副本,否则两份副本会来回让对方的引擎退役。-- **插件被移除、没先停用**:引擎每 15 秒检查一次,只认明确的迹象:插件缓存目录不在了,或者 `config.toml` 写着 `enabled = false`。连续两次,或者引擎退出前再查一次,就把 Codex 恢复直连。Windows 上引擎通常随插件服务一起被结束,来不及做这一步,所以面板、插件说明和 README 都写“先停用再移除”,卸载命令负责恢复。+- **插件被移除、没先停用**:引擎每 15 秒检查一次,只认明确的迹象:插件缓存目录不在了,或者 `config.toml` 写着 `enabled = false`。连续两次,或者引擎退出前再查一次,就把 Codex 恢复直连。Windows 上引擎通常随插件服务一起被结束,来不及做这一步,所以面板、插件说明和安装说明(INSTALL.md)都写“先停用再移除”,卸载命令负责恢复。## 6. 面板@@ -244,7 +244,7 @@- **上游问题**:#47512(面板地址变化后白屏)、#45913(页面访问不了 `localhost`)。- **桌面版会在用户消息里附一段 “Files mentioned by the user”**,写着上传文件的完整路径。引擎不改用户消息的文字,靠说明里“不要自己用工具去读取”约束模型;模型偶尔仍会自己打开文件。- **模型的差别**:小模型在低推理强度下(例如 GPT-6 Luna Light)偶尔会要错图,或者拿到错图时不说“这张里没有”,而是猜一个答案(v0.1-25 的录屏里遇到过)。- - v0.3 查证:GPT-6 Luna(low)读工具结果里的图,比读用户消息里的图差。同一张图放在消息里问,四次都读对;经 `cam_view_image` 或 Codex 自带的 `view_image` 送来,常把角落的小数字读错(5 读成 3,7 读成 2),有时说看不到数字。把取回的图挪进紧跟着的一条用户消息也没改善,问题在“先调用工具再看图”这个过程,不在图放在哪里。Sol、Astra 没有这个问题。README 和发布说明写明了这一点。+ - v0.3 查证:GPT-6 Luna(low)读工具结果里的图,比读用户消息里的图差。同一张图放在消息里问,四次都读对;经 `cam_view_image` 或 Codex 自带的 `view_image` 送来,常把角落的小数字读错(5 读成 3,7 读成 2),有时说看不到数字。把取回的图挪进紧跟着的一条用户消息也没改善,问题在“先调用工具再看图”这个过程,不在图放在哪里。Sol、Astra 没有这个问题。发布说明写明了这一点。- **桌面版的上下文比自测多**:桌面版每轮还带着电脑操作、浏览器等插件的工具说明(约 1 万 token)。自测为了不让测试模型操作用户的电脑,没开这些插件,所以个别只在桌面版出现的模型行为,自测复现不出来。## 12. Claude Code 接入(v0.4–v0.8)diff --git a/docs/spec.md b/docs/spec.mdindex 7fb85ec..ad51b93 100644--- a/docs/spec.md+++ b/docs/spec.md@@ -311,5 +311,5 @@ v0.1 之前的阶段验收(阶段 0 的重建路线、代理路线 P2)都已- 在插件页面移除或关掉插件、没先在面板里停用时,代理设置还在:- macOS、Linux 上,引擎会发现这一点,把 Codex 恢复直连,下次启动 Codex 时生效。- - Windows 上,引擎随插件服务一起被结束(Codex 的 Job 限制,见 [design.md](design.md) 第 5 节),Codex 会连不上,要运行卸载命令恢复。面板、插件说明和 README 都提示“先停用再移除”。+ - Windows 上,引擎随插件服务一起被结束(Codex 的 Job 限制,见 [design.md](design.md) 第 5 节),Codex 会连不上,要运行卸载命令恢复。面板、插件说明和安装说明(INSTALL.md)都提示“先停用再移除”。- 要不要让引擎不依赖插件启动(例如用 Windows 计划任务),需要用户同意在系统里注册任务,之后再定。