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
AGENTS.md
Context Attachment Manager(上下文素材管理器,2026-10-11 前叫 Codex Attachment Manager):让用户逐轮决定,Codex 任务和 Claude Code 会话里的哪些图片和文件进入下一轮请求。
从哪里读起
- docs/spec.md:目标、范围、硬约束和验收标准,是唯一的事实来源,描述当前版本。
- docs/design.md:技术方案,讲现在是怎么实现的。
- docs/v0.4/plan.md:Claude 桌面 Code 接入的 v0.4 变更方案;任务和验收分别见同目录的
tasks.md、acceptance.md。当前正式规格仍以docs/spec.md为准,未通过的迁移关卡不算已实现。 - docs/v0.5/plan.md:v0.5 方案,Claude Code 压缩后保留图片(已发布 0.5.0)。
- docs/v0.6/plan.md:v0.6 方案,默认开启自动选图、Claude 桌面版自动打开面板(已发布 0.6.0)。
- docs/v0.7/plan.md:v0.7 方案,Codex 的子代理和旁聊也自动选图(已发布 0.7.0)。
- docs/v0.8/plan.md:v0.8 方案,模型给每张图写特征行、压缩后照样拿对图,面板改成搜索加缩略图(已发布 0.8.0)。
- docs/v0.10/plan.md:v0.10 方案,压缩和续接之后照样拿回之前的图,编号不变(已发布 0.10.0;关卡结果见方案第 3 节)。
- docs/v0.11/plan.md:v0.11 方案,把插件拆成接入层、核心层、面板层,其他 Agent 平台只接核心、不带面板(已发布 0.11.0)。
- docs/history/v0.1/:v0.1 的开发记录(原方案、任务记录、各阶段报告、最初的构想),只作参考,不作依据。
- CHANGELOG.md:每个版本的更新记录,发布时就是 Release 说明。
- eval/README_CN.md:评测(英文版 eval/README.md),装插件和不装插件的对比:方法、结果和复现步骤。这一份是 Codex 里的关键帧对话;Claude Code 里压缩两次再分叉的长任务在 eval/long-task/。
已确认的规矩
- 原始对话记录和素材文件始终只读。
- 真实数据不进仓库:从真实会话和用户素材里提取的内容只能放在本机的
local/(已被 git 忽略)或工具的数据目录(Windows 是%USERPROFILE%\.codex-attachment-manager),任何时候都不提交。 - 插件本体在
plugin/(plugin/src是运行代码),测试和实验脚本在spike/,一行命令用的安装、卸载脚本在scripts/。改动运行代码后,要重新运行cam install,Codex 缓存里的插件副本才会更新;不要让已安装的配置指向不存在的文件。 scripts/*.ps1只用 ASCII 字符:Windows PowerShell 5.1 用irm … | iex下载时按 Latin-1 解码,中文会乱码。- 仓库里的文档和代码不写用户本机的具体路径;通用位置(如
~/.codex、%LOCALAPPDATA%)可以写。 - 对外的信息以英文为主:README.md、INSTALL.md、CONTRIBUTING.md、eval/README.md、仓库简介、CHANGELOG.md(发布时就是 Release 说明)用英文,README_CN.md、eval/README_CN.md 是中文版;
docs/下的规格、方案和开发记录,以及本文件,保持中文(用户 2026-09-28 定)。 - 评测的报告和结果放在
eval/,脚本在spike/src/eval-*.ts。README 是给所有用户看的,只在底部留一小节,用白话说两句并链接过去;评测是写给工程师看的(用户 2026-10-24 定)。 - CHANGELOG 的每一版(也就是 Release 说明)是写给所有用户看的:开头一句话说这一版带来什么,再用白话分“新功能”“修复”“更新后要做的”“怎么测的”,讲用户能感受到的变化;内部机制、token 数、版本号细节等写给工程师的内容,放进最后一个折叠的
<details>技术细节里(用户 2026-11-01 定)。 - 先在 Windows 上开发和测试。技术栈用 TypeScript/Node。
- 界面开发:Claude 自己截图检查效果;做到界面的关键节点时,截图给用户看,停下来等反馈再继续(用户 2026-09-24 确认)。
- 测试时调用模型一律用
gpt-6-sol,推理强度low,包括脚本自测和桌面版测试,为了省 token(用户 2026-09-24 要求)。 - 界面和提示文字分简体中文、英文两份:面板的在
plugin/src/panel/panel.html的文字表里,插件服务和命令行的在plugin/src/core/messages.ts。新增或修改文字时两份一起改,单元测试会检查条目一一对应。改发给模型的占位符和说明(plugin/src/core/words.ts)时,中文、英文(--lang en)各跑一次spike/src/v01-placeholder-selftest.ts(用户 2026-09-25 要求)和spike/src/v01-needs-selftest.ts(没有名字的工具截图全部取消后,模型能不能按编号要图、面板能不能认出来;用户 2026-09-26 要求);改的是自动选图的文字(自动版的占位符和说明、cam_view_image的说明和返回的文字)时,再跑spike/src/v03-auto-selftest.ts(模型该取图时会不会取、不该取时会不会不取;用户 2026-10-06 要求);改的是特征行说明时,再跑spike/src/v08-features-selftest.ts(模型会不会给新图写特征行、照原话记评价、正文里不提,压缩后能不能靠特征行拿对图;v0.8);改的是压缩后放回的说明和清单时,再跑spike/src/v10-compaction-selftest.ts(Codex 压缩之后,模型能不能靠清单认出之前的图、要看原图时按编号取对;v0.10)。这些自测三个 GPT-6 模型都要跑:gpt-6-sol、gpt-6-luna、gpt-6-astra,推理强度 low,用环境变量CAM_TEST_MODEL切换(用户 2026-09-28 要求)。自测在用户的 Codex 里建的任务,测完由脚本自动归档,不留给用户手动整理(用户 2026-09-28 要求);遗留的可以用spike/scripts/archive-test-threads.ts归档。 - 分工:Claude 维护
docs/下的规格和方案,并负责开发和测试(阶段 0 的 T0–T2 由 Codex 完成;测试需要在 Codex 之外启动 app-server,所以从 T3 起改由 Claude 执行)。其他协作者不修改 spec.md 和 design.md。
Git 规范
- 只维护
main一条长期分支,暂不设develop等分支。main必须始终可用。 - 不直接在
main上提交。每项工作都开一个短分支,命名格式为“类型/简短描述”,例如spike/phase0、feat/asset-index、fix/rollout-parse、docs/spec-update。 - 提交信息用约定式格式:
类型(范围): 描述,例如feat(indexer): 解析内联图片。 - 合并前先验证,确认相关测试和检查都通过。然后用
git merge --no-ff合并到main,不开 PR,合并后删除短分支。 - 不对
main强推,不改写main上已经推送的历史。 - GitHub 上
main有分支保护(用户 2026-09-28 要求):禁止强推和删除;其他人改main要提 PR,三个平台的 CI(test (windows-latest)、test (macos-latest)、test (ubuntu-latest))通过,并由仓库所有者批准。仓库所有者是管理员,不受这些限制,照常在本地--no-ff合并后推送。 - 远程只用 SSH(
[email protected]:…),不用 HTTPS。