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(phase0): 阶段 0 技术验证报告
chipfighterf97aea722a89
diff --git a/docs/phase0-report.md b/docs/phase0-report.mdnew file mode 100644index 0000000..2fe75cc--- /dev/null+++ b/docs/phase0-report.md@@ -0,0 +1,102 @@+# 阶段 0 技术验证报告++> 2026-09-24。T0–T2 由 Codex 执行,T3–T10 由 Claude 执行。本报告只写统计和必要的简短摘录,不含原任务的对话原文、图片和本机路径。详细证据都在本机被 git 忽略的 `local/` 目录里(见 [tasks.md](tasks.md) 各项的证据说明)。+> 验收关卡见 [spec.md](spec.md) 第 4 节,方法见 [plan.md](plan.md)。++## 1. 结论++- 关卡 1、3、4、5、6 已通过;关卡 3 的改图画面已由 Claude 对照原图核对,还需要用户确认。+- 关卡 2(桌面版里能看到、能继续、重启后能恢复)需要用户操作,尚未完成。+- 按 plan 的选择规则:如果关卡 2 通过,路线 A(用 `thread/inject_items` 重建)就作为首版主方案。+- 效果:重建后第一轮请求约 7.0 MB,是原来 43.8 MB 的 16%;重新勾选第三张图后约 10 MB,是原来的 23%。没勾选的 7 张图一次也没有被发送。++## 2. 环境++| 项目 | 版本 |+|---|---|+| 系统 | Windows 11 |+| Codex 桌面版 | 26.917.6896.0(MSIX) |+| 桌面版自带的 CLI | `codex-cli 0.155.0-alpha.16`(位于 `%LOCALAPPDATA%\OpenAI\Codex\bin\<hash>\`) |+| Node | 24.14.0(直接运行 TypeScript,无外部依赖) |+| 模型 | 沿用样本任务的模型,推理强度 medium |++T3–T9 期间桌面版没有运行,我们启动的 app-server 是唯一写入 `~/.codex` 的进程。所以“桌面版开着时会不会冲突”这次没有观察到(见第 7 节)。++## 3. 样本与根因++- **记录格式**:样本是分页格式的记录(`history_mode = paginated`)。+ - 每个记录文件是一个分段,首行的 `history_base` 指向“上一个分段截到哪个字节”。+ - 原任务有 7 个分段,其中 5 段是用户对同一条“带 4 张图”的消息的重试,每次重试都从失败那条消息之前重新接上。+ - fork 有 2 个分段,继承原任务第 531 条记录之前的全部内容。+- **素材**:共 38 条图片出现记录,归并为 10 份素材,没有无法识别的项。原任务里有 10 份不同的图;fork 的 4 张都能和原任务匹配。+- **日志里的真实请求大小**(`pre_compression_bytes`):+ - 原任务:请求一直在 30.2–30.45 MB 之间;加入 4 张图后变成 43.77 MB,此后每约 5 分钟重试一次,始终失败。+ - fork:第一个请求就有 30.49 MB。它虽然没有新图,但继承了原任务前面各轮的 10 张图。之后模型在一段脚本里同时调用 4 次看图,又带进 13.3 MB,请求变成 43.81 MB 并卡住。+ - 失败过程:WebSocket 连续 5 次“请求未完成就被服务端关闭”,回退到 HTTP,然后大请求反复失败。+- **图片占比**:图片占请求字节的 96%–97.5%。++## 4. 测量方法与校准++WebSocket 请求不会记录大小,所以新任务的请求大小用这个方法得出:按分页记录还原出模型可见的历史,计算序列化后的字节数。这个方法先用样本在日志里的真实数值校准过:++| 校准点 | 日志中的真实大小 | 还原结果 | 比值 |+|---|---:|---:|---:|+| fork 第 17 轮第一次请求 | 30,489,144 | 30,749,353 | 1.0085 |+| fork 看图工具返回之后 | 43,807,814 | 44,068,099 | 1.0059 |+| 原任务最后一次重试 | 43,772,927 | 44,039,886 | 1.0061 |++误差在 1% 以内,远小于 spec 要求的 ±20%。++## 5. 关卡结果++| 关卡 | 结果 | 依据 |+|---|---|---|+| 1 只读导入 | 通过 | 38 条出现记录、10 份素材、0 条无法识别;9 个样本记录文件和 10 个素材原件,从 T1 到 T9 结束哈希都没有变化 |+| 2 可见、可续 | 待用户 | 见第 8 节第 1 条 |+| 3 能继续改图 | 通过,待用户确认画面 | 重新勾选:IMG-005 下一轮作为附件带上,模型对天色、主体、车辆的描述与原图一致。改图:按编号让模型用内置生图把 IMG-008 改成黄昏,生成图的构图、步道、长椅都和 IMG-008 一致(最近一次附带的是 IMG-005,改图工具仍取了 IMG-008) |+| 4 未选不发送 | 通过 | 新任务历史里的全部内联图片按哈希核对,只有 IMG-004、IMG-008、IMG-005 和一张新生成的图,从没选过的 7 张一次都没出现 |+| 5 请求变小 | 通过 | 估算“注入文字 61.6 KB + 两张选中图 6.94 MB = 7.00 MB”,实测 7.04 MB(+0.6%),是基线的 16.1% |+| 6 占位符有效 | 通过 | 问 IMG-003 的画面细节,模型只回答“需要 IMG-003。”,没有编造,也没有调用任何工具 |++## 6. 各轮测试数据++| 轮次 | 附件 | 历史字节 | 输入 token(其中缓存) | 耗时 | 工具 |+|---|---|---:|---:|---:|---|+| 1 首轮 | IMG-004、IMG-008 | 7,044,437 | 39,881(12,800) | 17.7 s | 无 |+| 2 占位符 | 无 | 7,059,712 | 43,236(39,424) | 37.3 s | 无 |+| 3 重新勾选 | IMG-005 | 9,950,728 | 45,601(43,008) | 115.1 s | 无 |+| 4 改图 | 无(按编号引用 IMG-008) | 9,953,600 | 52,630(50,304) | 425.4 s | 读 imagegen 说明、生图 |++- **注入内容**:原任务的 18 轮被转成 58 条注入条目,共 61.6 KB。其中 1 条 developer 说明(规则和素材表)、18 条用户消息、39 条助手消息(含 10 条工具记录)。+- **占位符**:8 个“未提供”、2 个“已作为附件提供”,另有 4 条“同一素材”引用。+- **路径**:注入文字里没有任何本地绝对路径。++## 7. 附加实验(T9)++- **a. 关掉 `view_image`**:给模型一张本地图片的路径,它改用内置 `node_repl` 的 `js` 工具打开了图片,并正确描述了天色(已对照原图)。关掉看图工具挡不住模型看图;真正起作用的是关卡 6 验证过的“占位符 + 按编号索要”约定。+- **b. MCP 调用携带的信息**:只在我们启动的 app-server 进程上,用 `-c` 临时挂了一个 stdio 测试服务。每次 `tools/call` 的 `_meta` 都带有 `threadId`、`sessionId`,以及 `x-codex-turn-metadata`(其中有 thread_id、turn_id、模型、沙箱模式、Codex 版本)。所以插件能自动知道是哪个任务在调用它。另外,自定义 MCP 工具默认需要审批,把 `default_tools_approval_mode` 设为 `approve` 后才能直接调用。+- **c. 路线 B 交接包**:生成了一份 57 KB 的“交接说明.md”和选中图片的副本。手动继续需要 3 步:新建任务、附上说明和图片、让 Codex 先读说明。因为路线 A 已经通过,这条路线没有再跑模型做端到端验证。++## 8. 发现的问题与风险++1. **重建任务在界面上看不到原对话**:注入的历史只存在于模型可见的上下文里,界面层只显示新发的几轮。模型记得原来的内容,但用户在桌面版里看不到。+2. **新产生的图片会重新堆积**:改图生成的图(2.67 MB)同样以内联形式写进了新任务的历史,下一轮请求会涨到约 13.5 MB。首版需要把生成图和看图工具看过的图都纳入素材,在历史变大时提示重建。+3. **Codex 会缩放大图**:IMG-002 原图是 2400×6100,发送时被缩成 806×2048,按内容哈希对不上原文件。对用户上传的图,改用同一条消息里记录的路径来定位;附件则用记录里那一份的缓存。+4. **修掉的 bug**:多个看图调用并行时,按事件顺序给图片配路径会配错。已改为按内容哈希归属,并加了回归测试(改回旧逻辑时测试会失败)。+5. **没有观察到并发**:本次桌面版没有运行,“桌面版开着时由另一个 app-server 创建任务”的写锁冲突风险要在关卡 2 或首版里观察。+6. **版本敏感**:结论基于 0.155.0-alpha.16。上游正在推进图片按 `file_id` 引用(见 plan),更新后要按 plan 的止损点复测。+7. **没做类型检查**:本机没有安装 TypeScript 编译器,脚本由 Node 直接去掉类型后运行,没有做类型检查。7 个单元测试全部通过。++## 9. 路线建议++按 plan 第 2 节的规则:关卡 1、3、4、5、6 已通过;关卡 2 通过的话,首版采用路线 A;关卡 2 失败的话,改用路线 B,路线 A 留作研究。++## 10. 需要用户决定的事项++1. **完成关卡 2**:在桌面版里找到 `[CAM测试]` 开头的任务,打开,发一句话继续对话,然后重启桌面版,确认任务还在、还能继续。顺便看一眼第 4 轮生成的黄昏图(关卡 3)。+2. **界面上看不到原对话能否接受**(第 8 节第 1 条)。可选做法:+ - 接受,由我们的面板展示完整时间线;+ - 重建时在第一轮附一段可见的摘要;+ - 两者都做。+3. **生成图重新堆积的处理**(第 8 节第 2 条):建议在历史超过某个阈值(例如 20 MB)时,面板提示“重建并去掉不需要的图”。阈值需要用户定。+4. **关卡 2 通过后**,是否按路线 A 重写 plan 的第 2 节,并拆出首版任务。diff --git a/docs/tasks.md b/docs/tasks.mdindex 7bf57b8..5771d64 100644--- a/docs/tasks.md+++ b/docs/tasks.md@@ -67,7 +67,7 @@- b. 如果能通过配置覆盖临时挂一个测试用的 stdio MCP 服务,记录它收到的调用里 `_meta` 有哪些内容。做不到就跳过,不要为此修改用户配置。- c. 生成一份路线 B 的交接包,记录手动继续需要哪些步骤、体验如何。-- [ ] **T10 报告**+- [x] **T10 报告**(`docs/phase0-report.md`;关卡 2 的结果待用户完成 T5 后补上)- 写 `docs/phase0-report.md`,内容包括:- 环境和版本;- 每个关卡的结果(通过或失败)和证据;