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(v0.4): Claude 桌面 Code 接入方案按现有插件机制逐块移植
chipfighter647f293d251b
diff --git a/AGENTS.md b/AGENTS.mdindex 5c1421a..a77eb3a 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -6,6 +6,7 @@ Codex Attachment Manager(上下文素材管理器):让用户逐轮决定- [docs/spec.md](docs/spec.md):目标、范围、硬约束和验收标准,是唯一的事实来源,描述当前版本。- [docs/design.md](docs/design.md):技术方案,讲现在是怎么实现的。+- [docs/v0.4/plan.md](docs/v0.4/plan.md):Claude 桌面 Code 接入的 v0.4 变更方案;任务和验收分别见同目录的 `tasks.md`、`acceptance.md`。当前正式规格仍以 `docs/spec.md` 为准,未通过的迁移关卡不算已实现。- [docs/history/v0.1/](docs/history/v0.1/):v0.1 的开发记录(原方案、任务记录、各阶段报告、最初的构想),只作参考,不作依据。- [CHANGELOG.md](CHANGELOG.md):每个版本的更新记录,发布时就是 Release 说明。diff --git a/docs/v0.4/acceptance.md b/docs/v0.4/acceptance.mdnew file mode 100644index 0000000..c240236--- /dev/null+++ b/docs/v0.4/acceptance.md@@ -0,0 +1,100 @@+# v0.4 验收标准++> 状态:待执行的增量验收。方案见 [plan.md](plan.md),执行见 [tasks.md](tasks.md)。现行 v0.3 行为引用 [spec.md](../spec.md),不另定义一套行为。+> 必须区分:本机模拟、终端、真实桌面订阅、用户界面确认。前者通过不能自动替代后者。++## A04-01 官方订阅接入++真实 Claude 桌面 Code 的本地会话,保持官方订阅登录,不填 API key、不换账号。正式安装后无需手改配置,启用后请求经本机引擎到 Anthropic,回复完整;停用后恢复原始地址。++检查 OAuth capability 与认证透传、无意外 API key,以及实际安装副本和会话加载。原样文本探针已通过的是入口部分;正式安装、自动启动与恢复仍待验。++## A04-02 无选择变化时原样发送++没有取消项、自动模式未使用时,转发的请求正文与原始正文逐字节一致。必要的 HTTP 传输头处理单独比较;认证、版本和 beta 保留。错误状态/正文、查询串与 SSE 完整透传,取消客户端请求时上游结束。++图片不需要替换时,不重排消息、不重编码图片、不增加占位说明、不改工具调用或思考块。++## A04-03 同一会话取消与恢复++用合成图 A、B 和 A 的重复出现,先确认模型看到它们,再取消指定出现记录并继续同一个会话:++1. 下一次请求中只有指定目标变成正确占位符,其他图仍在。+2. 普通与重复占位符按本次仍发送的图决定,不因同内容而合并用户选择。+3. 重新勾选后,下一次请求恢复对应原图,模型可以读取测试标记;不另开会话或重建历史。+4. 新出现图按现行手动规则默认发送;选择不变时改写结果稳定。+5. 原始素材与已有历史保持只读,按 A04-09 取证。++同时检查用户图和工具结果图,不能只凭模型说“看不到”证明图片已删,必须检查发出的请求。++## A04-04 思考兼容与模型行为++**G04-1 前置子集**:模型用 Haiku 5.5,运行次数先与用户确认。在真实桌面订阅、正常使用的思考配置下,历史中确实已有思考块后执行 A04-03,并用最小工具取回实验覆盖工具图及取回副本下一轮省略;不要求先完成完整自动模式。++- 账号放行时,改写后的请求正常完成,模型按 A04-03 的要求回答。账号拒绝(400)时,包括用 `prefix_mismatch_behavior: "error"` 模拟的新账号,引擎原样重发、对话不断,面板提示这次没能按勾选改写,且不计入取消成功。记录真实模型、思考配置、账号表现及请求诊断。+- 引擎不删思考块、不加 `drop_block`、不关思考。若有必要取舍,记录影响与可复现证据,经用户确认并修改规格后再改验收;当前不默认接受。+- 未修改图片的文本往返、没有实际思考块的测试不能证明兼容;用户账号放行之外,必须再测一次模拟新账号的拒绝路径。官方文档不能替代桌面订阅实测。++**正式模型行为验收**:T04-05 覆盖手动模式,T04-08 覆盖完整自动模式。模型不收回之前看原图的有效描述,不补充现在看不到的新细节;手动按编号要图、恢复后能看图;自动模式该取图时取,不需要时不取。专项自测覆盖中英文,模型范围与成本上限先确定;Codex 的 GPT 自测不能代替它。++G04-1 只记录前置子集通过,不提前勾整项 A04-04;正式模型行为和思考兼容均通过后,此项才算完成。++## A04-05 索引、来源与编号++能按时间/轮次列出客户端实际支持的用户上传、工具查看/返回和生成图片的每次出现,展示稳定编号、名称、尺寸、大小和可靠来源。字节/像素相同的重复关系按现行规则判断;同图每次出现仍独立编号。++继续会话、重新打开、插件重载后编号不乱。模型取回的副本不增加新的素材行。认不准的来源不猜,Claude 没有的 Codex 专属来源不伪造;无法安全对应的图片保留并提示原因。++## A04-06 桌面内面板(前置关卡)++在真实 Code 界面中显示多张真实缩略图,能放大预览、单张勾选、保存与当前会话对应,操作无需模型参与。面板入口可由用户直接打开,不要求模型帮忙打开。先验 MCP 应用路线,不能再验 Mod 面板。++接口声明、示意图、终端界面或外部浏览器开发页均不能替代桌面内验收。关键节点由 Claude 截图检查并交用户反馈,反馈未解决时不勾完成。++## A04-07 完整交互与双语++按现行规格逐项检查:整轮勾选、来源筛选、编号定位、发送预览/上一次实际统计、任务名、自动刷新、预览、启停、主题和中英文文字。++筛选只影响显示;整轮选择只作用于该轮显示项;跳转隐藏项时按现行规则显示和定位。预估明确标为预估,不把请求大小或图片数量等同于已节省的模型 token。实际无法改写时在面板提示原因。走 Mod 面板时做不到的项,先列给用户确认,未确认不算通过。++## A04-08 自动选图++默认关,任务各管各的。开启后按现行 v0.3 语义:历史未固定图省略、本轮新图照常、固定图每轮发;手动勾选与固定发送分开保存。++模型按 IMG 编号取到原图,实际读出合成图随机标记;这份副本仅在本轮提供,下一轮不再发送,原位置占位符和前面的历史文本保持稳定。副本不另占列表行,不改变用户勾选或开关。面板显示最近取回编号和行标记;关闭自动后手动选择恢复。++覆盖中英文的需要图/不需要图场景,并通过 A04-04 的思考兼容检查。工具注册或返回一段 base64 文本不算模型已看到图。++## A04-09 原始数据只读与隐私++原始素材前后哈希不变;选择操作不改已有会话历史。对正在继续的会话,核对原有历史前缀或静态快照不变,并区分 Claude 自身正常追加记录,不能把官方追加误算成插件改写。++插件只写工具数据目录和自管安装配置;恢复不覆盖用户其他设置。日志不含认证值、原始图片和聊天正文,真实证据只在 `local/` 或工具数据目录。提交只含合成/脱敏样例,无用户具体路径和私有会话标识。++## A04-10 生命周期、隔离与失败恢复++验证两个同时运行的会话、继续/分叉、子代理、压缩与回退、重载、桌面重启、服务失败、停用/卸载、登录刷新和插件更新,以及只开 Claude 不开 Codex、两边同时使用同一个引擎。不会串勾选状态,不覆盖其他服务地址,不留下指向已停止服务的配置;只开 Claude 时引擎不因没有 Codex 进程而退出,两份插件副本不来回让对方的引擎退役。启用前服务就绪,恢复后真实请求可直连正常回答。++未识别、无法解析或不能安全改写的请求原样发送并提示原因;不静默发送后宣称已取消,也不把回退计入 A04-03/A04-08 的成功次数。自动恢复和平台限制按实测范围如实说明。++## A04-11 Codex 回归++现有 v0.1–v0.3 的相关单元、自测、安装/卸载冒烟通过;无取消、手动和自动模式语义不变。共享运行代码或文字修改时,按 AGENTS.md 跑对应自测并重新安装,验证实际安装副本。++Windows 优先。macOS/Linux 的 CI 与桌面实测分别记录,不将“CI 能启动”写成“桌面功能全通过”。++## A04-12 交付与证据++每项验收有对应任务、执行环境、最后相关改动后的结果、证据位置和审阅结论。界面关键节点与最终用户验收有反馈记录;全部通过后才更新正式支持声明和发布。++由 Claude 将确认结果更新到现行规格和方案,保持当前事实与版本一致。英文 README/CHANGELOG、中文说明与实际能力一致,不以本机探针或 API key 模式冒充官方订阅完整支持。++## 当前验收记录++| 项目 | 状态 | 说明 |+| --- | --- | --- |+| A04-01 实验入口部分 | 已通过 | T04-00;真实桌面官方订阅透明转发与恢复命令 |+| A04-01 正式交付部分 | 待执行 | 免配置安装、自动启动和正式恢复未完成 |+| A04-02–A04-12 | 待执行 | 模拟探针的测试不替代正式功能验收 |++关卡失败时记录“未通过”及原因,不用“部分可用”覆盖用户要求的完整目标。diff --git a/docs/v0.4/plan.md b/docs/v0.4/plan.mdnew file mode 100644index 0000000..b037970--- /dev/null+++ b/docs/v0.4/plan.md@@ -0,0 +1,151 @@+# v0.4 变更方案:Claude 桌面 Code 接入++> 状态:开发提案,正式功能尚未实现。2026-10-09 按用户要求整理;2026-10-10 用户确认:按现有插件的机制逐块移植,只在平台逼迫时改动(见第 1 节)。+> 当前版本的唯一规格仍是 [spec.md](../spec.md),现有实现见 [design.md](../design.md)。本目录记录 v0.4 的增量变更、关卡和开发任务,不另复制一套现行规格。+> 执行顺序:本方案 → [任务清单](tasks.md) → [验收标准](acceptance.md)。每个任务都要有对应验收和证据;通过路由实验不等于通过完整迁移。++## 1. 目标与范围++用户已明确的目标:在 **Claude 桌面应用的 Code 标签页、本地会话、官方订阅登录** 下使用当前素材管理能力。继续在同一个会话逐轮取消和恢复图片,原始对话与素材只读。只支持 API key、只支持终端,或只能转发文字,都不能满足该目标。++v0.4 按现行 v0.3 的图片管理语义验收:稳定编号、每次出现独立选择、重复关系、整轮勾选、来源筛选、发送预览、模型要图定位、自动选图和按需取回、中英文、面板与安装启停。各项详细行为引用现行规格,不在此重写。Claude 没有的 Codex 专属来源不伪造;只识别有可靠依据的来源。++按现有插件的机制逐块移植到 Claude(用户 2026-10-10 定):同仓新增 Claude 接入、保留 Codex 实现,不另起架构,不削减 v0.3 的功能。只有平台逼迫的地方才改,并写明原因;对应关系见下表。正式实现前由规格维护者将确认内容写回现有规格和方案。已有 Codex 功能保持可用是本方案的回归要求。++| 现有机制(见 design.md) | Claude 上的对应 |+| --- | --- |+| 本机引擎改写请求,同一个任务,历史不动 | 同一个引擎增加 `/v1/messages` 转发,上游固定为 `api.anthropic.com` |+| `config.toml` 里带标记的 `openai_base_url` | 平台逼迫:桌面版不认 settings 里的地址,由插件里的 Mod 用 `$.env.set` 切换(D04-01) |+| 插件的 MCP 服务拉起、看守引擎,给面板提供数据 | Claude 插件同样带这个 MCP 服务;Mod 只负责切地址(D04-01、D04-06) |+| 请求头 `x-codex-turn-metadata` 认出任务 | 请求头 `x-claude-code-session-id`(D04-02) |+| 从本地记录只读编号,只追加;引擎和插件服务各自计算,不共享状态 | 从 Claude Code 的本地会话记录只读编号,做法相同(D04-02) |+| 按条目 `id` 对齐请求和记录,没有就用 `call_id`,再没有就用类型、轮次和内容哈希 | 消息块没有 `id`:工具图用 `tool_use_id`,用户图用最后一档(D04-02) |+| 占位符、重复占位符、“已提供”标签;勾选不变时逐字节相同 | 照搬(D04-03) |+| “上下文管理说明”开发者消息,插在第一张被省略的图所在那一轮的用户消息之前 | 平台逼迫:改用 `role: "system"` 消息,放在那条用户消息之后(D04-03) |+| WebSocket 握手回 426,让 Codex 改走 HTTP | 不需要:Claude Code 本来就走 HTTP 和 SSE |+| 改写不了就原样发送,面板提示原因 | 照搬;思考签名被拒时也按这条处理(D04-03) |+| 面板是 MCP 应用,用户自己打开,不经过模型 | 先验证 Claude 桌面 Code 能否由用户打开插件的 MCP 应用;不能再退到 Mod 面板(D04-04) |+| 自动选图:`cam_view_image` 按编号取图,取回的图放在本轮末尾,副本下一轮换成说明 | 照搬,取图工具由同一个 MCP 服务提供(D04-05) |++本轮不扩大素材范围:原生 PDF/document、音频、视频和普通文本文件不因为换客户端就自动进入管理范围。工具渲染出的图片仍按图片处理。暂不增加其他模型供应商、云端会话、跨会话素材库或新的常驻系统服务。++## 2. 事实、证据与未知项++### 2.1 已实测++验证环境:Windows;Claude 桌面应用 2.26454.2.0,自带 Claude Code 2.1.293。结论只覆盖该环境,更新后需重跑相关验证。++- 项目 settings 中的 `ANTHROPIC_BASE_URL` 不能覆盖桌面宿主启动时传入的同名变量。+- Mod 的 `$.env.set()` 可以在会话运行时切换地址。真实桌面 Code 会话经过本机透明探针,保留 Bearer/OAuth capability、无 API key,请求带 `x-claude-code-session-id`,Anthropic 返回 HTTP 200,主回复流完整结束。+- 用户实际执行开启、发送消息、关闭命令,并确认了可见回复和恢复提示。+- 本机探针的透明转发、认证头、SSE、取消和恢复共 9 项回归测试通过;桌面自带命令行校验实际安装副本通过。这些是实验工具证据,不是正式 v0.4 功能验收。+- 只写 `enabledPlugins` 不完成安装;必须实际登记并安装插件,再加载到目标会话。首次命令缺失由漏安装造成,补安装后已解决。++私有实验记录位于验证机的 `local/claude-live-routing/`;不得把原始记录、凭据、图片或本机路径复制到提交中。仓库只保留上述脱敏结论和实验方法。该目录被忽略,克隆仓库后无需存在。++### 2.2 已查证的平台约束,仍需在订阅链路实测++2026-10-09 查官方文档(链接见第 8 节)和桌面自带 Claude Code 2.1.293 的 Mod 类型定义。文档说的是 API 行为,订阅链路的实际表现以实测为准。++- 桌面启动的环境变量过滤,与 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 尚未通过++带思考记录的图片取消/恢复、历史与请求中的图片出现记录对齐、完整桌面内面板、自动取图、续聊/分叉/多会话隔离、登录刷新、免配置安装及失败恢复。目前均不得标记为完成。++## 3. 变更要求与追踪++| 编号 | v0.4 增量要求 | 设计边界 | 任务 | 验收 |+| --- | --- | --- | --- | --- |+| R04-01 | 桌面本地 Code 保留官方订阅接入,免手改配置 | D04-01、D04-06 | T04-00、T04-03、T04-09 | A04-01、A04-10 |+| R04-02 | 同一会话逐轮取消、恢复;原始记录与素材只读 | D04-02、D04-03 | T04-01、T04-04、T04-05 | A04-02、A04-03、A04-04、A04-09 |+| R04-03 | 稳定编号、重复关系、可靠来源与会话隔离 | D04-02、D04-04 | T04-04、T04-06 | A04-05、A04-10 |+| R04-04 | Code 桌面内的完整图片管理面板 | D04-04 | T04-02、T04-07 | A04-06、A04-07 |+| R04-05 | 保持 v0.3 自动选图、固定发送、按需取回语义 | D04-03、D04-05 | T04-01、T04-08 | A04-04、A04-08 |+| R04-06 | 双语、隐私、原样转发和无法改写的可见提示 | D04-03、D04-04、D04-06 | T04-05、T04-07、T04-09 | A04-02、A04-07、A04-09、A04-10 |+| R04-07 | Codex 无退化,验证后再发布 | D04-01、D04-06 | T04-03、T04-10、T04-11 | A04-11、A04-12 |++## 4. 设计边界++### D04-01 接入与透明转发++沿用已验证的会话内 Mod 接入路径:先确认本机引擎就绪,再切换当前 Code 进程地址;保存原值,停用时恢复。Mod 只负责切地址这一件事。只绑定本机地址,保留系统代理和用户已有的 `NO_PROXY` 设置。引擎就是现有引擎,增加 `/v1/messages` 转发,固定官方 Anthropic 上游,不提供任意目的地转发。++照原机制,由插件的 MCP 服务拉起并看守引擎(见 design.md 第 5 节)。Codex 与 Claude 共用这个引擎,引擎的退出条件和替换规则改为同时考虑两边(现在只看有没有 Codex 进程)。OAuth、版本、beta 和会话相关请求头需要透传,认证值不得进入日志。查询串、错误响应和 SSE 都须保留;客户端取消时关闭上游请求。正文无需改写时保留原始字节。MCP 服务在 Claude 下的 Node 运行环境在 T04-03 中确定,不把实验端口或本机安装路径写死进正式安装包。++### D04-02 Claude 图片与会话适配++照原机制新增 Claude 的会话读取:从 Claude Code 的本地会话记录只读、增量地找图和编号,只追加,已有编号不变;引擎和插件服务各自计算,不共享状态。Mod 的读取接口只在 Claude Code 进程里,引擎拿不到,不作为编号依据。不写回原始会话。++区分直接图片块和嵌套工具结果中的图片;原生 document 等未知结构保留。编号对应每次出现,不能把图片哈希当作唯一出现编号。相同内容、不同出现、工具取回副本需要分别处理。对齐沿用原机制的顺序:消息块没有条目 `id`,工具结果里的图用 `tool_use_id`(相当于 `call_id`),用户消息里的图用类型、轮次和内容哈希。历史存储与发出请求可能有预处理差异,必须用实验确定匹配方式,无法可靠对应就原样放行并提示。++会话按每个请求的 `x-claude-code-session-id` 认出,不只在插件加载时缓存。Codex 与 Claude 的状态隔离;并行会话、续聊、分叉和子代理不能误用另一会话的选择。压缩(`/compact` 与自动压缩)和 `/rewind` 回退之后,已有编号不变、选择不串。++### D04-03 Claude 请求改写与思考兼容++单独适配 Anthropic Messages。只修改确定的目标图片块及必要的占位说明,保留工具容器、调用配对、消息顺序和未触碰字段。不得把整份请求转成 OpenAI Responses 再转回来。上下文管理说明改用 `role: "system"` 消息,放在第一张被省略的图所在那条用户消息之后(Anthropic 不允许放在用户消息之前);它和改图在同一处,不扩大思考失效的范围。订阅链路是否接受、Claude 模型的效果在 T04-01 中验证。++保留现行选择与占位语义,Claude 措辞需分别跑中英文模型验收。选择不变时输出稳定;自动取图不能反复修改前面的占位文本。++思考块按原机制原样转发:引擎不删思考块、不加 `drop_block`、不关思考。账号放行时效果与 Codex 相同;被拒(400)时按“改写不了就原样发送”处理,改发原始请求,面板提示这次没能按勾选改写,回退不计作取消成功。服务端上下文编辑不能指定某张图,不采用。要改变这一处理,先给出证据,由用户决定后再更新规格;不默认为用户接受功能降级。++### D04-04 面板与业务规则复用++照原机制,面板是插件 MCP 服务提供的 MCP 应用,用户自己打开,不经过模型。先验证 Claude 桌面 Code 能否由用户直接打开插件的 MCP 应用:能,就复用 `panel.html` 和面板数据,只隔离 Codex 特有的宿主握手、任务元数据、主题与工具权限;不能,才退到 Mod 面板,缩略图内嵌在 Svg 里,做不到的 v0.3 行为先列给用户确认。++复用候选包括选择状态、图片指纹、重复关系、缩略图处理、编号识别和面板数据字段。先做单图,再做多图的桌面内面板实验,验证缩略图、放大预览、勾选、状态保存与当前会话绑定。浏览器开发页可调试,但不能作为桌面内交付验收的替代。关键界面节点按 AGENTS.md 截图给用户,等待反馈后继续界面开发。++### D04-05 自动取图++先完成手动闭环,再接自动模式。保留当前默认关闭、手动与固定发送分开、当前轮新图照常发送、历史未固定图省略、取回只用于本轮、下一轮省略副本的规则。取图工具照原机制由插件的 MCP 服务提供,始终注册、不随开关增删:增删 `tools` 里的工具也会让之后的思考失效。++工具注册成功不代表图片已到模型。必须检查模型实际看到原图中的合成标记,并检查下一轮请求。思考兼容关卡也覆盖工具图及副本省略。模型无权修改用户选择或开关。++### D04-06 安装、恢复与回归++Claude 插件入口与 Codex 入口分别安装;只提取确实需要共享的规则,不先重构为通用供应商框架。Claude 插件的内容是 MCP 服务(与 Codex 共用 `plugin/src` 的运行代码)加一个只切地址的 Mod。运行代码在 `plugin/src`,测试与实验在 `spike`,安装脚本在 `scripts`;Claude 插件的目录与清单由 T04-03 确定。++安装必须校验实际安装副本和目标会话加载,不能只写启用配置。恢复只影响工具自管的地址/设置,不覆盖用户的其他配置。验证卸载、重载、桌面重启、引擎失败、登录刷新和版本更新;不新增系统计划任务等常驻机制。++Codex 现有自测、安装和卸载保持可用;共享运行代码变化后重新运行 `cam install`。不因新文档提前修改插件版本、README 支持声明或 Release。++## 5. 实施关卡++| 关卡 | 进入条件 | 工作 | 退出条件 |+| --- | --- | --- | --- |+| 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-2 正式适配 | G04-1 通过,规格维护者将目标与采用方案写回现有文档 | T04-03–T04-07 | 手动模式与完整面板通过对应验收 |+| G04-3 自动模式 | 手动模式稳定;核心关卡覆盖取图副本 | T04-08 | 自动取图语义和模型行为通过 |+| G04-4 交付 | 前述功能通过 | T04-09–T04-11 | 全部验收、回归、安装检查通过,用户确认后再发布 |++G04-1 任一核心能力失败时,不跳过关卡开发完整面板或宣称 v0.4 可用。先追溯原因、记录可行选项;涉及官方订阅、同会话连续性、桌面内交互或思考能力的取舍,由用户确认后更新规格。++## 6. 文档与开发纪律++- `docs/spec.md`、`docs/design.md` 按 AGENTS.md 继续由 Claude 维护。正式实现前将确认的 v0.4 增量写回原文;未发布时清楚区分当前已实现与计划内容,不另保存 old/new 两套规格。+- 任务按顺序执行,每项标明依赖、验收与证据。可自动化的行为按 TDD;未知原因的失败先按 systematic-debugging 复现和定位。+- 完成前按 verify-before-done 核验证据;跨模块、认证与服务边界按 code-review 审阅。文档改动只检查结构、链接、事实与状态,不为文档造运行测试。+- 在短分支工作;提交、合并和发布遵循 AGENTS.md。未验收的项目不勾完成。+- Codex 模型自测继续遵守 AGENTS.md 的模型、推理强度和双语矩阵。Claude 专项验收必须使用真实 Claude 桌面订阅模型;自动化前需确定模型范围和成本上限,不能用 GPT 自测替代,也不要求 API key。+- 真实证据只在 `local/` 或工具数据目录;可提交测试样例必须合成或脱敏。Windows 优先,其他平台的 CI 与桌面实测范围分别说明。++## 7. 开始正式实现前需确定++1. G04-1 的实测结论:订阅链路下账号放行还是拒绝、被拒后原样重发能否接上;`role: "system"` 说明的效果;面板走 MCP 应用还是 Mod。+2. 正式专项验收的模型范围与成本上限(G04-1 用 Haiku 5.5),以及要覆盖的账号差异(2026-08-31 前后注册)。+3. Claude 插件的目录与清单,以及 MCP 服务在 Claude 下的 Node 运行环境;启动方式照原机制。+4. 规格维护者将确认内容同步到现行 spec/design,保留唯一事实来源。++## 8. 资料依据++- [订阅与网关](https://code.claude.com/docs/en/llm-gateway#subscriptions-and-gateways):仅切换地址不等于切换凭据,OAuth capability 需要透传。+- [Mod API](https://code.claude.com/docs/en/plugins/mods/api)、[Mod 参考](https://code.claude.com/docs/en/plugins/mods/reference):环境、命令、工具和界面能力;以安装版本接口和真实桌面实验为准。+- [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking):做前缀校验的模型、按账号注册时间的处理、实验用的 beta 头;订阅链路的表现尚待验证。+- [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages):对话中途 `role: "system"` 消息的位置规则。+- [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing):服务端清理只按规则清最早的工具结果或思考,不能指定某张图。+- [插件安装](https://code.claude.com/docs/en/plugins/install):安装、启用和会话加载是不同步骤。diff --git a/docs/v0.4/tasks.md b/docs/v0.4/tasks.mdnew file mode 100644index 0000000..625cbef--- /dev/null+++ b/docs/v0.4/tasks.md@@ -0,0 +1,103 @@+# v0.4 任务清单++> 方案见 [plan.md](plan.md),验收见 [acceptance.md](acceptance.md),现行行为以 [spec.md](../spec.md) 为准。+> 按依赖执行。只有验收与证据齐全才勾选;实验通过不自动勾选对应的正式实现。++## 当前状态++2026-10-10:路由入口 T04-00 已完成;方案已按“现有机制逐块移植”改写(用户确认)。G04-1 尚未通过,正式运行代码尚未开发。下一步先做 T04-02(不用模型额度),再做 T04-01(Haiku 5.5);两者都通过后才能开始 G04-2。++## G04-0:路由入口++- [x] **T04-00 真实桌面官方订阅透明转发**。Windows 的 Claude 桌面 Code 本地会话,Mod 切换地址,保留 OAuth/Bearer、无 API key,收到 HTTP 200 与完整流式回复,用户执行恢复命令成功。+ - 关联:R04-01;A04-01 的实验入口部分。+ - 证据:验证机 `local/claude-live-routing/verification.md`、`metadata.jsonl`、用户截图;9 项探针回归、实际安装副本校验。+ - 范围:只证明透明路由;正式启动、长期认证、重启、卸载恢复未完成。++## G04-1:核心可行性++- [ ] **T04-01 历史图片取消/恢复与思考兼容**。依赖 T04-00。+ - 模型用 Haiku 5.5(用户 2026-10-10 定),思考用 Claude Code 的默认配置,先确认请求里确有思考块;运行次数在开始前与用户确认。+ - 用合成图 A、B 和一份重复出现,在同一桌面订阅会话中完成上传、看图、取消 A、继续对话、恢复 A、再继续;覆盖工具图片和实际出现过思考块的历史。+ - 确认本地出现记录与发出的图片块能够可靠对齐;同时检查被取消图确实未发、未取消图保留、恢复图回到应有位置。+ - 用最小取回工具在本轮提供原图、下一轮用实验改写省略副本,检查思考兼容;不要求先实现 T04-08 的完整自动模式。+ - 思考块原样转发。记录:账号放行还是返回 400;加 beta 头 `thinking-binding-controls-2026-08-01` 并设 `prefix_mismatch_behavior: "error"` 模拟新账号的结果;订阅链路是否接受该 beta 头;被拒后原样重发能否接上,Claude Code 自己怎么处理 400。没有实际思考块的文本测试不能覆盖签名约束。beta 头和诊断参数只用于实验,不加入正式请求。+ - 上下文管理说明用 `role: "system"` 放在第一张被省略的图所在那条用户消息之后,验证订阅链路接受、模型不收回之前的回答;先做最小改写,不提前搬整套引擎。+ - 关联:R04-02、R04-05;A04-02、A04-03、A04-04 的 G04-1 子集、A04-09。通过本任务不勾整项 A04-04。+ - 证据:本机脱敏请求差异、回应状态、只读检查、合成图的模型回答;失败时保存根因与选项。++- [ ] **T04-02 桌面内缩略图面板实验**。依赖 T04-00,可与 T04-01 并行。+ - 先试 MCP 应用:做最小 Claude 插件,由 MCP 服务提供面板(从现有 `cam_panel` 改),验证用户能否在桌面 Code 里自己打开、能否显示缩略图和放大预览。+ - 不行再试 Mod 面板:缩略图内嵌在 Svg 里,核对清洗后内嵌图是否保留、多张时的总量限制;与 v0.3 面板相比做不到的地方,列给用户确认。+ - 在真实 Code 中先显示一张、再显示多张合成图;验证缩略图、单张勾选、放大预览、保存和当前会话绑定,不通过模型执行操作。浏览器页只用于调试,不计桌面验收。+ - 关联:R04-04;A04-06。+ - 证据:Claude 自行检查截图;关键节点截图给用户,按现有规矩等待反馈。++- [ ] **T04-02a 核心关卡结论与规格同步**。依赖 T04-01、T04-02。+ - 将已验证、失败和待定项分别记录;在本轮实验约定的基础上,固化正式专项验收的模型范围与成本上限。+ - 由 Claude 将确认的目标、约束、验收与采用方案写回现行 `docs/spec.md`、`docs/design.md`,保持唯一事实来源。+ - 若需要功能/思考降级或改变桌面交互目标,先取得用户对具体取舍的确认;未确认不得开始正式适配。+ - 关联:全部 R04;G04-2 的进入条件。+ - 证据:关卡报告、文档差异和相关用户反馈,不用一条“可以用”代替完整结论。++## G04-2:正式手动模式++- [ ] **T04-03 Claude 接入与运行入口**。依赖 T04-02a。+ - 照原机制:Claude 插件带 MCP 服务(与 Codex 共用 `plugin/src`),由它拉起并看守引擎;Mod 只负责切地址,先确认引擎就绪再切,保存并恢复原值。确定 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。+ - 证据:回归测试和真实桌面订阅冒烟;不以实验插件代替正式包。++- [ ] **T04-04 会话索引与图片出现记录**。依赖 T04-02a。+ - 照原机制从 Claude Code 的本地会话记录只读、增量地找图和编号,引擎和插件服务各自计算;稳定编号、轮次、尺寸、重复关系与来源;处理直接图、工具图和取回副本。会话按 `x-claude-code-session-id` 认出。+ - 对齐按原机制的顺序:工具图用 `tool_use_id`,用户图用类型、轮次和内容哈希;核对历史预处理与发送块的差异;状态按客户端和会话隔离,未知结构保留。+ - 关联:R04-02、R04-03;A04-03、A04-05、A04-09。+ - 证据:合成 fixtures 的单元测试,真实桌面只读核对;提交中不含真实会话样本。++- [ ] **T04-05 Claude 手动请求改写**。依赖 T04-03、T04-04。+ - 只替换确定的授权图片,保留消息/工具结构与其余字段;普通/重复占位符、已提供标签、中英文照原机制实现,上下文管理说明用 `role: "system"` 放在那条用户消息之后;思考块原样转发,被拒时原样重发并提示。+ - 选择不变时改写稳定;无法安全改写时原样转发并给出可见原因,回退不算取消成功。+ - 关联:R04-02、R04-06;A04-02、A04-03、A04-04、A04-09。+ - 证据:先失败再通过的单元测试、请求差异、同会话桌面取消/恢复及双语模型自测。++- [ ] **T04-06 续聊、分叉与多会话**。依赖 T04-04、T04-05。+ - 识别当前会话变更、续聊、分叉与子代理;保留编号,按分叉时点继承并分别管理。压缩(`/compact` 与自动压缩)和 `/rewind` 回退之后,已有编号不变、选择不串。+ - 不只依赖 `session.start` 更新会话状态;核对真实事件时序。+ - 关联:R04-03;A04-05、A04-10。+ - 证据:两会话隔离、重载、续聊、分叉、压缩、回退、工具中间请求的回归与桌面记录。++- [ ] **T04-07 完整手动面板**。依赖 T04-02、T04-04、T04-05。+ - 接入完整列表、预览、整轮勾选、来源筛选、发送预估/实际统计、需要编号定位、任务名、刷新、启停、主题和双语。+ - 逐项引用现行 v0.3 的行为;筛选不改变发送,整轮选择按显示项处理。走 MCP 应用时复用 `panel.html`;走 Mod 面板时,做不到的项先列给用户确认。+ - 关联:R04-04、R04-06;A04-06、A04-07。+ - 证据:交互检查、双语截图、用户在关键节点的反馈;接口差异与降级不能隐瞒。++## G04-3:自动模式++- [ ] **T04-08 自动选图与原图工具**。依赖 T04-05、T04-06、T04-07;先确认 T04-01 覆盖取图副本省略。+ - 自动开关默认关;旧图省略、新图照常、固定发送与手动状态分开;模型按编号真正取到图片,副本仅在本轮提供。取图工具由插件的 MCP 服务提供,始终注册、不随开关增删。+ - 取回不另编号、不改用户勾选;下一轮省略副本,前面的占位文本保持稳定;关闭自动恢复手动状态。+ - 关联:R04-05;A04-04、A04-08。+ - 证据:带随机标记的合成图测试,工具图回传和后续请求检查,中英文该取/不该取测试。++## G04-4:交付++- [ ] **T04-09 安装、恢复与失败处理**。依赖 T04-03、T04-06、T04-08。+ - 正式安装/更新/卸载、停用、引擎失败、插件重载、桌面重启和登录刷新;尊重用户已有设置,验证卸载顺序和恢复。+ - 只写自管设置;不保存认证值;识别安装、启用、当前会话加载三个状态。+ - 关联:R04-01、R04-06;A04-01、A04-09、A04-10。+ - 证据:合成配置回归、实际安装副本与桌面订阅测试;记录平台覆盖,不将 CI 启动冒烟当成跨平台桌面实测。++- [ ] **T04-10 Codex 回归与最终审阅**。依赖 T04-03–T04-09。+ - 跑改动相关的现有测试,确认 v0.1–v0.3 语义、原样路径、自动模式和装卸不退化。+ - 共享占位/取图文字改动按 AGENTS.md 跑规定的 GPT-6 双语矩阵;运行代码变更重新 `cam install`。+ - 做认证/服务边界和跨模块审阅,检查仓库无真实数据、本机路径或凭据。+ - 关联:R04-07;A04-11。+ - 证据:最后相关改动后的测试结果、实际安装副本、审阅结论和最终差异。++- [ ] **T04-11 版本收尾与发布**。依赖全部验收通过。+ - Claude 更新现行规格和技术方案,清楚描述最终支持范围与限制;任务/验收状态与证据一致。+ - 再更新版本、英文 CHANGELOG/README 和中文版说明;按既有分支、合并、CI、草稿 Release 流程交付。+ - 关联:R04-07;A04-12。+ - 证据:完整验收矩阵、用户最终反馈、相关 CI 和发布检查。不得仅凭路由成功宣称完整迁移完成。