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

package/Agent.md

@@ -1,39 +1,41 @@
-# Agent.md — dsh-csv-and-image-preview 行为契约
-
-这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。它是给 agent 读的规则,搭配仓库里的独立 agent preset(`image-preview`)一起使用,把规则写进会话 persona。
-
-## 核心原则:先预览,后落地
-
-凡涉及**生成或修改图片 / SVG**,默认顺序必须是:
-
-1. **先预览** —— 调用 `preview_image`,把结果渲染到聊天里给用户看;
-   - 读磁盘文件:`path=<绝对路径>`
-   - 内联 SVG(未落盘):`content=<svg ...> mime=image/svg+xml`
-   - 任意资源:直接传 `path`
-2. **等确认** —— 预览后停止写入,等待用户明确同意;
-3. **用户认可**(如 `确认` / `可以` / `就这样`)后,才真正写文件 / 执行改动;
-4. **用户否决** 时,按反馈修改并**再次预览**,直到认可为止。
-
-## 不要做的事
-
-- 不要在没预览的情况下,直接覆盖或新增一个图片 / SVG 文件。
-- 不要把图片字节塞进回复文本或模型上下文 —— 那是 meta 的活,你只需拿到紧凑摘要。
-- 不要用 markdown `![alt](data:...)` 或 ```` ```dsh-ui ```` 的 `image` 组件来"显示图片"—— 聊天渲染器会拦截,必须走 `preview_image` 工具。
-
-## 交互话术
-
-- 预览后:**"这是预览,请确认后再写入。"** 或列出的差异点。
-- 等待确认时,保持在工作流里,不要擅自落地。
-- 确认后:**"已按预览图写入 `path`。"**
-
-## 插件能力
-
-| 能力 | 说明 |
-|---|---|
-| `preview_image` 工具 | 读取文件 / 内联 SVG → data-URI → 浏览器 `<img>` 渲染 |
-| 键控 toolview | `tool.call.toolview` key=`preview_image`,渲染原生 `<img>` |
-| meta 通道 | 图片字节只走 `presentationMeta` 进浏览器,不进模型上下文 |
-
-## 为什么
-
-聊天渲染器不渲染 markdown 或 genui 里的图片(白名单里也没有 `image` 组件)。`React.createElement('img')` 生成的是浏览器原生 `<img>`,不经过那套过滤,所以能真实显示。预览式工作流让用户**先看到结果再决策**,避免"生成即覆写"的返工。
+# Agent.md — dsh-csv-and-image-preview 行为契约
+
+这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。它是给 agent 读的规则,搭配仓库里的独立 agent preset(`image-preview`)一起使用,把规则写进会话 persona。
+
+## 核心原则:先预览,后落地
+
+凡涉及**生成或修改图片 / SVG / CSV**,默认顺序必须是:
+
+1. **先预览** —— 调用 `preview_image`(图片 / SVG)或 `preview_csv`(CSV / TSV 表格),把结果渲染到聊天里给用户看;
+   - 读磁盘文件:`path=<绝对路径>`
+   - 内联 SVG(未落盘):`content=<svg ...> mime=image/svg+xml`
+   - 内联 CSV(未落盘):`content=<csv 文本>`;可用 `maxRows` 控制预览行数(默认 50,上限 500),`delimiter` 指定分隔符
+   - 任意图片资源:直接传 `path`
+2. **等确认** —— 预览后停止写入,等待用户明确同意;
+3. **用户认可**(如 `确认` / `可以` / `就这样`)后,才真正写文件 / 执行改动;
+4. **用户否决** 时,按反馈修改并**再次预览**,直到认可为止。
+
+## 不要做的事
+
+- 不要在没预览的情况下,直接覆盖或新增一个图片 / SVG / CSV 文件。
+- 不要把图片字节或 CSV 全文/大段表格数据塞进回复文本或模型上下文 —— 那是 meta 的活,你只需拿到紧凑摘要。
+- 不要用 markdown `![alt](data:...)` 或 ```` ```dsh-ui ```` 的 `image` 组件来"显示图片"—— 聊天渲染器会拦截,必须走 `preview_image`;同理 CSV 必须走 `preview_csv`,不要用整段代码块充当"预览"。
+
+## 交互话术
+
+- 预览后:**"这是预览,请确认后再写入。"** 或列出的差异点。
+- 等待确认时,保持在工作流里,不要擅自落地。
+- 确认后:**"已按预览图写入 `path`。"**
+
+## 插件能力
+
+| 能力 | 说明 |
+|---|---|
+| `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` 进浏览器,不进模型上下文 |
+
+## 为什么
+
+聊天渲染器不渲染 markdown 或 genui 里的图片(白名单里也没有 `image` 组件)。`React.createElement('img')` 生成的是浏览器原生 `<img>`,不经过那套过滤,所以能真实显示;CSV 同理,原生 `<table>` 键控 toolview 直接渲染,模型只拿行列摘要。预览式工作流让用户**先看到结果再决策**,避免"生成即覆写"的返工。

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 jetecho
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 jetecho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -1,73 +1,79 @@
-# dsh-csv-and-image-preview
-
-English | [中文](README.md)
-
-Render images and SVG **for real** in the DeepSeek Harness (dsh) chat — and prepare CSV review — displayed as a native browser `<img>`, bypassing the chat renderer's markdown / genui image filter, and paired with a **preview-first workflow**: generate or modify an image, render it to you first, and only apply the real change once you confirm.
-
-## Install
-
-Standard Profile Bundle install (recommended):
-
-```sh
-dsh plugin --profile web add dsh-csv-and-image-preview
-```
-
-Or install the development copy from a local directory:
-
-```sh
-dsh plugin --profile web add ../dsh-csv-and-image-preview
-```
-
-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.
-
-## What it does
-
-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.
-
-## Usage examples
-
-```markdown
-<!-- Preview a file on disk -->
-I'll show you the preview first.
-[call preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
-```
-
-```markdown
-<!-- Preview inline SVG (not yet on disk) -->
-[call preview_image content=<svg ...> mime=image/svg+xml label=sketch]
-```
-
-The agent sees something like `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB).` while the picture appears in the tool card.
-
-## Convention: preview first
-
-This plugin treats "preview, then apply" as the default behavior:
-
-- When generating / modifying an SVG, image, or CSV, **preview it first** with `preview_image`; 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.
-
-To enforce this convention, pair it with the bundled agent preset (see `Agent.md`), which writes these rules into the session persona.
-
-## Layout
-
-```
-lib/index.js   host: registers the preview_image tool; reads files and projects data-URIs
-lib/client.js  browser bundle: registers the keyed toolview; renders a native <img>
-cordis.patch.yml  profile insert line
-```
-
-## Development
-
-```sh
-pnpm install
-pnpm build       # no-op: lib/ ships prebuilt, no transpile
-pnpm prepack     # verify the packed tarball contains lib/
-```
-
-## License
-
-MIT © [jetecho](./LICENSE). See [LICENSE](./LICENSE).
+# dsh-csv-and-image-preview
+
+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.
+
+## Install
+
+Standard Profile Bundle install (recommended):
+
+```sh
+dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
+```
+
+Or install the development copy from a local directory:
+
+```sh
+dsh plugin --profile web add ../dsh-csv-and-image-preview
+```
+
+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.
+
+## What it does
+
+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.
+
+## Usage examples
+
+```markdown
+<!-- Preview a file on disk -->
+I'll show you the preview first.
+[call preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
+```
+
+```markdown
+<!-- Preview inline SVG (not yet on disk) -->
+[call preview_image content=<svg ...> mime=image/svg+xml label=sketch]
+```
+
+```markdown
+<!-- Preview a CSV file (truncated to the first 100 rows) -->
+[call preview_csv path=E:\DSHConfig\data.csv label=sales maxRows=100]
+```
+
+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.
+
+## Convention: preview first
+
+This plugin treats "preview, then apply" as the default behavior:
+
+- 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.
+
+To enforce this convention, pair it with the bundled agent preset (see `Agent.md`), which writes these rules into the session persona.
+
+## Layout
+
+```
+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
+```
+
+## Development
+
+```sh
+pnpm install
+pnpm build       # no-op: lib/ ships prebuilt, no transpile
+pnpm prepack     # verify the packed tarball contains lib/
+```
+
+## License
+
+MIT © [jetecho](./LICENSE). See [LICENSE](./LICENSE).

