光学记忆压缩器cyijun/dsh-compaction-optical

dsh-compaction-optical

这是一个面向 DeepSeek Harness 的独立实验性光学记忆压缩 provider。它保留已发布 @deepseek-ai/dsh-compaction-basic 的压力策略、保留区间选择、上下文溢出恢复、锁、重试和持久替换事务，只覆盖现有的 protected summarize() 钩子，使 replacement summary 由生成的 PNG 页面组成。

本项目不是 DeepSeek 官方发布。目前目标版本为 Harness 0.1.1-rc.2，并绑定精确模型 id deepseek-v4-flash-vision-exp。

package.json 标记为 private 只是为了防止意外发布到 npm；仍然支持从 GitHub 源码或 tarball 安装。

设计探索 DeepSeek-OCR 技术报告提出的历史记忆方向：把文字映射为二维视觉表示，并对更旧页面逐级缩放。这个插件实现的是 Harness 层的记忆格式，不是 DeepSeek-OCR 训练得到的 DeepEncoder，也不声称具备等价的 OCR 或 agent 任务准确率。

两种模式

| 模式 | renderer 输入 | 辅助模型调用 |
|---|---|---|
| direct | 带角色标签的被选规范消息，包括文字、推理、工具调用和工具结果；原生图片保持独立图片块。 | 无。 |
| summary | 先由继承的 basic summarizer 生成安全文字，再将结果栅格化为光学记忆。 | 一次普通 purpose: compaction 调用；provider、model、cap、usage 与 raw output 继续保存在标准 compaction/summary 字段中。 |

两种模式都会把带版本的 JSON manifest 写为 summary 的第一个文字块，后面依次放生成页面和保留的原生图片。原有 compaction 事务会记录这些块，并在 replacement 用户消息中使用同一批引用，因此重放无需修改 Harness 的 session schema。

在 direct 模式中，后续压缩通过 CompactionId 识别已有光学 checkpoint，校验其已记录 summary 块并直接读取页面附件，不会先 OCR 回文字。页面数超过 maxPages 时，最旧且符合条件的连续页面组会合成为有序 2x2 contact sheet，代际加一；达到 maxGeneration 后如果仍无法满足页面预算，操作会失败，不会静默丢弃内容。

从 GitHub 安装

仓库附带 dsh.bundle patch：先禁用默认 compaction-basic provider，再插入 compaction-optical 并加载 invariant companion：

dsh plugin --profile headless add github:cyijun/dsh-compaction-optical

Git 依赖会运行本包的 prepare 构建。pnpm 10 及以上版本在执行包代码前要求显式授权；第一次命令报告被拦截的包后，把它打印的完整键原样加入 profile 的 pnpm-workspace.yaml，再执行一次。固定 commit 时，配置类似：

allowBuilds:
'dsh-compaction-optical@https://codeload.github.com/cyijun/dsh-compaction-optical/tar.gz/': true

这里的  必须替换成安装命令中的完整 commit SHA；不要对任意来源使用宽泛授权。

启动任务前先核对实际配置层和模型路由：

dsh --profile headless --dump-config
dsh --profile headless "你的任务"

生产环境应锁定 commit，例如 github:cyijun/dsh-compaction-optical#。当前对话路由必须解析到 deepseek-v4-flash-vision-exp，并声明支持 image 输入；缺少路由、模型不符或 catalog 只支持文字，都会在 summary 提交前失败。

附带 bundle 只支持 headless profile。Harness 自带的 Web bundle 把压缩能力放在 Agent Preset 内；把本 bundle 安装进 Web 会新增 Host-plane provider，却不会改写这些 preset 定义，因此该组合明确不受支持。

配置

Bundle 默认配置为：

- id: compaction-optical
name: dsh-compaction-optical
config:
mode: direct
thresholdRatio: 0.8
retainRatio: 0.16
maxPages: 8
maxGeneration: 1

所有 BasicCompactionConfig 字段仍然可用。光学字段如下：

| 键 | 默认值 | 含义 |
|---|---:|---|
| mode | direct | 直接渲染被选消息；summary 则渲染既有文字 compact 结果。 |
| rendererProfile | deepseek-v4-flash-vision-exp-v1 | 固定 renderer/目标 profile；其他值会在加载时失败。 |
| pageWidthPx / pageHeightPx | 800 / 800 | 生成 PNG 的尺寸。 |
| marginPx | 24 | 页面四边留白。 |
| fontSizePx / lineHeightPx | 12 / 16 | 字体大小与基线间距。 |
| characterWidthRatio | 0.62 | 确定性换行使用的等宽字符宽度乘数。 |
| tabWidth | 2 | 一个 tab 展开的空格数。 |
| fontFamily | 支持 CJK 的回退列表 | sharp 使用的 SVG font-family 列表。 |
| maxPages | 8 | 一条 checkpoint 最多保留的生成页面数。 |
| maxGeneration | 1 | 一个页面最多经历的 2x2 老化合成次数。 |

原生图片会占用 attachment 服务的单消息图片数量和总字节上限。生成页面预算会缩减以为它们留出位置；重复 attachment id 只按首次出现顺序保留一次。

Token 计量

DeepSeek 的 V4 Vision 发布说明写明，每张图片按最高 384 token 计费。这是计费上限，不是语义容量保证。

已发布 Harness 0.1.1-rc.2 的 compaction 钩子通过通用 token-meter estimator 计算 replacement；它目前根据序列化后的附件引用估算 ImageBlock，没有 provider 专属图片价格 override。因此 basic backend 的缩小判断与投影上下文压力都只是启发式数值，并不等于官方 384-token 上限。在上游 compaction seam 支持 producer 专属 replacement 计价前，maxPages 是实际控制边界。

验证

pnpm install
pnpm run check

无密钥测试覆盖 renderer 校验、CJK 宽度换行、PNG 尺寸、取消、递归老化、直接与先文字后光学两种模式、重放 manifest、附件上限、目标模型失败、invariant companion 和 Loader 组合。

真实 API 校准会检查默认 renderer 能否找回一个精确字面量；只有同时设置两个环境变量时才运行：

DEEPSEEK_API_KEY=... DEEPSEEK_VISION_E2E=1 pnpm run test:e2e

模型体验

模型会看到一条用户角色 compact checkpoint：先是 basic backend 的 framing，再是光学 manifest、有序页面图片和保留的原生图片；较新的保留消息原样跟在后面。summary 模式只让模型看到栅格化后的安全摘要，summarizer 的推理与 raw output 仍只存在日志中。

第一条被选消息被替换后，该位置之后的 KV cache 复用会失效。复用 attachment 身份让递归 checkpoint 可审计，但不保证 provider 侧复用图片 cache。

已知限制

- 光学压缩有损；DeepSeek-OCR 的重建测量不能证明这个 renderer 和模型具备长程 agent 记忆、代码保真或工具使用准确率。
- Renderer 使用宿主字体。换行、manifest 字段、页面顺序和源 digest 保持稳定，但精确像素字节可能因机器而异。
- 页面老化按顺序且有次数上限，不具备学习得到的显著性判断。
- 在不修改上游的前提下，Harness 当前公共钩子无法持久化专用 optical encoding union，也无法记录精确的 provider 专属 replacement 价格。
- 附带 bundle 只支持 headless profile；尚未包含 Web Agent Preset 集成。