dsh-read-animation 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,124 +1,169 @@
-# Changelog
-
-## 0.1.1 — 2026-10-14
-
-Fixed after the first release, from what a live session reported back.
-
-- **`read_animation` follows the path it advertises.** Every image a model receives
-  is shown as a normalized copy at `attachments/v1/objects/<2>/<digest>`, and that
-  is the path a model reaches for when it wants to look at the picture again. For a
-  pasted animation that copy is a single frame, so the tool answered "this picture
-  has one frame": true of that file, and useless as an answer. The tool now resolves
-  that path to the animation this plugin kept, and reports the file the bytes
-  actually came from. A bare `sha256:<digest>` is accepted too.
-- **The sheet says where the animation lives.** Its header ends with the path the
-  store keeps the original at, so a model that wants more than the eight samples can
-  read that path with explicit frame indices instead of searching the attachment
-  store for the file behind the picture it was sent.
-
-## 0.1.0 — 2026-10-14
-
-First release.
-
-Note for anyone publishing a later version of this package: npm routes the first
-release of a brand-new package name through staged publishing, and the registry
-carries a public `0.0.0-stage` placeholder while the real version is processed. The
-real version appears on its own a couple of minutes later; nothing needs approving.
-
-### Fixed after an adversarial audit
-
-Four independent reviews (blast radius, plugin code, packaging and lifecycle, then
-an adversarial pass over every high-severity finding) ran before this was
-published. What they found, and what changed:
-
-- **The frame sheet's `variantId` was not a content digest.** It was a hand-rolled
-  `sha256:filmanim…` string, and the DeepSeek adapter validates persisted ids
-  against `/^sha256:[0-9a-f]{64}$/` when it loads its upload index — then swallows
-  the failure into an *empty* index. The effect was not a visible error: it
-  discarded every other session's cached file id and re-uploaded every image.
-  Reproduced against the real exported index class (plugin id: written 1, reloaded
-  0; conforming id: 1/1). It is now the SHA-256 of the bytes being returned, which
-  also stops one on-disk cache entry from aliasing two different byte streams.
-- **The degraded path was worse than the missing feature.** The store reaches the
-  frame it re-encodes through its own `readImage` call, which this plugin wraps, so
-  falling back to the store's request read could hand the model the *whole
-  animation* where it expects one frame. The request path now suspends the
-  animation substitution around that call, and reads its own tiles through the
-  unwrapped read. Pinned by an integration check that breaks a stored frame and
-  asserts the fallback is exactly one frame.
-- **No decoded-pixel ceiling on the `read_animation` path.** `limitInputPixels`
-  was disabled with nothing in its place: a 60 KB file declaring a 9000x9000
-  canvas was refused by the deployment's own attachment store and decoded here
-  anyway, at about 310 MiB. Both the probe and the frame extraction now carry the
-  deployment's `imageLimits.maxImagePixels`.
-- **The sheet cache ignored the size the caller asked for**, so a caller with an
-  8 KiB budget could be served a 28 KB sheet built for a 4 MiB one. The target is
-  now part of the cache key, and a tile is never larger than a single frame would
-  have been for that caller.
-- **The measured header wrap could still be defeated.** A floor of 16 characters
-  kept the loop from reaching a budget that fit, so on a narrow canvas it gave up
-  and returned ink wider than the sheet. The floor is now low enough to be
-  satisfiable, and a canvas too narrow for legible text gets no header at all.
-- **The canvas was composed before it was shrunk**, building a 6156x6306 (about
-  111 MiB) image to throw away. Tile size and grid are settled first.
-- **Torn state files could poison the next record.** A crash part way through an
-  append left a line with no newline, so the following record concatenated onto it
-  and became unreadable too. A torn tail is now detected and compacted away.
-- **The store's bound applied to memory but not to what was read back**, and the
-  log was never compacted. Both fixed; the file is rewritten when it grows past
-  twice the entries worth keeping.
-- **Teardown was last-writer-wins.** Each install captured whatever was on the
-  method, so disposing one left another's patch removed and could reinstall a
-  disposed closure as a permanent own property. Three wrappers now share one
-  installer that resolves its delegate per call, removes cleanly (deleting an
-  inherited property rather than leaving a shadow behind), and reports whether it
-  actually took effect — the previous identity check compared a value that proxy
-  reads always re-wrap, so it could never detect a failed install.
-- **`npm test` did not run the invariant checks.** The no-`@deepseek-ai`-import
-  rule and the bundle/manifest consistency check lived only in the integration
-  harness, which prints SKIP and exits 0 without `DSH_HARNESS_MODULES`. Both now
-  run in `npm test`, which is also the `prepublishOnly` gate.
-- **`files[]` omitted `scripts/`** while `package.json` advertised two npm scripts
-  that live there, so the published package's own scripts were broken.
-
-- **A pasted animation keeps playing in the UI, and the message is left alone.**
-  The browser already uploads an animated GIF/WebP byte-for-byte and labelled as
-  such; the Host flattens it to a single
-  frame during prompt admission and keeps no copy of the source. The plugin wraps
-  `ctx.attachments.admitPromptContent` to capture the frames and the original file
-  at that moment, and `ctx.attachments.readImage` so the UI is served the animation
-  itself (the browser animates whatever bytes that one read returns). What you send
-  is what you send: the chat message is unchanged.
-- **The model now receives a labelled sheet of the frames.** The delivery step is
-  `ctx.attachments.readImageRequest(ref, target, signal)`, the method each adapter
-  calls to build its own copy of one image. It answers with exactly one image, so
-  the frames are composed into a grid chosen to be as square as the sheet budget
-  allows — every tile at its native size, with the frame index, duration and start
-  time printed under each, and the animation's own facts in a wrapped header. The
-  sheet is built once per animation and cached.
-- Rewriting the request from an `llm/stream` listener is **not** used and would not
-  work: a loop-built request arrives deep-frozen ("listeners read it, never rewrite
-  it"), so that earlier attempt silently did nothing.
-- Captured frames and the original are persisted per `$DSH_HOME` in
-  `read-animation/v1/pasted.jsonl`, keyed by the message's attachment id, so a
-  session resumed in a new process still displays — and still delivers — an
-  animation pasted before the restart.
-- A frame's index and start time ride in its attachment display name
-  (`x.gif#frame16@1960ms`), which the harness renders beside the picture once the
-  frames are delivered — so the timing never has to be repeated as message text.
-  (An earlier version of this feature put a header plus one caption per frame into
-  the user's own message; consecutive text parts are concatenated by the UI with
-  no separator, so a one-image message became an unreadable wall.)
-- `read_animation` tool: decodes an animated GIF or animated WebP, samples frames
-  across the timeline (or by explicit index / instant), commits each frame to the
-  attachment store, and returns a header plus one captioned image per frame.
-- Refuses animated PNG by name instead of silently returning its first frame,
-  which is what the host image library does with one.
-- Refuses static images and points at `read_image`; answers a single-frame GIF or
-  WebP with a note that it is not animated.
-- Discloses decode-time substitutions in the model-facing text: zero frame
-  delays treated as 100 ms, missing delays, transparency flattened onto white.
-- The package imports no `@deepseek-ai/*` module at runtime, so it loads both as
-  an installed package and as a `link:`ed checkout. The compiled schemas ship as
-  literals beside their authoring specs, and the integration harness keeps the
-  two in step.
+# Changelog
+
+## 0.1.2 — 2026-11-08
+
+- Fix [#7](https://github.com/NeoHotaru/dsh-read-animation/issues/7). Capture
+  uploaded GIF and animated WebP bytes at `attachments.saveImages`. DSH 0.2.2
+  normalizes uploads before prompt admission, so its stored references previously
+  bypassed capture. Original animation display, model frame sheets, and
+  normalized-copy reads now use the captured source.
+- Add raw-upload regressions through the real attachment store and, on DSH
+  0.2.2, its upload service and receipt resolution. Update the integration fixture
+  for the separate native tool executor and batch execution API.
+
+
+- **The supported DSH range is measured rather than assumed.** The plugin wraps
+  internal service methods, and `engines.dsh` claimed `>=0.1.7-alpha.1` on the
+  strength of one working install. The integration suite now runs against
+  `0.1.3-alpha.2` (the oldest release exposing every member), `0.1.7-alpha.2`,
+  `0.2.0-rc.2` — which is `latest` — and `0.2.1-alpha.3`, all 38/38, and
+  `scripts/check-dsh-compat.py` reads the type declarations of all 32 published
+  releases to find the floor: **0.1.3-alpha.2**. See
+  [COMPATIBILITY.md](COMPATIBILITY.md), including what is *not* claimed.
+- **A host missing a member now says so.** Nothing checked the members the plugin
+  calls before calling them: a host with `readImage` but no `saveImages` mounted
+  cleanly and then threw a `TypeError` from inside the tool. Mount reports every
+  missing member with the release it arrived in, the tool names the reason in its
+  own error, and a test covers the check itself.
+- **`preview-sheet` printed a path that does not exist.** It spelled the store
+  layout as `files/<name>` where the store uses `files/<2>/<digest>/<name>`. The
+  plugin asks `fileHostPath` and was always right; only the script's second copy of
+  the layout could drift.
+- **The integration harness needed `maxPixels` in a request target.** DSH
+  0.1.3-alpha.2 rejects a target without it; later releases default it. A test
+  artefact, not a compatibility problem, but it meant the suite could not run on
+  the floor version at all.
+
+## 0.1.1 — 2026-10-14
+
+Fixed after the first release, from what a live session reported back.
+
+- **`read_animation` follows the path it advertises.** Every image a model receives
+  is shown as a normalized copy at `attachments/v1/objects/<2>/<digest>`, and that
+  is the path a model reaches for when it wants to look at the picture again. For a
+  pasted animation that copy is a single frame, so the tool answered "this picture
+  has one frame": true of that file, and useless as an answer. The tool now resolves
+  that path to the animation this plugin kept, and reports the file the bytes
+  actually came from. A bare `sha256:<digest>` is accepted too.
+- **The sheet says where the animation lives.** Its header ends with the path the
+  store keeps the original at, so a model that wants more than the eight samples can
+  read that path with explicit frame indices instead of searching the attachment
+  store for the file behind the picture it was sent.
+
+## 0.1.0 — 2026-10-14
+
+First release.
+
+Note for anyone publishing a later version, because both releases so far looked like
+failures while they were simply still in flight:
+
+- `npm publish` answers `PUT … 202` and prints "Your package is being processed and
+  may take a few minutes to become available", then exits 0. For a brand-new package
+  name the registry also carries a public `0.0.0-stage` placeholder alongside it.
+  Nothing needs approving in either case.
+- Measured on 0.1.1: the version appeared in the packument **2m41s** after the PUT,
+  and its tarball became downloadable **7m05s** after it. In between, the packument
+  either 404s or lists the version while its tarball still 404s.
+- Check the tarball, not just `npm view versions`, and check it with a GET: a HEAD
+  request to the tarball URL answers 404 even once the tarball is live.
+- A mirror lags further. `registry.npmmirror.com` still served 0.1.0 well after
+  0.1.1 was live on npmjs.org, and a profile configured against it keeps installing
+  the previous version until it syncs.
+
+### Fixed after an adversarial audit
+
+Four independent reviews (blast radius, plugin code, packaging and lifecycle, then
+an adversarial pass over every high-severity finding) ran before this was
+published. What they found, and what changed:
+
+- **The frame sheet's `variantId` was not a content digest.** It was a hand-rolled
+  `sha256:filmanim…` string, and the DeepSeek adapter validates persisted ids
+  against `/^sha256:[0-9a-f]{64}$/` when it loads its upload index — then swallows
+  the failure into an *empty* index. The effect was not a visible error: it
+  discarded every other session's cached file id and re-uploaded every image.
+  Reproduced against the real exported index class (plugin id: written 1, reloaded
+  0; conforming id: 1/1). It is now the SHA-256 of the bytes being returned, which
+  also stops one on-disk cache entry from aliasing two different byte streams.
+- **The degraded path was worse than the missing feature.** The store reaches the
+  frame it re-encodes through its own `readImage` call, which this plugin wraps, so
+  falling back to the store's request read could hand the model the *whole
+  animation* where it expects one frame. The request path now suspends the
+  animation substitution around that call, and reads its own tiles through the
+  unwrapped read. Pinned by an integration check that breaks a stored frame and
+  asserts the fallback is exactly one frame.
+- **No decoded-pixel ceiling on the `read_animation` path.** `limitInputPixels`
+  was disabled with nothing in its place: a 60 KB file declaring a 9000x9000
+  canvas was refused by the deployment's own attachment store and decoded here
+  anyway, at about 310 MiB. Both the probe and the frame extraction now carry the
+  deployment's `imageLimits.maxImagePixels`.
+- **The sheet cache ignored the size the caller asked for**, so a caller with an
+  8 KiB budget could be served a 28 KB sheet built for a 4 MiB one. The target is
+  now part of the cache key, and a tile is never larger than a single frame would
+  have been for that caller.
+- **The measured header wrap could still be defeated.** A floor of 16 characters
+  kept the loop from reaching a budget that fit, so on a narrow canvas it gave up
+  and returned ink wider than the sheet. The floor is now low enough to be
+  satisfiable, and a canvas too narrow for legible text gets no header at all.
+- **The canvas was composed before it was shrunk**, building a 6156x6306 (about
+  111 MiB) image to throw away. Tile size and grid are settled first.
+- **Torn state files could poison the next record.** A crash part way through an
+  append left a line with no newline, so the following record concatenated onto it
+  and became unreadable too. A torn tail is now detected and compacted away.
+- **The store's bound applied to memory but not to what was read back**, and the
+  log was never compacted. Both fixed; the file is rewritten when it grows past
+  twice the entries worth keeping.
+- **Teardown was last-writer-wins.** Each install captured whatever was on the
+  method, so disposing one left another's patch removed and could reinstall a
+  disposed closure as a permanent own property. Three wrappers now share one
+  installer that resolves its delegate per call, removes cleanly (deleting an
+  inherited property rather than leaving a shadow behind), and reports whether it
+  actually took effect — the previous identity check compared a value that proxy
+  reads always re-wrap, so it could never detect a failed install.
+- **`npm test` did not run the invariant checks.** The no-`@deepseek-ai`-import
+  rule and the bundle/manifest consistency check lived only in the integration
+  harness, which prints SKIP and exits 0 without `DSH_HARNESS_MODULES`. Both now
+  run in `npm test`, which is also the `prepublishOnly` gate.
+- **`files[]` omitted `scripts/`** while `package.json` advertised two npm scripts
+  that live there, so the published package's own scripts were broken.
+
+- **A pasted animation keeps playing in the UI, and the message is left alone.**
+  The browser already uploads an animated GIF/WebP byte-for-byte and labelled as
+  such; the Host flattens it to a single
+  frame during prompt admission and keeps no copy of the source. The plugin wraps
+  `ctx.attachments.admitPromptContent` to capture the frames and the original file
+  at that moment, and `ctx.attachments.readImage` so the UI is served the animation
+  itself (the browser animates whatever bytes that one read returns). What you send
+  is what you send: the chat message is unchanged.
+- **The model now receives a labelled sheet of the frames.** The delivery step is
+  `ctx.attachments.readImageRequest(ref, target, signal)`, the method each adapter
+  calls to build its own copy of one image. It answers with exactly one image, so
+  the frames are composed into a grid chosen to be as square as the sheet budget
+  allows — every tile at its native size, with the frame index, duration and start
+  time printed under each, and the animation's own facts in a wrapped header. The
+  sheet is built once per animation and cached.
+- Rewriting the request from an `llm/stream` listener is **not** used and would not
+  work: a loop-built request arrives deep-frozen ("listeners read it, never rewrite
+  it"), so that earlier attempt silently did nothing.
+- Captured frames and the original are persisted per `$DSH_HOME` in
+  `read-animation/v1/pasted.jsonl`, keyed by the message's attachment id, so a
+  session resumed in a new process still displays — and still delivers — an
+  animation pasted before the restart.
+- A frame's index and start time ride in its attachment display name
+  (`x.gif#frame16@1960ms`), which the harness renders beside the picture once the
+  frames are delivered — so the timing never has to be repeated as message text.
+  (An earlier version of this feature put a header plus one caption per frame into
+  the user's own message; consecutive text parts are concatenated by the UI with
+  no separator, so a one-image message became an unreadable wall.)
+- `read_animation` tool: decodes an animated GIF or animated WebP, samples frames
+  across the timeline (or by explicit index / instant), commits each frame to the
+  attachment store, and returns a header plus one captioned image per frame.
+- Refuses animated PNG by name instead of silently returning its first frame,
+  which is what the host image library does with one.
+- Refuses static images and points at `read_image`; answers a single-frame GIF or
+  WebP with a note that it is not animated.
+- Discloses decode-time substitutions in the model-facing text: zero frame
+  delays treated as 100 ms, missing delays, transparency flattened onto white.
+- The package imports no `@deepseek-ai/*` module at runtime, so it loads both as
+  an installed package and as a `link:`ed checkout. The compiled schemas ship as
+  literals beside their authoring specs, and the integration harness keeps the
+  two in step.

package/COMPATIBILITY.md

@@ -0,0 +1,100 @@
+# Compatibility
+
+## Supported range
+
+**DSH 0.1.3-alpha.2 and later.** Upload compatibility rechecked on
+2026-11-08 against DSH 0.2.2-rc.1 and 0.1.7-alpha.2.
+
+## What was measured
+
+### The integration suite, actually run
+
+`test/integration/harness.mjs` boots the real `dsh-fs-local`,
+`dsh-attachment-local`, `dsh-system-prompt` and `dsh-tools` plugins in-process,
+registers the tool, and exercises the paste path through a real `llm.stream`
+dispatch. Pointed at four versions spanning the range:
+
+| DSH | checks |
+| --- | --- |
+| `0.1.3-alpha.2` — the oldest release with the full API | 38/38 |
+| `0.1.7-alpha.2` — the version this was developed against | 38/38 |
+| `0.2.0-rc.2` — `latest` on that date | 38/38 |
+| `0.2.1-alpha.3` — `alpha` on that date, newest | 38/38 |
+
+The table above records the 2026-10-14 baseline. The upload regression checks
+added on 2026-11-08 produced the following results:
+
+| DSH | checks |
+| --- | --- |
+| `0.1.7-alpha.2` — encoded-prompt and raw image-storage paths | 40/40 |
+| `0.2.2-rc.1` — includes the raw upload service and stored-reference admission | 41/41 |
+
+DSH 0.2.2 normalizes uploaded images before prompt admission. Capture now wraps
+`saveImages`, which receives raw bytes for both upload and encoded-prompt paths.
+The regressions check GIF and animated WebP display, frame sheets, and reads of
+normalized-copy paths. The 0.2.2 case also calls the real
+`FileUploads.uploadImageStream` and resolves its receipt into a stored image
+reference. The test harness mounts the native tool executor on hosts that expose
+that separate service.
+
+```sh
+DSH_HARNESS_MODULES=/path/to/dsh/node_modules node test/integration/harness.mjs
+```
+
+### The API surface, read from every published release
+
+`scripts/check-dsh-compat.py` downloads the type declarations of
+`@deepseek-ai/dsh-attachment` and `@deepseek-ai/dsh-attachment-local` for every
+published DSH version and reports which of the members this plugin calls are
+present. DSH publishes its whole monorepo at one version, so `dsh@X` pins
+`dsh-attachment-local@X`.
+
+```sh
+python scripts/check-dsh-compat.py
+```
+
+The result over all 32 published releases: every member is present from
+**0.1.3-alpha.2** onward and absent before it. The members, and the release each
+first appears in:
+
+| member | since |
+| --- | --- |
+| `saveImages` | `0.1.0-rc.7` |
+| `readImageRequest` | `0.1.2-alpha.3` |
+| `readFileStream` | `0.1.2-alpha.3` |
+| `saveFile` | `0.1.3-alpha.2` |
+| `fileHostPath` | `0.1.3-alpha.2` — optional; the plugin works without it |
+
+So the floor is set by `saveFile`, which is what keeps the original animation's
+bytes for the sheet, and by `fileHostPath`. Below `0.1.3-alpha.2` the plugin still
+mounts and still reads animations from files; pasted animations degrade to a
+single frame, and it says which member is missing and when that member arrived.
+
+## What is not claimed
+
+- **Four of the seventeen releases in the range were executed.** Every release in
+  the range was checked to expose the full member list, but a release whose types
+  are complete can still behave differently. The four points span floor to ceiling.
+- **The upper bound is a date, not a guarantee.** This plugin wraps
+  `saveImages`, `readImage`, and `readImageRequest` — internal service
+  methods. A DSH release that changes their signatures or the shape of a request
+  target will break it, and nothing here can detect that in advance.
+- **The `engines.dsh` field is documentation.** npm does not enforce a
+  non-standard `engines` key, and DSH does not read it. It records the measured
+  floor; it does not stop an install.
+
+## Re-measuring after a DSH release
+
+1. `python scripts/check-dsh-compat.py` — does the new release still expose
+   everything?
+2. Install it somewhere and run the suite against it:
+
+   ```sh
+   mkdir /tmp/dsh-probe && cd /tmp/dsh-probe
+   npm init -y && npm i @deepseek-ai/dsh@<version>
+   cd <this repo>
+   DSH_HARNESS_MODULES=/tmp/dsh-probe/node_modules node test/integration/harness.mjs
+   ```
+
+3. If it fails, the check that fails names the method. The messages raised at mount
+   and from the tool also name the missing member and the release it arrived in.

package/README.md

@@ -52,13 +52,13 @@ the chunk stream and refuses it by name instead of returning frame 0.
 paste handler hands the clipboard's own `File` straight to the upload path, and
 that path encodes `image/gif` and `image/webp` unchanged (`imageMediaType()`
 accepts both and returns them as-is) — no canvas, no `drawImage`, no `toBlob`.
-**The bytes reach the Host whole.** It is the Host that destroys them:
-`admitPromptContent` runs every image through the single-frame normalizer and
-keeps no copy of the source.
+**The bytes reach the Host whole.** The Host normalizes them through
+`attachments.saveImages`. In DSH 0.2.2 this happens during upload, so prompt
+admission receives an already-stored image reference.
 
-`admitPromptContent` is therefore the last moment the original bytes exist. The
-plugin wraps it, decodes the animation and stores the frames — then **returns the
-original result untouched**:
+The plugin wraps `saveImages`, captures the animation from its raw inputs, and
+stores the original and decoded frames against the returned image reference.
+This covers raw uploads and older encoded-prompt admission:
 
 ```
 you paste 1 animation
@@ -143,6 +143,9 @@ the gaps are gaps.
 
 ## Install
 
+Needs **DSH 0.1.3-alpha.2 or later** — see [COMPATIBILITY.md](COMPATIBILITY.md) for
+the measured range, how it was measured, and what is not claimed.
+
 ```sh
 dsh plugin --profile web add dsh-read-animation
 ```
@@ -239,8 +242,8 @@ tool refuses to run when the resolved model route does not declare image input,
 for the same reason `read_image` does.
 
 **A pasted animation** is handled in three steps, none of which touch your
-message: **capture** at admission (`ctx.attachments.admitPromptContent` is the last
-moment the original bytes exist), **display** at `ctx.attachments.readImage` (the
+message: **capture** at image storage (`ctx.attachments.saveImages` receives the
+original bytes), **display** at `ctx.attachments.readImage` (the
 one read the UI makes, served the original so it plays), and **delivery** at
 `ctx.attachments.readImageRequest` (the model's copy, composed into one labelled
 sheet). All three are **monkey-patches of core service methods**, so they do

package/README.zh.md

@@ -47,10 +47,11 @@ APNG 得的是同一种病，而且更隐蔽：libvips 8.18.7 根本不认 `acTL
 **入口一 · 贴进聊天框。** 浏览器那段路本身是干净的——粘贴处理器把 `clipboardData` 里的原始
 `File` 直接交出去，上传路径对 `image/gif` / `image/webp` 原样编码（`imageMediaType()` 明确
 接受这两种并原样返回），没有 canvas、没有 `drawImage`、没有 `toBlob`。**字节完好地到达宿主。**
-丢掉它的是宿主自己：`admitPromptContent` 把每张图都过一遍「单帧」归一化，源字节不保留。
+宿主通过 `attachments.saveImages` 将图片归一化。DSH 0.2.2 在上传阶段就完成这一步，
+之后消息接收入口拿到的是已存储的图片引用。
 
-`admitPromptContent` 是**原件还存在的最后一刻**，所以本插件在这里把它解码、把帧存下来——
-然后**把原样的结果还回去**：
+本插件在 `saveImages` 保存图片时，用仍可访问的原始字节解码动画，并将原件和帧关联到
+返回的图片引用。这同时覆盖原始文件上传和旧版编码图片入口：
 
 ```
 你贴 1 张动图
@@ -201,8 +202,8 @@ PNG，所以 harness 的归一化管线对它无事可做。
 `read_image` 完全一致。当解析出的模型路由未声明图片输入时，工具会拒绝执行——理由和
 `read_image` 相同。
 
-**贴进聊天框的动图**分三步，都不碰你的消息：**捕获**在准入层
-（`ctx.attachments.admitPromptContent` 是原件还在的最后一刻），**显示**在
+**贴进聊天框的动图**分三步，都不碰你的消息：**捕获**在图片存储层
+（`ctx.attachments.saveImages` 仍能访问上传原件），**显示**在
 `ctx.attachments.readImage`（界面取图的那一次读，返回原件所以会动），**交付**在
 `ctx.attachments.readImageRequest`（模型那份，拼成一张带标注的胶片条）。三步都是
 **猴补核心服务的方法**，所以写得很保守——

package/assets/icon.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96" role="img" aria-label="Four frames of one animation, with the subject growing across them">
+  <!--
+    The plugin's whole idea in one mark: one animation shown as a grid of frames
+    over time, with the subject changing across them.
+
+    Drawn for the size it is actually rendered at, roughly 40px on a bundle card:
+    four bold shapes, no gradients, no text, nothing that turns to mush. The
+    background is a mid-tone tile so the mark reads on both a light and a dark
+    card, and the frames inside carry the contrast.
+  -->
+  <rect width="96" height="96" rx="21" fill="#26333F"/>
+  <g fill="#EDF2F8">
+    <rect x="10" y="10" width="36" height="36" rx="7"/>
+    <rect x="50" y="10" width="36" height="36" rx="7"/>
+    <rect x="10" y="50" width="36" height="36" rx="7"/>
+    <rect x="50" y="50" width="36" height="36" rx="7"/>
+  </g>
+  <!--
+    The subject grows across the four moments. Size is a property the eye reads
+    even when it scans a grid out of order, which a position change is not: in a
+    2x2 layout, reading order jumps from the top right back to the bottom left, so
+    four dots each moving inside their own frame read as four unrelated things.
+  -->
+  <g fill="#26333F">
+    <circle cx="28" cy="28" r="5"/>
+    <circle cx="68" cy="28" r="7"/>
+    <circle cx="28" cy="68" r="9"/>
+  </g>
+  <!-- The last sampled moment is the one the sheet calls out, so it is the one
+       shape in the mark that is not greyscale. -->
+  <circle cx="68" cy="68" r="11" fill="#C9761B"/>
+</svg>

package/lib/admission.js

@@ -6,16 +6,15 @@
  * A pasted animation survives the browser intact: the chat input hands the
  * clipboard's own `File` to the upload path, and that path encodes `image/gif`
  * and `image/webp` unchanged — no canvas, no re-encode. The bytes arrive at the
- * Host whole. The Host then destroys them: `admitPromptContent` runs every image
- * through the attachment normalizer, which is single-frame by construction, and
- * the source is not kept. By the time any tool can see the attachment it is one
- * frame, so `read_animation` cannot help.
+ * Host whole. The attachment normalizer keeps only one frame and discards the
+ * source. DSH 0.2.2 runs it during raw upload, before prompt admission receives
+ * an already-stored image reference.
  *
- * `admitPromptContent` is the last moment the original bytes exist. This module
- * wraps it to decode the animation and store the frames — and then returns the
- * original result **unchanged**, so the message a person wrote stays exactly what
- * they wrote. `./display.js` serves the animation itself back to the UI, and
- * `./model.js` turns the frames into the model's own copy of that image.
+ * Both raw uploads and legacy encoded prompt admission call `saveImages`. This
+ * module captures its raw inputs against the returned references, before the
+ * caller can discard those bytes. The returned references remain unchanged.
+ * `./display.js` serves the animation itself back to the UI, and `./model.js`
+ * turns the frames into the model's own copy of that image.
  *
  * ### Why it is written defensively
  *
@@ -39,8 +38,8 @@ const ANIMATED_MEDIA_TYPES = new Set(['image/gif', 'image/webp'])
 const SUPPORTED_FORMATS = new Set(['gif', 'webp'])
 
 /**
- * Wrap the attachment service's prompt admission so a pasted animation's frames
- * are captured before the source bytes are discarded.
+ * Wrap image storage so uploaded and pasted animations are captured while their
+ * source bytes are still available.
  *
  * @param ctx - the plugin context; needs the mounted `attachments` service.
  * @param settings - the resolved plugin configuration.
@@ -53,27 +52,27 @@ export function installAdmissionCapture(ctx, settings, pasted) {
     warn(ctx, 'no attachment service is mounted; a pasted animation stays a single frame')
     return false
   }
-  if (typeof attachments.admitPromptContent !== 'function') {
-    warn(ctx, 'attachments.admitPromptContent is not a function; a pasted animation stays a single frame')
+  if (typeof attachments.saveImages !== 'function') {
+    warn(ctx, 'attachments.saveImages is not a function; a pasted animation stays a single frame')
     return false
   }
 
-  const patch = wrapServiceMethod(attachments, 'admitPromptContent', (base) =>
-    async function admitPromptContentCapturingAnimations(content) {
-      // The caller's result is never modified. Capture is best-effort and runs on
-      // the side; if it fails, the message is still exactly what was sent.
-      const admitted = await base(content)
+  const patch = wrapServiceMethod(attachments, 'saveImages', (base) =>
+    async function saveImagesCapturingAnimations(inputs) {
+      // Capture only after the host accepts the batch. Keep its references even
+      // if animation capture fails.
+      const refs = await base(inputs)
       try {
-        await capture(ctx, settings, pasted, content, admitted)
+        await capture(ctx, settings, pasted, inputs, refs)
       } catch (error) {
         warn(ctx, `could not capture a pasted animation: ${describe(error)}`)
       }
-      return admitted
+      return refs
     },
   )
 
   if (!patch.installed) {
-    warn(ctx, 'the admission wrapper did not take effect; a pasted animation stays a single frame')
+    warn(ctx, 'the image-storage wrapper did not take effect; a pasted animation stays a single frame')
     return false
   }
 
@@ -82,37 +81,36 @@ export function installAdmissionCapture(ctx, settings, pasted) {
 }
 
 /**
- * Decode each claimed image and record its frames against the admitted reference.
+ * Decode each claimed image and record its frames against the stored reference.
  *
  * @param ctx - the plugin context.
  * @param settings - the resolved plugin configuration.
  * @param pasted - the store to record into.
- * @param content - the parts as submitted, carrying the original bytes.
- * @param admitted - the parts the service returned, carrying the references.
+ * @param inputs - image storage inputs carrying the original bytes.
+ * @param refs - stored references returned in input order.
  */
-async function capture(ctx, settings, pasted, content, admitted) {
-  if (!Array.isArray(content) || !Array.isArray(admitted)) return
+async function capture(ctx, settings, pasted, inputs, refs) {
+  if (!Array.isArray(inputs) || !Array.isArray(refs)) return
 
   const claimed = []
-  content.forEach((part, index) => {
-    if (part?.type === 'image' && ANIMATED_MEDIA_TYPES.has(part.mediaType)) claimed.push(index)
+  inputs.forEach((input, index) => {
+    if (ANIMATED_MEDIA_TYPES.has(input?.mediaType)) claimed.push(index)
   })
   if (claimed.length === 0) return
 
   const limits = ctx.get('attachments')?.imageLimits
-  const stillImages = content.filter((part) => part?.type === 'image').length - claimed.length
+  const stillImages = inputs.length - claimed.length
   const allowance = Math.max(0, (limits?.maxImagesPerMessage ?? 20) - stillImages)
   const perAnimation = Math.min(settings.maxFrames, Math.floor(allowance / claimed.length))
   if (perAnimation < 2) return
 
   const sharp = loadSharp()
   for (const index of claimed) {
-    const target = admitted[index]
-    const attachmentId = target?.type === 'image' ? target.attachment?.attachmentId : undefined
+    const attachmentId = refs[index]?.attachmentId
     if (attachmentId === undefined) continue
 
-    const part = content[index]
-    const bytes = Buffer.from(part.data, 'base64')
+    const part = inputs[index]
+    const bytes = Buffer.from(part.data)
     const animation = await probeAnimation(sharp, bytes, { maxPixels: limits?.maxImagePixels })
     if (!SUPPORTED_FORMATS.has(animation.format) || animation.frameCount < 2) continue
 
@@ -124,7 +122,7 @@ async function capture(ctx, settings, pasted, content, admitted) {
       plan.plan,
       { maxEdge: settings.maxEdge, background: settings.background, maxPixels: limits?.maxImagePixels },
     )
-    const refs = await ctx.attachments.saveImages(
+    const frameRefs = await ctx.attachments.saveImages(
       rendered.map((frame) => ({
         data: frame.data,
         mediaType: 'image/png',
@@ -144,7 +142,7 @@ async function capture(ctx, settings, pasted, content, admitted) {
     })
 
     pasted.remember(attachmentId, {
-      frames: refs.map((ref) => ({
+      frames: frameRefs.map((ref) => ({
         attachmentId: ref.attachmentId,
         mediaType: ref.mediaType,
         bytes: ref.bytes,

package/lib/index.js

@@ -39,6 +39,7 @@ import { createPastedStore } from './pasted.js'
 import { installOriginalDisplay } from './display.js'
 import { installModelFrames } from './model.js'
 import { readAnimation } from './read.js'
+import { missingMethods, warn } from './patch.js'
 import { OUTPUT_SCHEMA, PARAMETERS, TOOL_NAME, describeTool, validateArguments } from './tool.js'
 
 /** Cordis plugin name; matches the `id` of this bundle's `cordis.patch.yml` row. */
@@ -62,10 +63,22 @@ const DEFAULT_MAX_INPUT_BYTES = 64 * 1024 * 1024
 export function apply(ctx, config = {}) {
   const settings = resolveConfig(config)
   ctx.inject(['attachments'], (imageCtx) => {
+    // Say what is missing once, in full, before any installer runs. Partial
+    // mounting is deliberate — the tool still works on a host with `saveImages`
+    // but no `readImageRequest` — so this is a report, not a refusal.
+    const gaps = hostGaps(imageCtx.get('attachments'))
+    if (gaps.length > 0) {
+      warn(
+        ctx,
+        `this DSH build is missing ${gaps.length} thing${gaps.length === 1 ? '' : 's'} read_animation needs: ` +
+          `${gaps.join(', ')}. Supported from DSH ${SUPPORTED_FROM}; parts of this plugin will be inert.`,
+      )
+    }
+
     let pasted
     if (settings.expandPastedAnimations) {
-      // Capture at admission (the last moment the animation's bytes exist) and
-      // hand the frames to the model at request time. The message is not touched.
+      // Capture raw image storage inputs, then hand the frames to the model at
+      // request time. This covers uploads normalized before prompt admission.
       pasted = createPastedStore(imageCtx)
       installAdmissionCapture(imageCtx, settings, pasted)
       const display = installOriginalDisplay(imageCtx, pasted)
@@ -105,6 +118,47 @@ function resolveConfig(config) {
   return settings
 }
 
+/**
+ * Attachment-service members this plugin calls, and the DSH version each arrived in.
+ *
+ * The floor is measured, not guessed: reading the published type declarations of
+ * every release shows `0.1.3-alpha.2` as the first version carrying all of these,
+ * and 0.1.2-rc.1 and earlier are missing `saveFile`,
+ * `readImageRequest`, `readFileStream` and `fileHostPath` in various combinations.
+ * `fileHostPath` is deliberately absent from this list: the plugin works without
+ * it, and says less on the sheet when it is missing.
+ */
+const REQUIRED = [
+  { name: 'saveFile', since: '0.1.3-alpha.2' },
+  { name: 'saveImages', since: '0.1.0-rc.7' },
+  { name: 'readImage', since: '0.0.1-rc.1' },
+  { name: 'readImageRequest', since: '0.1.2-alpha.3' },
+  { name: 'readFileStream', since: '0.1.2-alpha.3' },
+]
+
+/** The supported floor, quoted in the message an unsupported host gets. */
+const SUPPORTED_FROM = '0.1.3-alpha.2'
+
+/**
+ * What this host does not provide, in words the person reading the log can act on.
+ *
+ * Checked once at mount. Each installer also guards the method it wraps, but a
+ * guard only covers the method being replaced: a host with `readImage` and no
+ * `saveImages` would mount cleanly and then throw a `TypeError` from inside the
+ * tool, several layers below anything that names the cause.
+ */
+function hostGaps(attachments) {
+  if (attachments === undefined) return ['no attachment service is mounted']
+  const gaps = missingMethods(attachments, REQUIRED.map((entry) => entry.name)).map(
+    (name) => `attachments.${name}() (added in DSH ${REQUIRED.find((entry) => entry.name === name).since})`,
+  )
+  if (attachments.imageLimits === undefined) gaps.push('attachments.imageLimits')
+  else if (typeof attachments.imageLimits.maxImagePixels !== 'number') {
+    gaps.push('attachments.imageLimits.maxImagePixels')
+  }
+  return gaps
+}
+
 /** Build and register the `read_animation` tool definition. */
 function registerTool(ctx, settings, pasted) {
   ctx.tools.register({

package/lib/pacing.js

@@ -0,0 +1,217 @@
+/**
+ * Where an animation's change actually is, and which frames to show because of it.
+ *
+ * ### Why this exists
+ *
+ * Sampling a fixed number of frames at equal intervals answers "what does this
+ * animation look like", which is not the same question as "how does it go". The
+ * budget is spread over *time*, while an animation's content lives in *change*: a
+ * long hold at either end gets the same share as the moment something happens.
+ *
+ * Measured on a real 56-frame clip: even sampling spent three of its eight tiles
+ * on the opening where the frame-to-frame change is 1-6 (of 255), and never
+ * sampled the single largest change in the clip (frame 53, change 31.4). Padded to
+ * 136 frames with held ends — what a trimmed screen recording looks like — five of
+ * the eight tiles were pixel-identical to their neighbour.
+ *
+ * ### What it deliberately does not do
+ *
+ * It does not replace coverage with content. The literature on keyframe selection
+ * is split: content-aware selection wins on information-dense questions and
+ * uniform sampling keeps an edge on temporal continuity, which is exactly what a
+ * story is made of. So the equal-interval skeleton is kept, and a tile is moved
+ * **only when the stretch around it is measured to be still** — meaning that tile
+ * and its neighbour show the same picture and nothing is lost by moving it. When
+ * nothing qualifies, this returns the even picks unchanged.
+ *
+ * The module is pure: the caller decodes the frames (including the in-between
+ * probes) and this decides. That keeps the decision testable without an image
+ * library, and keeps the cost of probing a caller concern.
+ *
+ * @module dsh-read-animation/pacing
+ */
+
+/**
+ * Mean absolute pixel difference between two frames, on the 0-255 scale.
+ *
+ * Measured on real material: held frames score 0.0, a slow intro scores 1-6, and
+ * action scores 12-31. The two thresholds below come from that spread rather than
+ * from taste.
+ */
+export function changeBetween(a, b) {
+  const length = Math.min(a.length, b.length)
+  if (length === 0) return 0
+  let total = 0
+  for (let at = 0; at < length; at += 1) total += Math.abs(a[at] - b[at])
+  return total / length
+}
+
+/** Below this, two frames are the same picture for any practical purpose. */
+export const STILL = 2
+
+/** Above this, something is happening between the two frames. */
+export const BUSY = 8
+
+/**
+ * Describe the change in every gap between consecutive chosen frames.
+ *
+ * A gap is probed once, in the middle, and the two halves are compared: a gap
+ * whose middle differs from both ends is a gap where something moved.
+ *
+ * @param chosen - the frame indices that will be shown, in order.
+ * @param decoded - `Map<index, Uint8Array>` of greyscale pixels, holding at least
+ *   the chosen frames and whatever {@link probePlan} asked for in between.
+ * @param frameCount - frames in the whole animation.
+ * @returns per-gap facts, plus which gaps are still and which are busy.
+ */
+export function analyzePacing(chosen, decoded, frameCount) {
+  const at = (index) => decoded.get(index)
+
+  const gaps = []
+  for (let slot = 1; slot < chosen.length; slot += 1) {
+    const from = chosen[slot - 1]
+    const to = chosen[slot]
+    const middle = Math.round((from + to) / 2)
+    const left = at(from)
+    const right = at(to)
+    if (left === undefined || right === undefined) continue
+
+    const between = middle > from && middle < to ? at(middle) : undefined
+    const change =
+      between === undefined
+        ? changeBetween(left, right)
+        : Math.max(changeBetween(left, between), changeBetween(between, right))
+
+    gaps.push({ from, to, frames: to - from, change, still: change < STILL, busy: change > BUSY })
+  }
+
+  const busiest = gaps.reduce((best, gap) => (best === undefined || gap.change > best.change ? gap : best), undefined)
+
+  // How much of each end is still, which is what tells a reader where the story
+  // is rather than where the file happens to start.
+  const firstMoving = gaps.findIndex((gap) => !gap.still)
+  const lastMoving = gaps.length - 1 - [...gaps].reverse().findIndex((gap) => !gap.still)
+
+  return {
+    gaps,
+    busiest,
+    stillGaps: gaps.filter((gap) => gap.still),
+    busyGaps: gaps.filter((gap) => gap.busy),
+    stillUntil: firstMoving > 0 ? gaps[firstMoving].from : undefined,
+    stillFrom: lastMoving >= 0 && lastMoving < gaps.length - 1 ? gaps[lastMoving].to : undefined,
+    frameCount,
+  }
+}
+
+/**
+ * The frames to show, under the chosen strategy.
+ *
+ * `content` removes a tile only when **both** gaps beside it were measured still:
+ * removing it then merges two still stretches into one that is still by the same
+ * measurement, so nothing unmeasured is ever created. The freed tiles go into the
+ * busiest gaps, at the probe that measured them.
+ *
+ * The stricter rule is not caution for its own sake. The first version removed a
+ * tile when *either* neighbour was still, and on a padded clip that produced a
+ * 49-frame gap that had never been probed — a coverage hole presented as a
+ * saving. The constraint that matters is not "no long gaps" but "no *unmeasured*
+ * gaps": a sixty-frame stretch that was measured still is a correctly compressed
+ * hold, and losing it costs nothing.
+ *
+ * @param frameCount - frames in the animation.
+ * @param count - how many frames to choose.
+ * @param pacing - the report from {@link analyzePacing}, or undefined when the
+ *   caller did not probe (in which case only `even` is possible).
+ * @param strategy - `'even'` keeps equal intervals; `'content'` moves only the
+ *   tiles whose surroundings are measured still.
+ * @returns `{ indices, moved }`, where `moved` explains each relocation.
+ */
+export function chooseFrames(frameCount, count, pacing, strategy) {
+  const even = evenIndices(frameCount, count)
+  if (strategy !== 'content' || pacing === undefined || even.length < 3) {
+    return { indices: even, moved: [] }
+  }
+
+  const measured = new Map(pacing.gaps.map((gap) => [`${gap.from}:${gap.to}`, gap]))
+
+  /** The status of the gap between two kept frames, or undefined if nobody measured it. */
+  const gapBetween = (from, to) => {
+    const exact = measured.get(`${from}:${to}`)
+    if (exact !== undefined) return exact
+    const between = pacing.gaps.filter((gap) => gap.from >= from && gap.to <= to)
+    if (between.length === 0 || between.some((gap) => !gap.still)) return undefined
+    return { from, to, frames: to - from, change: Math.max(...between.map((gap) => gap.change)), still: true, busy: false }
+  }
+
+  // Remove the tiles that sit inside a still stretch, at both ends of it. The
+  // first and last frames are never removed: they are the animation's state.
+  const kept = [...even]
+  const freed = []
+  for (let at = even.length - 2; at >= 1; at -= 1) {
+    const before = measured.get(`${even[at - 1]}:${even[at]}`)
+    const after = measured.get(`${even[at]}:${even[at + 1]}`)
+    if (before?.still === true && after?.still === true) {
+      freed.push({ index: even[at], stillChange: Math.max(before.change, after.change) })
+      kept.splice(kept.indexOf(even[at]), 1)
+    }
+  }
+
+  const moved = []
+  for (const freedTile of freed) {
+    // The busiest gap that still has room for a frame in the middle of it.
+    const target = kept
+      .map((from, at) => (at + 1 < kept.length ? gapBetween(from, kept[at + 1]) : undefined))
+      .map((gap, at) => ({ gap, at }))
+      .filter(({ gap }) => gap?.busy === true && gap.frames > 2)
+      .sort((a, b) => b.gap.change - a.gap.change)[0]
+    if (target === undefined) break
+
+    const insert = Math.round((target.gap.from + target.gap.to) / 2)
+    const crowded = kept.some((index) => Math.abs(index - insert) < 2)
+    if (crowded || insert <= 0 || insert >= frameCount - 1) break
+
+    kept.splice(kept.findIndex((index) => index > insert), 0, insert)
+    moved.push({ from: freedTile.index, to: insert, gapChange: target.gap.change, stillChange: freedTile.stillChange })
+  }
+
+  return { indices: kept, moved }
+}
+
+/**
+ * Equal intervals, first and last included.
+ *
+ * This is the sampler the plugin has always used, kept as the default and as the
+ * skeleton the content strategy starts from.
+ */
+export function evenIndices(frameCount, count) {
+  if (frameCount <= 1 || count <= 1) return [0]
+  if (count >= frameCount) return [...Array(frameCount).keys()]
+  const picks = []
+  for (let slot = 0; slot < count; slot += 1) picks.push(Math.round((slot * (frameCount - 1)) / (count - 1)))
+  return [...new Set(picks)]
+}
+
+/**
+ * Where to probe for the change in each gap, without decoding every frame.
+ *
+ * One probe per gap, plus the two ends of the animation so the "still" stretches
+ * can be described. That is `count + 1` extra decodes regardless of how long the
+ * animation is, against `frameCount` for a full change profile — which is what
+ * makes this affordable on a 300-frame clip.
+ *
+ * @param indices - the chosen frames, in order.
+ * @param frameCount - frames in the animation.
+ * @returns `{ samples, probes }` as index lists, deduplicated and in order.
+ */
+export function probePlan(indices, frameCount) {
+  const wanted = new Set(indices)
+  for (let at = 1; at < indices.length; at += 1) {
+    const middle = Math.round((indices[at - 1] + indices[at]) / 2)
+    if (middle > indices[at - 1] && middle < indices[at]) wanted.add(middle)
+  }
+  // The frames just before the first sample and after the last, so an opening or
+  // closing hold is visible rather than inferred.
+  if (indices[0] > 0) wanted.add(indices[0] - 1)
+  if (indices[indices.length - 1] < frameCount - 1) wanted.add(indices[indices.length - 1] + 1)
+  return [...wanted].filter((index) => index >= 0 && index < frameCount).sort((a, b) => a - b)
+}

package/lib/patch.js

@@ -52,6 +52,24 @@ export function isWrapped(value) {
   return typeof value === 'function' && value[LEVEL] !== undefined
 }
 
+/**
+ * Which of `names` the service does not implement.
+ *
+ * Checked before wrapping anything. Installing a wrapper over a method that is not
+ * there used to *create* the property, so the host acquired a function whose only
+ * behaviour was to throw a `TypeError` from deep inside a call that looked
+ * ordinary — and the plugin reported nothing at mount, when it knew the host did
+ * not have what it needed.
+ *
+ * @param service - the service object, or undefined when the service is absent.
+ * @param names - the members this plugin calls.
+ * @returns the missing names, in the order given.
+ */
+export function missingMethods(service, names) {
+  if (service === undefined || service === null) return [...names]
+  return names.filter((name) => typeof service[name] !== 'function')
+}
+
 /**
  * Wrap one method.
  *

package/lib/read.js

@@ -54,6 +54,12 @@ export async function readAnimation(ctx, settings, args, exec, pasted) {
 
   const attachments = ctx.get('attachments')
   if (attachments === undefined) throw new Error('read_animation requires a mounted attachment store')
+  if (typeof attachments.saveImages !== 'function') {
+    throw new Error(
+      'read_animation needs attachments.saveImages() to store the frames it decodes, and this DSH build does not ' +
+        'provide it; read_animation supports DSH 0.1.3-alpha.2 and later',
+    )
+  }
   await assertImageCapableRoute(ctx, exec, args.file_path)
 
   const target = await ctx.fs.resolve(args.file_path, resolveOptions(exec))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-read-animation",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Let a DeepSeek Harness agent actually see an animated GIF or animated WebP: decode every frame, sample the animation across time, and hand the model a labelled sequence of real frames instead of the single first frame the harness otherwise delivers.",
   "type": "module",
   "main": "lib/index.js",
@@ -13,13 +13,16 @@
   "files": [
     "lib",
     "scripts",
+    "assets",
     "cordis.patch.yml",
     "README.md",
     "README.zh.md",
     "CHANGELOG.md",
+    "COMPATIBILITY.md",
     "THIRD_PARTY.md",
     "LICENSE"
   ],
+  "icon": "assets/icon.svg",
   "license": "MIT",
   "author": "NeoHotaru (https://github.com/NeoHotaru)",
   "repository": {
@@ -35,7 +38,7 @@
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.7-alpha.1"
+    "dsh": ">=0.1.3-alpha.2"
   },
   "keywords": [
     "dsh",
@@ -55,7 +58,7 @@
     }
   },
   "scripts": {
-    "test": "node --test test/animation.test.js test/decode.test.js test/envelope.test.js test/filmstrip.test.js test/model.test.js test/pasted.test.js test/patch.test.js test/read.test.js test/shipped.test.js test/tool.test.js",
+    "test": "node --test test/animation.test.js test/decode.test.js test/envelope.test.js test/filmstrip.test.js test/model.test.js test/pacing.test.js test/pasted.test.js test/patch.test.js test/read.test.js test/shipped.test.js test/tool.test.js",
     "test:integration": "node test/integration/harness.mjs",
     "test:all": "npm test && npm run test:integration",
     "prepublishOnly": "npm test",

package/scripts/check-dsh-compat.py

@@ -0,0 +1,121 @@
+# -*- coding: utf-8 -*-
+"""Which DSH versions expose every attachment-store member this plugin uses.
+
+DSH publishes its whole monorepo at one version, so dsh@X pins
+dsh-attachment-local@X. That makes the probe a straight walk over DSH versions:
+download the two packages that declare the attachment service, concatenate their
+type declarations, and ask which of the members this plugin calls are present.
+
+A version whose declarations could not be fetched is reported as NO DATA, never as
+a pass. The first version of this probe returned "OK" for every release because it
+looked in the wrong place and treated an empty haystack as an empty list of
+missing needles.
+"""
+import io
+import json
+import sys
+import tarfile
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+
+REG = 'https://registry.npmjs.org'
+CACHE = {}
+
+REQUIRED = [
+    'saveImages',
+    'saveFile',
+    'readImage',
+    'readImageRequest',
+    'readFileStream',
+    'fileHostPath',
+    'imageLimits',
+    'maxImagePixels',
+    'root',
+]
+
+PACKAGES = ['@deepseek-ai/dsh-attachment', '@deepseek-ai/dsh-attachment-local']
+
+
+def fetch(url, binary=False):
+    req = urllib.request.Request(url, headers={'cache-control': 'no-cache',
+                                               'user-agent': 'dsh-compat-probe'})
+    with urllib.request.urlopen(req, timeout=90) as r:
+        return r.read() if binary else r.read().decode('utf-8', 'replace')
+
+
+def packument(name):
+    key = 'meta:' + name
+    if key not in CACHE:
+        CACHE[key] = json.loads(fetch('%s/%s' % (REG, name.replace('/', '%2F'))))
+    return CACHE[key]
+
+
+def declarations(name, version):
+    """Every .d.ts in one published package, or None when there is nothing to read."""
+    key = '%s@%s' % (name, version)
+    if key in CACHE:
+        return CACHE[key]
+    CACHE[key] = None
+    try:
+        entry = packument(name)['versions'].get(version)
+        if entry is None:
+            return None
+        blob = fetch(entry['dist']['tarball'], binary=True)
+        text = []
+        with tarfile.open(fileobj=io.BytesIO(blob), mode='r:gz') as tar:
+            for member in tar.getmembers():
+                if member.name.endswith('.d.ts') and member.isfile():
+                    text.append(tar.extractfile(member).read().decode('utf-8', 'replace'))
+        CACHE[key] = '\n'.join(text) if text else None
+    except Exception as error:
+        print('  ! %s: %s' % (key, error), file=sys.stderr)
+    return CACHE[key]
+
+
+def main():
+    meta = packument('@deepseek-ai/dsh')
+    versions = sorted(meta['versions'], key=lambda v: meta['time'][v])
+
+    def probe(version):
+        texts = []
+        sources = []
+        for name in PACKAGES:
+            text = declarations(name, version)
+            if text:
+                texts.append(text)
+                sources.append(name.rsplit('/', 1)[-1])
+        if not texts:
+            return version, None, None
+        joined = '\n'.join(texts)
+        missing = [member for member in REQUIRED if member not in joined]
+        return version, missing, '+'.join(sources)
+
+    with ThreadPoolExecutor(max_workers=6) as pool:
+        results = list(pool.map(probe, versions))
+
+    print('%-18s %-9s %s' % ('dsh', 'read from', 'missing members'))
+    print('-' * 84)
+    state = {}
+    for version, missing, sources in results:
+        if missing is None:
+            label = 'NO DATA'
+        elif missing:
+            label = ', '.join(missing)
+        else:
+            label = 'OK'
+        state[version] = label
+        print('%-18s %-9s %s' % (version, sources or '-', label))
+
+    ok = [v for v in versions if state[v] == 'OK']
+    nodata = [v for v in versions if state[v] == 'NO DATA']
+    print('\nevery member present : %s' % (', '.join(ok) if ok else 'none'))
+    print('no data              : %s' % (', '.join(nodata) if nodata else 'none'))
+    if ok:
+        print('\n=> continuous support from %s through %s' % (ok[0], ok[-1]))
+        first_bad = [v for v in versions[:versions.index(ok[0])]]
+        if first_bad:
+            print('   versions before it that lack something: %s' % ', '.join(first_bad))
+
+
+if __name__ == '__main__':
+    main()

package/scripts/preview-sheet.mjs

@@ -37,10 +37,14 @@ const files = join(dshHome, 'attachments', 'v1', 'files')
  *
  * Mirrors `ctx.attachments.fileHostPath`, which the plugin uses for the header's
  * last line. This script has no mounted service, so the layout is spelled out
- * here; the integration harness asserts the real accessor returns a real path.
+ * here — and the first version of it spelled the layout wrong, printing
+ * `files/<name>` where the store uses `files/<2>/<digest>/<name>`, which put a
+ * path that does not exist onto the preview. The integration harness asserts the
+ * real accessor returns a real file, so only this script could drift.
  */
 function keptFilePath(ref) {
-  return join(files, ref.name)
+  const digest = String(ref.attachmentId).replace(/^sha256:/, '')
+  return join(files, digest.slice(0, 2), digest, ref.name)
 }
 
 /** Where a content-addressed attachment object lives. */