@jetecho/dsh-csv-and-image-preview 0.1.2 → 0.1.3

package/Agent.md

@@ -1,6 +1,6 @@
 # Agent.md — dsh-csv-and-image-preview 行为契约
 
-这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。它是给 agent 读的规则,搭配仓库里的独立 agent preset(`image-preview`)一起使用,把规则写进会话 persona。
+这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。可将这些规则加入会话指令。
 
 ## 核心原则:先预览,后落地
 
@@ -18,7 +18,8 @@
 ## 不要做的事
 
 - 不要在没预览的情况下,直接覆盖或新增一个图片 / SVG / CSV 文件。
-- 不要把图片字节或 CSV 全文/大段表格数据塞进回复文本或模型上下文 —— 那是 meta 的活,你只需拿到紧凑摘要。
+- 不要把图片字节或 CSV 全文/大段表格数据塞进回复文本或工具输出 —— 插件通过独立快照通道展示,你只需拿到紧凑摘要。
+- 返回“预览数据已生成”只表示快照保存成功。如果用户报告没有显示,按失败信息排查或重新预览,不要坚持声称已经显示。
 - 不要用 markdown `![alt](data:...)` 或 ```` ```dsh-ui ```` 的 `image` 组件来"显示图片"—— 聊天渲染器会拦截,必须走 `preview_image`;同理 CSV 必须走 `preview_csv`,不要用整段代码块充当"预览"。
 
 ## 交互话术
@@ -34,7 +35,10 @@
 | `preview_image` 工具 | 读取文件 / 内联 SVG → data-URI → 浏览器 `<img>` 渲染 |
 | `preview_csv` 工具 | 读取 CSV/TSV / 内联文本 → 有界解析(默认前 50 行,上限 500,列/单元格截断)→ 浏览器 `<table>` 渲染,控件限高局部滚动,表头可点击排序 |
 | 键控 toolview | `tool.call.toolview` key=`preview_image` / `preview_csv`,渲染原生 DOM |
-| meta 通道 | 图片字节与表格数据只走 `presentationMeta` 进浏览器,不进模型上下文 |
+| 聊天正文预览 | 回答结束后在正文末尾直接显示已生成的预览，不需要用户点击侧栏；刷新历史时重放调用并读取快照 |
+| 快照通道 | 按会话 ID 和调用 ID 保存快照,经 DSH 认证的 RPC 通道给浏览器读取;直接调用和 `run_code` 均支持;旧 meta 仍兼容 |
+
+预览本身会在插件数据目录保存快照,不修改目标文件。新建目标文件仍需遵循用户的预览确认约定。
 
 ## 为什么
 

package/README.en.md

@@ -2,78 +2,80 @@
 
 English | [中文](README.md)
 
-Render images, SVG, and CSV **for real** in the DeepSeek Harness (dsh) chat — images and SVG as a native browser `<img>`, CSV/TSV tables as a native `<table>` (sticky header, height-capped inner scrolling) — bypassing the chat renderer's markdown / genui filter, and paired with a **preview-first workflow**: generate or modify an image, SVG, or CSV, render it to you first, and only apply the real change once you confirm.
+Preview images, SVG and CSV/TSV in DeepSeek Harness chat using native `<img>` and `<table>` elements. Tables have sticky headers, 320px internal scrolling and sortable columns.
 
-## Install
+## 0.1.3: dedicated inline preview rows
 
-Standard Profile Bundle install (recommended):
+Version 0.1.3 registers dedicated keyed Chat nodes after turn/end, outside the collapsed process interval, preserving DSH's existing file cards. Native and nested preview calls and legacy metadata are replayed. Refreshing or reopening history reloads saved snapshots. Files presented only through DSH's `present` tool are outside this feature.
 
-```sh
-dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
-```
+Run `npm test`; set `DSH_UPSTREAM` to a DSH source checkout to include the real conversation assembler integration. `npm run preview:test` provides a browser fixture with a completion button and refresh verification.
 
-Or install the development copy from a local directory:
+## Install and upgrade
+
+Version 0.1.3 is tested with **DSH 0.1.5-rc.1** and requires its Connection RPC interface or a compatible newer version.
 
 ```sh
