# dsh-compaction-optical

[English](README.md) | 中文

这是一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/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 技术报告](https://arxiv.org/abs/2510.18234)提出的历史记忆方向：把文字映射为二维视觉表示，并对更旧页面逐级缩放。这个插件实现的是 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：

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

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

```yaml
allowBuilds:
  'dsh-compaction-optical@https://codeload.github.com/cyijun/dsh-compaction-optical/tar.gz/<commit>': true
```

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

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

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

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

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

## 配置

Bundle 默认配置为：

```yaml
- 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 发布说明](https://api-docs.deepseek.com/news/news260821)写明，每张图片按最高 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` 是实际控制边界。

## 验证

```sh
pnpm install
pnpm run check
```

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

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

```sh
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 集成。