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: 改为验证代理路线;记录免配置、按任务区分勾选、config.toml 授权
chipfighterb941e4df540c
diff --git a/docs/plan.md b/docs/plan.mdindex 9ce771d..91571c8 100644--- a/docs/plan.md+++ b/docs/plan.md@@ -1,6 +1,6 @@-# 技术方案:阶段 0 验证设计+# 技术方案-> 目标、约束和验收关卡以 [spec.md](spec.md) 为准。本文件说明怎么做、为什么这样做。阶段 0 结束后,按报告重写第 2 节,并补上首版架构。+> 目标、约束和验收关卡以 [spec.md](spec.md) 为准。本文件说明怎么做、为什么这样做。第 1–8 节是阶段 0 的设计(已完成,结果见 [phase0-report.md](phase0-report.md));第 9 节是正在验证的代理路线。## 1. 已知事实(2026-09-24)@@ -47,6 +47,8 @@### 怎么选+> 阶段 0 结果:关卡 1–6 全部通过,路线 A 在技术上可行。但用户不接受“重建后在界面上看不到原对话”,所以没有采用,改为验证代理路线(第 9 节)。以下是阶段 0 当时的规则。+- spec 阶段 0 的关卡 1–6 全部通过:路线 A 作为首版主方案。- 关卡 2 或 3 失败:首版改用路线 B,路线 A 留作研究。- 关卡 4 或 5 失败:先当实现问题排查。如果确认是结构性原因(例如 app-server 会自动带回未选的图片),改用路线 B。@@ -100,10 +102,48 @@| 路线 A 优先于只交接摘要 | 保留完整的对话文字,连续性更好 || 只搬文字和占位符,不搬 reasoning 和工具记录 | 加密条目和调用配对不可靠,工具记录还可能夹带大块内容 || 选中的图作为下一轮的附件发送 | 一套机制同时覆盖勾选和重新勾选,也贴近改图工具的取图方式 |+| 改为验证代理路线 | 用户要求在同一个任务里勾选、取消文件时对话连续可见,重建路线做不到 || 面板优先放进 Codex 对话(MCP Apps),做不到再做跟随窗口的外置面板 | 用户 2026-09-24 决定;对话内卡片在 Windows 上仍有渲染问题,需要先验证 || 首版只做单个任务、只做图片 | 全量扫描很重;图片是当前的痛点 || 用 TypeScript/Node | 验证机已有 Node 24;能生成官方协议类型;面板也用同一种语言 |## 8. 阶段 0 之后-根据 `docs/phase0-report.md` 重写第 2 节,并补上首版架构,大致包括:索引器、素材缓存、重建服务、本地网页面板、skill 和插件打包。首版的任务另行写进 tasks.md。+路线由第 9 节的验证结果决定,定下来之后再补首版架构和首版任务。++## 9. 代理路线(验证中)++### 思路++在 Codex 和 OpenAI 之间放一个只在本机监听的代理。++1. Codex 照常把完整请求发给代理;+2. 代理按这个任务当前的勾选,把没选的图换成占位符,再转发出去;+3. 回复原路返回,由 Codex 照常记进同一个任务。++任务不换,历史和界面都不动,勾选和取消从下一次请求起生效。++### 接入方式(已查证)++- **地址覆盖**:`config.toml` 顶层的 `openai_base_url` 可以覆盖内置 openai 通道的地址,ChatGPT 登录模式下同样生效。改了地址后,任务的归属仍然是 openai。+- **路径后缀**:地址必须以 `/backend-api/codex` 结尾,否则 Codex 会关掉后端专用的接口。所以代理地址用 `http://127.0.0.1:<端口>/backend-api/codex`,代理再把同样的路径转发到 `https://chatgpt.com`。+- **经过的接口**:对话走 `…/responses`,默认用 WebSocket,失败时回退到 HTTP;生图、改图走同一个通道的 `…/images/generations` 和 `…/images/edits`。+- **认出任务**:每个请求的请求头里都有 `x-codex-turn-metadata`(其中有 thread_id、turn_id),请求体里还有 `prompt_cache_key`,代理据此认出请求属于哪个任务。+- **系统代理**:验证机开着系统代理,而且 `127.0.0.1` 在 `NO_PROXY` 里。我们的代理往外连 chatgpt.com 时,自动沿用系统代理设置(环境变量或 Windows 设置),不需要用户填写。++### P1:只转发、不改写++- **转发**:原样转发 HTTP 请求和 WebSocket 连接,不改动任何字节,结果按流式返回。+- **日志**:只记元数据,包括方法、路径、状态码、字节数、耗时、任务 ID,以及请求里的图片数量和字节数。不记认证信息,也不记对话内容。+- **配置**:+ - 工具在 `config.toml` 顶层插入一段带标记的设置;+ - 改之前把原文件备份到 `local/`;+ - 恢复时只删掉这一段,其余内容逐字节不变;+ - 如果用户自己已经设了 `openai_base_url`,不覆盖,直接报告。+- **验证顺序**:+ 1. 先用我们自己启动的 app-server 走一遍:文字、附图、生图、改图。这一步用 `-c openai_base_url=…` 指定地址,不改配置。+ 2. 再改桌面版的配置。用户重启桌面版后,在任务里依次发文字、上传图片、让它生图、让它改图。+ 3. 看代理日志,确认这些请求都经过了代理并且成功,不同任务的请求各自带着自己的任务 ID。+- **风险**:代理没在运行时,Codex 会连不上。验证期间代理一直开着;验证结束后恢复配置,或者由用户决定是否保留。++P1 通过后,再按用户的节奏一步步探索改写。diff --git a/docs/spec.md b/docs/spec.mdindex 8df8819..d5e8f79 100644--- a/docs/spec.md+++ b/docs/spec.md@@ -18,6 +18,10 @@- **选择集**:用户勾选、允许进入下一轮的素材。按素材管理,每轮发送前都可以调整。- **文字索引**:说明素材编号和状态的一段文字。重建任务时随历史一起提供;之后在附带素材的轮次里注明“附件 1 = IMG-004”这样的对应关系。+### 免配置++用户不需要手动编辑任何文件。工具自动找到 Codex 的目录(Windows 上是 `CODEX_HOME`,没设时是 `%USERPROFILE%\.codex`),自动完成接入。每个任务(session)各有一套自己的勾选状态,互不影响。+### 选择规则- 任何素材在任何一轮都可以勾选或取消。取消的素材仍留在列表里,之后任何一轮都能重新勾选。@@ -60,10 +64,12 @@## 3. 硬约束-- 原始对话记录和素材文件始终只读,不修改、不移动、不删除。不直接写入 `~/.codex` 下的任何文件;唯一的例外是官方 app-server 在创建和运行任务时自己产生的正常写入。+- 原始对话记录和素材文件始终只读,不修改、不移动、不删除。不直接写入 `~/.codex` 下的任何文件,只有两个例外:+ - 官方 app-server 在创建和运行任务时自己产生的正常写入;+ - 为接入本地代理,工具可以修改 `config.toml` 里由它自己管理的那一段设置(用户 2026-09-24 授权)。改之前先备份,能一键恢复,其他设置一律不动。- 真实数据不进仓库:从真实会话和用户素材里提取的图片、记录片段、日志和备份,只能放在本机的 `local/` 目录(已被 git 忽略),任何时候都不提交。仓库里的样例数据只能是合成的或脱敏的。- 仓库里的文档和代码不写用户本机的具体路径(例如个人项目文件夹)。`~/.codex`、`%LOCALAPPDATA%` 这类通用位置可以写。本项目以后会开源。-- 对上下文的控制只通过“在新任务中继续”来实现,不改写原生任务的历史。+- 不改写原生任务的历史记录。- 选择权永远在用户:哪些素材进入上下文,只由用户在面板里勾选决定。工具和模型都不能自动勾选或取消;模型只能按约定索要(例如回复“需要 IMG-004”),给不给由用户决定。- 先在 Windows 上开发和测试。技术栈:TypeScript/Node。- 交付形态:Codex 插件(skill 加本地 MCP 服务);面板位置见第 1 节“界面”。@@ -92,4 +98,4 @@## 5. 待定问题-- 重建路线由阶段 0 的结果决定:路线 A 用 `thread/inject_items` 重建,路线 B 用交接包。选择规则见 plan.md。+- 路线待定。路线 A(用 `thread/inject_items` 在新任务里重建)已验证可行,但用户不接受“重建后在界面上看不到原对话”:在同一个任务里勾选、取消文件时,对话必须保持连续可见。现在验证代理路线,即任务不换,每次请求发出前由本地代理按勾选改写。第一步只转发、不改写,见 plan.md 第 9 节。diff --git a/docs/tasks.md b/docs/tasks.mdindex 7ba1b4c..807158d 100644--- a/docs/tasks.md+++ b/docs/tasks.md@@ -1,6 +1,31 @@-# 任务清单:阶段 0 技术验证+# 任务清单-> 验收关卡见 [spec.md](spec.md) 第 4 节,方法见 [plan.md](plan.md)。按顺序做,完成一项勾一项,并写明证据放在哪里。+> 方法见 [plan.md](plan.md)。按顺序做,完成一项勾一项,并写明证据放在哪里。++## 当前:代理验证 P1(只转发、不改写)++设计见 plan.md 第 9 节。++- [ ] **P1-1 配置工具**+ - 自动定位 Codex 目录,提供 enable、disable、status 三个命令。+ - 修改前备份;只增删带标记的那一段;如果已经有用户自己的 `openai_base_url`,不覆盖。+ - 单元测试覆盖:插入位置在所有表头之前、CRLF 和 BOM、重复启用、恢复后逐字节一致、冲突检测。+- [ ] **P1-2 透明代理**+ - HTTP 请求和 WebSocket 连接原样转发;自动沿用系统代理;只在 `127.0.0.1` 上监听。+ - 日志只记元数据,不含认证信息和对话内容。+- [ ] **P1-3 自测(不改配置)**+ - 我们自己启动的 app-server 用 `-c openai_base_url` 指向代理,依次验证文字、附图、生图、改图都能成功,日志里能看到对应的请求。+- [ ] **P1-4 桌面版验证**【需用户】+ - 修改桌面版的配置(先备份)。用户重启桌面版后,在任务里依次发文字、上传图片、让它生图、让它改图。+ - 通过代理日志确认这些请求全部经过代理并且成功,不同任务的请求带着各自的任务 ID。+- [ ] **P1-5 收尾**+ - 按用户的决定恢复或保留配置;写 `docs/p1-report.md`(只写统计)。++---++## 已完成:阶段 0 技术验证++> 验收关卡见 [spec.md](spec.md) 第 4 节。## 执行规则@@ -8,7 +33,7 @@- 从真实会话里提取的图片、记录片段、日志和备份,只放在 `local/`(已被 git 忽略),不提交。- 标了【需用户】的步骤,要由用户在桌面版上操作或做判断。走到这一步先停下,说清楚需要用户做什么。- 遇到 plan.md 没有覆盖的决策,停下来写进报告,交给用户决定。这类决策包括:改变路线、扩大范围、需要直接写入 `~/.codex`、需要修改用户配置。-- 不修改 `docs/spec.md` 和 `docs/plan.md`。发现需要修改的地方,写进报告。+- 其他协作者不修改 `docs/spec.md` 和 `docs/plan.md`(由 Claude 维护,见 AGENTS.md)。发现需要修改的地方,写进报告。## 任务