-dsh plugin --profile web add ../dsh-csv-and-image-preview
+# Install the published version
+dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
+
+# Build and install this checkout without publishing to npm
+npm ci
+npm test
+npm pack
+dsh plugin --profile web add ./jetecho-dsh-csv-and-image-preview-0.1.3.tgz
 ```
 
-After installing, restart `dsh web` so the new bundle joins the runtime. Legacy fallback for older versions: copy the package into the profile's `node_modules` and insert the `- insert: [...]` row in `cordis.patch.yml` — keep this for old-version compatibility only.
+Restart `dsh web` and refresh the browser after installation. Package name, bundle row ID and tool names are unchanged.
 
-## What it does
+## Compatibility fixes
 
-1. **Real image rendering.** The host registers a `preview_image` tool: it reads a file path (or inline SVG), infers the MIME, base64-encodes it into a data-URI, and projects it through the tool result's `presentationMeta`. The browser-side keyed toolview (`tool.call.toolview`, key `preview_image`) reads that meta and renders a native `<img>`. The image bytes travel only through meta into the browser — **never into the model context**.
-2. **Preview-first workflow.** After calling `preview_image`, the agent receives a compact summary (SVG/bitmap, dimensions, byte count) while the actual image is shown in chat; the agent then **waits for your confirmation** before writing files or applying changes.
-3. **Preview any resource.** Pass a local path to preview the matching image file, or pass inline SVG text to render without writing to disk.
-4. **CSV/TSV table preview.** The host registers a `preview_csv` tool: it reads a CSV/TSV file (or inline text), sniffs the delimiter (`,` `;` Tab `|`, or set `delimiter` explicitly), parses it with hard bounds, and projects the table through meta. The browser-side keyed toolview (key `preview_csv`) renders a native `<table>`. The widget is **capped at 320px with inner scrolling**; only the first 50 rows are delivered by default (`maxRows` adjustable up to 500), and overly wide columns / long cells are truncated too — the model receives only a row/column summary; table data never enters the model context. Click a header to **sort** (numeric vs. Chinese-pinyin collation auto-detected, empty values sink, asc → desc → off). Overlong cells get an ellipsis with full text on hover.
+The plugin registers only the exact `/api/csv-and-image-preview/get` route, preserving the shared `/api` interceptor owned by DSH's Gateway so history and plugin lists load normally. Upgrade, restart DSH and refresh the page; the fix does not modify session files.
 
-## Usage examples
+- Explicit client dependencies on `slots` and `connection`, and host dependencies on `tools` and `connection`. Late service startup parks the plugin; unloading cleans up registrations.
+- **Native calls and `run_code` child calls both work.** Current DSH computes `presentationMeta` only for top-level calls. New previews use a separate snapshot channel.
+- Inputs are read and parsed once, then saved before success is returned. Both the model and code program receive only a string summary, with no additional image bytes or table body.
+- Separate generating, loading, tool failure, missing snapshot and image decode failure states. Includes retry, reconnection refresh and cancellation of stale requests when navigating.
+- Legacy `block.meta.src` and `block.meta.rows` still render. Old nested calls that never persisted presentation data must be previewed again.
 
-```markdown
-<!-- Preview a file on disk -->
-I'll show you the preview first.
-[call preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
-```
+## Usage
 
-```markdown
-<!-- Preview inline SVG (not yet on disk) -->
-[call preview_image content=<svg ...> mime=image/svg+xml label=sketch]
+```text
+preview_image {"path":"D:/assets/logo.svg","label":"Logo preview"}
+preview_csv {"path":"D:/data/sales.csv","label":"Sales","maxRows":100}
+preview_csv {"content":"Name,Score\nAlice,90\nBob,85"}
 ```
 
-```markdown
-<!-- Preview a CSV file (truncated to the first 100 rows) -->
-[call preview_csv path=E:\DSHConfig\data.csv label=sales maxRows=100]
-```
+Inline SVG text can be supplied as `content`. Relative paths resolve against the session working directory. `path` takes precedence over `content`.
 
-The agent sees something like `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB).` while the picture appears in the tool card; for CSV it reads `已渲染 CSV 预览「sales」:CSV 表格 1234 行 × 5 列,分隔符 ",";显示前 100 行.` while the table appears in the tool card.
+Images support SVG, PNG, JPEG, GIF, WebP, BMP, ICO and AVIF. Inline non-SVG content requires standard base64 and a `mime` value. Image and CSV inputs are capped at 8 MiB; the inline base64 limit applies to encoded input size.
 
-## Convention: preview first
+CSV files require UTF-8 (BOM supported); other encodings produce an explicit conversion message. Delimiter detection supports comma, semicolon, Tab and pipe, with a `delimiter` override; `.tsv` defaults to Tab. Defaults: 50 rows; limits: 500 rows including the header, 40 columns and 200 characters plus an ellipsis per cell. Hover shows retained text only; discarded text is not recoverable. Headers cycle ascending, descending and original order, with empty values last.
 
-This plugin treats "preview, then apply" as the default behavior:
+## Storage and replay
 
-- When generating / modifying an image, SVG, or CSV, **preview it first** with `preview_image` / `preview_csv`; do not write the real file yet.
-- Only after the user confirms (`确认` / `可以` / `就这样`) do you actually write / mutate.
-- If the user rejects it, redo per feedback and preview again.
-- To preview any resource, pass `path` directly.
+Snapshots live in `$DSH_HOME/storages/csv-and-image-preview/`, defaulting to `~/.dsh/storages/csv-and-image-preview/`. Records are keyed by session ID, call ID and tool name using hashed filenames. Reads use DSH Connection's authenticated `/api` RPC channel and verify record identity.
 
-To enforce this convention, pair it with the bundled agent preset (see `Agent.md`), which writes these rules into the session persona.
+The same session can replay the original snapshot after refreshing, restarting DSH or changing/deleting the source file. Back up this directory alongside session data. Snapshots are not automatically pruned; deleting them removes new-format historical previews. Copying/forking into another session does not automatically migrate snapshots.
 
-## Layout
+The returned “preview data generated” summary acknowledges persistence, not successful browser decoding. Tool errors are reported as real failures.
 
-```
-lib/index.js   host: registers the preview_image / preview_csv tools; reads files and projects data-URIs / table meta
-lib/client.js  browser bundle: registers the keyed toolviews; renders a native <img> / <table>
-cordis.patch.yml  profile insert line
-```
+## Preview-first convention
+
+Preview generated or modified images/SVG/CSV before changing target files, then wait for user approval. Previewing itself writes a snapshot in the plugin data directory. This is an agent convention, not an enforcement mechanism against other write tools. Add [Agent.md](Agent.md) to your agent instructions if desired.
 
 ## Development
 
 ```sh
-pnpm install
-pnpm build       # no-op: lib/ ships prebuilt, no transpile
-pnpm prepack     # verify the packed tarball contains lib/
+npm ci
+npm test              # Cordis / DSH dispatch, persistence and React regression tests
+npm run preview:test  # Local browser verification page; prints its URL
+npm run build         # lib/ is publishable JavaScript
+npm pack --dry-run
 ```
 
-## License
+- `lib/index.js`: tool definitions and input parsing.
+- `lib/store.js`: atomic snapshots, bounded reads and authenticated channel handler.
+- `lib/client.js`: toolviews, RPC reads, status/retry and legacy metadata support.
+- `cordis.patch.yml`: Profile Bundle insertion.
 
-MIT © [jetecho](./LICENSE). See [LICENSE](./LICENSE).
+MIT © [jetecho](LICENSE).

package/README.md

@@ -2,78 +2,84 @@
 
 [English](README.en.md) | 中文
 
-在 DeepSeek Harness (dsh) 聊天里**真正把图片 / SVG / CSV 显示出来**的插件。图片与 SVG 以浏览器原生 `<img>` 渲染，CSV/TSV 表格以原生 `<table>` 渲染（粘性表头、控件限高局部滚动），均绕过聊天渲染器对 markdown / genui 的过滤；同时内置**预览式工作流**：生成或修改图片、SVG 或 CSV 时，先把结果渲染给你看，等你确认后再落地真正的改动。
+在 DeepSeek Harness 聊天中预览图片、SVG 和 CSV/TSV。图片使用原生 `<img>`，表格使用原生 `<table>`，支持粘性表头、320px 内部滚动和点击排序。
 
-## 安装
+## 安装与升级
 
-标准 Profile Bundle 安装（推荐）：
+0.1.3 针对 DSH **0.1.5-rc.1** 验证，使用新版 Connection RPC 接口。请使用该版本或兼容接口的更新版。
 
 ```sh
+# 安装已发布版本
 dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
+
+# 从当前仓库打包并安装修复版（无需发布 npm）
+npm ci
+npm test
+npm pack
+dsh plugin --profile web add ./jetecho-dsh-csv-and-image-preview-0.1.3.tgz
 ```
 
-或从本地目录安装开发版：
+安装后重启 `dsh web` 并刷新浏览器。包名、bundle 行 ID 和工具名均保持不变。
 
-```sh
-dsh plugin --profile web add ../dsh-csv-and-image-preview
-```
+## 0.1.3：修正正文预览的实际挂载
 
-安装后需重启 `dsh web` 让新 bundle 进入运行时。更早版本兼容做法是手动把包复制进 profile 的 `node_modules` 并在 `cordis.patch.yml` 插入 `- insert: [...]`，仅作旧版本兜底。
+0.1.3 使用独立的 `conversation.chat.node` 键控内容行，在 `turn/end` 之后显示预览，避开执行过程的折叠区间。原有文件卡片继续由 DSH 渲染。
 
-## 它做什么
+图片、SVG、CSV 支持直接调用、`run_code` 嵌套调用和旧版 meta。刷新或重新打开会话后重放已保存的预览；仅调用 DSH `present` 而没有调用本插件的文件不在此功能范围内。
 
-1. **真渲染图片**。宿主注册 `preview_image` 工具：读取文件路径（或内联 SVG），推断 MIME、base64 编码成 data-URI，通过工具结果的 `presentationMeta` 投递；浏览器端键控 toolview（`tool.call.toolview` key=`preview_image`）读取 meta 并渲染原生 `<img>`。图片字节只走 meta 进浏览器，**不进入模型上下文**。
-2. **预览式工作流**。调用 `preview_image` 后，脚本拿到的是紧凑摘要（SVG/位图、尺寸、字节数），真正的画面直接显示在聊天里；脚本会「等待用户确认」，等你点头后才写入文件/执行改动。
-3. **预览任意资源**。给一个本地路径即可预览对应图片文件；也能传入内联 SVG 文本直接渲染，无需落盘。
-4. **CSV/TSV 表格预览**。宿主注册 `preview_csv` 工具：读取 CSV/TSV 文件（或内联文本），自动嗅探分隔符（`,` `;` Tab `|`，可用 `delimiter` 指定），有界解析后把表格投递到 meta；浏览器端键控 toolview（key=`preview_csv`）渲染原生 `<table>`。表格控件**限高 320px 局部滚动**，默认只投递前 50 行（`maxRows` 可调，上限 500），超宽列数与超长单元格也会截断——模型只拿到行列摘要，表格数据不进模型上下文。表头**点击排序**（数值/中文拼音自适应，空值沉底，升→降→取消循环），单元格超长自动省略号、悬停看全文。
+验证：`npm test` 使用真实 SlotCore 校验注册。设置 `DSH_UPSTREAM` 为 DSH 源码目录后，可额外使用真实 ConversationNodeAssembler 和 ChatSnapshotBuilder 检查增量事件与历史回放。`npm run preview:test` 提供浏览器验收页；同时设置 `DSH_SESSION` 为本机会话文件时，只读回放该会话及已有快照，不修改原会话文件。
 
-## 用法示例
+## 兼容性修复
 
-```markdown
-<!-- 预览磁盘上的 logo -->
-我先给你看预览。
-[调用 preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
-```
+预览只注册 `/api/csv-and-image-preview/get` 精确路由，避免占用由 DSH 系统网关独享的 `/api` 拦截器，保证历史列表和插件列表正常加载。升级后重启 DSH 并刷新页面即可重新加载，修复不修改会话文件。
 
-```markdown
-<!-- 预览内联 SVG（未落盘） -->
-[调用 preview_image content=<svg ...> mime=image/svg+xml label=草图]
-```
+- 前端声明 `slots`、`connection` 服务依赖，后端声明 `tools`、`connection`；服务稍晚就绪时会等待，卸载时清理注册。
+- **直接调用和 `run_code` 嵌套调用均可预览。** 新版 DSH 不为嵌套调用生成 `presentationMeta`，因此本插件改用独立快照通道。
+- 工具只读取、解析一次输入，在返回成功之前保存快照。模型和 `run_code` 程序收到的仍是字符串摘要，不额外包含图片字节或表格正文。
+- 前端区分生成中、加载中、执行失败、快照缺失和图片解码失败，支持重试、连接恢复后重新读取，以及切换会话时取消过期请求。
+- 旧会话已有的 `block.meta.src` / `block.meta.rows` 继续显示。旧版嵌套调用如果从未保存展示数据，需重新调用预览工具。
+
+## 使用
 
-```markdown
-<!-- 预览 CSV 文件（截断到前 100 行） -->
-[调用 preview_csv path=E:\DSHConfig\data.csv label=销售数据 maxRows=100]
+让 agent 调用工具，例如：
+
+```text
+preview_image {"path":"D:/assets/logo.svg","label":"Logo 预览"}
+preview_csv {"path":"D:/data/sales.csv","label":"销售数据","maxRows":100}
+preview_csv {"content":"姓名,分数\n张三,90\n李四,85"}
 ```
 
-脚本会读到类似 `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB)。` 的返回，图片则显示在工具卡片里；CSV 则是 `已渲染 CSV 预览「销售数据」:CSV 表格 1234 行 × 5 列,分隔符 ",";显示前 100 行。`，表格显示在工具卡片里。
+内联 SVG 可直接传入 `content`。相对路径以当前会话工作目录为基准。`path` 与 `content` 同时存在时优先读取 `path`。
 
-## 约定：预览优先
+图片支持 SVG、PNG、JPEG、GIF、WebP、BMP、ICO、AVIF。内联非 SVG 内容使用标准 base64，同时指定 `mime`。图片和 CSV 输入均限制为 8 MiB；内联 base64 限制按编码后的输入大小计算。
 
-本插件把「先预览、后落地」作为默认约定：
+CSV 文件必须为 UTF-8，支持 UTF-8 BOM；其他编码会明确提示转换，而不是输出乱码。自动识别逗号、分号、Tab、竖线，或用 `delimiter` 指定；`.tsv` 默认 Tab。默认显示前 50 行，最多 500 行（均含表头）、40 列，每个单元格最多保存 200 字符加省略号。悬停显示已保存的单元格内容，截断部分无法还原。点击表头循环升序、降序、原始顺序，空值始终沉底。
 
-- 生成 / 修改图片、SVG 或 CSV 时，**先** `preview_image` / `preview_csv` 渲染，不做真实写入；
-- 用户确认（`确认` / `可以` / `就这样`）后，才真正写文件 / 执行改动；
-- 用户否决时，按反馈重做并再次预览；
-- 需要预览任意资源时，直接传 `path`。
+## 数据与历史预览
 
-要强制遵守这一约定，可以配合附带的 agent preset（见 `Agent.md`），它会把这套规则写进会话 persona。
+预览快照保存在 `$DSH_HOME/storages/csv-and-image-preview/`；未设置 `DSH_HOME` 时使用 `~/.dsh/storages/csv-and-image-preview/`。每条记录按会话 ID、调用 ID 和工具名定位，路径采用哈希文件名。通过 DSH Connection 的已认证 `/api` RPC 通道读取，并核对记录身份。
 
-## 组成部分
+刷新页面、重启 DSH 或修改/删除原文件后，同一会话仍显示生成时的快照。备份会话时应同时备份此目录。当前不自动清理快照；删除目录会让新版历史预览失效。复制/分叉成新会话时不自动迁移原会话的快照。
 
-```
-lib/index.js   宿主：注册 preview_image / preview_csv 工具，读取文件并投递 data-URI / 表格 meta
-lib/client.js  浏览器 bundle：注册键控 toolview，渲染原生 <img> / <table>
-cordis.patch.yml  profile 插入行
-```
+调用返回 `预览数据已生成…` 表示快照保存成功，不代表浏览器已解码显示。工具执行错误作为真正的失败交给 DSH，避免误报成功。
+
+## 预览优先约定
+
+生成或修改图片、SVG、CSV 时，先预览，用户认可后再修改目标文件；预览快照本身会写入插件数据目录。此约定由 agent 遵守，插件不阻止其他写文件工具。可将 [Agent.md](Agent.md) 的说明加入 agent 指令。
 
 ## 开发
 
 ```sh
