会话图片清理 ArbeiterKlassen/dsh-thread-image-cleaner

dsh-thread-image-cleaner

清理 DeepSeek Harness（DSH）会话里累积的图片引用，解决「读图读多了」导致的请求体膨胀、首字延迟暴涨、历史图片每次请求都要重发一遍的问题。

这是 Codex 生态里 codex-thread-image-cleaner 技能的 DSH 适配版。机制完全不同——

| | Codex 版 | DSH 版 |
| 存储 | thread_history_1.sqlite + rollout JSONL | session.v4.jsonl.zstd（zstd 多帧 JSONL）+ 附件内容寻址仓库 |
| 清理方式 | 等长字节中和 + 改 SQLite 的 path 引用 | 追加 image/offload 事件（append-only，DSH 原生支持） |
| 风险 | 破坏字节偏移会毁掉分页/lineage | 不动历史字节，只加一条事件；投影由 DSH 自己算 |

为什么需要它

DSH 不会把图片字节内联进会话日志，日志里只有引用：

{"type":"image","attachment":{"attachmentId":"sha256:1bf28b11…","mediaType":"image/png",
"bytes":279732,"width":1400,"height":840,"name":"copturex-dsh.png"}}

真实字节在 %USERPROFILE%\.dsh\attachments\v1\objects\<前2位hex>\<sha256>。

问题在于：每轮请求都会重放整段历史。一张 270 KiB 的截图在历史里出现一次，之后每个 request 都要把这份字节重新发一遍；同一张图被读 3 次、会话跑 50 轮，成本就翻着涨。Codex 那边直接表现为 413 Payload Too Large，DSH 这边表现为请求体越来越大、首字延迟越来越长。

解法：DSH 原生的 image/offload

DSH 自己就带 dsh-compaction-image-offload 包，契约是追加一条事件：

{"type":"image/offload","seq":776,"data":{"targets":[{"seq":423,"imageIndexes":[0]}]}}

投影时把被引用事件里的对应 image 块标成 offloaded:true，模型侧换成一段占位文本 + 附件只读路径（文件本身不删，想看随时还能读回来）。本仓库把这条契约的校验规则完整镜像了一遍，生成的事件保证能被 harness 的 imageOffloadProjection 接受。

安装

git clone https://github.com/ArbeiterKlassen/dsh-thread-image-cleaner.git \
"$USERPROFILE/.dsh/skills/dsh-thread-image-cleaner"

依赖：Python 3.9+，纯标准库（zstd 走 ctypes 绑 libzstd，找不到就回退 zstd CLI）。

工具

| 脚本 | 作用 |
| probe_images.py | 只读清点：有几张图、多大、哪些还在被重发、哪些已卸载 |
| offload_images.py | 生成并追加 image/offload 事件（DSH 官方路径） |
| verify_images.py | 验证「现在还剩多少字节在重发」 |
| tombstone_images.py | 在副本上做墓碑式重写，用于导出/归档不含图片的会话 |

cd "$USERPROFILE/.dsh/skills/dsh-thread-image-cleaner/scripts"

python probe_images.py # 默认当前/最新会话
python probe_images.py --session 94811e6d # id 前缀 / 完整 id / 目录 / 日志路径都可以

python offload_images.py --largest 3 # 干跑：只打印计划事件
python offload_images.py --seq 423 --indexes 0 --force # 真写（要求 DSH 已关闭）
python verify_images.py # 复查：still sent 0 occurrence(s), 0B

python tombstone_images.py --copy %TEMP%\clean-copy\session.v4.jsonl.zstd

常用参数

probe_images.py：--session --json --limit offload_images.py：--seq（可重复/逗号分隔）--indexes --oldest N --largest N --all --dry-run（默认）--force --allow-running --json tombstone_images.py：--session --copy <目标日志路径> --dry-run --json verify_images.py：--session --json

安全规则（非常重要）

1. 写操作要求 DSH 客户端关闭。 运行中的 DSH 自己持有 seq 计数器并追加 zstd 帧，外部写入会和它撞车。脚本会主动检测并拒绝，--allow-running 只在你清楚后果时用。
2. 先在副本上演练。 tombstone_images.py --dry-run 和 offload_images.py（默认干跑）都不会碰原文件。
3. offload 不删图。 附件文件仍在 attachments\v1\objects\ 里，想看就用 read_image 读那个路径。
4. 想彻底瘦身（连磁盘一起）才用 tombstone_images.py，它写的是副本，原会话保持完整。

已验证

- 真实会话：probe 定位到 seq 423 tool/result 273.2KiB 1400x840 copturex-dsh.png；干跑输出 append seq 776 {"targets":[{"seq":423,"imageIndexes":[0]}]}；写入副本后 verify 报 still sent 0 occurrence(s), 0B。
- 用 harness 自己的投影代码验证：把 dsh-compaction-image-offload/lib/types/projection.js 抽出来重放 surface 后调用 project()，单图 1/1 标记、多图全标记、--indexes 1 只标记 1/3。
- 9 类畸形声明全部被原生校验拒绝（data must contain a nonempty targets array、duplicate target seq、image index 99 does not exist、target seq N is not a current surface node、image index 0 is already offloaded 等）。

注意

- 逐行重写会让文件比源文件略大（每行一个 zstd 帧），这是预期行为。
- 会话日志格式随 DSH 版本变化，脚本只依赖公开的事件契约；遇到不认识的类型会跳过而不是报错。

许可

MIT