package/README.md

@@ -1,73 +1,79 @@
-# dsh-csv-and-image-preview
-
-[English](README.en.md) | 中文
-
-在 DeepSeek Harness (dsh) 聊天里**真正把图片 / SVG 显示出来**的插件——并支持 CSV 数据先行预览。它把图片以浏览器原生 `<img>` 渲染，绕过聊天渲染器对 markdown / genui 图片的过滤；同时内置**预览式工作流**：生成或修改图片或 CSV 时，先把结果渲染给你看，等你确认后再落地真正的改动。
-
-## 安装
-
-标准 Profile Bundle 安装（推荐）：
-
-```sh
-dsh plugin --profile web add dsh-csv-and-image-preview
-```
-
-或从本地目录安装开发版：
-
-```sh
-dsh plugin --profile web add ../dsh-csv-and-image-preview
-```
-
-安装后需重启 `dsh web` 让新 bundle 进入运行时。更早版本兼容做法是手动把包复制进 profile 的 `node_modules` 并在 `cordis.patch.yml` 插入 `- insert: [...]`，仅作旧版本兜底。
-
-## 它做什么
-
-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 文本直接渲染，无需落盘。
-
-## 用法示例
-
-```markdown
-<!-- 预览磁盘上的 logo -->
-我先给你看预览。
-[调用 preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
-```
-
-```markdown
-<!-- 预览内联 SVG（未落盘） -->
-[调用 preview_image content=<svg ...> mime=image/svg+xml label=草图]
-```
-
-脚本会读到类似 `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB)。` 的返回，图片则显示在工具卡片里。
-
-## 约定：预览优先
-
-本插件把「先预览、后落地」作为默认约定：
-
-- 生成 / 修改 SVG、图片或 CSV 时，**先** `preview_image` 渲染，不做真实写入；
-- 用户确认（`确认` / `可以` / `就这样`）后，才真正写文件 / 执行改动；
-- 用户否决时，按反馈重做并再次预览；
-- 需要预览任意资源时，直接传 `path`。
-
-要强制遵守这一约定，可以配合附带的 agent preset（见 `Agent.md`），它会把这套规则写进会话 persona。
-
-## 组成部分
-
-```
-lib/index.js   宿主：注册 preview_image 工具，读取文件并投递 data-URI
-lib/client.js  浏览器 bundle：注册键控 toolview，渲染原生 <img>
-cordis.patch.yml  profile 插入行
-```
-
-## 开发
-
-```sh
-pnpm install
-pnpm build       # no-op：lib/ 为成品，无需转译
-pnpm prepack     # 校验打包内容含 lib/
-```
-
-## License
-
-MIT © [jetecho](./LICENSE)，详见 [LICENSE](./LICENSE)。
+# dsh-csv-and-image-preview
+
+[English](README.en.md) | 中文
+
+在 DeepSeek Harness (dsh) 聊天里**真正把图片 / SVG / CSV 显示出来**的插件。图片与 SVG 以浏览器原生 `<img>` 渲染，CSV/TSV 表格以原生 `<table>` 渲染（粘性表头、控件限高局部滚动），均绕过聊天渲染器对 markdown / genui 的过滤；同时内置**预览式工作流**：生成或修改图片、SVG 或 CSV 时，先把结果渲染给你看，等你确认后再落地真正的改动。
+
+## 安装
+
+标准 Profile Bundle 安装（推荐）：
+
+```sh
+dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
+```
+
+或从本地目录安装开发版：
+
+```sh
+dsh plugin --profile web add ../dsh-csv-and-image-preview
+```
+
+安装后需重启 `dsh web` 让新 bundle 进入运行时。更早版本兼容做法是手动把包复制进 profile 的 `node_modules` 并在 `cordis.patch.yml` 插入 `- insert: [...]`，仅作旧版本兜底。
+
+## 它做什么
+
+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），超宽列数与超长单元格也会截断——模型只拿到行列摘要，表格数据不进模型上下文。表头**点击排序**（数值/中文拼音自适应，空值沉底，升→降→取消循环），单元格超长自动省略号、悬停看全文。
+
+## 用法示例
+
+```markdown
+<!-- 预览磁盘上的 logo -->
+我先给你看预览。
+[调用 preview_image path=E:\DSHConfig\logo-a.svg label=ALPHA]
+```
+
+```markdown
+<!-- 预览内联 SVG（未落盘） -->
+[调用 preview_image content=<svg ...> mime=image/svg+xml label=草图]
+```
+
+```markdown
+<!-- 预览 CSV 文件（截断到前 100 行） -->
+[调用 preview_csv path=E:\DSHConfig\data.csv label=销售数据 maxRows=100]
+```
+
+脚本会读到类似 `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB)。` 的返回，图片则显示在工具卡片里；CSV 则是 `已渲染 CSV 预览「销售数据」:CSV 表格 1234 行 × 5 列,分隔符 ",";显示前 100 行。`，表格显示在工具卡片里。
+
+## 约定：预览优先
+
+本插件把「先预览、后落地」作为默认约定：
+
+- 生成 / 修改图片、SVG 或 CSV 时，**先** `preview_image` / `preview_csv` 渲染，不做真实写入；
+- 用户确认（`确认` / `可以` / `就这样`）后，才真正写文件 / 执行改动；
+- 用户否决时，按反馈重做并再次预览；
+- 需要预览任意资源时，直接传 `path`。
+
+要强制遵守这一约定，可以配合附带的 agent preset（见 `Agent.md`），它会把这套规则写进会话 persona。
+
+## 组成部分
+
+```
+lib/index.js   宿主：注册 preview_image / preview_csv 工具，读取文件并投递 data-URI / 表格 meta
+lib/client.js  浏览器 bundle：注册键控 toolview，渲染原生 <img> / <table>
+cordis.patch.yml  profile 插入行
+```
+
+## 开发
+
+```sh
+pnpm install
+pnpm build       # no-op：lib/ 为成品，无需转译
+pnpm prepack     # 校验打包内容含 lib/
+```
+
+## License
+
+MIT © [jetecho](./LICENSE)，详见 [LICENSE](./LICENSE)。

package/cordis.patch.yml

@@ -1,6 +1,6 @@
-# dsh-csv-and-image-preview bundle patch: one host row over the web profile.
-# The row name resolves from the profile's own node_modules where
-# `dsh plugin --profile web add <path>` installed this package.
-- insert:
-    - id: csv-and-image-preview
-      name: dsh-csv-and-image-preview
+# dsh-csv-and-image-preview bundle patch: one host row over the web profile.
+# The row name resolves from the profile's own node_modules where
+# `dsh plugin --profile web add <path>` installed this package.
+- insert:
+    - id: csv-and-image-preview
+      name: '@jetecho/dsh-csv-and-image-preview'