Skip to content

Stop paying the multimodal tax. Your AI agent keeps every image it has seen but only sends the ones it needs: lighter chats, no endless reconnecting, no starting over. Works with Codex, Claude Code, Cline, Gemini CLI, OpenCode, WorkBuddy and more. Install once, forget it.

docs(release): 发布工作流、更新记录,文档按新的安装方式更新

chipfighterf1748b1ff8d4
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d2b9bdc..4c43b4c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,7 +3,9 @@
name: CI
on:
+ # Branches only: a release tag runs this workflow through release.yml.
push:
+ branches: ["**"]
pull_request:
workflow_dispatch:
workflow_call:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..d339f21
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,53 @@
+# A tag v<version> makes a draft release: CI runs on the three platforms, the tag must match the plugin's version, and
+# the one-line install scripts are attached with the tag written in, so each installs exactly this release. One plugin
+# serves Windows, macOS and Linux (Codex runs it with its own Node); the scripts are what differs per platform.
+# The draft is published by hand after a last look; "releases/latest/download/<script>" then points at it.
+name: Release
+
+on:
+ push:
+ tags: ["v*"]
+
+permissions:
+ contents: read
+
+jobs:
+ ci:
+ uses: ./.github/workflows/ci.yml
+
+ release:
+ needs: ci
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v7
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 24
+ - name: The tag must match the plugin's version
+ run: |
+ version=$(node -p "require('./plugin/.codex-plugin/plugin.json').version")
+ if [ "$GITHUB_REF_NAME" != "v$version" ]; then echo "tag $GITHUB_REF_NAME does not match plugin version $version"; exit 1; fi
+ - name: Install scripts for this release
+ run: |
+ mkdir dist
+ for file in install.sh uninstall.sh install.ps1 uninstall.ps1; do
+ sed "s/__CAM_REF__/$GITHUB_REF_NAME/g" "scripts/$file" > "dist/$file"
+ done
+ - name: Release notes from CHANGELOG.md
+ run: |
+ node --input-type=module - > dist/notes.md <<'EOF'
+ import { readFileSync } from "node:fs";
+ const version = process.env.GITHUB_REF_NAME.replace(/^v/, "");
+ const text = readFileSync("CHANGELOG.md", "utf8");
+ const start = text.search(new RegExp(`^## \\[?${version.replaceAll(".", "\\.")}\\]?`, "m"));
+ if (start < 0) throw new Error(`CHANGELOG.md has no section for ${version}`);
+ const rest = text.slice(start);
+ const next = rest.slice(1).search(/^## /m);
+ process.stdout.write(next < 0 ? rest : rest.slice(0, next + 1));
+ EOF
+ - name: Draft release
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: gh release create "$GITHUB_REF_NAME" dist/install.sh dist/uninstall.sh dist/install.ps1 dist/uninstall.ps1 --draft --verify-tag --title "$GITHUB_REF_NAME" --notes-file dist/notes.md
diff --git a/AGENTS.md b/AGENTS.md
index a9f3e41..8117a10 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,8 @@ Codex 上下文素材管理器(暂名):让用户逐轮决定,Codex 任
- 原始对话记录和素材文件始终只读。
- 真实数据不进仓库:从真实会话和用户素材里提取的内容只能放在本机的 `local/`(已被 git 忽略)或工具的数据目录 `%LOCALAPPDATA%\codex-attachment-manager`,任何时候都不提交。
-- 插件本体在 `plugin/`(`plugin/src` 是运行代码),测试和实验脚本在 `spike/`。改动运行代码后,要重新运行 `cam install`,Codex 缓存里的插件副本才会更新;不要让已安装的配置指向不存在的文件。
+- 插件本体在 `plugin/`(`plugin/src` 是运行代码),测试和实验脚本在 `spike/`,一行命令用的安装、卸载脚本在 `scripts/`。改动运行代码后,要重新运行 `cam install`,Codex 缓存里的插件副本才会更新;不要让已安装的配置指向不存在的文件。
+- `scripts/*.ps1` 只用 ASCII 字符:Windows PowerShell 5.1 用 `irm … | iex` 下载时按 Latin-1 解码,中文会乱码。
- 仓库里的文档和代码不写用户本机的具体路径;通用位置(如 `~/.codex`、`%LOCALAPPDATA%`)可以写。
- 先在 Windows 上开发和测试。技术栈用 TypeScript/Node。
- 界面开发:Claude 自己截图检查效果;做到界面的关键节点时,截图给用户看,停下来等反馈再继续(用户 2026-09-24 确认)。
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..1ab94a0
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,22 @@
+# 更新记录
+
+每个版本发布时,这里对应的一节就是 GitHub Release 的说明。
+
+## [0.1.0] - 未发布
+
+第一个公开版本(MVP):在同一个 Codex 任务里,逐轮决定哪些历史图片随下一条消息发给模型。
+
+### 功能
+
+- Codex 桌面版右侧的侧边面板里多出“上下文素材”:按轮次列出任务历史里的全部图片(上传的、模型查看和生成的),带缩略图、编号、来源、尺寸和大小,点开看大图。
+- 勾选的图照常发送;取消的图从下一条消息起换成占位符。有内容相同的图还在发送时,占位符指向那一张。任务不换,对话连续。
+- 省略图片时,给模型一条“上下文管理说明”:原图是用户为了节省上下文省略的,之前看着原图做出的回答仍然有效。模型不会因此收回之前的回答,也不编造没看到的细节;需要原图时回复“需要 IMG-xxx”。
+- 面板顶部预估下一条消息的请求大小,以及和全部发送相比省了多少;改写失败,或者 WebSocket 这一轮仍带着原图时会提示。
+- 安装不用开终端:在 Codex 的插件页面添加插件市场、装上插件,在面板里点“启用”。也可以用一行命令安装、卸载。
+- 卸载前在面板里点“停用”,Codex 恢复直连;卸载命令不需要插件文件,Codex 连不上时也能用它恢复。
+- 插件升级后,新引擎接替还在运行的旧引擎,正在进行的请求照常完成。
+
+### 平台
+
+- Windows:在 Codex 桌面版 26.917 上实测。
+- macOS、Linux:CI 上验证过 Codex 能装上插件、启动插件服务和引擎,安装、卸载脚本能正常工作;还没有人在这两个平台的桌面版上实测,欢迎在 issue 里反馈。
diff --git a/README.md b/README.md
index cbc9b43..86be391 100644
--- a/README.md
+++ b/README.md
@@ -10,45 +10,58 @@
- Codex 右侧的侧边面板里多出一个“上下文素材”标签页,按时间顺序列出这个任务里的全部图片:你上传的,以及模型查看、生成的。
- 取消勾选的图,从下一条消息起换成一小段占位文字。如果有内容相同的图还在发送,占位文字会指向那一张。任务不换,对话连续。
-- 模型需要某张被取消的图时,会回复“需要 IMG-xxx”。给不给,由你在面板里决定。
+- 模型知道那些图是你为了节省上下文省略的:它之前看着原图给出的回答仍然算数,不会因此改口,也不会编造没看到的细节。需要某张图时,它会回复“需要 IMG-xxx”,给不给由你在面板里决定。
- 面板顶部显示下一条消息会发送什么,以及请求大约能小多少。
## 工作原理
- 插件在本机启动一个小代理(引擎),Codex 发往 OpenAI 的请求先经过它。
-- 你取消勾选的图,在请求发出前被换成占位符;其余内容原样转发。
+- 你取消勾选的图,在请求发出前被换成占位符,并附上一条说明,告诉模型这些图是你省略的;其余内容原样转发。
- 勾选状态按任务分别保存,只有你能改,模型不能。
- 面板是 Codex 的插件页面,从侧边面板手动打开,不经过模型,也不花 token。
## 环境要求
-- Windows:Codex 桌面版,在 26.917 上实测过。
-- macOS、Linux:CI 上验证过 Codex 能装上插件、启动插件服务和引擎,但还没有人在这两个平台的桌面版上实测过。遇到问题请在 GitHub 上提 issue。
+- Codex 桌面版。Windows 上在 26.917 上实测过。
+- macOS、Linux:CI 上验证过 Codex 能装上插件、启动插件服务和引擎,安装和卸载命令也能正常工作;但还没有人在这两个平台的桌面版上实测过。遇到问题请[提 issue](https://github.com/chipfighter/codex-attachment-manager/issues)。
- 不需要另外安装 Node:插件使用 Codex 自带的 Node 24;找不到时,才用系统里 24 以上的 `node`。
## 安装
-```bat
-git clone [email protected]:chipfighter/codex-attachment-manager.git
-cd codex-attachment-manager
-cam install
+### 方式一:在 Codex 里安装,不用开终端
+
+1. 打开 Codex 的插件页面,点“添加插件市场”。
+2. “来源”填 `chipfighter/codex-attachment-manager`,其余留空,点“添加市场”。
+3. 在插件列表里找到“上下文素材管理器”,安装。
+4. 打开一个任务,点右上角“显示/隐藏侧边面板”,再点“新建标签页”,在“插件和 MCP”下选“上下文素材”。找不到的话,先重启一次 Codex。
+5. 面板顶部会提示“还没有接入 Codex”。点“启用”,然后**重启 Codex**。
+
+### 方式二:一行命令
+
+Windows(PowerShell):
+
+```powershell
+irm https://github.com/chipfighter/codex-attachment-manager/releases/latest/download/install.ps1 | iex
```
-安装会做下面几件事:
+macOS、Linux:
-1. 用 Codex 自己的命令行,把这个仓库登记为插件市场,并安装插件。
-2. 启动装好的插件服务做一次自检;通过了,才改下一步的设置。
-3. 在 `~/.codex/config.toml` 里写入一段带标记的代理设置。如果你的环境变量里设了代理,还会在 `~/.codex/.env` 里写一段 `NO_PROXY`,只包含本机地址。
+```bash
+curl -fsSL https://github.com/chipfighter/codex-attachment-manager/releases/latest/download/install.sh | sh
+```
+
+命令会用 Codex 自己的命令行装好插件,并写好代理设置。装完**重启 Codex**。以后再运行一次,就是升级到最新版本。
-改之前,`config.toml` 会先备份到数据目录。
+### 安装会改什么
-然后**重启 Codex**。
+- 在 `~/.codex/config.toml` 里写一段带标记的代理设置,改之前先备份到数据目录。
+- 如果你的环境变量里设了代理,还会在 `~/.codex/.env` 里写一段 `NO_PROXY`,只包含本机地址。
+- 别的设置一概不动。如果你自己已经设了 `openai_base_url`,安装会停下来,什么都不写。
## 使用
-1. 打开一个任务,点右上角“显示/隐藏侧边面板”。
-2. 在侧边面板里点“新建标签页”,在“插件和 MCP”下选“上下文素材”。
-3. 取消勾选不想再发送的图(点缩略图可以看大图),然后点“确定”。从下一条消息起生效。
+1. 打开一个任务,在侧边面板里打开“上下文素材”(位置见上面安装的第 4 步)。
+2. 取消勾选不想再发送的图(点缩略图可以看大图),然后点“确定”。从下一条消息起生效。
面板里的标签:
@@ -63,26 +76,42 @@ cam install
## 卸载
-```bat
-cam uninstall
+**先停用,再移除**:在面板标题右侧点“停用”并确认,然后在插件页面移除插件,重启 Codex。
+
+也可以用一行命令,它会恢复直连,并移除插件:
+
+Windows(PowerShell):
+
+```powershell
+irm https://github.com/chipfighter/codex-attachment-manager/releases/latest/download/uninstall.ps1 | iex
+```
+
+macOS、Linux:
+
+```bash
+curl -fsSL https://github.com/chipfighter/codex-attachment-manager/releases/latest/download/uninstall.sh | sh
```
-卸载会先恢复直连,再移除插件,最后提示你重启 Codex。
+勾选记录和日志留在数据目录里(见下面“数据和隐私”),不需要可以删掉。
+
+## Codex 连不上怎么办
-**请用这个命令卸载,不要只在 Codex 的插件页面里关掉或移除插件。** 只关插件的话,代理设置还在,却没有东西启动引擎,Codex 会连不上。万一遇到这种情况,运行一次 `cam uninstall` 就能恢复。
+如果没先停用就移除了插件,或者引擎没能启动,Codex 会报错,错误里带着 `localhost:17891`。这时运行上面的卸载命令,再重启 Codex,就能恢复直连。卸载命令不需要插件的文件,插件删掉了也能用。
-`cam status` 可以查看当前的安装状态。
+macOS、Linux 上,插件被移除或关掉后,引擎会自己恢复直连,下次启动 Codex 时生效。
## 已知限制
- 目前只管理图片,其他类型的文件以后再支持。
- Codex 自带生图工具的结果不能取消。
- 取消勾选时,如果这一轮对话还在进行,并且走的是 WebSocket,这一轮剩下的请求仍会带着原图。面板会提示,从下一条消息起生效。
+- 启用、停用和升级,都要重启 Codex 才生效。
- Codex 刚启动的头几十秒里,引擎可能会重启几次,偶尔会看到一次“正在重新连接”。
+- 引擎沿用系统代理:Windows 读系统设置,macOS 只认 HTTP(S) 代理(不支持 PAC 和 SOCKS),Linux 读 `HTTPS_PROXY` 等环境变量。
## 数据和隐私
-- 所有数据只留在本机的 `%LOCALAPPDATA%\codex-attachment-manager`:
+- 所有数据只留在本机的数据目录:Windows 是 `%LOCALAPPDATA%\codex-attachment-manager`,macOS 是 `~/Library/Application Support/codex-attachment-manager`,Linux 是 `~/.local/share/codex-attachment-manager`。里面有:
- 勾选记录;
- 请求统计:只记大小和数量,不记内容;
- 日志:不记对话内容和凭据;
@@ -92,10 +121,11 @@ cam uninstall
## 开发
-- 插件本体在 `plugin/`;`spike/` 里是测试和早期实验脚本。
-- 运行测试:`cd spike && node --test`
-- 不开 Codex 调面板:`node spike/scripts/panel-dev.ts`,然后在浏览器里打开 `http://127.0.0.1:17895/?solo=1`。页面用合成的测试图,不读取你的真实数据。
-- 规格、方案和各阶段报告在 `docs/` 下,从 [docs/spec.md](docs/spec.md) 读起。
+- 插件本体在 `plugin/`;`spike/` 里是测试和早期实验脚本;`scripts/` 里是一行命令用的安装、卸载脚本。
+- 从源码装进自己的 Codex:在仓库里运行 `cam install`(macOS、Linux 上是 `./cam install`),卸载用 `cam uninstall`,`cam status` 查看安装状态。
+- 运行测试:`cd spike && node --test`。CI 在 Windows、macOS、Linux 上跑全部单元测试,再用 Codex 自己的命令行真的装一遍插件、跑一遍安装和卸载脚本。
+- 不开 Codex 调面板:`node spike/scripts/panel-dev.ts`,然后在浏览器里打开 `http://127.0.0.1:17895/?solo=1`。页面用合成的测试图和一个临时的 Codex 目录,不读取、不修改你的真实数据。
+- 规格、方案和各阶段报告在 `docs/` 下,从 [docs/spec.md](docs/spec.md) 读起。更新记录见 [CHANGELOG.md](CHANGELOG.md)。
## 许可证
diff --git a/docs/plan.md b/docs/plan.md
index 5020b8a..3675925 100644
--- a/docs/plan.md
+++ b/docs/plan.md
@@ -338,7 +338,7 @@ P1 通过后,再按用户的节奏一步步探索改写。
- 仓库根目录的 `.agents/plugins/marketplace.json` 指向它;
- `spike/` 留测试和实验脚本。
- **启动**:
- - `.mcp.json` 用 `cmd.exe /d /s /c call ./scripts/launch.cmd ./src/plugin-server.ts` 启动插件服务,`launch.cmd` 优先用 Codex 自带的 Node;
+ - `.mcp.json` 用 `cmd.exe /d /s /c call ./scripts/launch.cmd ./src/plugin-server.ts` 启动插件服务,`launch.cmd` 优先用 Codex 自带的 Node(v0.1 起改成三个平台通用的 `./scripts/launch`,见第 14 节);
- 根目录的 `cam.cmd` 用同一个脚本运行命令行,用户不用另装 Node。
- **数据目录**:`%LOCALAPPDATA%\codex-attachment-manager`。插件目录会在更新时被 Codex 替换,而且不往 `~/.codex` 里写。
- **安装顺序**:
@@ -349,3 +349,52 @@ P1 通过后,再按用户的节奏一步步探索改写。
5. 迁移旧的勾选记录,确保引擎在运行。
- **卸载顺序**:先去掉代理设置,恢复直连;再卸插件、去掉市场。
- **已知风险**:只在插件页面关掉插件、不运行 uninstall,Codex 会连不上,见 spec.md 第 5 节。
+
+## 14. 发布准备(v0.1)
+
+### 已查证的事实
+
+依据 Codex 的公开源码(codex-rs)、官方文档、桌面版 26.917 的前端代码,以及 CI 上 npm 版命令行 0.157.0 的实测:
+
+- **三个平台都有桌面版**:Linux 版 2026-08 起预览,包名 `chatgpt`。macOS 桌面版的命令行在 `<app>/Contents/Resources/codex`;Codex 自己的安装脚本把命令行放在 `~/.local/bin/codex`。桌面版会把 `CODEX_CLI_PATH`、`CODEX_ELECTRON_RESOURCES_PATH` 传给插件服务。
+- **插件服务怎么启动**:
+ - Windows 上用 `which` 按 PATHEXT 解析命令,所以 `./scripts/launch` 会找到 `launch.cmd`;
+ - macOS、Linux 上直接运行命令,并放进新的进程组;
+ - 插件的 `cwd` 按插件目录解析。OpenAI 自带插件也是同一套:一个无扩展名的 POSIX 脚本,加一个同名的 `.cmd`。
+- **Windows 的 Job**:插件服务在一个“关闭即结束、不许脱离”的 Job 里,它启动的引擎也在里面,服务一结束引擎就跟着结束。所以插件被移除后,Windows 上没有我们的进程还能收尾。macOS、Linux 上引擎用 `setsid` 脱离了进程组,会留下来。
+- **桌面版的插件页面能添加插件市场**:来源可以是 GitHub 仓库(`owner/repo`)、Git 地址或本地文件夹,可选 Git ref。所以用户可以完全不开终端:添加市场、装插件,再在面板里启用。
+- **Windows PowerShell 5.1**:`irm … | iex` 把 GitHub 发布文件按 Latin-1 解码,脚本里的中文会乱码,所以两个 `.ps1` 只用 ASCII。
+- **Windows 上的句柄继承**:Node 在 Windows 上启动子进程时,子进程会继承父进程可继承的句柄。所以引擎会拿着启动它的脚本的输出管道;只有测试会因此多等,用户不受影响。
+
+### 设计
+
+- **一份 `.mcp.json` 通用三个平台**:命令写 `./scripts/launch`,`scripts/launch`(POSIX,可执行位,LF)和 `scripts/launch.cmd` 按同样的顺序找 Node:
+ 1. Codex 传来的路径;
+ 2. 桌面版资源目录里的 `cua_node`;
+ 3. primary runtime;
+ 4. PATH 上 24 以上的 `node`。
+- **平台差异**:
+ - 进程检测:Windows 用 `tasklist`,其他平台用 `ps` 按可执行文件名 `codex` 统计;
+ - 系统代理:Windows 读注册表,macOS 读 `scutil --proxy`(只认 HTTP(S) 代理),Linux 只看环境变量;
+ - 数据目录:macOS 在 `~/Library/Application Support`,Linux 按 XDG。
+- **升级时替换引擎**:引擎报告 build(运行目录里 .ts 文件的哈希,换行统一成 LF)和版本。插件服务发现代码不同、版本不低,就请旧引擎退役:
+ - 旧引擎立刻停止监听,放掉空闲连接,把正在进行的请求和 WebSocket 这一轮做完再退出;
+ - 新引擎马上接手端口。
+- **启用、停用**(`setup.ts`,命令行、面板和引擎共用):只增删带标记的块,改之前备份 config.toml,整文件写好再替换。
+ - 面板的 `cam_setup` 只接受面板的调用;
+ - 启用、停用都要重启 Codex 才生效,面板会提示。
+- **插件被移除或关掉、没先停用**:
+ - 引擎每 15 秒检查一次,判断依据只用明确的迹象:插件缓存目录不在了,或者 config.toml 写着 `enabled = false`;
+ - 连续两次,或者引擎退出前再查一次,就恢复直连;
+ - 在 Windows 上这一步通常来不及(见上面的 Job),所以面板、插件说明和 README 都写“先停用再移除”,卸载命令负责恢复。
+- **安装路径**:
+ - 插件页面:添加市场 `chipfighter/codex-attachment-manager` → 装插件 → 面板里启用 → 重启;
+ - 一行命令:`install.ps1` / `install.sh` 用 Codex 的命令行装插件,再运行装好的副本里的 `cam.ts setup`;
+ - 卸载:`uninstall.ps1` / `uninstall.sh` 不需要 Node 和插件文件,先按同样的规则去掉带标记的块,再卸插件和市场。
+- **发布**:推送 `v<版本>` 标签后,Release 工作流先在三个平台跑 CI,再核对标签和插件版本一致,然后把标签写进四个脚本,建一个草稿 Release。说明取自 CHANGELOG.md。人工看过再发布。
+ - 三个平台共用同一个插件,只有安装脚本分平台;
+ - `releases/latest/download/<脚本>` 始终指向最新的发布。
+- **验证**:
+ - `spike/src/plugin-smoke.ts`:Codex 自己的命令行装插件,app-server 开任务,插件服务就绪,引擎启动;
+ - `spike/src/scripts-smoke.ts`:真的跑安装、卸载脚本,config.toml 和 .env 恢复原样;
+ - CI 在 Windows、macOS、Linux 上都跑这两项和全部单元测试。
diff --git a/docs/spec.md b/docs/spec.md
index d0d9a88..8cc6add 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -19,7 +19,7 @@
### 免配置
-用户不需要手动编辑任何文件。工具自动找到 Codex 的目录(Windows 上是 `CODEX_HOME`,没设时是 `%USERPROFILE%\.codex`),自动完成接入。每个任务(session)各有一套自己的勾选状态,互不影响。
+用户不需要手动编辑任何文件。工具自动找到 Codex 的目录(`CODEX_HOME`,没设时是 `~/.codex`),自动完成接入。每个任务(session)各有一套自己的勾选状态,互不影响。
代理跟着 Codex 一起启动、一起退出(用户 2026-09-24 确认)。只要配置指向代理,代理就必须在运行,否则 Codex 连不上。
@@ -75,15 +75,17 @@
- 原始对话记录和素材文件始终只读,不修改、不移动、不删除。不直接写入 `~/.codex` 下的任何文件,只有四个例外:
- 通过 Codex 自己的命令行登记插件市场、安装和卸载插件时,Codex 对 `config.toml` 和插件缓存的正常写入(P5);
- 官方 app-server 在创建和运行任务时自己产生的正常写入;
- - 为接入本地代理和面板服务,工具可以修改 `config.toml` 里由它自己管理、带标记的设置(用户 2026-09-24 授权)。改之前先备份,能一键恢复,其他设置一律不动;
+ - 为接入本地代理和面板服务,工具可以修改 `config.toml` 里由它自己管理、带标记的设置(用户 2026-09-24 授权)。改之前先备份,能一键恢复,其他设置一律不动。只在这些时候改:用户运行安装或卸载命令;用户在面板里点“启用”或“停用”;插件被移除或关掉、又没先停用时,引擎把 Codex 恢复直连(v0.1);
- 为让生图和改图也能连到本地代理,工具可以在 `~/.codex/.env` 里写一段带标记的 `NO_PROXY`,只含本机地址,并保留用户自己的条目(用户 2026-09-24 同意)。`.env` 可能含密钥,工具不复制、不输出它,只增删自己的那一段;文件里只剩这一段时,恢复时连文件一起删掉。
-- 真实数据不进仓库:从真实会话和用户素材里提取的图片、记录片段、日志和备份,只能放在本机,开发时放在 `local/` 目录(已被 git 忽略),装好的插件放在数据目录 `%LOCALAPPDATA%\codex-attachment-manager`;任何时候都不提交。仓库里的样例数据只能是合成的或脱敏的。
+- 真实数据不进仓库:从真实会话和用户素材里提取的图片、记录片段、日志和备份,只能放在本机,开发时放在 `local/` 目录(已被 git 忽略),装好的插件放在数据目录(Windows 是 `%LOCALAPPDATA%\codex-attachment-manager`,macOS 是 `~/Library/Application Support/codex-attachment-manager`,Linux 是 `~/.local/share/codex-attachment-manager`);任何时候都不提交。仓库里的样例数据只能是合成的或脱敏的。
- 仓库里的文档和代码不写用户本机的具体路径(例如个人项目文件夹)。`~/.codex`、`%LOCALAPPDATA%` 这类通用位置可以写。本项目以后会开源。
- 不改写原生任务的历史记录。
- 代理只替换用户取消的图片,连同 Codex 附在它前后的路径标签;有图片被省略时,另外插入一条“上下文管理说明”开发者消息(用户 2026-09-25 要求告诉模型原因,见第 1 节“占位符”)。请求里的其他内容原样转发。
- 选择权永远在用户:哪些素材进入上下文,只由用户在面板里勾选决定。工具和模型都不能自动勾选或取消;模型只能按约定索要(例如回复“需要 IMG-004”),给不给由用户决定。
-- 先在 Windows 上开发和测试。技术栈:TypeScript/Node。
-- 交付形态:Codex 插件。插件带一个本地 MCP 服务,负责拉起引擎、提供面板;仓库根目录就是插件市场。用户运行 `cam install` 一次装好,`cam uninstall` 一次恢复。面板位置见第 1 节“界面”。
+- 先在 Windows 上开发和测试。技术栈:TypeScript/Node。macOS、Linux 由 CI 验证能装上、能启动;这两个平台桌面版上的实测,等用户在 GitHub 上反馈(用户 2026-09-25 定)。
+- 交付形态:Codex 插件。插件带一个本地 MCP 服务,负责拉起引擎、提供面板;仓库根目录就是插件市场。面板位置见第 1 节“界面”。
+ - 用户在 Codex 的插件页面添加插件市场 `chipfighter/codex-attachment-manager`、装上插件,再在面板里点“启用”;卸载前在面板里点“停用”。
+ - 也可以用发布附带的一行命令安装、卸载。开发时用仓库里的 `cam install` / `cam uninstall`。
## 4. 验收标准
@@ -114,7 +116,7 @@
> 按代理路线写成(2026-09-24 改写,原来按路线 A 写的版本已作废)。第 8、9 条是用户 2026-09-25 定的 v0.1 安排。
-1. 装好后不用手动配置:工具自动接入 Codex,代理跟着 Codex 一起启动、一起退出;关闭工具时一键恢复,只删掉自己写入的内容。
+1. 装好后不用手动配置:在插件页面装上插件后,面板里点“启用”(或者用一行命令安装),代理就跟着 Codex 一起启动、一起退出;卸载前点“停用”(或者用一行命令卸载),一键恢复直连,只删掉自己写入的内容。
2. 在 Codex 里打开面板,按时间顺序列出当前任务的全部图片出现记录,包括缩略图、编号、名称、来源、轮次、尺寸、大小、内容相同的关系和勾选状态。无法识别或不能取消的项要单独标出。
3. 勾选、取消、重新勾选都从下一次请求起生效;对话始终在同一个任务里,连续可见。
4. 面板显示本次会发送什么:照常发送的图、重复占位符和普通占位符,以及取消前后的请求大小对比。
@@ -128,4 +130,7 @@
- 路线:路线 A(用 `thread/inject_items` 在新任务里重建)技术上可行,但用户不接受“重建后在界面上看不到原对话”。代理路线(任务不换,每次请求发出前由本地代理按勾选改写)已在桌面版验证通过:P1 只转发、P2 按勾选改写,生图和改图也包括在内,见 plan.md 第 9、10 节和 p2-report.md。面板已在 P4 做完,见 p4-report.md。
- 许可证:MIT(用户 2026-09-25 确定)。
-- 只在 Codex 的插件页面里关掉或移除插件、没有运行 `cam uninstall` 时,代理设置还在,却没有东西启动引擎,Codex 会连不上。现在的做法是在 README 里写明,并让 `cam uninstall` 随时能恢复。要不要让引擎不依赖插件启动(例如用 Windows 计划任务),需要用户同意在系统里注册任务,之后再定。
+- 在插件页面移除或关掉插件、没先在面板里停用时,代理设置还在:
+ - macOS、Linux 上,引擎会发现这一点,把 Codex 恢复直连,下次启动 Codex 时生效。
+ - Windows 上,引擎随插件服务一起被结束(Codex 的 Job 限制,见 plan.md 第 14 节),Codex 会连不上,要运行卸载命令恢复。面板、插件说明和 README 都提示“先停用再移除”。
+ - 要不要让引擎不依赖插件启动(例如用 Windows 计划任务),需要用户同意在系统里注册任务,之后再定。
diff --git a/docs/tasks.md b/docs/tasks.md
index 0310150..0680f91 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -25,10 +25,19 @@
- 引擎用 `ps` 检测 Codex 进程;macOS 读系统代理(`scutil --proxy`);数据目录按平台惯例;找 Codex 命令行的位置按平台区分;根目录加 POSIX 版 `cam`。
- `spike/src/plugin-smoke.ts`:用 Codex 自己的命令行把插件装进临时目录,再由 app-server 开任务,确认插件服务起来、工具和面板都在、引擎启动;不用登录。本机桌面版的命令行(0.155.0-alpha)和 CI 上 npm 的命令行(0.157.0,三个平台)都通过,macOS、Linux 上装进缓存后启动脚本仍可执行。
- 没验证到的:macOS、Linux 桌面版里的面板显示,以及系统代理下 Codex 能否连到本机引擎,要等用户反馈。
-- [ ] **v0.1-5 更方便的安装**:用户不用打开 GitHub,就能把插件装进 Codex,并完成代理设置。
-- [ ] **v0.1-6 在 GitHub 上发布 v0.1**。
+- [x] **v0.1-5 更方便的安装**(`setup.ts`、`panel.html`、`plugin-server.ts`、`scripts/`;新增 3 个单元测试,共 92 个;证据:CI 上三个平台的 `scripts-smoke.ts` 都通过;设计见 plan.md 第 14 节)
+ - 不开终端:桌面版的插件页面能“添加插件市场”(来源填 `chipfighter/codex-attachment-manager`),装好插件后,在面板里点“启用”,重启 Codex。
+ - 面板:
+ - 没接入时显示“启用”;
+ - 标题右侧的“停用”要确认一次;
+ - 启用、停用后提示重启 Codex 生效;
+ - 工具 `cam_setup` 只接受面板的调用。
+ - 一行命令:`install.ps1` / `install.sh` 用 Codex 的命令行装插件,再运行装好的副本里的 `cam setup`;`uninstall.ps1` / `uninstall.sh` 不需要 Node 和插件文件,Codex 连不上时也能恢复。
+ - 插件被移除或关掉却没先停用:macOS、Linux 上引擎会恢复直连;Windows 上引擎随插件服务一起结束(Codex 的 Job 限制),只能靠停用或卸载命令。面板、插件说明和 README 都写了“先停用再移除”。
+ - 顺手修复:引擎的工作目录不再是插件目录;面板开发页的导入路径,以及它改用临时 Codex 目录。
+- [ ] **v0.1-6 在 GitHub 上发布 v0.1**:Release 工作流已备好(`.github/workflows/release.yml`:推 `v0.1.0` 标签后先跑三个平台的 CI,再建草稿 Release,附带写好版本号的四个安装、卸载脚本,说明取自 `CHANGELOG.md`)。发布前还差最后一步【需用户】:README、演示视频、截图、仓库目录结构调整;仓库改成公开。
- [x] **v0.1-7 许可证和 CI**(用户 2026-09-25 定:MIT,并加上 CI):`LICENSE`(插件目录里也放一份);`.github/workflows/ci.yml` 在 Windows、macOS、Linux 上跑单元测试;问题反馈模板,方便 macOS、Linux 用户在 GitHub 上报问题。
-- 待定:只关插件、不卸载时 Codex 会断连(见 spec.md 第 5 节)。
+- 待定:Windows 上不先停用就移除插件,Codex 会断连,只能靠卸载命令恢复;要不要用计划任务让引擎不依赖插件启动,见 spec.md 第 5 节。
---
diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json
index 7a8ea4f..7b143a4 100644
--- a/plugin/.codex-plugin/plugin.json
+++ b/plugin/.codex-plugin/plugin.json
@@ -13,7 +13,7 @@
"interface": {
"displayName": "上下文素材管理器",
"shortDescription": "选择哪些历史图片随下一条消息发给模型",
- "longDescription": "长任务里的图片会一轮轮累积在上下文里。这个插件在 Codex 右侧的侧边面板里,按时间顺序列出任务历史里的全部图片:勾选的照常发送,取消的换成占位符(有内容相同的图还在发送时,指向那一张)。任务不换,对话连续。模型需要某张图时会回复“需要 IMG-xxx”,给不给由你决定。所有数据只留在本机;除了 Codex 本来就要发给 OpenAI 的请求,不向任何地方发送数据。",
+ "longDescription": "长任务里的图片会一轮轮累积在上下文里。这个插件在 Codex 右侧的侧边面板里,按时间顺序列出任务历史里的全部图片:勾选的照常发送,取消的换成占位符(有内容相同的图还在发送时,指向那一张)。任务不换,对话连续。模型需要某张图时会回复“需要 IMG-xxx”,给不给由你决定。所有数据只留在本机;除了 Codex 本来就要发给 OpenAI 的请求,不向任何地方发送数据。装好后打开面板(侧边面板 → 新建标签页 → 插件和 MCP → 上下文素材),点“启用”,再重启 Codex。移除插件前,请先在面板里点“停用”。",
"developerName": "chipfighter",
"category": "Productivity",
"capabilities": ["Interactive", "Read", "Write"],