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(phase0): 阶段 0 技术验证报告

chipfighterf97aea722a89
diff --git a/docs/phase0-report.md b/docs/phase0-report.md
new file mode 100644
index 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.md
index 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`,内容包括:
- 环境和版本;
- 每个关卡的结果(通过或失败)和证据;