dsh-compaction-optical
English | 中文
An independent, experimental optical-memory compaction provider for DeepSeek Harness. It keeps the released @deepseek-ai/dsh-compaction-basic pressure policy, retention selection, overflow recovery, lock, retry, and durable replacement transaction, but overrides the existing protected summarize() hook so the replacement summary contains generated PNG pages.
This project is not an official DeepSeek release. It currently targets the 0.1.1-rc.2 Harness packages and the exact model id deepseek-v4-flash-vision-exp.
The package is marked private only to prevent accidental npm publication; GitHub source and tarball installation remain supported.
The design explores the historical-memory direction proposed by the DeepSeek-OCR technical report: text is mapped into a two-dimensional visual representation, and older pages may be progressively resized. This plugin is a Harness-level memory format, not DeepSeek-OCR's learned DeepEncoder, and it does not claim equivalent OCR or agent-task accuracy.
Modes
| Mode | Renderer input | Auxiliary model call |
|---|
direct | Selected canonical messages with role labels, text, reasoning, tool calls, and tool results. Native images remain independent image blocks. | None. |
summary | The safe text output from the inherited basic summarizer, then rasterized as optical memory. | One ordinary purpose: compaction call. Its provider, model, cap, usage, and raw output remain in the standard compaction/summary fields. |
Both modes write a versioned JSON manifest as the first summary text block, followed by generated pages and preserved native images. The stock compaction transaction records those blocks and places the same references in its replacement user message, so replay needs no Harness schema patch.
In direct mode, a later compaction recognizes an earlier optical checkpoint by CompactionId, validates its recorded summary blocks, and reads the page attachments directly. It does not OCR them back to text. When the page count exceeds maxPages, the oldest eligible contiguous group becomes an ordered 2x2 contact sheet and its generation increments. The operation fails instead of discarding content after maxGeneration prevents further aging.
Install from GitHub
The repository ships a dsh.bundle patch that disables the default compaction-basic provider, inserts compaction-optical, and adds the invariant companion:
dsh plugin --profile headless add github:cyijun/dsh-compaction-optical
A git dependency runs this package's prepare build. pnpm 10 and later require explicit authorization before executing package code. After the first command reports the blocked package, copy its complete printed key into the profile's pnpm-workspace.yaml, then run it again. For a pinned commit, the setting resembles:
allowBuilds:
'dsh-compaction-optical@https://codeload.github.com/cyijun/dsh-compaction-optical/tar.gz/<commit>': true
Replace <commit> with the full commit SHA from the install command. Do not grant broad authorization to arbitrary sources.
Verify the effective layer and model route before starting a task:
dsh --profile headless --dump-config
dsh --profile headless "your task"
Pin a commit in production, for example github:cyijun/dsh-compaction-optical#<commit>. The active conversation route must resolve to deepseek-v4-flash-vision-exp and declare image input; missing routing, a different model, or a text-only catalog entry fails before the summary commits.
The included bundle is supported only in the headless profile. The shipped Web bundle keeps compaction inside Agent Presets; installing this bundle into Web would add a Host-plane provider without rewriting those preset definitions, so that composition is intentionally unsupported.
Configuration
The bundle defaults to:
- id: compaction-optical
name: dsh-compaction-optical
config:
mode: direct
thresholdRatio: 0.8
retainRatio: 0.16
maxPages: 8
maxGeneration: 1
All BasicCompactionConfig fields remain available. Optical fields are:
| Key | Default | Meaning |
|---|
mode | direct | Render selected messages directly, or render the existing text compact result with summary. |
rendererProfile | deepseek-v4-flash-vision-exp-v1 | Fixed renderer/target profile; other values fail load. |
pageWidthPx / pageHeightPx | 800 / 800 | Generated PNG dimensions. |
marginPx | 24 | Inset on every edge. |
fontSizePx / lineHeightPx | 12 / 16 | Text size and baseline distance. |
characterWidthRatio | 0.62 | Monospace width multiplier used for deterministic wrapping. |
tabWidth | 2 | Spaces used to expose one tab. |
fontFamily | CJK-capable fallback list | SVG font-family list used by sharp. |
maxPages | 8 | Maximum generated pages retained in one checkpoint. |
maxGeneration | 1 | Maximum number of 2x2 aging composites applied to a page. |
Native images consume the attachment service's per-message image count and aggregate byte limits. The generated-page budget shrinks to leave slots for those images, and duplicate attachment ids are retained once in first-seen order.
Token accounting
DeepSeek's V4 Vision release note says each image is tokenized for billing at up to 384 tokens. That is a billing ceiling, not a guarantee about semantic capacity.
The released Harness 0.1.1-rc.2 compaction hook prices the replacement through the generic token-meter estimator, which currently estimates an ImageBlock from its serialized attachment reference. It has no provider-specific image-price override. Consequently, the basic backend's shrink check and projected context pressure are heuristic and do not reproduce the official 384-token ceiling. maxPages is the practical bound until the upstream compaction seam exposes producer-specific replacement pricing.
Verification
pnpm install
pnpm run check
The keyless suite covers renderer validation, CJK-width wrapping, PNG dimensions, cancellation, recursive aging, direct and text-first modes, replay manifests, attachment limits, target-model failures, the invariant companion, and Loader composition.
A real API calibration checks whether the default renderer recovers one exact literal. It runs only when both environment variables are present:
DEEPSEEK_API_KEY=... DEEPSEEK_VISION_E2E=1 pnpm run test:e2e
Model experience
The model sees one user-role compact checkpoint with the basic backend's framing, then the optical manifest, ordered page images, and any preserved native images. Recent retained messages follow unchanged. In summary mode, only the rasterized safe summary is visible; the summarizer's reasoning and raw output remain log-only.
Replacing the first selected message invalidates KV-cache reuse after that position. Reused attachment identities make recursive checkpoints auditable but do not guarantee provider-side image-cache reuse.
Known limitations
- Optical compression is lossy. DeepSeek-OCR reconstruction measurements do not establish long-horizon agent recall, code fidelity, or tool-use accuracy for this renderer and model.
- The renderer uses host fonts. Wrapping, manifest fields, page order, and source digests are stable, but exact raster bytes may vary across machines.
- Page aging is ordered and bounded, not learned or salience-aware.
- The public Harness hook cannot persist a dedicated optical encoding union or exact provider-specific replacement price without upstream changes.
- The included bundle supports the headless profile only; Web Agent Preset integration is not included.
