开源工具压缩AI Agent图片会话，50MB变2MB

背景

在使用 AI 编码助手（如 Claude Code、Codex 等）进行长时间开发会话时，用户常常需要频繁上传截图（如 UI 设计稿、报错信息等）。这些截图以 base64 编码的形式嵌入在对话历史中，并在每一轮请求中重复发送。这意味着即使模型在首轮已经看过某张图片，后续几十轮对话中依然会为该图片的 token 付费。随着会话进行，session 体积迅速膨胀，可能达到 50MB 甚至更大，导致上下文窗口被大量无用的历史图片占用，token 消耗飙升，甚至触发 HTTP 413 错误（请求体过大），整个会话被迫废弃。

官方统计显示，在 Claude Code 的一个真实 UI 开发会话中，86.3% 的上下文窗口被截图占据；Codex 方面，有用户抓到单个请求体高达 8.34MB，对应超过 500 万 prompt token。社区用户对此问题呼声很高，但官方修复进展缓慢。一位网名为“肥波”的开发者（自称交通专业，仅会粗浅 Python）在调研后决定自己动手，开发了一个开源项目 —— image-context-cascade，旨在解决这一痛点。

核心内容

该项目是一个请求级别的图片生命周期中间件，专门针对 AI 编码 Agent（如 Claude Code、Codex、Pi 等）设计。其核心思路是将会话中的图片按时间热度分为三类，并自动执行降级策略：

• Hot（热）：当前轮次上传的图片，原样保留，不影响正常使用。
• Warm（温）：近期历史图片，自动转换为缩略图。缩略图占用 token 大幅减少，但仍保留大致内容，AI 可据此判断是否需要将某张图片重新提升为 Hot 状态。
• Cold（冷）：更早的图片，被替换为稳定的占位符。占位符不包含原始图像数据，但 AI 可以在需要时主动找回原图（通过命令 image-cascade restore <hash>）。

该机制不会影响缓存命中率（经过优化实测），并且支持主流图片格式，甚至 base64 编码的 PDF。项目默认按需启用，即每次上传图片时自动执行优化；也可手动触发。

安装与使用：用户只需将一条配置指令发给 AI Agent（如 Pi、Claude Code、Codex 等），让 AI 读取项目文档并自动完成配置。例如：

Read and follow https://raw.githubusercontent.com/dlgod7/image-context-cascade/main/docs/setup/README.md
— identify which agent host YOU are running in, then apply the guide for YOUR host
(Pi / Claude Code / Codex / generic). This is configuration only: do NOT read, list,
or rewrite any session/transcript files. When done, report what you changed and how to undo it.

此外，项目还提供“抢救”功能，可对已有超大 session 进行分析和压缩：先 dry-run 查看可节省的空间，再执行实际压缩（生成备份文件，每张移除的图片均可通过 hash 找回）。

兼容性：项目对 Pi 等开源且允许修改请求构造的 Agent 支持最完整（“真满血”版）；对于 Claude Code、Codex 等闭源或不易修改请求构造钩子的 Agent，则提供“半自动”或通过 hook/CLI 实现的“残血”版。由于是中间件性质，不同用户的配置环境可能导致安装失败，但失败概率不大，且 AI 通常可以协助修复。

关键要点

• 问题根源：AI 编码 Agent 在长会话中重复发送历史截图，导致 token 浪费、session 膨胀、可能触发 413 错误。
• 解决方案：image-context-cascade 基于图片生命周期（Hot/Warm/Cold）自动降级，仅保留当前轮次图片原样，将历史图片转为缩略图或占位符，并支持按需恢复原图。
• 零运行时依赖：项目体积小，无需额外安装包，默认自动启用。
• 不影响缓存命中：经过优化，降级后 AI 的缓存机制仍能正常工作。
• 支持多种格式：包括常见图片格式和 base64 编码的 PDF。
• 使用方式：通过一条指令让 AI 自主配置，或手动执行 CLI 命令进行 session 分析和压缩。
• 兼容性提示：对不同 Agent 支持程度不同，Pi 最好，Claude Code/Codex 需半自动模式；可能存在安装失败个例，但 AI 可协助解决。
• 安全与备份：压缩操作会生成 .icc-backup 备份文件，每张被移除的图片均可通过 hash 找回，不会删除原始数据。
• 项目初衷：作者希望 coding Agent 能原生内置图片生命周期管理，届时本项目使命即完成。

意义与影响

1. 直接降低 AI 使用成本：对于频繁上传图片的开发场景（如 UI 设计、调试截图、视觉分析），该项目可大幅减少 token 消耗，节省 API 费用，并避免 session 因体积过大而报废。
2. 提升长会话的可用性：通过压缩历史图片，让 session 保持轻量，即使在几十轮对话后仍能流畅运行，不再因上下文窗口过载而中断。
3. 开源社区的实用工具：项目代码完全开源，且已通过社区推广规范验证，用户可自行修改、集成到本地工作流中。对于不同 Agent 的适配，社区也能贡献代码改进。
4. 推动行业改进：作者明确表示，希望该项目能促使主流 AI 编码 Agent 原生支持图片生命周期管理。如果官方采纳类似思路，将从根本上解决此问题，使得所有用户受益。
5. 降低技术门槛：整个项目由 AI 辅助开发（作者自称只会粗浅 Python），但最终效果良好，说明 AI 编程工具本身也能帮助非专业开发者解决复杂问题，形成良性循环。