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(p5): README、cam.cmd,规格和方案按插件形态更新
chipfighteraf8ebbc86ef4
diff --git a/AGENTS.md b/AGENTS.mdindex 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.mdnew file mode 100644index 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.cmdnew file mode 100644index 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.mdindex 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.mdindex 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.mdindex 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