JessenReinhart/dsh-snapcompact

dsh-snapcompact

用于 DeepSeek Harness（DSH）的位图帧上下文压缩插件。

灵感来自 @oh-my-pi/snapcompact。

snapcompact 不要求 LLM 用有损的文字描述来总结被丢弃的对话历史，而是将确切的对话序列化，并把文本渲染成由像素字体字形组成的密集 PNG 帧，供视觉模型直接读取。整个过程是本地、快速且确定性的——没有辅助 LLM API 调用，没有摘要延迟，除了紧凑的位图帧之外没有任何额外的 token 成本开销。

功能特性

- 本地且确定性：使用原生像素字体渲染（@oh-my-pi/pi-natives）进行高吞吐量光栅化。
- 感知提供商的形状：
- anthropic（11on16-bw）：8x13 字体，11px 步进，黑白。
- google（8on22-bw）：8x13 字体，22px 间距，针对 Gemini 视觉预算调优。
- openai（8on22-bw）：8x13 字体，22px 间距，以 detail: "original" 发送。
- cjk（silver16-bw）：Silver TrueType 字体，16x16 网格，用于东亚（中文、日文、韩文）文本。
- 结构化转录序列化：
- ¶user: 用户消息部分
- ¶think: 助手推理块
- ¶ai: 助手消息部分
- ¶call: name(args)//intent 带参数的工具调用
- ... 格式化的工具结果，带有变暗的噪声
- 自动 FILES 部分，跟踪读取和修改的文件（(Read)、(Write)、(RW)）
- DSH 附件集成：
- 渲染 PNG 帧并通过 ctx.attachments.saveImages 持久化它们
- 完全兼容 DSH 会话持久化和重放
- 命令与服务支持：
- /snapcompact [--frames ] [--shape ] [--all] 命令，用于按需手动压缩
- SnapcompactEngine 实现标准的 DSH CompactionEngine 服务
- 在 agent/pre-step 上自动进行步骤压力压缩
- 在 agent/request-error 上自动进行上下文溢出恢复

安装

1. 克隆到 DSH Profile

将仓库克隆到你当前活跃的 DSH profile 的 packages/ 目录中（例如 desktop）：

Windows PowerShell
git clone https://github.com/JessenReinhart/dsh-snapcompact.git "$env:USERPROFILE\.dsh\profiles\desktop\packages\dsh-snapcompact"

macOS / Linux
git clone https://github.com/JessenReinhart/dsh-snapcompact.git ~/.dsh/profiles/desktop/packages/dsh-snapcompact

2. 在 Profile 配置中注册 Bundle

将 packages/dsh-snapcompact 添加到你的 profile 的 package.json（例如 ~/.dsh/profiles/desktop/package.json）中的 dsh.profile.bundles：

{
"dsh": {
"profile": {
"bundles": [
"packages/dsh-snapcompact"
]
}
}
}

该插件通过捆绑的 cordis.patch.yml 自动挂载其 Cordis 行。

3. 原生光栅化器

Snapcompact 使用高性能的原生像素字体光栅化器二进制文件（pi_natives..node）。
插件会自动从以下任意位置发现此二进制文件：
- ~/.omp/natives//pi_natives..node
- ~/.bun/install/cache/@oh-my-pi/pi-natives-*
- 环境变量覆盖：PI_NATIVES_PATH=/path/to/pi_natives..node

4. 重启 DSH

重启 DeepSeek Harness 以加载配置文件包。在聊天中，使用以下命令进行测试：
/snapcompact status

用法

命令

在任何 DSH 会话聊天中：

- /snapcompact — 使用智能默认值立即归档较早的历史记录（自动形状，最多 8 帧，以纯文本形式保留 16% 的近期 token）。
- /snapcompact auto — 在代理空闲时切换自动后台压缩。
- /snapcompact auto on — 启用自动空闲压缩。
- /snapcompact auto off — 禁用自动空闲压缩。
- /snapcompact auto threshold  — 设置触发空闲压缩的上下文窗口阈值百分比（默认 80%）。
- /snapcompact status — 显示当前配置、阈值和实时会话 token 使用情况。
- /snapcompact --frames  — 使用自定义最大帧数归档历史记录。
- /snapcompact --shape  — 使用特定的字体/形状变体归档历史记录（11on16-bw、8on22-bw、silver16-bw）。
- /snapcompact --all — 归档所有符合条件的历史记录，不保留近期纯文本。

持久化

自动压缩偏好设置会保存到 ~/.dsh/snapcompact-config.json，并在会话和应用程序重启后保持不变。

编程式压缩

const snapcompact = ctx.get("snapcompact");
await snapcompact.compactNow(agent, signal);