-pnpm install
-pnpm build       # no-op：lib/ 为成品，无需转译
-pnpm prepack     # 校验打包内容含 lib/
+npm ci
+npm test              # Cordis / DSH 工具调度、持久化、React 组件回归
+npm run preview:test  # 本地浏览器验收页，终端显示地址
+npm run build         # lib/ 为可直接发布的 JavaScript
+npm pack --dry-run    # 检查发布文件
 ```
 
-## License
+- `lib/index.js`：工具定义、输入读取与解析。
+- `lib/store.js`：原子快照写入、读取边界、认证通道处理函数。
+- `lib/client.js`：工具视图、RPC 读取、状态与重试、旧 meta 兼容。
+- `cordis.patch.yml`：标准 Profile Bundle 插入行。
 
-MIT © [jetecho](./LICENSE)，详见 [LICENSE](./LICENSE)。
+MIT © [jetecho](LICENSE).

package/lib/client.js

@@ -2,9 +2,9 @@
  * dsh-csv-and-image-preview 浏览器端 bundle(单文件,经 __ModuleLoader__ 加载)。
  *
  * 为两个工具注册键控 toolview(`tool.call.toolview`, key = 工具名):
- *  - `preview_image`:从结果节点 meta 读取 { src, mime, label },渲染浏览器
+ *  - `preview_image`:通过会话/调用 ID 读取快照(兼容旧 meta),渲染浏览器
  *    原生 <img>;
- *  - `preview_csv`:从结果节点 meta 读取 { label, delimiter, rows, ... },
+ *  - `preview_csv`:读取表格快照 { label, delimiter, rows, ... },
  *    渲染原生 <table>(粘性表头、控件限高 320px 局部滚动、表头点击排序)。
  *
  * 这样图片/表格都不经过聊天渲染器的 markdown/genui 白名单,直接以真实 DOM
@@ -30,6 +30,7 @@ window.__ModuleLoader__.load({
       '.dip-img{display:block;max-width:100%;height:auto;border-radius:8px}',
       '.dip-img.svg{background:#fff}',
       '.dip-missing{font-size:12px;color:var(--dsw-alias-label-tertiary)}',
+      '.dip-error{font-size:12px;color:var(--dsw-alias-state-error-primary,#c33)}',
       '/* preview_csv 表格:控件限高,内部滚动,不撑爆聊天卡片 */',
       '.dip-table-wrap{max-height:320px;max-width:100%;overflow:auto;border:1px solid var(--dsw-alias-border-l1);border-radius:8px}',
       '.dip-table{border-collapse:separate;border-spacing:0;font-size:12px;line-height:20px;white-space:nowrap}',
@@ -57,19 +58,71 @@ window.__ModuleLoader__.load({
       return block !== null && typeof block === 'object' && 'meta' in block ? block.meta : undefined
     }
 
+    function legacyMeta(props) {
+      const meta = metaOf(props)
+      if (!meta || typeof meta !== 'object') return null
+      if (props.toolName === 'preview_image' && typeof meta.src === 'string') return meta
+      if (props.toolName === 'preview_csv' && Array.isArray(meta.rows)) return meta
+      return null
+    }
+
+    /** Cancel stale reads on navigation; re-read after connection recovery or retry. */
+    function usePreview(props) {
+      const block = props.block
+      const legacy = legacyMeta(props)
+      const settled = block?.kind === 'tool-result'
+      const text = (block?.content || []).filter(c => c.type === 'text').map(c => c.text).join('\n')
+      const failed = block?.isError || /^preview_(?:image|csv) 失败:/.test(text)
+      const key = JSON.stringify([props.sessionId, props.callId, props.toolName])
+      const [attempt, setAttempt] = React.useState(0)
+      const [state, setState] = React.useState(null)
+      const generation = React.useSyncExternalStore(props.subscribeConnection, props.getConnection, props.getConnection)
+      React.useEffect(() => {
+        if (legacy || !settled || failed) return
+        const controller = new AbortController()
+        let active = true
+        setState({ key, loading: true })
+        props.loadPreview({ sessionId: props.sessionId, callId: props.callId, toolName: props.toolName }, controller.signal)
+          .then(meta => { if (active) setState({ key, meta }) })
+          .catch(error => { if (active) setState({ key, error: error.message || '加载预览失败。' }) })
+        return () => { active = false; controller.abort() }
+      }, [key, settled, failed, legacy, attempt, generation, props.loadPreview])
+      if (failed) return { error: text || '预览执行失败。' }
+      if (legacy) return { meta: legacy }
+      if (!settled) return { loading: true, message: '正在生成预览…' }
+      const current = state?.key === key ? state : { loading: true }
+      return { ...current, retry: () => setAttempt(n => n + 1) }
+    }
+
+    function PreviewStatus({ state }) {
+      return React.createElement('div', { className: 'dip-root', 'data-dip-preview': true },
+        React.createElement('span', { className: state.error ? 'dip-error' : 'dip-missing', role: state.error ? 'alert' : 'status' },
+          state.error || state.message || '正在加载预览…'),
+        state.error && state.retry ? React.createElement('button', { type: 'button', onClick: state.retry }, '重试') : null)
+    }
+
+    function validImage(meta) {
+      return meta && typeof meta.src === 'string'
+        && /^data:image\/(?:svg\+xml|png|jpeg|gif|webp|bmp|x-icon|avif);base64,/.test(meta.src)
+    }
+
     /**
      * 键控 toolview(preview_image):从 meta 读取 { src, mime, label } 渲染
      * 原生 <img>。
      */
     function PreviewToolView(props) {
-      const meta = metaOf(props)
+      const state = usePreview(props)
+      const meta = state.meta
+      const [failedSrc, setFailedSrc] = React.useState(null)
+      React.useEffect(() => { setFailedSrc(null) }, [props.sessionId, props.callId])
       const label = typeof meta === 'object' && meta !== null && typeof meta.label === 'string' ? meta.label : '预览'
       const src = typeof meta === 'object' && meta !== null && typeof meta.src === 'string' ? meta.src : null
       const isSvg = typeof meta === 'object' && meta !== null && meta.mime === 'image/svg+xml'
-      if (src === null) {
-        return React.createElement('div', { className: 'dip-root', 'data-dip-preview': true },
-          React.createElement('span', { className: 'dip-missing' }, '图片预览缺少数据(meta 缺失)'))
-      }
+      if (!meta) return React.createElement(PreviewStatus, { state })
+      if (!validImage(meta)) return React.createElement(PreviewStatus, { state: { error: '图片预览格式无效。' } })
+      if (failedSrc === src) return React.createElement(PreviewStatus, { state: {
+        error: '浏览器无法解码这张图片，请检查图片文件或重新生成预览。', retry: () => setFailedSrc(null),
+      } })
       return React.createElement('div', { className: 'dip-root', 'data-dip-preview': true },
         React.createElement('span', { className: 'dip-label' }, label),
         React.createElement('figure', { className: 'dip-figure' },
@@ -77,6 +130,7 @@ window.__ModuleLoader__.load({
             className: 'dip-img' + (isSvg ? ' svg' : ''),
             src: src,
             alt: label,
+            onError: () => setFailedSrc(src),
           })))
     }
 
@@ -123,15 +177,17 @@ window.__ModuleLoader__.load({
      * rows[0] 为表头;数字单元格右对齐;表头点击循环排序(升→降→取消)。
      */
     function CsvToolView(props) {
-      const meta = metaOf(props)
-      const ok = meta !== null && typeof meta === 'object' && Array.isArray(meta.rows) && meta.rows.length > 0
+      const state = usePreview(props)
+      const meta = state.meta
+      const ok = meta !== null && typeof meta === 'object' && Array.isArray(meta.rows)
+        && meta.rows.length > 0 && meta.rows.every(Array.isArray)
       // hooks 必须无条件调用,放在提前 return 之前。
       const sortPair = React.useState(null) // null | { col, dir }
       const sort = sortPair[0]
       const setSort = sortPair[1]
+      React.useEffect(() => { setSort(null) }, [meta])
       if (!ok) {
-        return React.createElement('div', { className: 'dip-root', 'data-dip-preview': true },
-          React.createElement('span', { className: 'dip-missing' }, 'CSV 预览缺少数据(meta 缺失)'))
+        return React.createElement(PreviewStatus, { state: meta ? { error: 'CSV 预览数据无效。' } : state })
       }
       const label = typeof meta.label === 'string' && meta.label !== '' ? meta.label : 'CSV 预览'
 
@@ -166,21 +222,93 @@ window.__ModuleLoader__.load({
     }
 
     // ── 服务接入 ─────────────────────────────────────────────────────────────
-    const inject = []
+    const PREVIEWS_KEY = 'csv-and-image-preview'
+    const isPreviewTool = name => name === 'preview_image' || name === 'preview_csv'
+
+    // Replay successful native and PTC previews as dedicated Chat nodes.
+    // Their end-of-turn anchors remain outside the collapsible process interval.
+    const previewCalls = {
+      kind: PREVIEWS_KEY + '/calls',
+      target: 'chat',
+      match(event) {
+        if (event.type === 'tool/call') return { id: String(event.data.callId), role: 'start' }
+        if (event.type === 'tool/result' && event.surfaceOp === 'append') {
+          return { id: String(event.data.message.source.callId), role: 'update' }
+        }
+        if (event.type === 'tool/ptc-dispatch' && typeof event.data.rootCallId === 'string') {
+          return { id: event.data.rootCallId, role: 'update' }
+        }
+        return null
+      },
+      start(_context, match) { return { name: match.event.data.name, previews: [] } },
+      update(context, match) {
+        const { event } = match
+        const nested = event.type === 'tool/ptc-dispatch'
+        const toolName = nested ? event.data.name : context.state.name
+        const result = nested ? event.data : event.data.message.content[0]
+        if (!isPreviewTool(toolName) || !result || result.isError) return context.state
+        const content = result.content || []
+        if (content.some(item => item.type === 'text' && /^preview_(?:image|csv) 失败:/.test(item.text))) return context.state
+        const callId = String(nested ? event.data.subCallId : event.data.message.source.callId)
+        const preview = { callId, toolName, seq: event.seq,
+          block: { kind: 'tool-result', isError: false, content,
+            ...!nested && event.data.meta ? { meta: event.data.meta } : {} } }
+        return { ...context.state, previews: [...context.state.previews.filter(item => item.callId !== callId), preview] }
+      },
+      buildViewNode(context) {
+        const location = context.start?.location
+        if (!context.state || !location?.turn) return null
+        const end = location.turn.end
+        return { key: context.key, id: context.id, kind: context.kind, target: 'chat', location,
+          // Placing this row after turn/end keeps it outside the process interval.
+          // A hidden node keeps its identity while the toolview handles live output.
+          anchorSeq: end ? end.seq + 0.01 : context.start.event.seq,
+          visibility: end && context.state.previews.length ? 'visible' : 'hidden',
+          data: { previews: context.state.previews } }
+      },
+    }
+    function ChatPreviews(props) {
+      return React.createElement('div', { className: 'dip-root', 'data-dip-turn-previews': true },
+        props.node.data.previews.map(preview => React.createElement(preview.toolName === 'preview_image' ? PreviewToolView : CsvToolView,
+          { ...props, ...preview, key: props.sessionId + ':' + preview.callId })))
+    }
+
+    const inject = ['slots', 'connection', 'uiConversation']
     function apply(ctx) {
-      const slots = ctx.get('slots')
-      if (slots === undefined) return
-      const disposals = [
+      const slots = ctx.slots
+      const connection = ctx.connection
+      const bindings = {
+        async loadPreview(request, signal) {
+          const result = await connection.rpc.call('/api', 'csv-and-image-preview/get', request, signal)
+          if (!result.ok) throw new Error(result.error.message)
+          const value = result.value
+          if (request.toolName === 'preview_image' ? !validImage(value)
+            : !value || !Array.isArray(value.rows) || !value.rows.length || !value.rows.every(Array.isArray)) {
+            throw new Error('返回的预览数据无效。')
+          }
+          return result.value
+        },
+        subscribeConnection: listener => connection.generation.subscribe(listener),
+        getConnection: () => connection.generation.getSnapshot(),
+      }
+      ctx.effect(() => {
+        const disposals = [
+        ctx.uiConversation.events.register(previewCalls),
         slots.inject('tool.call.toolview', () => slots.register(
-          { name: 'tool.call.toolview', key: 'preview_image' },
+          { name: 'tool.call.toolview', key: 'preview_image', inject: () => bindings },
           PreviewToolView,
         )),
         slots.inject('tool.call.toolview', () => slots.register(
-          { name: 'tool.call.toolview', key: 'preview_csv' },
+          { name: 'tool.call.toolview', key: 'preview_csv', inject: () => bindings },
           CsvToolView,
         )),
-      ]
-      return () => { for (const dispose of disposals) dispose() }
+        slots.inject('conversation.chat.node', () => slots.register(
+          { name: 'conversation.chat.node', key: PREVIEWS_KEY + '/calls', inject: () => bindings },
+          ChatPreviews,
+        )),
+        ]
+        return () => { for (const dispose of disposals) dispose() }
+      }, 'preview: toolviews')
     }
 
     exports.apply = apply

package/lib/index.js

@@ -6,24 +6,20 @@
  *     推断 MIME、base64 编码为 data-URI;
  *  2. 注册 `preview_csv` 工具:读取 CSV/TSV(磁盘路径或内联文本),嗅探分隔符、
  *     有界解析(输入体积/行数/列数/单元格四重截断),产出可序列化的表格 meta;
- *  3. 两者都把展示数据通过工具结果的 `presentationMeta` 投递出去,浏览器端
- *     键控 toolview 据此渲染原生 <img> / <table> —— 绕过聊天渲染器的过滤;
- *  4. `execute` 返回紧凑的模型可读摘要,真正的图片字节/表格数据只走 meta,
- *     不进模型上下文。
- *
- * 注意:`output.presentationMeta` 必须**同步**返回 lossless JSON(它是展示
- * 期别名,在结果落地时就读取,不能返回 Promise),因此这里用同步 fs 读取;
- * `execute` 本身是 async,但内部调用同一个同步构建器。
+ *  3. 以会话和调用 ID 保存快照,通过已认证的 Connection RPC 投递到浏览器;
+ *  4. `execute` 仅返回摘要。直接调用和 run_code 子调用使用同一通道,
+ *     不依赖仅顶层调用才计算的 presentationMeta,文件也只读取一次。
  *
  * 不导入 cordis/dsh-* 运行时包中的 Service/Context 类:仅用 ctx API 与 Node
  * 内建能力,与宿主进程共享同一套运行时实例。
  * @module dsh-csv-and-image-preview
  */
 
-import { readFileSync, statSync } from 'node:fs'
-import { resolve } from 'node:path'
-
-export const name = 'csv-and-image-preview'
+import { resolve } from 'node:path'
+import { PreviewStore, readBounded, MAX_INPUT_BYTES, executionIdentity, createPreviewRoute } from './store.js'
+
+export const name = 'csv-and-image-preview'
+export const inject = ['tools', 'connection']
 
 /** 扩展名 → MIME 推断表。 */
 const MIME_BY_EXT = {
@@ -70,10 +66,9 @@ function imageSummary(mime) {
 }
 
 /**
- * 同步构建一次预览结果,返回 { src, mime, label, bytes, summary };有错抛 Error。
- * 同步是因为 `presentationMeta` 必须同步返回 lossless JSON。
- */
-function buildPreviewSync(args) {
+ * 构建一次预览结果,返回 { src, mime, label, bytes, summary };有错抛 Error。
+ */
+async function buildPreview(args, exec) {
   if (typeof args !== 'object' || args === null) {
     throw new Error('preview_image 需要对象参数(带 path 或 content)。')
   }
@@ -81,29 +76,34 @@ function buildPreviewSync(args) {
 
   // 优先:磁盘文件路径。
   if (typeof args.path === 'string' && args.path !== '') {
-    const abs = resolve(args.path)
-    const mime = mimeOf(abs)
-    const buf = readFileSync(abs)
-    const st = statSync(abs)
+    const abs = resolve(exec?.agent?.session?.header?.cwd || process.cwd(), args.path)
+    const mime = mimeOf(abs)
+    if (!Object.values(MIME_BY_EXT).includes(mime)) throw new Error('不支持此图片格式。')
+    const buf = await readBounded(abs, MAX_INPUT_BYTES, exec?.signal)
     const b64 = buf.toString('base64')
     return {
       src: `data:${mime};base64,${b64}`,
       mime,
       label,
-      bytes: st.size,
+      bytes: buf.length,
       summary: imageSummary(mime),
     }
   }
 
   // 备选:调用方直接给内容。
   if (typeof args.content === 'string' && args.content !== '') {
-    const mime = args.mime === 'image/svg+xml' ? 'image/svg+xml' : (typeof args.mime === 'string' ? args.mime : 'image/svg+xml')
-    if (mime === 'image/svg+xml') {
-      const b64 = Buffer.from(args.content, 'utf8').toString('base64')
-      return { src: `data:image/svg+xml;base64,${b64}`, mime, label, bytes: b64.length, summary: `inline SVG ${svgDimension(args.content)}` }
-    }
-    // 假定 content 已是 base64。
-    return { src: `data:${mime};base64,${args.content}`, mime, label, bytes: args.content.length, summary: `inline ${mime}` }
+    const mime = args.mime === 'image/svg+xml' ? 'image/svg+xml' : (typeof args.mime === 'string' ? args.mime : 'image/svg+xml')
+    if (!Object.values(MIME_BY_EXT).includes(mime)) throw new Error('不支持此图片 MIME。')
+    if (Buffer.byteLength(args.content, 'utf8') > MAX_INPUT_BYTES) throw new Error('内联图片超过 8 MB 预览上限。')
+    if (mime === 'image/svg+xml') {
+      const b64 = Buffer.from(args.content, 'utf8').toString('base64')
+      return { src: `data:image/svg+xml;base64,${b64}`, mime, label, bytes: Buffer.byteLength(args.content), summary: `inline SVG ${svgDimension(args.content)}` }
+    }
+    const b64 = args.content.replace(/\s/g, '')
+    if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(b64) || !b64) {
+      throw new Error('图片 content 必须是有效的 base64。')
+    }
+    return { src: `data:${mime};base64,${b64}`, mime, label, bytes: Buffer.from(b64, 'base64').length, summary: `inline ${mime}` }
   }
 
   throw new Error('preview_image 需要 path 或 content 参数。')
@@ -111,15 +111,15 @@ function buildPreviewSync(args) {
 
 /**
  * 构建 preview_image 工具定义。注册进工具注册表后,模型可用它发起一次
- * “预览”:宿主读取图片并投递 data-URI 到 meta,浏览器端 toolview 渲染。
+ * “预览”:宿主读取图片并保存快照,浏览器端 toolview 按调用 ID 读取。
  */
-export function createPreviewTool() {
+export function createPreviewTool(store = new PreviewStore()) {
   return {
     name: 'preview_image',
     description:
       '在聊天里预览一张图片或 SVG——用浏览器原生 <img> 渲染,绕过聊天渲染器对图片的过滤。'
       + ' 传 path 读取磁盘文件,或传 content(内联 SVG 文本)直接预览。'
-      + ' 图片字节只走 meta 投递到浏览器,不进入模型上下文;返回的是紧凑摘要。'
+      + ' 图片快照通过独立通道投递到浏览器,不进入模型上下文;返回的是紧凑摘要。'
       + ' 生成/修改图片时先调用它给用户预览,等用户确认后再做真正的写入/修改。',
     parameters: {
       type: 'object',
@@ -148,24 +148,12 @@ export function createPreviewTool() {
       render(_args, value) {
         return [{ type: 'text', text: String(value) }]
       },
-      presentationMeta(args) {
-        // 必须同步返回 lossless JSON(genui 的 render_ui 正是如此:从 args 直接推导)。
-        try {
-          const r = buildPreviewSync(args)
-          return { src: r.src, mime: r.mime, label: r.label }
-        } catch {
-          return null
-        }
-      },
-    },
-    async execute(args) {
-      try {
-        const r = buildPreviewSync(args)
-        return `已渲染预览「${r.label}」:${r.summary}(${r.bytes} B)。图片已显示在聊天中,等待用户确认后再做真正的修改。`
-      } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error)
-        return `preview_image 失败:${detail}`
-      }
+    },
+    async execute(args, exec) {
+      const identity = executionIdentity(exec, 'preview_image')
+      const r = await buildPreview(args, exec)
+      await store.put(identity, { src: r.src, mime: r.mime, label: r.label }, exec.signal)
+      return `预览数据已生成「${r.label}」:${r.summary}(${r.bytes} B)。请查看预览,等待用户确认后再做真正的修改。`
     },
     presentCall(args) {
       return { card: 'generic', title: `预览「${labelOf(args, '预览图片')}」`, kind: 'other' }
@@ -277,11 +265,11 @@ function capCell(c) {
 }
 
 /**
- * 同步构建 CSV 预览 meta,返回 { label, delimiter, rows, totalRows, totalCols,
+ * 构建 CSV 预览快照,返回 { label, delimiter, rows, totalRows, totalCols,
  * rowsShown, colsShown };有错抛 Error。rows 含表头行,已被列数/单元格截断并
  * 补齐成规则矩形,浏览器可直接渲染。
  */
-function buildCsvPreviewSync(args) {
+async function buildCsvPreview(args, exec) {
   if (typeof args !== 'object' || args === null) {
     throw new Error('preview_csv 需要对象参数(带 path 或 content)。')
   }
@@ -289,12 +277,10 @@ function buildCsvPreviewSync(args) {
 
   let text = ''
   if (typeof args.path === 'string' && args.path !== '') {
-    const abs = resolve(args.path)
-    const buf = readFileSync(abs)
-    if (buf.length > CSV_MAX_INPUT_BYTES) {
-      throw new Error(`文件 ${fmtBytes(buf.length)} 超过预览上限 ${fmtBytes(CSV_MAX_INPUT_BYTES)},请先截取再预览。`)
-    }
-    text = buf.toString('utf8')
+    const abs = resolve(exec?.agent?.session?.header?.cwd || process.cwd(), args.path)
+    const buf = await readBounded(abs, CSV_MAX_INPUT_BYTES, exec?.signal)
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(buf) }
+    catch { throw new Error('CSV 不是有效的 UTF-8 编码，请转换为 UTF-8 后重试。') }
   } else if (typeof args.content === 'string' && args.content !== '') {
     if (Buffer.byteLength(args.content, 'utf8') > CSV_MAX_INPUT_BYTES) {
       throw new Error(`内联内容超过预览上限 ${fmtBytes(CSV_MAX_INPUT_BYTES)},请先截取再预览。`)
@@ -339,9 +325,9 @@ function csvSummaryText(r) {
 
 /**
  * 构建 preview_csv 工具定义。模型传 CSV 路径/文本发起一次「表格预览」:
- * 宿主有界解析后把表格投递到 meta,浏览器端 toolview 渲染原生 <table>。
+ * 宿主有界解析后保存表格快照,浏览器端 toolview 渲染原生 <table>。
  */
-export function createCsvTool() {
+export function createCsvTool(store = new PreviewStore()) {
   return {
     name: 'preview_csv',
     description:
@@ -349,7 +335,7 @@ export function createCsvTool() {
       + ' 传 path 读取磁盘文件(.csv/.tsv 等),或传 content(内联 CSV 文本)。'
       + ' 分隔符自动嗅探(, ; Tab |),可用 delimiter 指定;默认只投递前 '
       + `${CSV_MAX_ROWS_DEFAULT} 行(可用 maxRows 调大,上限 ${CSV_MAX_ROWS_LIMIT})。`
-      + ' 表格数据只走 meta 投递到浏览器,不进入模型上下文;返回的是行列摘要。'
+      + ' 表格快照通过独立通道投递到浏览器,不进入模型上下文;返回的是行列摘要。'
       + ' 生成/修改 CSV 时先调用它给用户预览,等用户确认后再做真正的写入/修改。',
     parameters: {
       type: 'object',
@@ -383,23 +369,12 @@ export function createCsvTool() {
       render(_args, value) {
         return [{ type: 'text', text: String(value) }]
       },
-      presentationMeta(args) {
-        // 必须同步返回 lossless JSON;解析全程同步。
-        try {
-          return buildCsvPreviewSync(args)
-        } catch {
-          return null
-        }
-      },
-    },
-    async execute(args) {
-      try {
-        const r = buildCsvPreviewSync(args)
-        return `已渲染 CSV 预览「${r.label}」:${csvSummaryText(r)}表格已显示在聊天中,等待用户确认后再做真正的修改。`
-      } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error)
-        return `preview_csv 失败:${detail}`
-      }
+    },
+    async execute(args, exec) {
+      const identity = executionIdentity(exec, 'preview_csv')
+      const r = await buildCsvPreview(args, exec)
+      await store.put(identity, r, exec.signal)
+      return `CSV 预览数据已生成「${r.label}」:${csvSummaryText(r)}请查看预览,等待用户确认后再做真正的修改。`
     },
     presentCall(args) {
       return { card: 'generic', title: `CSV 预览「${labelOf(args, 'CSV 表格')}」`, kind: 'other' }
@@ -410,25 +385,10 @@ export function createCsvTool() {
   }
 }
 
-/**
- * 注册工具。`tools` 服务可能晚于本插件绑定(启动顺序),因此既在 apply 时
- * 探测一次,也订阅 `internal/service`(cordis 在每次服务绑定时发出),确保
- * 一旦工具注册表出现就立即注册。
- */
-export function apply(ctx) {
-  let registered = false
-  const tryRegister = (value) => {
-    if (registered) return
-    const tools = value ?? ctx.reflect.get('tools', false)
-    if (tools === undefined) return
-    tools.register(createPreviewTool())
-    tools.register(createCsvTool())
-    registered = true
-  }
-  tryRegister(undefined)
-  if (typeof ctx.on === 'function') {
-    ctx.on('internal/service', (name, value) => {
-      if (name === 'tools') tryRegister(value)
-    })
-  }
-}
+/** Service declarations park this plugin until dependencies are active. */
+export function apply(ctx) {
+  const store = new PreviewStore()
+  ctx.effect(() => ctx.connection.fetch.register(createPreviewRoute(store)), 'preview: exact RPC route')
+  ctx.tools.register(createPreviewTool(store))
+  ctx.tools.register(createCsvTool(store))
+}

package/lib/store.js

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, open, rename, unlink } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+export const PREVIEW_ENDPOINT = 'csv-and-image-preview/get'
+export const MAX_INPUT_BYTES = 8 * 1024 * 1024
+const MAX_RECORD_BYTES = 16 * 1024 * 1024
+
+function defaultDirectory() {
+  let home = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
+  if (home === '~') home = homedir()
+  else if (/^~[/\\]/.test(home)) home = join(homedir(), home.slice(2))
+  return resolve(home, 'storages', 'csv-and-image-preview')
+}
+
+/** Bound the allocation even when a source file grows after stat(). */
+export async function readBounded(path, limit = MAX_INPUT_BYTES, signal) {
+  signal?.throwIfAborted()
+  const file = await open(path, 'r')
+  try {
+    const info = await file.stat()
+    if (!info.isFile()) throw new Error('预览路径必须是普通文件。')
+    if (info.size > limit) throw new Error(`文件超过预览上限 ${limit / 1024 / 1024} MB。`)
+    const buffer = Buffer.alloc(Math.min(info.size + 1, limit + 1))
+    let length = 0
+    while (length < buffer.length) {
+      signal?.throwIfAborted()
+      const { bytesRead } = await file.read(buffer, length, buffer.length - length, null)
+      if (bytesRead === 0) break
+      length += bytesRead
+    }
+    signal?.throwIfAborted()
+    if (length > limit || length > info.size) throw new Error('文件在读取时变大，请重试预览。')
+    return buffer.subarray(0, length)
+  } finally {
+    await file.close()
+  }
+}
+
+function validIdentity(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 512
+}
+
+export function validateRequest(request) {
+  if (!request || !validIdentity(request.sessionId) || !validIdentity(request.callId)
+    || !['preview_image', 'preview_csv'].includes(request.toolName)) {
+    throw new Error('无效的预览请求。')
+  }
+}
+
+export function executionIdentity(exec, toolName) {
+  const identity = { sessionId: exec?.agent?.session?.id, callId: exec?.callId, toolName }
+  validateRequest(identity)
+  return identity
+}
+
+/** Immutable per-call snapshots, outside model output and original workspace files. */
+export class PreviewStore {
+  constructor(directory = defaultDirectory()) { this.directory = resolve(directory) }
+
+  path(identity) {
+    validateRequest(identity)
+    const key = createHash('sha256').update(JSON.stringify([
+      identity.sessionId, identity.callId, identity.toolName,
+    ])).digest('hex')
+    return join(this.directory, `${key}.json`)
+  }
+
+  async put(identity, payload, signal) {
+    const target = this.path(identity)
+    const body = JSON.stringify({ version: 1, ...identity, payload })
+    if (Buffer.byteLength(body) > MAX_RECORD_BYTES) throw new Error('预览快照超过存储上限。')
+    signal?.throwIfAborted()
+    await mkdir(this.directory, { recursive: true })
+    const temporary = `${target}.${randomUUID()}.tmp`
+    try {
+      const file = await open(temporary, 'wx', 0o600)
+      try {
+        await file.writeFile(body, { encoding: 'utf8', signal })
+        await file.sync()
+      } finally { await file.close() }
+      signal?.throwIfAborted()
+      await rename(temporary, target)
+    } finally {
+      await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error })
+    }
+  }
+
+  async get(identity, signal) {
+    let bytes
+    try { bytes = await readBounded(this.path(identity), MAX_RECORD_BYTES, signal) }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error }
+    const record = JSON.parse(bytes.toString('utf8'))
+    if (record.version !== 1 || record.sessionId !== identity.sessionId
+      || record.callId !== identity.callId || record.toolName !== identity.toolName) {
+      throw new Error('预览快照与当前会话不匹配。')
+    }
+    return record.payload
+  }
+}
+
+/** Connection applies browser authentication before this handler is invoked. */
+export function createPreviewHandler(store) {
+  return async (_endpoint, request, signal) => {
+    try { validateRequest(request) }
+    catch { return { ok: false, error: { code: 'preview/invalid', message: '无效的预览请求。', details: {} } } }
+    try {
+      const value = await store.get(request, signal)
+      if (value === null) return { ok: false, error: {
+        code: 'preview/missing', message: '未找到此调用的预览快照，旧版嵌套调用需要重新预览。', details: {},
+      } }
+      return { ok: true, value }
+    } catch {
+      return { ok: false, error: { code: 'preview/read', message: '读取预览快照失败，请重试。', details: {} } }
+    }
+  }
+}
+
+/** Own only this exact path. The single shared /api interceptor belongs to DSH's Gateway. */
+export function createPreviewRoute(store) {
+  const handle = createPreviewHandler(store)
+  return {
+    path: `/api/${PREVIEW_ENDPOINT}`,
+    methods: ['POST'],
+    requestBody: 'buffered',
+    async fetch(request) {
+      if (request.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/json') {
+        return new Response('content type must be application/json', { status: 415 })
+      }
+      let message
+      try { message = await request.json() }
+      catch { return new Response('invalid JSON', { status: 400 }) }
+      if (!message || message.type !== 'client-request' || !validIdentity(message.rpcId)
+        || message.method !== PREVIEW_ENDPOINT) {
+        return new Response('invalid preview RPC envelope', { status: 400 })
+      }
+      return Response.json({
+        type: 'server-response', rpcId: message.rpcId,
+        result: await handle(PREVIEW_ENDPOINT, message.payload, request.signal),
+      }, { headers: { 'Cache-Control': 'private, no-store' } })
+    },
+  }
+}

package/lib/types/index.d.ts

@@ -2,7 +2,18 @@
  * Public type surface for the dsh-csv-and-image-preview host half.
  * The runtime is plain JS; these declarations describe the cordis plugin
  * contract so TS consumers and the `.d.ts` re-export resolve cleanly.
- */
+ */
+
+/** Execution identity supplied by DSH for native and run_code child calls. */
+export interface PreviewExecution {
+  callId: string
+  signal: AbortSignal
+  agent: { session: { id: string; header: { cwd?: string } } }
+}
+
+export interface PreviewSnapshotStore {
+  put(identity: { sessionId: string; callId: string; toolName: string }, payload: unknown, signal?: AbortSignal): Promise<void>
+}
 
 /** The `preview_image` tool definition (a dsh ToolDefinition object). */
 export interface PreviewToolDefinition {
@@ -10,7 +21,7 @@ export interface PreviewToolDefinition {
   description: string
   parameters: Record<string, unknown>
   output: Record<string, unknown>
-  execute(args: unknown): Promise<string>
+  execute(args: unknown, exec: PreviewExecution): Promise<string>
   presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
   presentResult(args: unknown): { card: string; title: string } | undefined
 }
@@ -21,7 +32,7 @@ export interface CsvToolDefinition {
   description: string
   parameters: Record<string, unknown>
   output: Record<string, unknown>
-  execute(args: unknown): Promise<string>
+  execute(args: unknown, exec: PreviewExecution): Promise<string>
   presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
   presentResult(args: unknown): { card: string; title: string } | undefined
 }
@@ -50,5 +61,8 @@ export interface CsvPreviewMeta {
   colsShown: number
 }
 
-declare const plugin: ImagePreviewPlugin
-export default plugin
+export declare const name: 'csv-and-image-preview'
+export declare const inject: string[]
+export declare function apply(ctx: unknown): void
+export declare function createPreviewTool(store?: PreviewSnapshotStore): PreviewToolDefinition
+export declare function createCsvTool(store?: PreviewSnapshotStore): CsvToolDefinition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetecho/dsh-csv-and-image-preview",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Preview images / SVG and CSV tables in the DeepSeek Harness chat, rendered as real browser <img> / <table> elements. Preview-first workflow: show the user the asset, wait for approval, then apply the real change.",
   "type": "module",
   "main": "lib/index.js",
@@ -24,6 +24,8 @@
     "LICENSE"
   ],
   "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "preview:test": "node scripts/preview-test.mjs",
     "build": "node scripts/build.mjs",
     "prepack": "node scripts/prepack.mjs"
   },
@@ -32,7 +34,11 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "inject": [],
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
       "platform": "web"
     }
   },
@@ -58,10 +64,18 @@
   },
   "homepage": "https://github.com/jetecho/dsh-csv-and-image-preview#readme",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis": "^4.0.2",
     "react": "^18.0.0 || ^19.0.0"
   },
-  "dependencies": {
-    "react": "^18.3.1"
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
+    "immer": "^10.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-test-renderer": "^18.3.1",
+    "zustand": "~4.4.7"
   }
 }