前言¶
在 DeepSeek Harness（DSH）里做长时间编码或排错，会话 transcript 会不断变长。上下文触顶后，常见做法是走原生文本摘要：省 token，但命令、路径、标识符可能被改写或丢失。若你还需要「四十轮之前那条 shell 命令的原文」，摘要并不总是可靠。
dsh-snapcompact 是 Cyberbolt 维护的工作流类 DSH 插件（GitHub 约 2 stars，MIT 许可证）。它把被丢弃的中间历史在本地渲染成若干 PNG 位图帧，由支持图像输入的路由上的视觉模型直接阅读；该路径不调用摘要模型。精确的头尾文本仍留在上下文中，完整历史写入带 sha256 的可检索归档，可通过 snapcompact_recall 按行取回字符串。
下面介绍其定位、能力、安装与适用边界。事实以 GitHub 仓库 与 npm 包 dsh-snapcompact@0.6.0 文档为准。
这是什么¶
dsh-snapcompact 面向「会话已很长、仍需可追溯原文」的场景：压缩中间段时优先本地渲染为视觉帧，保留头尾明文，并维护可搜索归档与受控的 FILES 索引（来自 read/write/edit 调用，不是磁盘快照）。
与「全量保留原文」「单轮原生摘要」相比，插件 README 用表格概括了三者的取舍：原生摘要通常每轮上下文最小；视觉路径在无额外生成调用的前提下，单次压缩成本为 0（本地渲染），且归档中的精确字符串仍可事后召回。
核心功能¶
视觉路径：不调用摘要模型¶
中间被 DSH 选中丢弃的区域，经本地渲染变成多张可读 PNG。机制前提是：在清晰度允许范围内，视觉模型按图像面积计费，高密度帧有时能比同等字符数的明文更省 token——这是 README 给出的设计理由，具体是否划算取决于你的路由定价与图像 token 策略。
精确召回与 FILES 索引¶
- 头、尾对话文本保持在 checkpoint 中。
- 完整历史以
sha256:…等形式归档，checkpoint 中会提示使用snapcompact_recall取精确字符串。 FILES索引记录会话中出现的文件路径，并标注(Read)/(Write)/(RW)。
压缩方法链与安全回退¶
DSH 在安全区域内选择压缩策略，顺序为：
snapcompact → shake → soft
| 顺序 | 方法 | 模型调用 | 输出要点 |
|---|---|---|---|
| 1 | snapcompact | 无 | 密集帧、精确头尾、FILES、归档引用 |
| 2 | shake | 无 | 归档大工具输出，替换为有界摘要片段 |
| 3 | soft | 原生摘要 | DSH 文本摘要 |
仅当路由声明了图像输入与计价（或带标注的估算），且 checkpoint 能放进触发后剩余空间时，才走视觉方法；否则链路落到文本侧。取消压缩不会静默切换到下一方法。
区域选择、事务锁、恢复与容量检查仍由 DSH 宿主负责，插件不替代这些行为。
三种启用变体（preset）¶
安装后需在新会话中选择变体才会启用；已有会话保持创建时的 preset。minimal 不支持（故意省略 read/write/edit，与帧和归档召回的设计冲突）。
| 官方模式 | 界面选项 | 保留能力（README 表述） |
|---|---|---|
| standard | Snapcompact (Standard) | Shell、文件、搜索、子代理、工作流、Web、plan mode 等 |
| ptc | Snapcompact (PTC) | 仅 run_code 为直接工具，其余经 tools.* |
| cordis | Snapcompact (Cordis) | tool-cordis 与官方 Cordis 编写技能 |
安装与启用¶
环境要求（package.json / README）：
- DSH：
^0.2.2-rc.1（README 写明在0.2.2-rc.1上验证） - Node.js：24+
- npm 包内含已编译
dist/，无需本地 build
图形界面¶
- 打开 Plugins → Add plugin。
- 安装
dsh-snapcompact@0.6.0。 - 若提示则重启，新建会话并选择 Snapcompact (Standard)（或 PTC / Cordis）。
命令行¶
将 web 换成你的 profile 名。DSH Desktop 上优先用应用内 Plugins 页，CLI 可能写入桌面端未使用的 profile。
dsh plugin --profile web add dsh-snapcompact@0.6.0
README 还说明可通过本地 pnpm pack 产物或 tarball URL 安装；日常以 npm 预构建包为主。
安装会添加可选 preset，不会改写官方 preset 或正在运行的会话。
典型用法与自检¶
压缩发生后，上下文里会出现类似结构的 checkpoint（节选）：
Snapcompact v2; method=snapcompact
Exact archived history: sha256:…
Visual checkpoint: N frames; ¶ marks a source newline; use snapcompact_recall for exact strings.
FILES (from read/write/edit; not a disk snapshot)
…
需要某条历史里的精确命令或路径时，按 checkpoint 提示使用 snapcompact_recall，从归档按行读取，而不是依赖模型对帧的转述。
README 提供固定 fixture 基准（40 问）：Raw 38/40、Native summary 40/40、Snapcompact 36/40，中间段探测 8/10；并指出不同路由上优劣可能颠倒，建议在你的路线上执行 /snapcompact benchmark 自测。
适用场景与注意¶
较适合：
- 长时间编码、调试会话，上下文经常触顶。
- 路由对图像 token 相对便宜，且支持图像输入。
- 压缩后仍要找回精确字符串（命令、路径、标识符）。
不太适合：
- 短会话、纯文本路由，或 terse 摘要已足够时。
- 未选择 Snapcompact 变体的新会话之外仍期望自动生效（需在新会话里选 variant）。
安全与权限： 插件随当前 DSH 进程权限运行，可访问该进程能触及的资源。安装前请阅读源码与 MIT 许可证，确认符合你的合规要求。
社区目录 SkillHub 插件页 与 GitHub 为独立信息来源，与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 生态的通用理念，不代表官方应用商店。
结尾¶
dsh-snapcompact 把长会话中间段变成视觉模型可读的本地渲染帧，在视觉路径上避免摘要模型调用，同时用归档与 snapcompact_recall 保留精确字符串召回能力，并与 shake、原生 soft 摘要组成回退链。
- 目录页：https://www.skillhub.cn/plugins/Cyberbolt/dsh-snapcompact
- 源码与文档：https://github.com/Cyberbolt/dsh-snapcompact
