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: 面板标题显示任务名、新任务自动绑定、分叉后面板卡顿的设计

chipfighter96d3ad10f073
diff --git a/docs/plan.md b/docs/plan.md
index 3675925..28e7734 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -398,3 +398,42 @@ P1 通过后,再按用户的节奏一步步探索改写。
- `spike/src/plugin-smoke.ts`:Codex 自己的命令行装插件,app-server 开任务,插件服务就绪,引擎启动;
- `spike/src/scripts-smoke.ts`:真的跑安装、卸载脚本,config.toml 和 .env 恢复原样;
- CI 在 Windows、macOS、Linux 上都跑这两项和全部单元测试。
+
+## 15. 面板和任务的对应(v0.1-9 到 v0.1-11)
+
+### 已查证的事实
+
+依据桌面版 26.917 的前端代码、Codex 的公开源码(codex-rs)和用户 2026-09-25 的实测:
+
+- **侧边面板按任务保存**:每个任务各记自己的面板开没开、有哪些标签页、哪个在前面。切到没开过面板的任务,面板是关的;切回来,原来的标签页还在。一个任务可以开好几个标签页。
+- **面板里的调用带着固定的任务编号**:面板每次调用插件,带的都是它被打开时所在任务的编号,之后不会变。
+- **新任务页面**:在这里打开的面板,绑在 Codex 预先准备的任务上。发第一条消息时,Codex 可能丢掉这个预备任务、另开一个,并把标签页带到新任务上,但面板里的编号不变(v0.1-8)。
+- **分叉**:Codex 分叉时会把原任务的侧边面板布局复制过去。用户实测:在分叉里新开的面板绑在分叉上,勾选按第 1 节的规则继承。
+- **任务名**:在 `<CODEX_HOME>/session_index.jsonl` 里,每行 `{id, thread_name, updated_at}`。名称只追加,同一个任务以最后一行为准;Codex 删除某个任务的名称时,会整个文件重写。
+- **任务来源**:任务记录的第一行(`session_meta`)写明:
+ - `source`:`cli`、`vscode`、`exec`、`mcp`,或者 `{subagent: …}`、`{internal: …}`;
+ - `thread_source`:`user`、`subagent`,或者某个功能的名字;
+ - `forked_from_id`、`parent_thread_id`。
+ - 带历史启动的子代理,Codex 也记成从父任务分叉(`forked_from_id` 是父任务)。
+- **每个任务各有一个插件服务进程**。所以分叉出来的任务第一次开面板时,插件服务是新起的,内存里的缓存是空的。
+
+### 设计
+
+- **标题**:显示 `session_index.jsonl` 里的名称;没有名称时,显示第一条用户消息的开头;任务还没开始时,显示“新任务”。改名后,面板下次刷新时跟着变。
+- **新任务自动绑定**:
+ - 面板所在的任务还没有记录时,插件服务列出“刚开始的、用户自己开的任务”:
+ - 第一次写入记录的时间,不早于面板打开前 10 秒,而且在最近 30 秒内;
+ - 来源不是子代理、内部任务、`exec` 或 `mcp`,不是分叉,`thread_source` 为空或者是 `user`。
+ - 面板只在自己显示在屏幕上时处理这份名单:正好一个就自动切过去;两个以上就列出名称,让用户选。
+ - 30 秒的限制是为了排除这种情况:面板开在一个新任务页上,用户却去别处开了任务,之后才回来。
+ - 绑定记在数据目录的 `bindings/<面板的任务编号>.json`。之后这个标签页的所有调用都按新任务处理,面板重新加载后也一样。
+ - 只接受面板的绑定调用,模型调用会被拒绝。
+- **卡顿**:
+ - 实测(合成数据:12 张 1920×1080 截图共 10.6 MB,另有 400 个其他任务):
+ - 新进程第一次读面板数据要 1.2 秒,其中 0.9 秒花在逐张解码 PNG、计算像素指纹;
+ - 每张缩略图要 0.14 秒;
+ - 之后每次读面板数据要 30–60 毫秒,主要花在遍历所有任务记录的目录上。任务越多越慢。
+ - 改法:
+ - 像素指纹存进数据目录的 `cache/pixels/`,引擎和各个插件服务共用。只存指纹,不存图片内容。
+ - 任务记录的目录只完整遍历一次,之后每次只重新列出今天和昨天的目录;每分钟再完整遍历一次,作为兜底。
+ - 缩略图不写到磁盘,免得在数据目录里留下图片内容;仍然在内存里缓存。
diff --git a/docs/spec.md b/docs/spec.md
index 650b7c4..3a53e60 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -58,11 +58,17 @@
- 平时每 3 秒读一次;
- 用户把鼠标移进面板、点击、滚动时立刻读一次;
- 标题右侧有“刷新”按钮,超过 30 秒没更新时变成橙色。
-- 在新任务发出第一条消息之前打开的面板,可能一直停在 Codex 预先准备、后来又换掉的任务上,刷新也没用。这时面板提示关掉标签页再打开一次(v0.1-8)。
+- 面板左上角显示任务名,和 Codex 里的名称一致,用户改名后跟着变;没有名称时显示第一条消息的开头,还没开始的任务显示“新任务”(用户 2026-09-25 定)。
+- Codex 的侧边面板按任务分开:一个标签页只属于一个任务,切到别的任务再切回来,标签页还在。所以面板不用跟随任务切换。
+- 在新任务发出第一条消息之前打开的面板,发出第一条消息后自动切到这个任务(用户 2026-09-25 定,取代 v0.1-8 的“关掉再打开”):
+ - 只认用户自己开的任务,子代理、分叉和后台自动任务都不算;
+ - 只认面板显示在屏幕上时开始的任务;
+ - 同时有两个任务都符合时,列出名称让用户点选。
+- 子代理不单独处理:带历史启动的子代理,Codex 记成从主任务分叉,按分叉的规则继承勾选。其他情况等开源后按用户反馈再定(用户 2026-09-25 定)。
- 标题右侧是“停用插件”或“启用插件”,两种样式不同。点一下立即生效,不用再确认(用户 2026-09-25 定)。
- 停用或启用后,中间的提示说明要重启 Codex 才生效,另一个按钮随时可以撤回;
- 撤回到 Codex 启动时的状态,就不再提示重启。
-- 以上是用户 2026-09-24 定的 MVP,外加 2026-09-25 要求补上的发送预览、改写失败提示、自动刷新和这两个按钮的位置、名称。
+- 以上是用户 2026-09-24 定的 MVP,外加 2026-09-25 要求补上的发送预览、改写失败提示、自动刷新、这两个按钮的位置和名称、标题里的任务名,以及新任务的自动绑定。
### 为后续扩展预留
diff --git a/docs/tasks.md b/docs/tasks.md
index 4895a92..f913a0a 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -52,6 +52,13 @@
- “停用”改名“停用插件”,停用后显示“启用插件”,两种样式区分开,放在标题右侧;
- 按用户第二次的要求,点一下立即生效,不用再确认;中间的提示说明要重启 Codex;
- 撤回到 Codex 启动时的状态,就不再提示重启。
+- [ ] **v0.1-9 面板标题显示任务名**(用户 2026-09-25 定)
+ - 名称取自 Codex 的 `session_index.jsonl`,同一个任务以最后一行为准,改名后面板下次刷新就跟着变;
+ - 没有名称时显示第一条用户消息的开头,还没开始的任务显示“新任务”。
+- [ ] **v0.1-10 新任务发出第一条消息后,面板自动切过去**(用户 2026-09-25 定;取代 v0.1-8 的“关掉再打开”提示;规则见 plan.md 第 15 节)
+ - 查证:Codex 的侧边面板按任务保存,切换任务不用处理(桌面版前端代码,用户实测);在分叉里新开的面板绑在分叉上,勾选按规则继承(用户实测)。
+ - 子代理不单独处理,等开源后的反馈(用户 2026-09-25 定)。
+- [ ] **v0.1-11 分叉后打开面板有点卡**(用户 2026-09-25 报告;测量和改法见 plan.md 第 15 节)
- [x] **v0.1-7 许可证和 CI**(用户 2026-09-25 定:MIT,并加上 CI):`LICENSE`(插件目录里也放一份);`.github/workflows/ci.yml` 在 Windows、macOS、Linux 上跑单元测试;问题反馈模板,方便 macOS、Linux 用户在 GitHub 上报问题。
- 待定:Windows 上不先停用就移除插件,Codex 会断连,只能靠卸载命令恢复;要不要用计划任务让引擎不依赖插件启动,见 spec.md 第 5 节。