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(p4): 面板做进 Codex 侧边面板、桌面版端到端测通;记下入口机制和 MVP 范围
chipfighterb1f24fbb393f
diff --git a/docs/p4-report.md b/docs/p4-report.mdnew file mode 100644index 0000000..a4564f7--- /dev/null+++ b/docs/p4-report.md@@ -0,0 +1,63 @@+# 界面 P4 报告++> 2026-09-24,由 Claude 执行。本报告只写统计和测试任务里的简短问答,不含真实对话、图片和本机路径。设计见 [plan.md](plan.md) 第 12 节,任务见 [tasks.md](tasks.md)。测试调用模型一律用 gpt-6-sol、推理强度 low。++## 1. 结论++- **面板已经嵌进 Codex**:它是 Codex 右侧侧边面板里的一个标签页“上下文素材”。用户在侧边面板的“新建标签页 → 插件和 MCP”里手动打开,不经过模型,也不花 token。+- **按用户定的 MVP 做完**:+ - 按时间顺序、按轮次列出任务历史里的图,可以滚动;+ - 显示缩略图,点开可以看大图预览;+ - 勾选后点“确定”保存,从下一条消息起生效;+ - 主题、字体和配色跟随 Codex。+- **在用户的桌面版上端到端测通**:打开面板,预览,重新勾选被取消的图,然后再提问,模型答对了这张图的内容。++## 2. 入口++- 这一版桌面版允许工具在 `_meta["openai/ui"].entrypoints` 里声明入口。声明成 `thread` 类型后,这个工具的页面就出现在侧边面板的“新建标签页 → 插件和 MCP”里。+- 用户点开后,桌面版用当前任务的编号调用这个工具,把结果交给页面。页面之后的调用也都带着这个编号,所以面板天然知道自己属于哪个任务。+- 标题栏没有给插件的入口,所以不做外挂窗口。+- 面板的入口工具是 `cam_panel`,列表里的名字取工具标题“上下文素材”,图标由插件服务提供,浅色和深色各一份。++## 3. 面板++- 每张图显示:+ - 缩略图、编号、名称;+ - 来源:用户上传、查看的图片、生成的图片或工具返回;+ - 尺寸和大小。+- 状态标签:+ - “不发送”:会换成普通占位符;+ - “由 IMG-xxx 代替”:会换成指向那张图的重复占位符;+ - “与 IMG-xxx 相同”;+ - “模型需要这张”:模型最近一次回复说了“需要 IMG-xxx”,而这张图没勾选;+ - “无法取消”:托管生图的结果。+- 改动先暂存,被改动的行用蓝点标出,底部可以撤销或确定。代理没在运行时,面板会提示取消暂时不会生效。+- 面板每 3 秒刷新一次,新一轮的图会自动出现,滚动位置保持不变。+- 开发页 `spike/scripts/panel-dev.ts` 用合成测试图,在浏览器里扮演 Codex 的侧边面板,用来截图和调试,不会出现在 Codex 里。++## 4. 桌面版实测++测试用 P3-6 那个任务:两张测试图 a.png 和 b.png,a.png 之前被取消,模型当时回复“需要 IMG-002”。++| 步骤 | 结果 |+|---|---|+| 从“插件和 MCP”打开“上下文素材” | 列出 2 张图:b.png 已勾选;a.png(IMG-002)显示“不发送”,并标出“模型需要这张”。缩略图正常,浅色主题正常 |+| 查插件服务日志和任务记录 | 面板读页面、读状态、读缩略图、定时刷新,全部是非模型调用,没有报错;任务记录里没有一条面板调用 |+| 预览 a.png,勾上它,点“确定” | 预览正常;保存成功,a.png 的取消记录清空 |+| 再问 a.png 的背景、形状和角标 | 这次请求带 2 张图,没有替换;模型回答“a.png 是白色背景,中央有一个红色正方形,右下角有一个黑色小方块。” |++这一轮走的是 HTTP。原因是 Codex 启动时,a.png 还没勾上,引擎按设计拒绝了 WebSocket 预连接,这个会话之后就一直用 HTTP。结果不受影响,重启 Codex 后会恢复 WebSocket。++## 5. 顺带修的问题++- **缩略图卡在加载中**:原来缩略图只在“滚动到可见”时才加载。页面不可见或还没绘制时,这个判断不会触发,缩略图就一直卡着。现在改为全部按顺序排队加载,看得见的优先。+- **日志太多**:面板每 3 秒刷新时都会写一行日志。现在只记录勾选变动、模型调用和出错。++## 6. 下一步++- **P5**:打包成插件、写说明,在桌面版上做端到端验证。+- **待定**:spec.md 第 4 节“首版”第 4、6 条要不要做:发送内容预览里的“取消前后请求大小对比”,以及“改写不了时在面板上提示”。+- **已知限制照旧**:+ - Codex 启动的头几十秒里,引擎会来回重启;+ - 取消时如果某一轮正在进行、并且走 WebSocket,这一轮剩下的请求可能仍带着原图;+ - 托管生图的结果不能取消。diff --git a/docs/plan.md b/docs/plan.mdindex e0f2e73..e239ccd 100644--- a/docs/plan.md+++ b/docs/plan.md@@ -269,10 +269,7 @@ P1 通过后,再按用户的节奏一步步探索改写。- 它和引擎之间只通过文件共享状态,任何一方不在,另一方都照常工作。- **不用钩子**:插件服务本来就由 Codex 启动,不用用户批准,比钩子更适合做启动器。- **安装和恢复**:一个命令写好全部带标记的配置(代理地址、`respect_system_proxy`、插件服务,需要时加 `.env`),一个命令全部恢复。-- **界面(P4 再做)**:用户自己打开,不经过模型。候选做法:- - 桌面版右侧侧栏里的 MCP App:已验证能显示,但目前只能由模型打开;- - 紧贴 Codex 窗口右侧的外挂窗口。- - 标题栏按钮要看桌面版是否开放扩展,到时再查。+- **界面**:见第 12 节。做成右侧侧边面板里的 MCP App,用户从“新建标签页 → 插件和 MCP”手动打开(P4 已完成)。### 验证顺序@@ -283,3 +280,32 @@ P1 通过后,再按用户的节奏一步步探索改写。4. P3-4 安装和恢复命令。5. P3-5 稳定性自测:多个任务同时用、历史压缩、引擎中途重启、Codex 退出后引擎自动退出、分叉任务。6. P4 界面,做到关键节点截图给用户看;P5 打包成插件、写说明。++## 12. 面板(P4)++### 已查证的事实++依据桌面版 26.917 的前端代码,以及 P4 实测:++- **不经过模型的入口**:工具可以在 `_meta["openai/ui"].entrypoints` 里声明入口,工具同时要用 `_meta.ui.resourceUri` 指向一个 `ui://` 页面。入口有四种:+ - `thread`:出现在任务右侧侧边面板的“新建标签页 → 插件和 MCP”里;+ - `global`:出现在左侧导航栏;+ - `settings`:出现在设置里;+ - `file`:按扩展名打开文件。+ - 列表里显示的名字是工具的 `title`,图标取自插件服务 `serverInfo.icons`,只收 https 或 data URL,可以分浅色和深色。+- **打开后**:+ - 桌面版先读页面资源,再用当前任务的编号调用这个工具,把结果交给页面。页面之后的工具调用也带着这个任务的编号(`_meta.threadId`)。+ - 这些调用不写进聊天记录,不占模型的上下文(P4 实测:任务记录里没有一条面板调用)。+ - 工具结果的 `_meta` 会原样交给页面,所以图片数据放在 `_meta` 里。+- **主题**:握手时,桌面版会传来主题(light/dark)和一组样式变量,包括颜色和字体,例如 `--color-background-primary`、`--color-text-primary`、`--font-sans`。页面用这些变量,就和 Codex 的外观一致。+- **标题栏**:没有给插件的入口。++### 设计++- **入口工具**:`cam_panel`,标题“上下文素材”,声明 `thread` 入口,页面固定为 `ui://codex-attachment-manager/panel.html`(地址变了可能白屏,见 #47512)。它和其他面板工具一样只给面板用(`visibility: ["app"]`)。+- **页面**:`spike/src/panel.html`,单文件,不联网。+ - 按轮次列出任务历史里的图;缩略图排队加载,看得见的优先;点开后预览大图。+ - 勾选先暂存,点“确定”才调用 `cam_set_selection` 保存。+ - 每 3 秒刷新一次,没有变化就不重画。页面报告自己不可见时降到 15 秒一次,因为有的宿主会误报。+- **取图**:`cam_image`。PNG 超过要求的尺寸就缩小,其他格式原样交给页面,由浏览器缩放。+- **开发页**:`spike/scripts/panel-dev.ts` 在浏览器里扮演 Codex 的侧边面板,用合成测试图调通页面,不用重启 Codex。页面上的“切换明暗”“加一张图”只用来模拟 Codex 的操作,不会出现在 Codex 里。diff --git a/docs/spec.md b/docs/spec.mdindex 0c0fa87..09b7f27 100644--- a/docs/spec.md+++ b/docs/spec.md@@ -45,12 +45,12 @@### 界面-- 位置:优先放在 Codex 对话里;做不到时,做成贴在 Codex 窗口旁、跟着窗口移动和缩放的面板。-- 打开方式:用户自己手动打开,不经过模型,也不花 token;打开后能查看任务历史里的全部文件。入口放在 Codex 标题栏右侧,或者做成紧贴 Codex 窗口右侧的外挂面板(用户 2026-09-24 反馈)。-- 先把核心做完、测稳,再做界面(用户 2026-09-24 决定)。-- 按时间顺序列出出现记录,每条显示缩略图或图标、轮次、来源、大小、重复/版本关系和勾选状态。-- 提供“本轮将发送什么”预览,区分实际发送的素材、重复引用和占位符,并给出预计字节数。预览不得被说成已经发出的请求。-- 明确标出当前是“只读预览”还是“受控发送”。+- 位置:Codex 右侧侧边面板里的一个标签页“上下文素材”。用户在侧边面板的“新建标签页 → 插件和 MCP”里手动打开,不经过模型,也不花 token(P4 实测通过)。Codex 标题栏没有给插件的入口,所以不做外挂窗口。+- 只列这个任务历史里已有的图:用户上传的,和模型在这个任务里查看、生成的。面板不新增素材。+- 按时间顺序、按轮次列出,可以滚动。每条显示缩略图、编号、名称、来源、尺寸、大小、内容相同的关系和勾选状态;点缩略图放大预览。+- 勾选和取消先暂存,点“确定”才保存,从下一条消息起生效。+- 主题、字体和配色跟随 Codex。+- 以上是用户 2026-09-24 定的 MVP。“本轮将发送什么”的完整预览(取消前后的请求大小对比)、改写不了时的提示、“只读预览 / 受控发送”的标识,是否要做,之后再定。### 为后续扩展预留@@ -120,4 +120,4 @@## 5. 待定问题-- 路线:路线 A(用 `thread/inject_items` 在新任务里重建)技术上可行,但用户不接受“重建后在界面上看不到原对话”。代理路线(任务不换,每次请求发出前由本地代理按勾选改写)已在桌面版验证通过:P1 只转发、P2 按勾选改写,生图和改图也包括在内,见 plan.md 第 9、10 节和 p2-report.md。用户 2026-09-24 决定接下来做面板。+- 路线:路线 A(用 `thread/inject_items` 在新任务里重建)技术上可行,但用户不接受“重建后在界面上看不到原对话”。代理路线(任务不换,每次请求发出前由本地代理按勾选改写)已在桌面版验证通过:P1 只转发、P2 按勾选改写,生图和改图也包括在内,见 plan.md 第 9、10 节和 p2-report.md。面板已在 P4 做完,见 p4-report.md。diff --git a/docs/tasks.md b/docs/tasks.mdindex 978a783..90137db 100644--- a/docs/tasks.md+++ b/docs/tasks.md@@ -2,9 +2,26 @@> 方法见 [plan.md](plan.md)。按顺序做,完成一项勾一项,并写明证据放在哪里。-## 当前:核心完善 P3(先做核心、测稳,界面放到 P4)+## 当前:界面 P4(已完成),打包 P5++设计见 plan.md 第 12 节,结果见 `docs/p4-report.md`。测试时调用模型一律用 `gpt-6-sol`,推理强度 `low`。++- [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 个)+ - 按轮次列出任务历史里的图片,缩略图、编号、名称、来源、尺寸、大小;点缩略图放大预览;勾选先暂存,点“确定”才保存。+ - 标出“不发送”、“由 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 条),做不做、什么时候做,之后再定。++----设计见 plan.md 第 11 节,验收标准见 spec.md 第 4 节“首版”。测试时调用模型一律用 `gpt-6-sol`,推理强度 `low`。+## 已完成:核心完善 P3++设计见 plan.md 第 11 节,验收标准见 spec.md 第 4 节“首版”。- [x] **P3-1 试验面板**【需用户】(2026-09-24 通过;证据:`local/p3/panel-probe.jsonl`、用户截图;结果见 plan.md 第 11 节)- 面板能在桌面版右侧侧栏显示;握手、回调、data URL 小图都正常;访问 `localhost` 被拦截。@@ -18,9 +35,6 @@- `cam.ts install` 后,重启 Codex,插件服务自动拉起引擎;取消 a.png 后,下一轮被改写,模型回复“需要 IMG-002”。- 两种退出都实测过:安装时启动的引擎,在 Codex 关闭后自己退出;插件服务拉起的引擎,随 Codex 一起结束。- Codex 启动的头 40 秒里,引擎来回重启了 4 次(已知限制),当时没有对话,没有影响。-- [ ] **P4 界面**【需用户】:用户自己打开,不经过模型;关键节点截图给用户看,等反馈。-- [ ] **P5 打包成插件、写说明,桌面版端到端验证**【需用户】。----## 已完成:代理验证 P2(按勾选改写)