Skip to content

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.

docs(v0.7): spec、design 和 README 写上子代理和旁聊

chipfighter8dcc723dec6b
diff --git a/README.md b/README.md
index a2943a7..611404f 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.6: Auto-select is on by default, and in Claude Desktop the panel opens by itself.** New tasks and sessions start with Auto-select on, so images from earlier turns stay out unless the model needs them, even if you never open the panel; tasks and sessions you already have keep their setting. In Claude Desktop the panel opens next to the conversation once a session has images. **Earlier:** 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.
+> **New in 0.7: subagents and side chats in Codex follow Auto-select too.** A side chat no longer resends the task's images, and a subagent leaves out the images of its own earlier turns; both fetch the ones they need by ID. The task's panel lists them, with a switch to turn this off. **Earlier:** 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/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, 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 check are pinned and go every turn. New tasks and sessions start with it on; switch it off to choose yourself. The panel shows 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 now goes out with those images as placeholders, except the ones you pinned, 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. The task's panel lists both, with an *Auto-select too* switch, on by default.
- **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.
@@ -49,6 +50,7 @@ So I wanted to keep the long conversation going and decide, turn by turn, which
- 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 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 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 applies the task's switch for them; 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.
## Requirements
@@ -113,7 +115,8 @@ Then start a new session in the Code tab. There is nothing to set up: the plugin
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. Check the images that should go every turn, such as a reference image. 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 it. 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. Switching Auto-select on again brings your pins back, and off again your own checks.
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. Tasks you had before installing 0.6 keep their setting.
+5. Once the model starts subagents, or you open a side chat in the task, the panel shows them under the request size, folded to one line with an **Auto-select too** switch. Unfold it to see each one's last request; switch it off to let their requests go out as they are.
+6. Tasks you had before installing 0.6 keep their own Auto-select setting.
### In Claude Desktop
@@ -159,6 +162,7 @@ Your selections and logs stay in the data folder (see [Privacy](#privacy)); dele
- **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.
+- 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.
@@ -177,7 +181,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`, 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.
+- 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. 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
diff --git a/README_CN.md b/README_CN.md
index 53b7055..7693a49 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.6 新增:默认开启自动选图;Claude 桌面版里面板自己打开。** 新任务和新会话一开始就开着自动选图,之前各轮的图只在模型需要时才发,不打开面板也一样;你已有的任务和会话保持原来的设置。Claude 桌面版里,会话有了图,面板就在对话旁边自己打开。**之前的版本:** 0.5 起 Claude Code 压缩对话后勾选照样有效,0.4 起 Claude 桌面版也能用。项目原名 *Codex Attachment Manager*,因为不再只给 Codex 用,改了名。
+> **0.7 新增:Codex 的子代理和旁聊也按自动选图来。** 旁聊不再把任务里的图重发一遍,子代理也省掉它自己前几轮的图;需要时都能按编号取回。任务的面板会列出它们,并有一个开关可以关掉。**之前的版本:** 0.6 起默认开启自动选图、Claude 桌面版里面板自己打开,0.5 起 Claude Code 压缩对话后勾选照样有效,0.4 起 Claude 桌面版也能用。项目原名 *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.6 起默认开启):面板底栏的“自动选图”,每个任务或会话各开各的。之前各轮的图默认不发,模型需要哪张,就按编号取回,只在那一轮提供,要几张就一次取几张;勾上的图固定发送,每轮都发。新任务和新会话一开始就开着,想自己选就关掉。面板会标出模型最近一轮取回了哪几张。
+- **子代理和旁聊也管**(0.7 新增,Codex):在任务里开的旁聊带着任务的全部历史,图也在里面;现在发出去时这些图换成占位文字(你固定发送的照发),回答需要时,模型从任务里取回那张图。模型开的、不带任务历史的子代理,也省掉它自己前几轮的图,同样按需取回。任务的面板会列出它们,并有一个“也自动选图”开关,默认开着。
- **压缩对话后勾选照样有效**(0.5 新增,Claude Code):Claude Code 压缩对话后,不再发送之前的图。插件把你勾着的那些接着发出去,放在摘要后面、标着编号,并告诉模型还有哪些没发,它照样可以要图或取图。面板里这些图标着“压缩前”。
- **看得见省了多少**:面板预估下一条请求的大小,以及比全部发送省了多少;请求没能改写时会提示。
- **中英文界面**:面板、标签页名字和给模型的说明,都跟随 Codex 的界面语言(简体中文、英文);没装 Codex 时跟随系统语言。
@@ -49,6 +50,7 @@
- 在 Codex 里,安装时把 Codex 指向引擎。在 Claude 桌面版里,插件在每个 Claude Code 会话启动时把它指向引擎,会话结束时还原。
- 开着自动选图时,引擎对之前各轮没有固定发送的图也这样处理;插件给模型一个工具 `cam_view_image`,用来把某张图取回到当前这一轮。前面的占位文字保持不变,请求里已经缓存的部分不受影响。
- 勾选状态和自动选图开关按任务或会话分别保存,只有你能改;模型只能在开着自动选图时,取回某张图在那一轮看。
+- Codex 发出旁聊和子代理的每个请求时,都带着它来自哪个任务,所以引擎按那个任务的开关处理它们;旁聊的图到它来自的任务里去找。
- 面板不经过模型,也不花 token。在 Codex 里它是侧边面板里的 MCP 应用;在 Claude 桌面版里,由引擎把同一个页面提供给自带的浏览器,只在本机访问。
## 环境要求
@@ -113,7 +115,8 @@ claude plugin install codex-attachment-manager@codex-attachment-manager
2. 新任务一开始就开着**自动选图**(在面板底栏):之前各轮的图默认不发,模型需要时自己取回。勾上每轮都要发的图,比如一直要对照的参考图。每次改动立刻保存,从下一条消息起生效。
3. 想自己选,就关掉自动选图:所有图照常发送,取消勾选的才不发。模型回复“需要 IMG-xxx”、而那张图没有勾上时,面板顶部会列出它;点编号跳到那张图,勾上即可。再打开自动选图,固定发送的勾选原样回来;再关掉,你自己的勾选也原样回来。
4. 图多的时候,点刷新旁边的筛选按钮,选要看的来源。这时整轮勾选只管显示出来的图。
-5. 装 0.6 之前就有的任务,保持原来的设置。
+5. 模型开了子代理,或者你在任务里开了旁聊之后,面板在请求大小下面显示它们,收起成一行,右边是“也自动选图”开关。展开能看到每一个的上次请求;关掉开关,它们的请求就原样发出。
+6. 装 0.6 之前就有的任务,自动选图保持原来的设置。
### 在 Claude 桌面版里
@@ -159,6 +162,7 @@ curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/la
- **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 里,带着任务历史启动的子代理,和分叉出来的任务一样沿用任务的勾选。子代理在同一轮里读的图都留在那一轮(自动选图本来就照发这一轮的图),从它的下一轮起才省掉。
- 取消勾选时,如果 Codex 这一轮还在进行,并且走的是 WebSocket,这一轮剩下的请求仍会带着原图。面板会提示,从下一条消息起生效。
- 在 Codex 里,启用、停用和升级都要重启 Codex 才生效。在 Claude 桌面版里,新版本从新建的会话起生效;升级先运行 `claude plugin marketplace update codex-attachment-manager`,再运行 `claude plugin update codex-attachment-manager@codex-attachment-manager`。
- 切换 Codex 的界面语言后,面板立刻跟着换,给模型的说明从下一条消息起换;侧边面板里标签页的名字要重启 Codex 才换。
@@ -177,7 +181,7 @@ curl -fsSL https://github.com/chipfighter/context-attachment-manager/releases/la
- 从源码装进自己的 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` 两个自测,改的是自动选图的文字时再跑 `spike/src/v03-auto-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`)各一次;子代理和旁聊用 `spike/src/v07-children-selftest.ts` 测。它们会自己启动引擎和 app-server,使用你的 Codex 账号,测完把建的测试任务归档。
- 更新记录见 [CHANGELOG.md](CHANGELOG.md)。
## 许可证
diff --git a/docs/design.md b/docs/design.md
index 5b901f6..52a6364 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -89,6 +89,12 @@
- 副本只在取回的那一轮发送;之后换成一句说明(“IMG-xxx 的原图:模型当时用 cam_view_image 取回,只在那一轮提供,现在已省略”)。关掉自动以后也这样,因为面板不单列副本,用户没法取消它。
- 关着时,传给改写的参数和 v0.2 一样,输出逐字节相同:对照 v0.2 的改写代码,所有勾选组合(中英文、像素相同与否)都比过。
- v0.6 起新任务默认开着(`selection.ts`):引擎和插件服务启动时,在勾选目录里写下这个版本第一次运行的时间(`auto-default.json`,只写一次,Codex 和 Claude 各一份)。任务没有自己的开关时,开始时间(会话记录第一条 `session_meta` 的时间,分叉的按来源任务算,`threadStartedAt`)不早于它,就当作开着,从开始时算起;还没有会话记录的算新的。默认值不写进勾选文件,面板里一改就写下来。读勾选的地方都经过它:改写、是否需要改写(所以新任务从一开始就走 HTTP)、面板、取图工具。
+- **子代理和旁聊**(v0.7,`proxy.ts`、`selection.ts`、`thread-index.ts`、`children.ts`;Codex 的做法见第 11 节):
+ - 认出来源:`x-codex-turn-metadata` 里除了 `thread_id`、`turn_id`,还读 `forked_from_thread_id`、`parent_thread_id`(没有时看请求头 `x-codex-parent-thread-id`)、`subagent_kind`,一起记进日志。
+ - 开关:主任务勾选文件里的 `childrenAuto`,没有就是开。
+ - 旁聊:请求所属的任务没有会话记录、请求里又有 `forked_from_thread_id`,就是旁聊(`sideChatOrigin`;用户自己分叉的任务有记录,照旧按分叉规则)。开关看原任务所属的主任务(原任务也可以是子代理)。开着时用原任务的索引改写:原任务的各轮都算之前的轮次,所以带过来的图都换成自动版占位符,原任务里固定发送的照发(`sideChatSelection`);关着时原样转发,WebSocket 也不拦。
+ - 子代理:会话记录第一条 `session_meta` 里有 `source.subagent.thread_spawn`、没有 `forked_from_id` 的,是不带历史启动的子代理(`spawnParent`),顺着父任务一路找到最上面的主任务(`mainTaskOf`)。子代理自己没有开关时,开着就是自动选图,从子代理开始时算起;关着就关(`childSelection`)。带历史启动的子代理是分叉,照旧。子代理的第一个请求可能早于它的会话记录,这时按 v0.6 的默认算;它的第一个请求里没有之前各轮的图。
+ - 登记:引擎每次看到子代理或旁聊的请求(HTTP 和 WebSocket 都算),就把它记在主任务名下(数据目录 `state/children/<主任务>.json`:类型、来自哪个任务、第一次请求的时间),每个只写一次。旁聊没有会话记录,这是面板知道它的唯一来源。
- **切到 HTTP**:WebSocket 连接上 Codex 只发新增的条目,靠 `previous_response_id` 接上服务端保存的历史,已经发过的图去不掉。所以:
- 任务一需要改写(有取消项,或者用过自动选图),引擎就对它的 WebSocket 握手回 426,Codex 在这个会话里改走 HTTP,每次都发完整历史;
- 它已有的 WebSocket 连接,空闲 1.5 秒后由引擎关掉;
@@ -111,9 +117,10 @@
- **形态**:侧边面板里的 MCP 应用。工具 `cam_panel` 声明 `thread` 入口(`_meta["openai/ui"].entrypoints`),出现在“新建标签页 → 插件和 MCP”里。页面固定为 `ui://codex-attachment-manager/panel.html`,地址一变就可能白屏(上游 #47512)。
- **不经过模型**:面板的调用不写进聊天记录,不占上下文。每次调用带着面板打开时所在任务的编号(`_meta.threadId`),之后不变。所有面板工具都只给面板用(`visibility: ["app"]`),改动状态的工具拒绝模型调用。
-- **工具**:`cam_panel`(面板数据)、`cam_set_selection`(勾选和取消,v0.3 起也开关自动选图)、`cam_image`(缩略图和预览)、`cam_setup`(启用和停用)、`cam_bind`(新任务绑定);v0.3 加了给模型用的 `cam_view_image`,见下。
+- **工具**:`cam_panel`(面板数据)、`cam_set_selection`(勾选和取消,v0.3 起也开关自动选图,v0.7 起也开关子代理和旁聊的自动选图 `childrenAuto`)、`cam_image`(缩略图和预览)、`cam_setup`(启用和停用)、`cam_bind`(新任务绑定);v0.3 加了给模型用的 `cam_view_image`,见下。
- **取图工具 `cam_view_image`**(v0.3):唯一一个模型能调用的工具(没有 app-only 的设置,标着只读)。
- 只在开了自动选图的任务里工作,否则返回一句“这个任务没有开自动选图……需要时写‘需要 IMG-xxx’”。
+ - v0.7:子代理里按它自己的索引取。旁聊没有会话记录,调用的 `_meta["x-codex-turn-metadata"]` 里有 `forked_from_thread_id`,就去原任务的索引取;主任务的“也自动选图”关着时,和没开自动选图一样拒绝。
- 按编号返回原图(不缩小),每张前面一行“[图片 IMG-xxx 取回的原图|名称|来源|轮次|尺寸]”,不带 Codex 自己的“[Image #N]”:那个编号只在原来那条消息里有意义,GPT-6 Luna 曾把它当成要读的数字。
- 工具的标题、说明和返回的文字都是给模型看的,所以写在 `rewrite.ts`,跟着界面语言。
- **拿数据**:页面访问不了 `localhost`(上游 #45913),所以一律经 Codex 回调插件服务;图片放在工具结果的 `_meta` 里,用 data URL。PNG 超过要求的尺寸就缩小;缩略图只缓存在内存里,不写磁盘。
@@ -132,6 +139,9 @@
- 切换前,先把还没保存的勾选按原来的模式存完;切换进行中不接受勾选,免得记错地方。
- “最近一轮模型取回”来自索引里最后一轮的副本;手动模式下不显示,提示条照旧是“模型需要”。
- 预计请求只算固定发送的图,数字后面加“起”(英文把标签换成 At least),悬停说明模型取回的图不算在内。
+- **子代理和旁聊**(v0.7,`panel-state.ts`、`panel.html`):
+ - 面板数据多两项:`childrenAuto`(主任务的开关)和 `children`:引擎登记的子代理和旁聊,按第一次请求的时间排,每个带名字(子代理的 `agent_nickname`,没有时用 `agent_path` 的最后一段)、现在管不管(旁聊看 `sideChatSelection`,子代理看它的有效勾选)、最近一次完整请求带了几张图,以及和主任务一样算出的上次请求(替换几张、前后大小)。
+ - 有子代理或旁聊时,请求大小下面显示一块。标题行(展开按钮和开关)只建一次,轮询不丢悬停和焦点;各行只在内容变了时重建。开关的保存方式和“自动选图”一样:先存完没保存的勾选,保存进行中不接受再点。
- **任务名**:读 `<CODEX_HOME>/session_index.jsonl`,同一个任务以最后一行为准。
- **新任务绑定**:在新任务页打开的面板,绑在 Codex 预先准备的任务上,发第一条消息后可能换成另一个任务。
- 页面记下自己哪些时间段显示在屏幕上,读数据时带给插件服务。
@@ -158,7 +168,7 @@
- Windows 是 `%USERPROFILE%\.codex-attachment-manager`,macOS 是 `~/Library/Application Support/codex-attachment-manager`,Linux 按 XDG 是 `~/.local/share/codex-attachment-manager`;`CAM_DATA_DIR` 可以改(测试、开发用)。
- Windows 上不放在 AppData 下:Codex 是微软商店应用,它启动的程序在 AppData 里新建的文件会被转存到应用的私有目录,Codex 外面的命令行和引擎就看不到了。
-- 里面有:`selection/`(勾选状态,每个任务一个文件,只记取消的识别键;v0.3 起还记自动选图的开关 `auto`、最近一次切换的时间 `autoAt`、第一次打开的时间 `autoSince` 和固定发送的识别键 `pinned`;v0.6 起还有 `auto-default.json`,新任务默认开着自动选图的起始时间)、`bindings/`、`state/requests/`(请求统计)、`cache/pixels/`、`proxy/`(引擎日志)、`plugin-server.jsonl`、`language.json`、`config-backup/`。
+- 里面有:`selection/`(勾选状态,每个任务一个文件,只记取消的识别键;v0.3 起还记自动选图的开关 `auto`、最近一次切换的时间 `autoAt`、第一次打开的时间 `autoSince` 和固定发送的识别键 `pinned`;v0.6 起还有 `auto-default.json`,新任务默认开着自动选图的起始时间;v0.7 起主任务的文件里还记子代理和旁聊的开关 `childrenAuto`,改过才有)、`bindings/`、`state/requests/`(请求统计)、`state/children/`(v0.7,每个主任务的子代理和旁聊)、`cache/pixels/`、`proxy/`(引擎日志)、`plugin-server.jsonl`、`language.json`、`config-backup/`。
- 分叉任务沿用原任务在分叉那一刻的勾选,之后各管各的。v0.3:固定发送一样按时间继承;开关在分叉前打开、之后没再切换过才继承;分叉前用过自动选图的,分叉也记下 `autoSince`,以便省略历史里的副本。
- `migrate-data.ts` 在第一次使用时,把旧位置(旧的 AppData 目录和各应用私有目录里的副本)的数据复制过来,用锁文件保证只有一个进程在复制。
@@ -188,6 +198,11 @@
- D 组(v0.6)不设开关,检查新任务默认开着;一个问题同时要两张没取过的图,检查都取回、答对;
- C 组只有一张图,排除上下文的干扰。
- 2026-10-06 的结果:sol、astra 中英文全部通过;luna 取不取的判断基本都对(英文 C 组漏取一次),读取回的图偶尔读错数字(见第 11 节“模型的差别”)。
+- **子代理和旁聊自测**(v0.7,`v07-children-selftest.ts`):同样的引擎、app-server 和插件服务,另打开 Codex 的 `multi_agent_v2`(`spawn_agent` 的 `fork_turns`)。旁聊照 Codex 的做法开(`thread/fork`,`ephemeral: true`),带一句和 Codex 给旁聊的类似的说明。测试图和自动选图自测一样:
+ - S 组:主任务描述两张图后开旁聊,先问文字问题(图都换成占位,不取图),再问角落的数字(从原任务取回,答对);
+ - C 组:子代理第一轮用 `view_image` 看图,主任务用 `followup_task` 给它第二轮,问角落的数字(前一轮的图换成占位,取回,答对);
+ - O 组:主任务的开关关掉后,旁聊和子代理的请求原样发;
+ - 每组最后看主任务面板列出的子代理和旁聊。结果见 [v0.7/plan.md](v0.7/plan.md) 第 5 节。
## 11. 依赖的 Codex 行为和已知的坑
@@ -205,6 +220,11 @@
- 工具返回的 MCP 图片,模型在代码里用 `image()` 交给自己;记录里是 `custom_tool_call_output` 里的 `input_image`,数据和原图逐字节相同,`detail` 是 `high`。
- 模型调用插件工具时,`_meta` 带着 `threadId` 和 `x-codex-turn-metadata`(其中有 `thread_id`、`turn_id`)。插件的 `.mcp.json` 设了 `default_tools_approval_mode = "approve"`,不用逐次批准。
- 同一个任务里第一次取图时,模型常先查一次 `ALL_TOOLS` 确认工具名,多一来回。
+- **子代理和旁聊**(v0.7 查证,Codex 0.162;源码 `codex-rs/core/src/responses_metadata.rs`、`turn_metadata.rs`、`mcp_tool_call.rs`):
+ - 旁聊是 app-server 的 `thread/fork`(`ephemeral: true`,这个版本要求同时 `excludeTurns: true`;终端版的 `/side` 也是这样),不写会话记录。它的请求(包括 WebSocket 握手)和模型调用工具的 `_meta` 里,`x-codex-turn-metadata` 的 `thread_id` 是旁聊自己,`forked_from_thread_id` 是原任务。
+ - `spawn_agent` 开的子代理有自己的会话记录,`session_meta` 有 `parent_thread_id` 和 `source.subagent.thread_spawn`(`depth`、`agent_path`、`agent_nickname`)。它的请求里 `parent_thread_id` 是父任务,`subagent_kind` 是 `thread_spawn`,`session_id` 是主任务,另有请求头 `x-codex-parent-thread-id`、`x-openai-subagent: collab_spawn`。请求里有父任务时,Codex 不再写 `forked_from_thread_id`,所以带历史的子代理只能从会话记录认出。
+ - 子代理的会话记录文件先建好,第一行稍后才写,它的第一个请求可能落在中间(2026-10-13 自测里早了约 40 毫秒)。所以读到空文件时不当结论、不缓存(`spawnParent`、`forkOrigin`、`threadStartedAt`)。
+ - 子代理之后的轮次由父任务用 `followup_task` 发起;app-server 拒绝直接给 multi_agent_v2 子代理开新的一轮。归档主任务时,子代理一起归档。
- **上游问题**:#47512(面板地址变化后白屏)、#45913(页面访问不了 `localhost`)。
- **桌面版会在用户消息里附一段 “Files mentioned by the user”**,写着上传文件的完整路径。引擎不改用户消息的文字,靠说明里“不要自己用工具去读取”约束模型;模型偶尔仍会自己打开文件。
- **模型的差别**:小模型在低推理强度下(例如 GPT-6 Luna Light)偶尔会要错图,或者拿到错图时不说“这张里没有”,而是猜一个答案(v0.1-25 的录屏里遇到过)。
diff --git a/docs/spec.md b/docs/spec.md
index 828849b..df515d2 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -1,6 +1,6 @@
# 规格:Context Attachment Manager(上下文素材管理器)
-> 本文件是目标、范围、约束和验收标准的唯一事实来源(2026-09-24 经用户、Claude、Codex 三方确认),描述当前版本 v0.6.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)。v0.6 的默认开启自动选图和 Claude 桌面版自动打开面板标着“v0.6”,见 [v0.6/plan.md](v0.6/plan.md)。项目 2026-10-11 由 Codex Attachment Manager 改名,因为不再只给 Codex 用(用户定);安装用的标识(`codex-attachment-manager`)和数据目录不变,已装的用户照常升级。
+> 本文件是目标、范围、约束和验收标准的唯一事实来源(2026-09-24 经用户、Claude、Codex 三方确认),描述当前版本 v0.6.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)。v0.6 的默认开启自动选图和 Claude 桌面版自动打开面板标着“v0.6”,见 [v0.6/plan.md](v0.6/plan.md)。v0.7 的 Codex 子代理和旁聊也自动选图标着“v0.7”,见 [v0.7/plan.md](v0.7/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. 目标
@@ -19,6 +19,7 @@ v0.4:同样的管理也用在 Claude 桌面应用的 Code 标签页里(本
- **内容相同**:两条出现记录的字节完全相同,或者解码后的像素完全相同,就算内容相同,与文件名无关。缩放或重新压缩过的图不算。
- **勾选状态**:每个任务各有一套。勾选的图照常发送;取消的图在发出的请求里换成占位符。
- **自动选图**:每个任务各有一个开关。v0.6 起,新任务和新会话默认开着,升级之前就有的任务和会话保持原样,用户改过的以用户的为准(用户 2026-10-13 定:有些用户连面板都不会打开);之前默认关。打开后,之前各轮的图默认不发,模型需要看哪张,就用取图工具按编号取回原图,只在这一轮提供;勾选的意思变成“固定发送”,默认都不勾,勾上的图每轮都发(v0.3,用户 2026-10-06 定:不在模型开口之前替它准备可能要的图,由它自己按编号要)。
+- **子代理和旁聊**(v0.7,Codex):主任务派出去的子代理和在任务里开的旁聊,默认也按自动选图管,主任务面板里有一个开关管它们(见“选择规则”和“界面”)。
- **来源**:每条出现记录属于一类来源:用户上传、PDF 页面、网页截图、查看的图片、工具返回、生成的图片。PDF 页面和网页截图是用户在 Codex 桌面版里给 PDF 或网页加评论时,Codex 随消息附上的截图,靠 Codex 写在图前面的固定说明认出(例如 “The next image shows PDF page 3 at the time of Comment 1.”)。PDF 页面记下页码;同一条消息只提到一个 PDF 时,再记下文件名。认不出的仍算用户上传(v0.2,用户 2026-09-29 定:只做认得准的来源)。
### 免配置
@@ -32,6 +33,11 @@ v0.4:同样的管理也用在 Claude 桌面应用的 Code 标签页里(本
- 新出现的图默认勾选,照常发送,包括和前面内容相同的副本(用户 2026-09-24 决定)。用户没有取消任何图时,请求原样转发,Codex 的表现和没装工具时一样。
- 任何一条出现记录都可以在任何一轮取消或重新勾选,从下一次请求起生效,不换任务、不重建。取消的记录仍留在列表里。
- 分叉出来的任务,沿用原任务在分叉那一刻的勾选;之后两边各管各的(用户 2026-09-24 决定)。
+- 子代理和旁聊(v0.7,用户 2026-10-13 定,起因是 [issue #2](https://github.com/chipfighter/context-attachment-manager/issues/2);之前只管带历史启动的子代理,按分叉的规则):
+ - 主任务面板有一个“也自动选图”开关管它们,默认开,老任务也一样。它和主任务自己的自动选图开关是分开的:开着时,不管主任务自己开没开自动选图,子代理和旁聊都按自动选图管;关掉就不管,请求原样发。
+ - 旁聊(Codex 只放在内存里的分叉)用原任务的图。开着时,从原任务带过来的图都换成占位,原任务里固定发送的照发,原任务这一轮正在看的也换掉;模型要看哪张,用取图工具去原任务里取。
+ - 启动时不带主任务历史的子代理:开着时按自动选图管它自己的图,这一轮看的照发,前几轮的换成占位,要看再取。子代理再派的子代理也一样,开关看最上面的主任务。子代理自己有开关时以它的为准。
+ - 带着主任务历史启动的子代理照旧按分叉的规则继承勾选;Codex 自己的后台任务(代码审查、对话压缩、记忆整理)不算子代理。
- 取消时由工具判断用哪种占位符:本次请求里还有一条内容相同、仍在发送的记录,就用“重复”占位符指向它;没有,就用普通占位符。
- 只是看起来相似的图(例如缩放或重新压缩过)不算内容相同。
- 工具认不出的图,或者没法安全改写的请求,一律原样发送,并记下原因。只有用户明确取消的图才会被换掉。
@@ -103,7 +109,11 @@ v0.4:同样的管理也用在 Claude 桌面应用的 Code 标签页里(本
- 只认用户自己开的任务,子代理、分叉和后台自动任务都不算;
- 只认面板显示在屏幕上时开始的任务;
- 面板显示期间开始了好几个任务时,跟最新的一个;只有两个任务几乎同时开始(相差 20 秒以内)时,才列出名称让用户点选(用户 2026-09-25 改:原来只要有两个就让用户选,而 Codex 每隔几分钟给新任务页换一个预备任务,面板会被反复询问)。
-- 子代理不单独处理:带历史启动的子代理,Codex 记成从主任务分叉,按分叉的规则继承勾选。其他情况等开源后按用户反馈再定(用户 2026-09-25 定)。
+- 子代理和旁聊(v0.7,用户 2026-10-13 看过截图后定;规则见上面“选择规则”):
+ - 引擎见过这个任务的子代理或旁聊之后,请求大小下面多一块“子代理和旁聊”;没见过时不显示。
+ - 默认收起成一行:数量、它们上次请求一共少发多少,右边是“也自动选图”开关,点一下就保存,模型不能改。
+ - 展开后每个一行:子代理写它在 Codex 里的名字,旁聊写开始的时间;右边标现在的规则(“自动选图”,关掉后是“原样发送”);第二行写几张图、上次请求替换了几张、少发多少,还没有请求经过引擎时写“还没有经过代理的请求”。
+ - 这里不能逐张勾选子代理和旁聊的图。
- 标题右侧是“停用插件”或“启用插件”,两种样式不同。点一下立即生效,不用再确认(用户 2026-09-25 定)。
- 停用或启用后,中间的提示说明要重启 Codex 才生效,另一个按钮随时可以撤回;
- 撤回到 Codex 启动时的状态,就不再提示重启。
@@ -161,6 +171,7 @@ v0.1 到 v0.3 都不做下面这些。其中音频和其他语言已确认是后
- 在 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` 或新会话带上过去的图(那是另一个会话);子代理的请求(仍只管主对话)。
+- v0.7 也不做(用户 2026-10-13 定):Claude Code 的子代理(它们一般一次跑完、只有一轮,按自动选图的规则本来就全发);在主任务面板里逐张勾选子代理和旁聊的图;给每个子代理单独设开关;改“这一轮看的图照发”的规则。
## 3. 硬约束
@@ -174,7 +185,7 @@ v0.1 到 v0.3 都不做下面这些。其中音频和其他语言已确认是后
- 仓库里的文档和代码不写用户本机的具体路径(例如个人项目文件夹)。`~/.codex`、`%LOCALAPPDATA%` 这类通用位置可以写。本项目以后会开源。
- 不改写原生任务的历史记录。
- 代理只替换用户取消的图片,连同 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 定,取代原来的“选择权永远在用户”)。v0.6 起新任务和新会话默认开着自动选图,用户随时可以关(用户 2026-10-13 定)。
+- 选择权在用户:默认只由用户在面板里勾选决定,工具和模型都不能自动勾选或取消;模型只能按约定索要(例如回复“需要 IMG-004”),给不给由用户决定。用户给某个任务打开“自动选图”后,之前各轮的图默认不发,由模型用取图工具按编号取回需要的图,只在这一轮有效;模型不能改用户的勾选,也不能替用户开关自动选图(v0.3,用户 2026-10-06 定,取代原来的“选择权永远在用户”)。v0.6 起新任务和新会话默认开着自动选图,用户随时可以关(用户 2026-10-13 定)。v0.7 起 Codex 任务的子代理和旁聊也默认按自动选图管,用户可以在主任务面板里关掉(用户 2026-10-13 定)。
- 先在 Windows 上开发和测试。技术栈:TypeScript/Node。macOS、Linux 由 CI 验证能装上、能启动;这两个平台桌面版上的实测,等用户在 GitHub 上反馈(用户 2026-09-25 定)。
- 交付形态:Codex 插件。插件带一个本地 MCP 服务,负责拉起引擎、提供面板;仓库根目录就是插件市场。面板位置见第 1 节“界面”。
- 用户在 Codex 的插件页面添加插件市场 `chipfighter/context-attachment-manager`、装上插件,再在面板里点“启用”;卸载前在面板里点“停用”。
@@ -253,6 +264,15 @@ v0.1 之前的阶段验收(阶段 0 的重建路线、代理路线 P2)都已
3. Claude 桌面版里有图的会话自动打开面板;被桌面版关掉的,下一轮重新打开;用户关掉的不再自动打开,`/cam` 能再打开;只留一个面板标签页。
4. 原有测试和 Codex 自测不退化。
+### v0.7
+
+> 用户 2026-10-13 定,方案和实测见 [v0.7/plan.md](v0.7/plan.md)。
+
+1. 开关默认开:旁聊的请求里,原任务的图换成占位,模型要看时能从原任务取回并看图作答;不带历史的子代理,前几轮的图换成占位,要看时能取回并看图作答。
+2. 开关关掉:子代理和旁聊的请求原样发。
+3. 主任务面板列出子代理和旁聊,统计和规则对得上;开关只有用户能改。
+4. 主任务自己的行为、原有测试和 Codex 自测不退化。
+
## 5. 待定问题
- 在插件页面移除或关掉插件、没先在面板里停用时,代理设置还在: