dsh-snapcompact
Verifieddsh-snapcompact · v0.6.2 · MIT · Web UI
DeepSeek Harness plugin that compacts long chats by rendering history into compact bitmap frames a vision model can read, while keeping exact head/tail text and a searchable archive.
Install
dsh plugin add dsh-snapcompact Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-snapcompact
English · 简体中文
把长会话渲染成图片来压缩,而不是总结掉。
会话变长时,Snapcompact 把对话中段渲染成密集的 PNG 帧,交给视觉模型直接阅读。视觉路径本身不调用摘要模型;精确头尾文本留在原位,可检索归档保存原文,命令、路径和标识符都能找回。
适合长代码或调试会话——几十轮之后,你还要精确找回某条命令。不适合短会话、纯文本模型或 minimal 模式。
安装: 插件 → 添加插件 → [email protected] → 新建会话 → Snapcompact (Standard)。无需构建。
为什么用图片
视觉模型主要按图片面积计费,和图片里塞了多少字符关系不大。在可读的前提下,一帧密集图片用同样的 token 能装下更多字符。于是,被丢弃的中段变成几张可读的图片,而不是一段有损摘要。
| 原始历史 | 原生摘要 | Snapcompact(视觉路径) | |
|---|---|---|---|
| 保留内容 | 全部 | 摘要 | 精确头尾 + 归档中段 |
| 压缩成本 | 0 | 一次模型调用 | 0(本地渲染) |
| 每轮上下文 | 最大 | 通常最小 | 比原始小,通常比精简摘要大 |
| 精确字符串 | 有 | 可能丢失 | 可从归档回查 |
什么时候划算: 长历史、图片 token 便宜的路由,以及压缩后仍要精确找回原文的工作。什么时候不划算: 短会话、纯文本路由,或者一段精简摘要就够用。
你得到什么
- 视觉路径不调用摘要模型。 渲染在本地完成:没有生成成本,不联网,也不需要额外的 API key。
- 压缩后仍能精确回查。 精确头尾文本 + 可检索归档;
snapcompact_recall可以逐行读取。 - 文件地图不会丢。 由 read/write/edit 调用生成的有界
FILES索引,带(Read)/(Write)/(RW)标记。 - 失败有兜底。
snapcompact → shake → soft,原生摘要是最后一步。 - 保留 DSH 原生行为。 区间选择、事务锁、恢复和容量校验仍由宿主负责。
实测
| 对照(fixture v3,三次) | 接受匹配 | 严格匹配 | 中段 | 每轮读取 | 一次性生成 |
|---|---|---|---|---|---|
| 原始历史 | 40/40 | 38.7/40 | 60/60 | 15,955 | 0 |
| 原生摘要 | 38.3/40 | 37.3/40 | 59/60 | 1,701 | 24,409 |
| Snapcompact(仅帧) | 34.0/40 | 33.7/40 | 43/60 | 6,803 | 0 |
| Snapcompact + recall(出厂配置) | 40/40 | 36.7/40 | 60/60 | 30,841 | 0 |
2026-11-11 用路由 opencode-go/deepseek-v4.1-flash 的真实三次运行。出厂配置——帧加 snapcompact_recall——在接受匹配上打平未压缩原文(三次都是 40/40),并超过原生摘要(38.3/40);checkpoint 本身用 6,803 token 承载 63,423 字符历史。只用帧是 34/40:剩下的中段标识符需要每道精确串题做一次 search,所以 recall 臂的每轮读取更高——那是单回合回答 40 题时 24 次校验调用,不是稳态成本。严格匹配更低,因为带标签的引用算接受匹配但不算逐字相同。协议见 evaluation.md,明细见 evaluation-results.md。
安装
需要 DSH ^0.2.2-rc.1(在 0.2.2-rc.1 上验证)和 Node.js 24+。npm 包已包含编译后的 dist/,没有构建步骤,也没有安装脚本。0.2.x 的 patch 可以直接安装,不需要重新发布插件;下一条 minor 只在重新验证后才会声明。
- 打开 插件(Plugins)→ 添加插件(Add plugin)。
- 安装
[email protected]。 - 若页面提示重启,按提示完成;然后新建会话,选择变体。
| 官方模式 | 选择 | 保留的行为 |
|---|---|---|
standard |
Snapcompact (Standard) | shell、文件工具、搜索、子代理、workflow、web、plan mode |
ptc |
Snapcompact (PTC) | run_code 仍是唯一直接工具,其余工具通过 tools.* 调用 |
cordis |
Snapcompact (Cordis) | tool-cordis 与官方 Cordis 技能目录 |
安装只会新增可选 preset,不会修改官方 preset 或运行中的会话;选中变体就是启用动作,已有会话保持启动时的 preset。minimal 不提供:这个模式刻意去掉 read/write/edit,加入帧和归档回查会违背其定位。
通过命令行安装:
dsh plugin --profile web add [email protected]
把 web 换成你实际使用的 profile。使用 DSH Desktop 时优先用应用内插件页:CLI 可能写入桌面端不使用的 profile。
其他分发来源
也可以安装本地打包的 tarball 或 tarball URL:
pnpm install --ignore-scripts
pnpm pack
dsh plugin --profile web add "file:$PWD/dsh-snapcompact-0.6.0.tgz"
dsh plugin --profile web add https://example.com/dsh-snapcompact-0.6.0.tgz
npm 包是预构建选项;使用本地源码时需要先执行 pnpm pack(或 pnpm run build)。
工作原理
DSH 选择安全的压缩区间
│
▼
精确归档(sha256) ── 在 checkpoint 之后仍然保留
│
▼
snapcompact → shake → soft
│
▼
原生事务提交一个 checkpoint
| 顺序 | 方法 | 模型调用 | 产出 |
|---|---|---|---|
| 1 | snapcompact |
无 | 密集帧、精确头尾、FILES 索引、归档引用 |
| 2 | shake |
无 | 大工具输出先归档,再用有界摘录替代 |
| 3 | soft |
原生摘要 | DSH 原生文本摘要 |
只有当路由声明支持图片输入并提供计价(或带标签的估算),且 checkpoint 放得进触发阈值下的剩余空间时,才会走视觉路径;否则按链回退到文本。取消会终止本次压缩,不会静默改用下一种方法。
一个 checkpoint 大致如下(已删节;示例为实际 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)
(Read) read-only; (Write) written without a read; (RW) read and written
# src/compaction/
visual-source.ts (Read)
## methods/
snapcompact.ts (RW)
[exact text head]
[frame 1 of N] … [frame N of N]
[exact text tail]
[file] snapcompact archive reference
使用
| 入口 | 作用 |
|---|---|
/compact |
手动压缩;在任一 Snapcompact preset 内由 Snapcompact 链执行 |
/snapcompact status |
查看路由、有效阈值、可压空间、各方法可用性和归档数量 |
/snapcompact benchmark [1-5] |
运行合成 v3 对照;单次最多八次辅助调用,可能产生费用 |
snapcompact_recall |
列举、分页读取或字面量搜索归档 |
{ "action": "list" }
{ "action": "read", "archiveId": "sha256:…", "offset": 0, "limit": 100 }
{ "action": "search", "archiveId": "sha256:…", "query": "pnpm deploy --filter" }
回查返回物理行号和 (nextOffset, nextColumn) 游标。文本分页最多返回 200 行片段和 20,000 个 UTF-16 码元。搜索是区分大小写的字面量子串匹配,不是正则。只有当前会话中已完成压缩引用过的归档 ID 才能访问。
配置
插件 → Snapcompact 设置卡覆盖常用项,通过 DSH 的设置服务写入当前 profile 的配置补丁。一张卡同时配置三个变体;保存后的改动对新会话生效。
| 界面项 | 配置键 | 默认 |
|---|---|---|
| 方法链 | methodOrder |
[snapcompact, shake, soft] |
| 触发阈值 | policy.thresholdRatio |
宿主默认 0.8 |
| 保留尾部 | 自动派生 thresholdRatio ÷ 5;YAML 可用 retainRatio / retainTokens 覆盖 |
0.8 时 0.16 |
| 帧尺寸 | rendering.width / rendering.height |
1568 |
| 最多帧数 | rendering.maxFrames |
20(上限 64) |
| 归档上限 | archiveMaxBytes |
64 MiB |
| 外置阈值 | shakeThresholdChars |
8192 |
guard、serialization、routePolicies 和渲染上限只在 YAML 里配置。完整字段见配置文档。
限制与隐私
- 不是无损压缩。 帧可能漏字符;行尾不可见空格会被裁掉,每个源换行变成
¶。以归档为准,但归档也救不回其他插件已经删掉的内容。最多携带 4 张已有图片。 - 省不省取决于路由和使用时长。 短会话里精简摘要可能更小;长历史或图片 token 便宜时视觉路径更划算。checkpoint 更小,不等于账单更低。
- 图片路径的适用条件很窄。 路由必须声明图片输入和计价;帧不可读或预算不够时回退文本。路由没有图片计价时,DSH 自身的上下文计量可能在下一次 provider usage 锚定前滞后;插件用自己的保守帧价做视觉 gate。
FILES是索引,不是磁盘快照。 它只看 read/write/edit,不看bash或 apply-patch。- 无遥测。 归档保存在 profile 的 attachment 存储里,对话数据不会上传到别处。
常见问题
安装后 preset 选择器里没有 Snapcompact 变体
先确认插件显示为已安装;如果插件页要求重启,请完成重启;然后新建会话,查找 Snapcompact (Standard)、Snapcompact (PTC) 和 Snapcompact (Cordis)。已有会话会保持它启动时使用的 preset。使用 DSH Desktop 时,请确认是通过应用内插件页安装,而不是装进了桌面端不使用的 CLI profile。
总是回退文本,从不渲染图片
运行 /snapcompact status。最常见的原因是当前路由没有声明图片输入或没有图片计价,这是预期的安全行为。历史中已有图片时会优先携带,最多 4 张;没有剩余图片槽位时才回退到文本链(shake 摘录 → 原生摘要)。
压缩失败,提示 “No compaction method produced a safe smaller checkpoint”
说明所有候选都被跳过或未通过预算检查。先看 /snapcompact status,等历史更长一些再试,或换用文本摘要可用的路由。错误信息会列出每个方法的原因;取消是单独报告的,不会继续回退。
启动被拒绝,提示 “leaves only … of the window compactable”
通常是 YAML 里显式写了 retainRatio/retainTokens,留给 checkpoint 的空间太小。提高 policy.thresholdRatio、降低或删除显式尾部,或设置 guard.minCompactableRatio: 0。
压缩失败,提示 “below the …-token floor”
本次源历史小于 max(1024, 窗口 × guard.minSourceRatio)。等历史更长再压缩,或调低 guard.minSourceRatio(设为 0 关闭收益门槛)。该守卫在创建归档和调用方法之前运行,所以没有产生任何开销。
安装被判定为不兼容
这个构建声明 DSH ^0.2.2-rc.1,并在 0.2.2-rc.1 上验证。请安装声明了你所用 minor 的 Snapcompact 版本;不要手改兼容性检查来强装。
文档
开发
pnpm install --ignore-scripts
pnpm run check # 类型、lint、格式、构建、preset、测试、包资源
pnpm run check:install # 把打包后的 tarball 安装到一次性 DSH profile
pnpm run release:plan # 预演当前版本是否会被发布
pnpm pack
check:install 不会触碰真实 profile,临时目录保留在 .artifacts/ 下,可用 --keep 保留用于排查。DSH 包是宿主提供的 peer;开发安装只用于本地类型和集成测试模块。本包不需要安装脚本。
源码按压缩、归档、渲染、计量、DSH 适配和评测分层,开启严格 TypeScript 检查。建议从架构与阅读顺序开始。注释与主文档使用英文,中文文档同步维护。
许可
原创应用代码使用 MIT。内置的 GNU Unifont 18.0.01 数据保留 SIL Open Font License 1.1;见第三方声明。