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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/Agent.md +45 -41
  2. package/LICENSE +21 -21
  3. package/README.en.md +81 -79
  4. package/README.md +85 -79
  5. package/cordis.patch.yml +6 -6
  6. package/lib/client.js +318 -190
  7. package/lib/index.js +380 -420
  8. package/lib/store.js +144 -0
  9. package/lib/types/index.d.ts +63 -49
  10. package/package.json +81 -67
package/Agent.md CHANGED
@@ -1,41 +1,45 @@
1
- # Agent.md — dsh-csv-and-image-preview 行为契约
2
-
3
- 这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。它是给 agent 读的规则,搭配仓库里的独立 agent preset(`image-preview`)一起使用,把规则写进会话 persona。
4
-
5
- ## 核心原则:先预览,后落地
6
-
7
- 凡涉及**生成或修改图片 / SVG / CSV**,默认顺序必须是:
8
-
9
- 1. **先预览** —— 调用 `preview_image`(图片 / SVG)或 `preview_csv`(CSV / TSV 表格),把结果渲染到聊天里给用户看;
10
- - 读磁盘文件:`path=<绝对路径>`
11
- - 内联 SVG(未落盘):`content=<svg ...> mime=image/svg+xml`
12
- - 内联 CSV(未落盘):`content=<csv 文本>`;可用 `maxRows` 控制预览行数(默认 50,上限 500),`delimiter` 指定分隔符
13
- - 任意图片资源:直接传 `path`
14
- 2. **等确认** —— 预览后停止写入,等待用户明确同意;
15
- 3. **用户认可**(如 `确认` / `可以` / `就这样`)后,才真正写文件 / 执行改动;
16
- 4. **用户否决** 时,按反馈修改并**再次预览**,直到认可为止。
17
-
18
- ## 不要做的事
19
-
20
- - 不要在没预览的情况下,直接覆盖或新增一个图片 / SVG / CSV 文件。
21
- - 不要把图片字节或 CSV 全文/大段表格数据塞进回复文本或模型上下文 —— 那是 meta 的活,你只需拿到紧凑摘要。
22
- - 不要用 markdown `![alt](data:...)` 或 ```` ```dsh-ui ```` 的 `image` 组件来"显示图片"—— 聊天渲染器会拦截,必须走 `preview_image`;同理 CSV 必须走 `preview_csv`,不要用整段代码块充当"预览"。
23
-
24
- ## 交互话术
25
-
26
- - 预览后:**"这是预览,请确认后再写入。"** 或列出的差异点。
27
- - 等待确认时,保持在工作流里,不要擅自落地。
28
- - 确认后:**"已按预览图写入 `path`。"**
29
-
30
- ## 插件能力
31
-
32
- | 能力 | 说明 |
33
- |---|---|
34
- | `preview_image` 工具 | 读取文件 / 内联 SVG → data-URI → 浏览器 `<img>` 渲染 |
35
- | `preview_csv` 工具 | 读取 CSV/TSV / 内联文本 → 有界解析(默认前 50 行,上限 500,列/单元格截断)→ 浏览器 `<table>` 渲染,控件限高局部滚动,表头可点击排序 |
36
- | 键控 toolview | `tool.call.toolview` key=`preview_image` / `preview_csv`,渲染原生 DOM |
37
- | meta 通道 | 图片字节与表格数据只走 `presentationMeta` 进浏览器,不进模型上下文 |
38
-
39
- ## 为什么
40
-
41
- 聊天渲染器不渲染 markdown 或 genui 里的图片(白名单里也没有 `image` 组件)。`React.createElement('img')` 生成的是浏览器原生 `<img>`,不经过那套过滤,所以能真实显示;CSV 同理,原生 `<table>` 键控 toolview 直接渲染,模型只拿行列摘要。预览式工作流让用户**先看到结果再决策**,避免"生成即覆写"的返工。
1
+ # Agent.md — dsh-csv-and-image-preview 行为契约
2
+
3
+ 这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。可将这些规则加入会话指令。
4
+
5
+ ## 核心原则:先预览,后落地
6
+
7
+ 凡涉及**生成或修改图片 / SVG / CSV**,默认顺序必须是:
8
+
9
+ 1. **先预览** —— 调用 `preview_image`(图片 / SVG)或 `preview_csv`(CSV / TSV 表格),把结果渲染到聊天里给用户看;
10
+ - 读磁盘文件:`path=<绝对路径>`
11
+ - 内联 SVG(未落盘):`content=<svg ...> mime=image/svg+xml`
12
+ - 内联 CSV(未落盘):`content=<csv 文本>`;可用 `maxRows` 控制预览行数(默认 50,上限 500),`delimiter` 指定分隔符
13
+ - 任意图片资源:直接传 `path`
14
+ 2. **等确认** —— 预览后停止写入,等待用户明确同意;
15
+ 3. **用户认可**(如 `确认` / `可以` / `就这样`)后,才真正写文件 / 执行改动;
16
+ 4. **用户否决** 时,按反馈修改并**再次预览**,直到认可为止。
17
+
18
+ ## 不要做的事
19
+
20
+ - 不要在没预览的情况下,直接覆盖或新增一个图片 / SVG / CSV 文件。
21
+ - 不要把图片字节或 CSV 全文/大段表格数据塞进回复文本或工具输出 —— 插件通过独立快照通道展示,你只需拿到紧凑摘要。
22
+ - 返回“预览数据已生成”只表示快照保存成功。如果用户报告没有显示,按失败信息排查或重新预览,不要坚持声称已经显示。
23
+ - 不要用 markdown `![alt](data:...)` 或 ```` ```dsh-ui ```` 的 `image` 组件来"显示图片"—— 聊天渲染器会拦截,必须走 `preview_image`;同理 CSV 必须走 `preview_csv`,不要用整段代码块充当"预览"。
24
+
25
+ ## 交互话术
26
+
27
+ - 预览后:**"这是预览,请确认后再写入。"** 或列出的差异点。
28
+ - 等待确认时,保持在工作流里,不要擅自落地。
29
+ - 确认后:**"已按预览图写入 `path`。"**
30
+
31
+ ## 插件能力
32
+
33
+ | 能力 | 说明 |
34
+ |---|---|
35
+ | `preview_image` 工具 | 读取文件 / 内联 SVG → data-URI → 浏览器 `<img>` 渲染 |
36
+ | `preview_csv` 工具 | 读取 CSV/TSV / 内联文本 → 有界解析(默认前 50 行,上限 500,列/单元格截断)→ 浏览器 `<table>` 渲染,控件限高局部滚动,表头可点击排序 |
37
+ | 键控 toolview | `tool.call.toolview` key=`preview_image` / `preview_csv`,渲染原生 DOM |
38
+ | 聊天正文预览 | 回答结束后在正文末尾直接显示已生成的预览，不需要用户点击侧栏；刷新历史时重放调用并读取快照 |
39
+ | 快照通道 | 按会话 ID 和调用 ID 保存快照,经 DSH 认证的 RPC 通道给浏览器读取;直接调用和 `run_code` 均支持;旧 meta 仍兼容 |
40
+
41
+ 预览本身会在插件数据目录保存快照,不修改目标文件。新建目标文件仍需遵循用户的预览确认约定。
42
+
43
+ ## 为什么
44
+
45
+ 聊天渲染器不渲染 markdown 或 genui 里的图片(白名单里也没有 `image` 组件)。`React.createElement('img')` 生成的是浏览器原生 `<img>`,不经过那套过滤,所以能真实显示;CSV 同理,原生 `<table>` 键控 toolview 直接渲染,模型只拿行列摘要。预览式工作流让用户**先看到结果再决策**,避免"生成即覆写"的返工。
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 jetecho
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2025 jetecho
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.en.md CHANGED
@@ -1,79 +1,81 @@
1
- # dsh-csv-and-image-preview
2
-
3
- English | [中文](README.md)
4
-
5
- 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.
6
-
7
- ## Install
8
-
9
- Standard Profile Bundle install (recommended):
10
-
11
- ```sh
12
- dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
13
- ```
14
-
15
- Or install the development copy from a local directory:
16
-
17
- ```sh
18
- dsh plugin --profile web add ../dsh-csv-and-image-preview
19
- ```
20
-
21
- 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.
22
-
23
- ## What it does
24
-
25
- 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**.
26
- 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.
27
- 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.
28
- 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.
29
-
30
- ## Usage examples
31
-
32
- ```markdown
33
- <!-- Preview a file on disk -->
34
- I'll show you the preview first.
35
- [call preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
36
- ```
37
-
38
- ```markdown
39
- <!-- Preview inline SVG (not yet on disk) -->
40
- [call preview_image content=<svg ...> mime=image/svg+xml label=sketch]
41
- ```
42
-
43
- ```markdown
44
- <!-- Preview a CSV file (truncated to the first 100 rows) -->
45
- [call preview_csv path=E:\DSHConfig\data.csv label=sales maxRows=100]
46
- ```
47
-
48
- 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.
49
-
50
- ## Convention: preview first
51
-
52
- This plugin treats "preview, then apply" as the default behavior:
53
-
54
- - When generating / modifying an image, SVG, or CSV, **preview it first** with `preview_image` / `preview_csv`; do not write the real file yet.
55
- - Only after the user confirms (`确认` / `可以` / `就这样`) do you actually write / mutate.
56
- - If the user rejects it, redo per feedback and preview again.
57
- - To preview any resource, pass `path` directly.
58
-
59
- To enforce this convention, pair it with the bundled agent preset (see `Agent.md`), which writes these rules into the session persona.
60
-
61
- ## Layout
62
-
63
- ```
64
- lib/index.js host: registers the preview_image / preview_csv tools; reads files and projects data-URIs / table meta
65
- lib/client.js browser bundle: registers the keyed toolviews; renders a native <img> / <table>
66
- cordis.patch.yml profile insert line
67
- ```
68
-
69
- ## Development
70
-
71
- ```sh
72
- pnpm install
73
- pnpm build # no-op: lib/ ships prebuilt, no transpile
74
- pnpm prepack # verify the packed tarball contains lib/
75
- ```
76
-
77
- ## License
78
-
79
- MIT © [jetecho](./LICENSE). See [LICENSE](./LICENSE).
1
+ # dsh-csv-and-image-preview
2
+
3
+ English | [中文](README.md)
4
+
5
+ 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.
6
+
7
+ ## 0.1.3: dedicated inline preview rows
8
+
9
+ 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.
10
+
11
+ 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.
12
+
13
+ ## Install and upgrade
14
+
15
+ Version 0.1.3 is tested with **DSH 0.1.5-rc.1** and requires its Connection RPC interface or a compatible newer version.
16
+
17
+ ```sh
18
+ # Install the published version
19
+ dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
20
+
21
+ # Build and install this checkout without publishing to npm
22
+ npm ci
23
+ npm test
24
+ npm pack
25
+ dsh plugin --profile web add ./jetecho-dsh-csv-and-image-preview-0.1.3.tgz
26
+ ```
27
+
28
+ Restart `dsh web` and refresh the browser after installation. Package name, bundle row ID and tool names are unchanged.
29
+
30
+ ## Compatibility fixes
31
+
32
+ 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.
33
+
34
+ - Explicit client dependencies on `slots` and `connection`, and host dependencies on `tools` and `connection`. Late service startup parks the plugin; unloading cleans up registrations.
35
+ - **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.
36
+ - 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.
37
+ - Separate generating, loading, tool failure, missing snapshot and image decode failure states. Includes retry, reconnection refresh and cancellation of stale requests when navigating.
38
+ - Legacy `block.meta.src` and `block.meta.rows` still render. Old nested calls that never persisted presentation data must be previewed again.
39
+
40
+ ## Usage
41
+
42
+ ```text
43
+ preview_image {"path":"D:/assets/logo.svg","label":"Logo preview"}
44
+ preview_csv {"path":"D:/data/sales.csv","label":"Sales","maxRows":100}
45
+ preview_csv {"content":"Name,Score\nAlice,90\nBob,85"}
46
+ ```
47
+
48
+ Inline SVG text can be supplied as `content`. Relative paths resolve against the session working directory. `path` takes precedence over `content`.
49
+
50
+ 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.
51
+
52
+ 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.
53
+
54
+ ## Storage and replay
55
+
56
+ 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.
57
+
58
+ 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.
59
+
60
+ The returned “preview data generated” summary acknowledges persistence, not successful browser decoding. Tool errors are reported as real failures.
61
+
62
+ ## Preview-first convention
63
+
64
+ 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.
65
+
66
+ ## Development
67
+
68
+ ```sh
69
+ npm ci
70
+ npm test # Cordis / DSH dispatch, persistence and React regression tests
71
+ npm run preview:test # Local browser verification page; prints its URL
72
+ npm run build # lib/ is publishable JavaScript
73
+ npm pack --dry-run
74
+ ```
75
+
76
+ - `lib/index.js`: tool definitions and input parsing.
77
+ - `lib/store.js`: atomic snapshots, bounded reads and authenticated channel handler.
78
+ - `lib/client.js`: toolviews, RPC reads, status/retry and legacy metadata support.
79
+ - `cordis.patch.yml`: Profile Bundle insertion.
80
+
81
+ MIT © [jetecho](LICENSE).
package/README.md CHANGED
@@ -1,79 +1,85 @@
1
- # dsh-csv-and-image-preview
2
-
3
- [English](README.en.md) | 中文
4
-
5
- 在 DeepSeek Harness (dsh) 聊天里**真正把图片 / SVG / CSV 显示出来**的插件。图片与 SVG 以浏览器原生 `<img>` 渲染，CSV/TSV 表格以原生 `<table>` 渲染（粘性表头、控件限高局部滚动），均绕过聊天渲染器对 markdown / genui 的过滤；同时内置**预览式工作流**：生成或修改图片、SVG 或 CSV 时，先把结果渲染给你看，等你确认后再落地真正的改动。
6
-
7
- ## 安装
8
-
9
- 标准 Profile Bundle 安装（推荐）：
10
-
11
- ```sh
12
- dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
13
- ```
14
-
15
- 或从本地目录安装开发版：
16
-
17
- ```sh
18
- dsh plugin --profile web add ../dsh-csv-and-image-preview
19
- ```
20
-
21
- 安装后需重启 `dsh web` 让新 bundle 进入运行时。更早版本兼容做法是手动把包复制进 profile 的 `node_modules` 并在 `cordis.patch.yml` 插入 `- insert: [...]`，仅作旧版本兜底。
22
-
23
- ## 它做什么
24
-
25
- 1. **真渲染图片**。宿主注册 `preview_image` 工具：读取文件路径（或内联 SVG），推断 MIME、base64 编码成 data-URI，通过工具结果的 `presentationMeta` 投递；浏览器端键控 toolview（`tool.call.toolview` key=`preview_image`）读取 meta 并渲染原生 `<img>`。图片字节只走 meta 进浏览器，**不进入模型上下文**。
26
- 2. **预览式工作流**。调用 `preview_image` 后，脚本拿到的是紧凑摘要（SVG/位图、尺寸、字节数），真正的画面直接显示在聊天里；脚本会「等待用户确认」，等你点头后才写入文件/执行改动。
27
- 3. **预览任意资源**。给一个本地路径即可预览对应图片文件；也能传入内联 SVG 文本直接渲染，无需落盘。
28
- 4. **CSV/TSV 表格预览**。宿主注册 `preview_csv` 工具：读取 CSV/TSV 文件（或内联文本），自动嗅探分隔符（`,` `;` Tab `|`，可用 `delimiter` 指定），有界解析后把表格投递到 meta；浏览器端键控 toolview（key=`preview_csv`）渲染原生 `<table>`。表格控件**限高 320px 局部滚动**，默认只投递前 50 行（`maxRows` 可调，上限 500），超宽列数与超长单元格也会截断——模型只拿到行列摘要，表格数据不进模型上下文。表头**点击排序**（数值/中文拼音自适应，空值沉底，升→降→取消循环），单元格超长自动省略号、悬停看全文。
29
-
30
- ## 用法示例
31
-
32
- ```markdown
33
- <!-- 预览磁盘上的 logo -->
34
- 我先给你看预览。
35
- [调用 preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
36
- ```
37
-
38
- ```markdown
39
- <!-- 预览内联 SVG（未落盘） -->
40
- [调用 preview_image content=<svg ...> mime=image/svg+xml label=草图]
41
- ```
42
-
43
- ```markdown
44
- <!-- 预览 CSV 文件（截断到前 100 行） -->
45
- [调用 preview_csv path=E:\DSHConfig\data.csv label=销售数据 maxRows=100]
46
- ```
47
-
48
- 脚本会读到类似 `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB)。` 的返回，图片则显示在工具卡片里；CSV 则是 `已渲染 CSV 预览「销售数据」:CSV 表格 1234 行 × 5 列,分隔符 ",";显示前 100 行。`，表格显示在工具卡片里。
49
-
50
- ## 约定：预览优先
51
-
52
- 本插件把「先预览、后落地」作为默认约定：
53
-
54
- - 生成 / 修改图片、SVG 或 CSV 时，**先** `preview_image` / `preview_csv` 渲染，不做真实写入；
55
- - 用户确认（`确认` / `可以` / `就这样`）后，才真正写文件 / 执行改动；
56
- - 用户否决时，按反馈重做并再次预览；
57
- - 需要预览任意资源时，直接传 `path`。
58
-
59
- 要强制遵守这一约定，可以配合附带的 agent preset（见 `Agent.md`），它会把这套规则写进会话 persona。
60
-
61
- ## 组成部分
62
-
63
- ```
64
- lib/index.js 宿主：注册 preview_image / preview_csv 工具，读取文件并投递 data-URI / 表格 meta
65
- lib/client.js 浏览器 bundle：注册键控 toolview，渲染原生 <img> / <table>
66
- cordis.patch.yml profile 插入行
67
- ```
68
-
69
- ## 开发
70
-
71
- ```sh
72
- pnpm install
73
- pnpm build # no-op：lib/ 为成品，无需转译
74
- pnpm prepack # 校验打包内容含 lib/
75
- ```
76
-
77
- ## License
78
-
79
- MIT © [jetecho](./LICENSE)，详见 [LICENSE](./LICENSE)。
1
+ # dsh-csv-and-image-preview
2
+
3
+ [English](README.en.md) | 中文
4
+
5
+ 在 DeepSeek Harness 聊天中预览图片、SVG 和 CSV/TSV。图片使用原生 `<img>`，表格使用原生 `<table>`，支持粘性表头、320px 内部滚动和点击排序。
6
+
7
+ ## 安装与升级
8
+
9
+ 0.1.3 针对 DSH **0.1.5-rc.1** 验证，使用新版 Connection RPC 接口。请使用该版本或兼容接口的更新版。
10
+
11
+ ```sh
12
+ # 安装已发布版本
13
+ dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
14
+
15
+ # 从当前仓库打包并安装修复版（无需发布 npm）
16
+ npm ci
17
+ npm test
18
+ npm pack
19
+ dsh plugin --profile web add ./jetecho-dsh-csv-and-image-preview-0.1.3.tgz
20
+ ```
21
+
22
+ 安装后重启 `dsh web` 并刷新浏览器。包名、bundle 行 ID 和工具名均保持不变。
23
+
24
+ ## 0.1.3：修正正文预览的实际挂载
25
+
26
+ 0.1.3 使用独立的 `conversation.chat.node` 键控内容行，在 `turn/end` 之后显示预览，避开执行过程的折叠区间。原有文件卡片继续由 DSH 渲染。
27
+
28
+ 图片、SVG、CSV 支持直接调用、`run_code` 嵌套调用和旧版 meta。刷新或重新打开会话后重放已保存的预览；仅调用 DSH `present` 而没有调用本插件的文件不在此功能范围内。
29
+
30
+ 验证：`npm test` 使用真实 SlotCore 校验注册。设置 `DSH_UPSTREAM` 为 DSH 源码目录后，可额外使用真实 ConversationNodeAssembler 和 ChatSnapshotBuilder 检查增量事件与历史回放。`npm run preview:test` 提供浏览器验收页；同时设置 `DSH_SESSION` 为本机会话文件时，只读回放该会话及已有快照，不修改原会话文件。
31
+
32
+ ## 兼容性修复
33
+
34
+ 预览只注册 `/api/csv-and-image-preview/get` 精确路由，避免占用由 DSH 系统网关独享的 `/api` 拦截器，保证历史列表和插件列表正常加载。升级后重启 DSH 并刷新页面即可重新加载，修复不修改会话文件。
35
+
36
+ - 前端声明 `slots`、`connection` 服务依赖，后端声明 `tools`、`connection`；服务稍晚就绪时会等待，卸载时清理注册。
37
+ - **直接调用和 `run_code` 嵌套调用均可预览。** 新版 DSH 不为嵌套调用生成 `presentationMeta`，因此本插件改用独立快照通道。
38
+ - 工具只读取、解析一次输入，在返回成功之前保存快照。模型和 `run_code` 程序收到的仍是字符串摘要，不额外包含图片字节或表格正文。
39
+ - 前端区分生成中、加载中、执行失败、快照缺失和图片解码失败，支持重试、连接恢复后重新读取，以及切换会话时取消过期请求。
40
+ - 旧会话已有的 `block.meta.src` / `block.meta.rows` 继续显示。旧版嵌套调用如果从未保存展示数据，需重新调用预览工具。
41
+
42
+ ## 使用
43
+
44
+ 让 agent 调用工具，例如：
45
+
46
+ ```text
47
+ preview_image {"path":"D:/assets/logo.svg","label":"Logo 预览"}
48
+ preview_csv {"path":"D:/data/sales.csv","label":"销售数据","maxRows":100}
49
+ preview_csv {"content":"姓名,分数\n张三,90\n李四,85"}
50
+ ```
51
+
52
+ 内联 SVG 可直接传入 `content`。相对路径以当前会话工作目录为基准。`path` 与 `content` 同时存在时优先读取 `path`。
53
+
54
+ 图片支持 SVG、PNG、JPEG、GIF、WebP、BMP、ICO、AVIF。内联非 SVG 内容使用标准 base64，同时指定 `mime`。图片和 CSV 输入均限制为 8 MiB；内联 base64 限制按编码后的输入大小计算。
55
+
56
+ CSV 文件必须为 UTF-8，支持 UTF-8 BOM；其他编码会明确提示转换，而不是输出乱码。自动识别逗号、分号、Tab、竖线，或用 `delimiter` 指定；`.tsv` 默认 Tab。默认显示前 50 行，最多 500 行（均含表头）、40 列，每个单元格最多保存 200 字符加省略号。悬停显示已保存的单元格内容，截断部分无法还原。点击表头循环升序、降序、原始顺序，空值始终沉底。
57
+
58
+ ## 数据与历史预览
59
+
60
+ 预览快照保存在 `$DSH_HOME/storages/csv-and-image-preview/`；未设置 `DSH_HOME` 时使用 `~/.dsh/storages/csv-and-image-preview/`。每条记录按会话 ID、调用 ID 和工具名定位，路径采用哈希文件名。通过 DSH Connection 的已认证 `/api` RPC 通道读取，并核对记录身份。
61
+
62
+ 刷新页面、重启 DSH 或修改/删除原文件后，同一会话仍显示生成时的快照。备份会话时应同时备份此目录。当前不自动清理快照；删除目录会让新版历史预览失效。复制/分叉成新会话时不自动迁移原会话的快照。
63
+
64
+ 调用返回 `预览数据已生成…` 表示快照保存成功，不代表浏览器已解码显示。工具执行错误作为真正的失败交给 DSH，避免误报成功。
65
+
66
+ ## 预览优先约定
67
+
68
+ 生成或修改图片、SVG、CSV 时，先预览，用户认可后再修改目标文件；预览快照本身会写入插件数据目录。此约定由 agent 遵守，插件不阻止其他写文件工具。可将 [Agent.md](Agent.md) 的说明加入 agent 指令。
69
+
70
+ ## 开发
71
+
72
+ ```sh
73
+ npm ci
74
+ npm test # Cordis / DSH 工具调度、持久化、React 组件回归
75
+ npm run preview:test # 本地浏览器验收页，终端显示地址
76
+ npm run build # lib/ 为可直接发布的 JavaScript
77
+ npm pack --dry-run # 检查发布文件
78
+ ```
79
+
80
+ - `lib/index.js`：工具定义、输入读取与解析。
81
+ - `lib/store.js`：原子快照写入、读取边界、认证通道处理函数。
82
+ - `lib/client.js`：工具视图、RPC 读取、状态与重试、旧 meta 兼容。
83
+ - `cordis.patch.yml`：标准 Profile Bundle 插入行。
84
+
85
+ MIT © [jetecho](LICENSE).
package/cordis.patch.yml CHANGED
@@ -1,6 +1,6 @@
1
- # dsh-csv-and-image-preview bundle patch: one host row over the web profile.
2
- # The row name resolves from the profile's own node_modules where
3
- # `dsh plugin --profile web add <path>` installed this package.
4
- - insert:
5
- - id: csv-and-image-preview
6
- name: dsh-csv-and-image-preview
1
+ # dsh-csv-and-image-preview bundle patch: one host row over the web profile.
2
+ # The row name resolves from the profile's own node_modules where
3
+ # `dsh plugin --profile web add <path>` installed this package.
4
+ - insert:
5
+ - id: csv-and-image-preview
6
+ name: '@jetecho/dsh-csv-and-image-preview'