Skip to content

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.

docs(p5): README、cam.cmd,规格和方案按插件形态更新

chipfighteraf8ebbc86ef4
diff --git a/AGENTS.md b/AGENTS.md
index 3c6bdca..a9f3e41 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,7 +12,8 @@ Codex 上下文素材管理器(暂名):让用户逐轮决定,Codex 任
## 已确认的规矩
- 原始对话记录和素材文件始终只读。
-- 真实数据不进仓库:从真实会话和用户素材里提取的内容只能放在 `local/`(已被 git 忽略),任何时候都不提交。
+- 真实数据不进仓库:从真实会话和用户素材里提取的内容只能放在本机的 `local/`(已被 git 忽略)或工具的数据目录 `%LOCALAPPDATA%\codex-attachment-manager`,任何时候都不提交。
+- 插件本体在 `plugin/`(`plugin/src` 是运行代码),测试和实验脚本在 `spike/`。改动运行代码后,要重新运行 `cam install`,Codex 缓存里的插件副本才会更新;不要让已安装的配置指向不存在的文件。
- 仓库里的文档和代码不写用户本机的具体路径;通用位置(如 `~/.codex`、`%LOCALAPPDATA%`)可以写。
- 先在 Windows 上开发和测试。技术栈用 TypeScript/Node。
- 界面开发:Claude 自己截图检查效果;做到界面的关键节点时,截图给用户看,停下来等反馈再继续(用户 2026-09-24 确认)。
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5f064f3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,101 @@
+# Codex 上下文素材管理器(暂名)
+
+一个 Codex 桌面版插件:在同一个任务里,逐轮决定哪些历史图片随下一条消息发给模型。
+
+## 它解决什么问题
+
+在 Codex 里做设计、改图、看截图,一个任务里的图片会越积越多。之后每一次请求,都会把这些图重新发给模型:请求越来越大,越来越慢,也越来越贵。想去掉旧图,原本只能新开任务,前面的对话就接不上了。
+
+装上这个插件后:
+
+- Codex 右侧的侧边面板里多出一个“上下文素材”标签页,按时间顺序列出这个任务里的全部图片:你上传的,以及模型查看、生成的。
+- 取消勾选的图,从下一条消息起换成一小段占位文字。如果有内容相同的图还在发送,占位文字会指向那一张。任务不换,对话连续。
+- 模型需要某张被取消的图时,会回复“需要 IMG-xxx”。给不给,由你在面板里决定。
+- 面板顶部显示下一条消息会发送什么,以及请求大约能小多少。
+
+## 工作原理
+
+- 插件在本机启动一个小代理(引擎),Codex 发往 OpenAI 的请求先经过它。
+- 你取消勾选的图,在请求发出前被换成占位符;其余内容原样转发。
+- 勾选状态按任务分别保存,只有你能改,模型不能。
+- 面板是 Codex 的插件页面,从侧边面板手动打开,不经过模型,也不花 token。
+
+## 环境要求
+
+- Windows,Codex 桌面版(在 26.917 上验证过)。
+- 不需要另外安装 Node:插件使用 Codex 自带的 Node 24;找不到时,才用系统里的 `node`。
+
+## 安装
+
+```bat
+git clone [email protected]:chipfighter/codex-attachment-manager.git
+cd codex-attachment-manager
+cam install
+```
+
+安装会做下面几件事:
+
+1. 用 Codex 自己的命令行,把这个仓库登记为插件市场,并安装插件。
+2. 启动装好的插件服务做一次自检;通过了,才改下一步的设置。
+3. 在 `~/.codex/config.toml` 里写入一段带标记的代理设置。如果你的环境变量里设了代理,还会在 `~/.codex/.env` 里写一段 `NO_PROXY`,只包含本机地址。
+
+改之前,`config.toml` 会先备份到数据目录。
+
+然后**重启 Codex**。
+
+## 使用
+
+1. 打开一个任务,点右上角“显示/隐藏侧边面板”。
+2. 在侧边面板里点“新建标签页”,在“插件和 MCP”下选“上下文素材”。
+3. 取消勾选不想再发送的图(点缩略图可以看大图),然后点“确定”。从下一条消息起生效。
+
+面板里的标签:
+
+| 标签 | 含义 |
+|---|---|
+| 不发送 | 换成普通占位符 |
+| 由 IMG-xxx 代替 | 有内容相同的图还在发送,占位符会指向它 |
+| 与 IMG-xxx 相同 | 这两张图内容相同 |
+| 模型需要这张 | 模型上一次回复说了“需要 IMG-xxx” |
+| 已不在上下文 | 这张图已被 Codex 压缩出历史,不会再发送 |
+| 无法取消 | Codex 自带生图工具的结果,格式上不能替换 |
+
+## 卸载
+
+```bat
+cam uninstall
+```
+
+卸载会先恢复直连,再移除插件,最后提示你重启 Codex。
+
+**请用这个命令卸载,不要只在 Codex 的插件页面里关掉或移除插件。** 只关插件的话,代理设置还在,却没有东西启动引擎,Codex 会连不上。万一遇到这种情况,运行一次 `cam uninstall` 就能恢复。
+
+`cam status` 可以查看当前的安装状态。
+
+## 已知限制
+
+- 目前只管理图片,其他类型的文件以后再支持。
+- Codex 自带生图工具的结果不能取消。
+- 取消勾选时,如果这一轮对话还在进行,并且走的是 WebSocket,这一轮剩下的请求仍会带着原图。面板会提示,从下一条消息起生效。
+- Codex 刚启动的头几十秒里,引擎可能会重启几次,偶尔会看到一次“正在重新连接”。
+
+## 数据和隐私
+
+- 所有数据只留在本机的 `%LOCALAPPDATA%\codex-attachment-manager`:
+ - 勾选记录;
+ - 请求统计:只记大小和数量,不记内容;
+ - 日志:不记对话内容和凭据;
+ - `config.toml` 的备份。
+- 除了 Codex 本来就要发给 OpenAI 的请求,插件不向任何地方发送数据。
+- 原始对话记录只读,不修改。
+
+## 开发
+
+- 插件本体在 `plugin/`;`spike/` 里是测试和早期实验脚本。
+- 运行测试:`cd spike && node --test`
+- 不开 Codex 调面板:`node spike/scripts/panel-dev.ts`,然后在浏览器里打开 `http://127.0.0.1:17895/?solo=1`。页面用合成的测试图,不读取你的真实数据。
+- 规格、方案和各阶段报告在 `docs/` 下,从 [docs/spec.md](docs/spec.md) 读起。
+
+## 许可证
+
+尚未确定。
diff --git a/cam.cmd b/cam.cmd
new file mode 100644
index 0000000..1dff045
--- /dev/null
+++ b/cam.cmd
@@ -0,0 +1,4 @@
+@echo off
+rem Purpose: the tool's command line without a separate Node install: runs plugin\src\cam.ts with the same Node the
+rem plugin uses (the one Codex ships, else node on PATH). Usage: cam install ^| uninstall ^| status ^| list ^<thread id^>
+call "%~dp0plugin\scripts\launch.cmd" "%~dp0plugin\src\cam.ts" %*
diff --git a/docs/plan.md b/docs/plan.md
index e239ccd..5020b8a 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -309,3 +309,43 @@ P1 通过后,再按用户的节奏一步步探索改写。
- 每 3 秒刷新一次,没有变化就不重画。页面报告自己不可见时降到 15 秒一次,因为有的宿主会误报。
- **取图**:`cam_image`。PNG 超过要求的尺寸就缩小,其他格式原样交给页面,由浏览器缩放。
- **开发页**:`spike/scripts/panel-dev.ts` 在浏览器里扮演 Codex 的侧边面板,用合成测试图调通页面,不用重启 Codex。页面上的“切换明暗”“加一张图”只用来模拟 Codex 的操作,不会出现在 Codex 里。
+
+## 13. 打包成插件(P5)
+
+### 已查证的事实
+
+依据桌面版 26.917、它自带的命令行 0.155,以及它自带的插件:
+
+- **插件**:插件目录里放 `.codex-plugin/plugin.json`。
+ - 字段有 name、version、description、author、homepage、repository、keywords;`mcpServers` 指向 `.mcp.json`。
+ - `interface` 里有 displayName、shortDescription、longDescription、developerName、category、capabilities、brandColor、logo、composerIcon。
+- **`.mcp.json`**:
+ - 服务的 command、args、cwd(`.` 表示插件目录)、default_tools_approval_mode、startup_timeout_sec;
+ - `env_vars` 是一张白名单,列出允许传给服务的环境变量。
+- **插件市场**:一个目录里的 `.agents/plugins/marketplace.json`,列出其中的插件和它们的相对路径。
+- **命令行**:
+ - `codex plugin marketplace add <本地路径、owner/repo 或 Git 地址>`、`codex plugin add <插件>@<市场>`、`codex plugin remove`、`codex plugin marketplace remove`;
+ - 安装会把插件目录复制到 `~/.codex/plugins/cache/<市场>/<插件>/<版本>/`,并在 config.toml 里写 `[marketplaces.<市场>]` 和 `[plugins."<插件>@<市场>"]`。
+- **桌面版自带的东西**:
+ - 命令行在 `%LOCALAPPDATA%\OpenAI\Codex\bin\<版本号>\codex.exe`;
+ - 自带 Node 24,能直接运行 TypeScript。自带插件用一个 .cmd 启动脚本按顺序找这个 Node。
+- **重启才生效**:正在运行的桌面版不会立即加载新装的插件。
+
+### 设计
+
+- **目录**:
+ - `plugin/` 是插件本体:清单、`.mcp.json`、`scripts/launch.cmd`、`src/`;
+ - 仓库根目录的 `.agents/plugins/marketplace.json` 指向它;
+ - `spike/` 留测试和实验脚本。
+- **启动**:
+ - `.mcp.json` 用 `cmd.exe /d /s /c call ./scripts/launch.cmd ./src/plugin-server.ts` 启动插件服务,`launch.cmd` 优先用 Codex 自带的 Node;
+ - 根目录的 `cam.cmd` 用同一个脚本运行命令行,用户不用另装 Node。
+- **数据目录**:`%LOCALAPPDATA%\codex-attachment-manager`。插件目录会在更新时被 Codex 替换,而且不往 `~/.codex` 里写。
+- **安装顺序**:
+ 1. 检查和用户自己设置的冲突,然后备份 config.toml;
+ 2. 登记市场,装插件(每次都重装,让 Codex 的副本和仓库一致);
+ 3. 自检装好的副本:用它自己的启动脚本起服务,问工具列表和面板页面;
+ 4. 写代理设置;
+ 5. 迁移旧的勾选记录,确保引擎在运行。
+- **卸载顺序**:先去掉代理设置,恢复直连;再卸插件、去掉市场。
+- **已知风险**:只在插件页面关掉插件、不运行 uninstall,Codex 会连不上,见 spec.md 第 5 节。
diff --git a/docs/spec.md b/docs/spec.md
index 09b7f27..44eb0bd 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -50,7 +50,9 @@
- 按时间顺序、按轮次列出,可以滚动。每条显示缩略图、编号、名称、来源、尺寸、大小、内容相同的关系和勾选状态;点缩略图放大预览。
- 勾选和取消先暂存,点“确定”才保存,从下一条消息起生效。
- 主题、字体和配色跟随 Codex。
-- 以上是用户 2026-09-24 定的 MVP。“本轮将发送什么”的完整预览(取消前后的请求大小对比)、改写不了时的提示、“只读预览 / 受控发送”的标识,是否要做,之后再定。
+- 面板顶部显示下一条消息的发送预览:照常发送几张、占位几张(其中重复几张),预计请求大小和全部发送时的对比,以及上一次请求实际少发了多少。预计值以引擎记录的上一次完整请求为基准,标明是“预计”,不写成已经发出的请求。
+- 上一次请求没能按勾选改写,或者取消时这一轮还在走 WebSocket,面板上都有提示;代理没在运行时也提示。
+- 以上是用户 2026-09-24 定的 MVP,外加 2026-09-25 要求补上的发送预览和改写失败提示。
### 为后续扩展预留
@@ -69,17 +71,18 @@
## 3. 硬约束
-- 原始对话记录和素材文件始终只读,不修改、不移动、不删除。不直接写入 `~/.codex` 下的任何文件,只有三个例外:
+- 原始对话记录和素材文件始终只读,不修改、不移动、不删除。不直接写入 `~/.codex` 下的任何文件,只有四个例外:
+ - 通过 Codex 自己的命令行登记插件市场、安装和卸载插件时,Codex 对 `config.toml` 和插件缓存的正常写入(P5);
- 官方 app-server 在创建和运行任务时自己产生的正常写入;
- 为接入本地代理和面板服务,工具可以修改 `config.toml` 里由它自己管理、带标记的设置(用户 2026-09-24 授权)。改之前先备份,能一键恢复,其他设置一律不动;
- 为让生图和改图也能连到本地代理,工具可以在 `~/.codex/.env` 里写一段带标记的 `NO_PROXY`,只含本机地址,并保留用户自己的条目(用户 2026-09-24 同意)。`.env` 可能含密钥,工具不复制、不输出它,只增删自己的那一段;文件里只剩这一段时,恢复时连文件一起删掉。
-- 真实数据不进仓库:从真实会话和用户素材里提取的图片、记录片段、日志和备份,只能放在本机的 `local/` 目录(已被 git 忽略),任何时候都不提交。仓库里的样例数据只能是合成的或脱敏的。
+- 真实数据不进仓库:从真实会话和用户素材里提取的图片、记录片段、日志和备份,只能放在本机,开发时放在 `local/` 目录(已被 git 忽略),装好的插件放在数据目录 `%LOCALAPPDATA%\codex-attachment-manager`;任何时候都不提交。仓库里的样例数据只能是合成的或脱敏的。
- 仓库里的文档和代码不写用户本机的具体路径(例如个人项目文件夹)。`~/.codex`、`%LOCALAPPDATA%` 这类通用位置可以写。本项目以后会开源。
- 不改写原生任务的历史记录。
- 代理只替换用户取消的图片,连同 Codex 附在它前后的路径标签;请求里的其他内容原样转发。
- 选择权永远在用户:哪些素材进入上下文,只由用户在面板里勾选决定。工具和模型都不能自动勾选或取消;模型只能按约定索要(例如回复“需要 IMG-004”),给不给由用户决定。
- 先在 Windows 上开发和测试。技术栈:TypeScript/Node。
-- 交付形态:Codex 插件(技能、本地 MCP 服务和钩子);面板位置见第 1 节“界面”。
+- 交付形态:Codex 插件。插件带一个本地 MCP 服务,负责拉起引擎、提供面板;仓库根目录就是插件市场。用户运行 `cam install` 一次装好,`cam uninstall` 一次恢复。面板位置见第 1 节“界面”。
## 4. 验收标准
@@ -121,3 +124,5 @@
## 5. 待定问题
- 路线:路线 A(用 `thread/inject_items` 在新任务里重建)技术上可行,但用户不接受“重建后在界面上看不到原对话”。代理路线(任务不换,每次请求发出前由本地代理按勾选改写)已在桌面版验证通过:P1 只转发、P2 按勾选改写,生图和改图也包括在内,见 plan.md 第 9、10 节和 p2-report.md。面板已在 P4 做完,见 p4-report.md。
+- 许可证:尚未确定,开源之前由用户决定。
+- 只在 Codex 的插件页面里关掉或移除插件、没有运行 `cam uninstall` 时,代理设置还在,却没有东西启动引擎,Codex 会连不上。现在的做法是在 README 里写明,并让 `cam uninstall` 随时能恢复。要不要让引擎不依赖插件启动(例如用 Windows 计划任务),需要用户同意在系统里注册任务,之后再定。
diff --git a/docs/tasks.md b/docs/tasks.md
index 90137db..be472e2 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -2,21 +2,36 @@
> 方法见 [plan.md](plan.md)。按顺序做,完成一项勾一项,并写明证据放在哪里。
-## 当前:界面 P4(已完成),打包 P5
+## 当前:打包 P5
+
+设计见 plan.md 第 13 节。测试时调用模型一律用 `gpt-6-sol`,推理强度 `low`。
+
+- [x] **面板补充:发送预览和改写失败提示**(2026-09-25,用户要求;spec.md 第 4 节“首版”第 4、6 条)
+ - 引擎分开记“最近一次事件”和“最近一次完整请求”(带每张图的大小),WebSocket 在取消后仍在传数据时记一笔(`plugin/src/request-stats.ts`、`proxy.ts`)。
+ - 面板顶部:下一条消息发送几张、占位几张,预计请求大小和全部发送的对比,上一次请求实际少发多少;两类提示(`panel-state.ts`、`panel.html`)。新增 4 个单元测试。
+- [x] **P5-1 查证插件格式和安装方式**:插件清单、`.mcp.json`、插件市场清单、Codex 命令行的 `plugin marketplace add` / `plugin add` / `plugin remove`、插件缓存位置、Codex 自带的 Node 24(结果见 plan.md 第 13 节)。
+- [x] **P5-2 打包**:运行代码搬进 `plugin/src`;`plugin/.codex-plugin/plugin.json`(名称、说明、图标)、`.mcp.json`、`scripts/launch.cmd`;仓库根目录的 `.agents/plugins/marketplace.json`;`cam.cmd` 不用另装 Node 就能运行命令行。
+- [x] **P5-3 安装和卸载改成插件方式**(`cam.ts`、`install.ts`、`codexcli.ts`;共 79 个单元测试)
+ - install:检查冲突 → 备份 → 登记市场 → 装插件 → 自检装好的副本 → 写代理设置 → 迁移旧勾选 → 确保引擎在运行。
+ - uninstall:先恢复直连,再卸插件、去掉市场。数据目录改到 `%LOCALAPPDATA%\codex-attachment-manager`。
+ - 2026-09-25 在用户机器上安装成功:插件进了 Codex 缓存,自检通过,旧版写的服务块已去掉,迁移了 6 份勾选记录。
+- [x] **P5-4 README**:用途、原理、安装、使用、卸载(强调要用 `cam uninstall`)、限制、数据和隐私、开发。
+- [ ] **P5-5 桌面版端到端验证**【需用户】:重启 Codex → 插件页面能看到插件 → 从侧边面板打开面板、看发送预览 → 取消一张图再问一次 → 日志确认插件服务从 Codex 的缓存启动、引擎由它拉起。
-设计见 plan.md 第 12 节,结果见 `docs/p4-report.md`。测试时调用模型一律用 `gpt-6-sol`,推理强度 `low`。
+---
+
+## 已完成:界面 P4
+
+设计见 plan.md 第 12 节,结果见 `docs/p4-report.md`。
- [x] **P4-1 找入口**(2026-09-24;依据:桌面版 26.917 的前端代码):工具在 `_meta["openai/ui"].entrypoints` 里声明 `thread` 入口后,面板出现在右侧侧边面板“新建标签页 → 插件和 MCP”里,用户手动打开,不经过模型;打开后桌面版用当前任务的编号调用工具。标题栏没有给插件的入口,所以不做外挂窗口。
-- [x] **P4-2 面板**(`spike/src/panel.html`,`plugin-server.ts` 的 `cam_panel` / `cam_image`,`panel-state.ts`;开发页 `spike/scripts/panel-dev.ts`;新增 3 个单元测试,共 73 个)
+- [x] **P4-2 面板**(`panel.html`,`plugin-server.ts` 的 `cam_panel` / `cam_image`,`panel-state.ts`,P5 起都在 `plugin/src`;开发页 `spike/scripts/panel-dev.ts`;新增 3 个单元测试,共 73 个)
- 按轮次列出任务历史里的图片,缩略图、编号、名称、来源、尺寸、大小;点缩略图放大预览;勾选先暂存,点“确定”才保存。
- 标出“不发送”、“由 IMG-xxx 代替”、“与 IMG-xxx 相同”、“模型需要这张”、“无法取消”;代理没在运行时提示。
- 主题、字体、配色跟随 Codex;每 3 秒刷新,新图自动出现。
- [x] **P4-3 桌面版实测**【需用户】(2026-09-24 通过;证据:`local/plugin-server.jsonl`、`local/proxy/2026-09-24.jsonl`、用户截图;结果见 `docs/p4-report.md`)
- 从“插件和 MCP”打开面板,数据、缩略图、主题都对;面板的调用没有写进聊天记录。
- 预览、勾上 a.png、点“确定”后,下一次请求带上两张图、不做替换,模型答出了 a.png 的背景、形状和角标。
-- [ ] **P5 打包成插件、写说明,桌面版端到端验证**【需用户】。
-- 未定:面板上的“本轮将发送什么”完整预览(取消前后的请求大小对比)和“改写不了时在面板上提示”(spec.md 第 4 节“首版”第 4、6 条),做不做、什么时候做,之后再定。
-
---
## 已完成:核心完善 P3