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(v0.4): 写回 Claude 面板方案:同一份 panel.html 由引擎提供,/cam 在 Claude 桌面自带浏览器里打开

chipfighter46d12a211136
diff --git a/docs/v0.4/acceptance.md b/docs/v0.4/acceptance.md
index c240236..266bfbe 100644
--- a/docs/v0.4/acceptance.md
+++ b/docs/v0.4/acceptance.md
@@ -47,7 +47,7 @@ G04-1 只记录前置子集通过,不提前勾整项 A04-04;正式模型行
## A04-06 桌面内面板(前置关卡)
-在真实 Code 界面中显示多张真实缩略图,能放大预览、单张勾选、保存与当前会话对应,操作无需模型参与。面板入口可由用户直接打开,不要求模型帮忙打开。先验 MCP 应用路线,不能再验 Mod 面板。
+在真实 Code 界面中显示多张真实缩略图,能放大预览、单张勾选、保存与当前会话对应,操作无需模型参与。用户自己输入 `/cam`,面板在 Claude 桌面自带的浏览器里打开,不要求模型帮忙打开(D04-04)。
接口声明、示意图、终端界面或外部浏览器开发页均不能替代桌面内验收。关键节点由 Claude 截图检查并交用户反馈,反馈未解决时不勾完成。
@@ -55,7 +55,7 @@ G04-1 只记录前置子集通过,不提前勾整项 A04-04;正式模型行
按现行规格逐项检查:整轮勾选、来源筛选、编号定位、发送预览/上一次实际统计、任务名、自动刷新、预览、启停、主题和中英文文字。
-筛选只影响显示;整轮选择只作用于该轮显示项;跳转隐藏项时按现行规则显示和定位。预估明确标为预估,不把请求大小或图片数量等同于已节省的模型 token。实际无法改写时在面板提示原因。走 Mod 面板时做不到的项,先列给用户确认,未确认不算通过。
+筛选只影响显示;整轮选择只作用于该轮显示项;跳转隐藏项时按现行规则显示和定位。预估明确标为预估,不把请求大小或图片数量等同于已节省的模型 token。实际无法改写时在面板提示原因。
## A04-08 自动选图
diff --git a/docs/v0.4/plan.md b/docs/v0.4/plan.md
index b037970..87eda7d 100644
--- a/docs/v0.4/plan.md
+++ b/docs/v0.4/plan.md
@@ -16,7 +16,7 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
| --- | --- |
| 本机引擎改写请求,同一个任务,历史不动 | 同一个引擎增加 `/v1/messages` 转发,上游固定为 `api.anthropic.com` |
| `config.toml` 里带标记的 `openai_base_url` | 平台逼迫:桌面版不认 settings 里的地址,由插件里的 Mod 用 `$.env.set` 切换(D04-01) |
-| 插件的 MCP 服务拉起、看守引擎,给面板提供数据 | Claude 插件同样带这个 MCP 服务;Mod 只负责切地址(D04-01、D04-06) |
+| 插件的 MCP 服务拉起、看守引擎,给面板提供数据 | Claude 插件同样带这个 MCP 服务拉起、看守引擎;面板的数据改由引擎的本机接口提供(D04-04);Mod 负责切地址和 `/cam`(D04-01、D04-04) |
| 请求头 `x-codex-turn-metadata` 认出任务 | 请求头 `x-claude-code-session-id`(D04-02) |
| 从本地记录只读编号,只追加;引擎和插件服务各自计算,不共享状态 | 从 Claude Code 的本地会话记录只读编号,做法相同(D04-02) |
| 按条目 `id` 对齐请求和记录,没有就用 `call_id`,再没有就用类型、轮次和内容哈希 | 消息块没有 `id`:工具图用 `tool_use_id`,用户图用最后一档(D04-02) |
@@ -24,7 +24,7 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
| “上下文管理说明”开发者消息,插在第一张被省略的图所在那一轮的用户消息之前 | 平台逼迫:改用 `role: "system"` 消息,放在那条用户消息之后(D04-03) |
| WebSocket 握手回 426,让 Codex 改走 HTTP | 不需要:Claude Code 本来就走 HTTP 和 SSE |
| 改写不了就原样发送,面板提示原因 | 照搬;思考签名被拒时也按这条处理(D04-03) |
-| 面板是 MCP 应用,用户自己打开,不经过模型 | 先验证 Claude 桌面 Code 能否由用户打开插件的 MCP 应用;不能再退到 Mod 面板(D04-04) |
+| 面板是 MCP 应用,用户自己打开,不经过模型 | 平台逼迫:用户打不开插件的 MCP 应用,Mod 面板放不进网页。同一份 `panel.html` 改由引擎作为本机页面提供,用户输入 `/cam` 后在 Claude 桌面自带的浏览器里打开,仍不经过模型(D04-04) |
| 自动选图:`cam_view_image` 按编号取图,取回的图放在本轮末尾,副本下一轮换成说明 | 照搬,取图工具由同一个 MCP 服务提供(D04-05) |
本轮不扩大素材范围:原生 PDF/document、音频、视频和普通文本文件不因为换客户端就自动进入管理范围。工具渲染出的图片仍按图片处理。暂不增加其他模型供应商、云端会话、跨会话素材库或新的常驻系统服务。
@@ -40,6 +40,8 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
- 用户实际执行开启、发送消息、关闭命令,并确认了可见回复和恢复提示。
- 本机探针的透明转发、认证头、SSE、取消和恢复共 9 项回归测试通过;桌面自带命令行校验实际安装副本通过。这些是实验工具证据,不是正式 v0.4 功能验收。
- 只写 `enabledPlugins` 不完成安装;必须实际登记并安装插件,再加载到目标会话。首次命令缺失由漏安装造成,补安装后已解决。
+- 面板(2026-10-10 桌面实测):Mod 面板只能画 Claude 自带的元素,放不进网页;Claude Code 不登记只给应用调用的工具,用户打不开插件的 MCP 应用。Mod 面板里的链接,点开交给系统默认浏览器。Mod 用 `$.mcp.call("Claude_Browser", "preview_start", { url })` 能在桌面自带的浏览器里打开本机页面,默认权限模式下也不弹确认;这是桌面版给模型用的工具,不是公开给插件的接口,终端和 VS Code 里没有。
+- 桌面版的新会话,发出第一条输入时才启动 Claude Code 进程。Mod 注册的命令在那之前不在输入框的命令列表里:输入时提示命令不存在,发出后照常执行。插件自带的命令文件一律带插件名前缀(`/codex-attachment-manager:cam`)。
私有实验记录位于验证机的 `local/claude-live-routing/`;不得把原始记录、凭据、图片或本机路径复制到提交中。仓库只保留上述脱敏结论和实验方法。该目录被忽略,克隆仓库后无需存在。
@@ -50,7 +52,6 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
- 桌面启动的环境变量过滤,与 Mod 运行时设置是不同入口;正式生命周期是否一直保持有效,不能从一次文本请求推断。
- **思考签名**:Fable 5.1、Opus 5.5、Sonnet 5.5、Haiku 5.5 做前缀校验。替换历史里的一张图、缩短一个工具结果,或增删 `tools` 里的工具,都会让之后所有的思考块失效。2026-08-31 起注册的账号默认返回 400;更早的账号照样校验,但放行给模型。加 beta 头 `thinking-binding-controls-2026-08-01` 并设 `thinking.block_binding.prefix_mismatch_behavior: "error"`,老账号也按新账号拒绝,可用于实验;只加 beta 头、不设该字段,响应会列出放行的失效块。文档明说代理自己的改写也算编辑。服务端上下文编辑只能按规则清掉最早的工具结果,不能指定某张图,也碰不到用户消息里的图。待实测:订阅链路是否接受该 beta 头,Claude Code 收到 400 后怎么处理,用户自己的账号是哪一种。
- **说明消息的位置**:对话中途可以放 `role: "system"` 消息,不需要 beta 头,但它必须紧跟在用户消息之后,后面是助手消息或已是最后一条。所以 Codex 的位置(那一轮用户消息之前)在 Claude 上不合法。待实测:订阅链路是否接受,Claude 模型的效果。
-- **桌面面板**:桌面版 Mod 能用的元素只有 Box、Text、Button、Input、Select、Svg、Link、Code、Markdown、Client;`Image`、`Raster` 只在终端,`Client` 模块也画不了图。Mod 面板要显示缩略图,只能把图内嵌在 Svg 里(单个上限 131072 字符,标记会被清洗,是否保留内嵌图未知),大图预览放不下。Claude 桌面 Code 能否由用户直接打开插件的 MCP 应用,未知。
- `turn.step` 只能改模型和推理强度,不是历史消息改写接口,不能替代请求改写引擎。
### 2.3 尚未通过
@@ -73,7 +74,7 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
### D04-01 接入与透明转发
-沿用已验证的会话内 Mod 接入路径:先确认本机引擎就绪,再切换当前 Code 进程地址;保存原值,停用时恢复。Mod 只负责切地址这一件事。只绑定本机地址,保留系统代理和用户已有的 `NO_PROXY` 设置。引擎就是现有引擎,增加 `/v1/messages` 转发,固定官方 Anthropic 上游,不提供任意目的地转发。
+沿用已验证的会话内 Mod 接入路径:先确认本机引擎就绪,再切换当前 Code 进程地址;保存原值,停用时恢复。Mod 负责切地址,以及 `/cam` 打开面板(D04-04)。只绑定本机地址,保留系统代理和用户已有的 `NO_PROXY` 设置。引擎就是现有引擎,增加 `/v1/messages` 转发,固定官方 Anthropic 上游,不提供任意目的地转发。
照原机制,由插件的 MCP 服务拉起并看守引擎(见 design.md 第 5 节)。Codex 与 Claude 共用这个引擎,引擎的退出条件和替换规则改为同时考虑两边(现在只看有没有 Codex 进程)。OAuth、版本、beta 和会话相关请求头需要透传,认证值不得进入日志。查询串、错误响应和 SSE 都须保留;客户端取消时关闭上游请求。正文无需改写时保留原始字节。MCP 服务在 Claude 下的 Node 运行环境在 T04-03 中确定,不把实验端口或本机安装路径写死进正式安装包。
@@ -95,9 +96,11 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
### D04-04 面板与业务规则复用
-照原机制,面板是插件 MCP 服务提供的 MCP 应用,用户自己打开,不经过模型。先验证 Claude 桌面 Code 能否由用户直接打开插件的 MCP 应用:能,就复用 `panel.html` 和面板数据,只隔离 Codex 特有的宿主握手、任务元数据、主题与工具权限;不能,才退到 Mod 面板,缩略图内嵌在 Svg 里,做不到的 v0.3 行为先列给用户确认。
+面板与 Codex 一致(用户 2026-10-10 要求):复用同一份 `panel.html` 和面板数据,用户自己打开,不经过模型。平台逼迫的改动(见 2.1):用户打不开插件的 MCP 应用,Mod 面板放不进网页,所以由引擎在本机提供面板页(`/__cam/panel?session=<会话 id>`),页面前加一段桥接脚本代替 MCP 应用宿主,把面板的调用转成引擎的本机接口;Codex 特有的启用、停用和新任务绑定不出现。页面和接口只接受用本机名字访问、不来自其他网站的请求。
-复用候选包括选择状态、图片指纹、重复关系、缩略图处理、编号识别和面板数据字段。先做单图,再做多图的桌面内面板实验,验证缩略图、放大预览、勾选、状态保存与当前会话绑定。浏览器开发页可调试,但不能作为桌面内交付验收的替代。关键界面节点按 AGENTS.md 截图给用户,等待反馈后继续界面开发。
+用户输入 `/cam`,面板就在 Claude 桌面自带的浏览器里打开,在对话旁边(用户 2026-10-10 选定)。只有两种情况弹出 Mod 小面板:自带浏览器打不开(终端、VS Code 或调用失败)时,给出面板链接和复制按钮;本会话的请求没经过引擎、勾选不会生效时,提醒用户。新会话的第一条输入就是 `/cam` 时,输入框会提示命令不存在,发出后照常打开;保持现状,在用户文档里写明(用户 2026-10-10 定)。
+
+复用候选包括选择状态、图片指纹、重复关系、缩略图处理、编号识别和面板数据字段。先做单图,再做多图的桌面内面板实验,验证缩略图、放大预览、勾选、状态保存与当前会话绑定。验收在 Claude 桌面里用 `/cam` 打开的面板上做;在外部浏览器里打开同一页面只用于调试。关键界面节点按 AGENTS.md 截图给用户,等待反馈后继续界面开发。
### D04-05 自动取图
@@ -107,7 +110,7 @@ v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独
### D04-06 安装、恢复与回归
-Claude 插件入口与 Codex 入口分别安装;只提取确实需要共享的规则,不先重构为通用供应商框架。Claude 插件的内容是 MCP 服务(与 Codex 共用 `plugin/src` 的运行代码)加一个只切地址的 Mod。运行代码在 `plugin/src`,测试与实验在 `spike`,安装脚本在 `scripts`;Claude 插件的目录与清单由 T04-03 确定。
+Claude 插件入口与 Codex 入口分别安装;只提取确实需要共享的规则,不先重构为通用供应商框架。Claude 插件的内容是 MCP 服务(与 Codex 共用 `plugin/src` 的运行代码)加一个 Mod(切地址、`/cam` 打开面板)。运行代码在 `plugin/src`,测试与实验在 `spike`,安装脚本在 `scripts`;Claude 插件的目录与清单由 T04-03 确定。
安装必须校验实际安装副本和目标会话加载,不能只写启用配置。恢复只影响工具自管的地址/设置,不覆盖用户的其他配置。验证卸载、重载、桌面重启、引擎失败、登录刷新和版本更新;不新增系统计划任务等常驻机制。
@@ -118,7 +121,7 @@ Codex 现有自测、安装和卸载保持可用;共享运行代码变化后
| 关卡 | 进入条件 | 工作 | 退出条件 |
| --- | --- | --- | --- |
| G04-0 路由入口 | 真实桌面官方订阅 | 最小透明转发实验 | 已通过 T04-00;仅证明入口 |
-| G04-1 核心可行性 | G04-0;T04-01 用 Haiku 5.5(用户 2026-10-10 定),运行次数在开始前与用户确认 | T04-02 面板实验(先 MCP 应用,后 Mod),T04-01 图片/思考闭环及最小取回副本实验 | A04-04 的前置子集及面板实验有实测证据;界面经用户反馈;没有未确认的降级 |
+| G04-1 核心可行性 | G04-0;T04-01 用 Haiku 5.5(用户 2026-10-10 定),运行次数在开始前与用户确认 | T04-02 面板实验(面板形式见 D04-04),T04-01 图片/思考闭环及最小取回副本实验 | A04-04 的前置子集及面板实验有实测证据;界面经用户反馈;没有未确认的降级 |
| G04-2 正式适配 | G04-1 通过,规格维护者将目标与采用方案写回现有文档 | T04-03–T04-07 | 手动模式与完整面板通过对应验收 |
| G04-3 自动模式 | 手动模式稳定;核心关卡覆盖取图副本 | T04-08 | 自动取图语义和模型行为通过 |
| G04-4 交付 | 前述功能通过 | T04-09–T04-11 | 全部验收、回归、安装检查通过,用户确认后再发布 |
@@ -136,7 +139,7 @@ G04-1 任一核心能力失败时,不跳过关卡开发完整面板或宣称 v
## 7. 开始正式实现前需确定
-1. G04-1 的实测结论:订阅链路下账号放行还是拒绝、被拒后原样重发能否接上;`role: "system"` 说明的效果;面板走 MCP 应用还是 Mod。
+1. G04-1 的实测结论:订阅链路下账号放行还是拒绝、被拒后原样重发能否接上;`role: "system"` 说明的效果。
2. 正式专项验收的模型范围与成本上限(G04-1 用 Haiku 5.5),以及要覆盖的账号差异(2026-08-31 前后注册)。
3. Claude 插件的目录与清单,以及 MCP 服务在 Claude 下的 Node 运行环境;启动方式照原机制。
4. 规格维护者将确认内容同步到现行 spec/design,保留唯一事实来源。
diff --git a/docs/v0.4/tasks.md b/docs/v0.4/tasks.md
index 625cbef..f65e856 100644
--- a/docs/v0.4/tasks.md
+++ b/docs/v0.4/tasks.md
@@ -27,9 +27,8 @@
- 证据:本机脱敏请求差异、回应状态、只读检查、合成图的模型回答;失败时保存根因与选项。
- [ ] **T04-02 桌面内缩略图面板实验**。依赖 T04-00,可与 T04-01 并行。
- - 先试 MCP 应用:做最小 Claude 插件,由 MCP 服务提供面板(从现有 `cam_panel` 改),验证用户能否在桌面 Code 里自己打开、能否显示缩略图和放大预览。
- - 不行再试 Mod 面板:缩略图内嵌在 Svg 里,核对清洗后内嵌图是否保留、多张时的总量限制;与 v0.3 面板相比做不到的地方,列给用户确认。
- - 在真实 Code 中先显示一张、再显示多张合成图;验证缩略图、单张勾选、放大预览、保存和当前会话绑定,不通过模型执行操作。浏览器页只用于调试,不计桌面验收。
+ - 面板形式见 plan.md 的 D04-04(用户 2026-10-10 定):同一份 `panel.html` 由引擎在本机提供,`/cam` 在 Claude 桌面自带的浏览器里打开。
+ - 在真实 Code 中先显示一张、再显示多张合成图;验证缩略图、单张勾选、放大预览、保存和当前会话绑定,不通过模型执行操作。在外部浏览器打开同一页面只用于调试,不计桌面验收。
- 关联:R04-04;A04-06。
- 证据:Claude 自行检查截图;关键节点截图给用户,按现有规矩等待反馈。
@@ -43,7 +42,7 @@
## G04-2:正式手动模式
- [ ] **T04-03 Claude 接入与运行入口**。依赖 T04-02a。
- - 照原机制:Claude 插件带 MCP 服务(与 Codex 共用 `plugin/src`),由它拉起并看守引擎;Mod 只负责切地址,先确认引擎就绪再切,保存并恢复原值。确定 Claude 插件的目录与清单、MCP 服务在 Claude 下的 Node 运行环境和安装副本检查。
+ - 照原机制:Claude 插件带 MCP 服务(与 Codex 共用 `plugin/src`),由它拉起并看守引擎;Mod 负责切地址(先确认引擎就绪再切,保存并恢复原值)和 `/cam`。确定 Claude 插件的目录与清单、MCP 服务在 Claude 下的 Node 运行环境和安装副本检查。
- Codex 和 Claude 共用一个引擎:现在引擎在没有 Codex 进程时自己退出(`engine.ts` 的 `watchForCodex`),要改成两边都不在用时才退出;替换规则要避免两份插件副本版本相同、代码不同时来回让对方的引擎退役。改的是共用代码,改完重新 `cam install`,确认 Codex 照常能连上。
- 覆盖 HTTP 查询、认证、系统代理、SSE、上游错误、取消;无改写路径保持原始正文。
- 关联:R04-01、R04-07;A04-01、A04-02、A04-10、A04-11。
@@ -69,7 +68,7 @@
- [ ] **T04-07 完整手动面板**。依赖 T04-02、T04-04、T04-05。
- 接入完整列表、预览、整轮勾选、来源筛选、发送预估/实际统计、需要编号定位、任务名、刷新、启停、主题和双语。
- - 逐项引用现行 v0.3 的行为;筛选不改变发送,整轮选择按显示项处理。走 MCP 应用时复用 `panel.html`;走 Mod 面板时,做不到的项先列给用户确认。
+ - 逐项引用现行 v0.3 的行为;筛选不改变发送,整轮选择按显示项处理。复用 `panel.html`(D04-04)。
- 关联:R04-04、R04-06;A04-06、A04-07。
- 证据:交互检查、双语截图、用户在关键节点的反馈;接口差异与降级不能隐瞒。