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

package/Agent.md

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

package/README.en.md

@@ -2,14 +2,14 @@
 
 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.
+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 dsh-csv-and-image-preview
+dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
 ```
 
 Or install the development copy from a local directory:
@@ -25,6 +25,7 @@ After installing, restart `dsh web` so the new bundle joins the runtime. Legacy
 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
 
@@ -39,13 +40,18 @@ I'll show you the preview first.
 [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.
+```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 SVG, image, or CSV, **preview it first** with `preview_image`; do not write the real file yet.
+- 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.
@@ -55,8 +61,8 @@ To enforce this convention, pair it with the bundled agent preset (see `Agent.md
 ## 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>
+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
 ```
 

package/README.md

@@ -2,14 +2,14 @@
 
 [English](README.en.md) | 中文
 
-在 DeepSeek Harness (dsh) 聊天里**真正把图片 / SVG 显示出来**的插件——并支持 CSV 数据先行预览。它把图片以浏览器原生 `<img>` 渲染，绕过聊天渲染器对 markdown / genui 图片的过滤；同时内置**预览式工作流**：生成或修改图片或 CSV 时，先把结果渲染给你看，等你确认后再落地真正的改动。
+在 DeepSeek Harness (dsh) 聊天里**真正把图片 / SVG / CSV 显示出来**的插件。图片与 SVG 以浏览器原生 `<img>` 渲染，CSV/TSV 表格以原生 `<table>` 渲染（粘性表头、控件限高局部滚动），均绕过聊天渲染器对 markdown / genui 的过滤；同时内置**预览式工作流**：生成或修改图片、SVG 或 CSV 时，先把结果渲染给你看，等你确认后再落地真正的改动。
 
 ## 安装
 
 标准 Profile Bundle 安装（推荐）：
 
 ```sh
-dsh plugin --profile web add dsh-csv-and-image-preview
+dsh plugin --profile web add @jetecho/dsh-csv-and-image-preview
 ```
 
 或从本地目录安装开发版：
@@ -25,6 +25,7 @@ dsh plugin --profile web add ../dsh-csv-and-image-preview
 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），超宽列数与超长单元格也会截断——模型只拿到行列摘要，表格数据不进模型上下文。表头**点击排序**（数值/中文拼音自适应，空值沉底，升→降→取消循环），单元格超长自动省略号、悬停看全文。
 
 ## 用法示例
 
@@ -39,13 +40,18 @@ dsh plugin --profile web add ../dsh-csv-and-image-preview
 [调用 preview_image content=<svg ...> mime=image/svg+xml label=草图]
 ```
 
-脚本会读到类似 `已渲染预览「ALPHA」:SVG 矢量图(1.3 KB)。` 的返回，图片则显示在工具卡片里。
+```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` 渲染，不做真实写入；
+- 生成 / 修改图片、SVG 或 CSV 时，**先** `preview_image` / `preview_csv` 渲染，不做真实写入；
 - 用户确认（`确认` / `可以` / `就这样`）后，才真正写文件 / 执行改动；
 - 用户否决时，按反馈重做并再次预览；
 - 需要预览任意资源时，直接传 `path`。
@@ -55,8 +61,8 @@ dsh plugin --profile web add ../dsh-csv-and-image-preview
 ## 组成部分
 
 ```
-lib/index.js   宿主：注册 preview_image 工具，读取文件并投递 data-URI
-lib/client.js  浏览器 bundle：注册键控 toolview，渲染原生 <img>
+lib/index.js   宿主：注册 preview_image / preview_csv 工具，读取文件并投递 data-URI / 表格 meta
+lib/client.js  浏览器 bundle：注册键控 toolview，渲染原生 <img> / <table>
 cordis.patch.yml  profile 插入行
 ```
 

package/lib/client.js

@@ -1,12 +1,14 @@
 /**
  * dsh-csv-and-image-preview 浏览器端 bundle(单文件,经 __ModuleLoader__ 加载)。
  *
- * 为 `preview_image` 工具注册键控 toolview(`tool.call.toolview`, key =
- * 'preview_image'):宿主把 data-URI 投递到结果节点的 meta,这里读取它并渲染
- * 成浏览器原生 <img>。这样图片不经过聊天渲染器的 markdown/genui 白名单,
- * 直接以真实 DOM 显示。
+ * 为两个工具注册键控 toolview(`tool.call.toolview`, key = 工具名):
+ *  - `preview_image`:从结果节点 meta 读取 { src, mime, label },渲染浏览器
+ *    原生 <img>;
+ *  - `preview_csv`:从结果节点 meta 读取 { label, delimiter, rows, ... },
+ *    渲染原生 <table>(粘性表头、控件限高 320px 局部滚动、表头点击排序)。
  *
- * 样式使用 --dsw-* 主题变量,跟随全局亮/暗主题。
+ * 这样图片/表格都不经过聊天渲染器的 markdown/genui 白名单,直接以真实 DOM
+ * 显示。样式使用 --dsw-* 主题变量,跟随全局亮/暗主题。
  * @module dsh-csv-and-image-preview/client
  */
 
@@ -28,6 +30,15 @@ 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)}',
+      '/* 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}',
+      '.dip-table th{position:sticky;top:0;z-index:1;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-secondary);font-weight:600;text-align:left;cursor:pointer;user-select:none;-webkit-user-select:none}',
+      '.dip-table th,.dip-table td{padding:4px 10px;border-bottom:1px solid var(--dsw-alias-border-l1);border-right:1px solid var(--dsw-alias-border-l1);overflow:hidden;text-overflow:ellipsis}',
+      '.dip-table th:last-child,.dip-table td:last-child{border-right:none}',
+      '.dip-table tbody tr:nth-child(even) td{background:rgba(127,127,127,0.08)}',
+      '.dip-table td.num{text-align:right;font-variant-numeric:tabular-nums}',
+      '.dip-csv-note{font-size:12px;color:var(--dsw-alias-label-tertiary);line-height:18px}',
     ].join('\n')
     if (typeof document !== 'undefined') {
       const key = 'dip-' + 'dsh-csv-and-image-preview'
@@ -40,13 +51,18 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /** 从 props.block 取 meta;工具调用 running 或回退时 meta 不存在。 */
+    function metaOf(props) {
+      const block = props && props.block
+      return block !== null && typeof block === 'object' && 'meta' in block ? block.meta : undefined
+    }
+
     /**
-     * 键控 toolview:从结果节点 `block.meta` 读取宿主投递的 { src, mime, label }。
-     * meta 仅在 settled 结果节点上存在;running 调用或回退时显示摘要行。
+     * 键控 toolview(preview_image):从 meta 读取 { src, mime, label } 渲染
+     * 原生 <img>。
      */
     function PreviewToolView(props) {
-      const block = props && props.block
-      const meta = block !== null && typeof block === 'object' && 'meta' in block ? block.meta : undefined
+      const meta = metaOf(props)
       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'
@@ -64,16 +80,107 @@ window.__ModuleLoader__.load({
           })))
     }
 
+    const NUMERIC_RE = /^-?\d+(\.\d+)?$/
+
+    /** 截断/统计脚注:「显示前 50 / 1234 行 · 前 5 / 8 列 · 分隔符 ","」。 */
+    function csvNote(meta) {
+      const parts = []
+      parts.push(meta.rowsShown < meta.totalRows
+        ? `显示前 ${meta.rowsShown} / ${meta.totalRows} 行`
+        : `共 ${meta.totalRows} 行`)
+      if (meta.colsShown < meta.totalCols) parts.push(`前 ${meta.colsShown} / ${meta.totalCols} 列`)
+      parts.push(`分隔符 "${meta.delimiter === '\t' ? 'Tab' : meta.delimiter}"`)
+      return parts.join(' · ')
+    }
+
+    /**
+     * 对数据行(不含表头)按列排序:整列(除空串)可解析为数字时按数值比较,
+     * 否则按中文 locale 比较;空值恒沉底。dir=1 升序,-1 降序。
+     */
+    function sortBodyRows(meta, col, dir) {
+      const body = meta.rows.slice(1)
+      const numeric = body.every((r) => {
+        const v = col < r.length ? r[col] : ''
+        return v === '' || NUMERIC_RE.test(v)
+      }) && body.some((r) => col < r.length && NUMERIC_RE.test(r[col]))
+      const cmp = numeric
+        ? (a, b) => (parseFloat(a) || 0) - (parseFloat(b) || 0)
+        : (a, b) => String(a).localeCompare(String(b), 'zh-Hans-CN')
+      return body
+        .map((_, i) => i)
+        .sort((x, y) => {
+          const a = x < body.length && col < body[x].length ? body[x][col] : ''
+          const b = y < body.length && col < body[y].length ? body[y][col] : ''
+          if ((a === '') !== (b === '')) return a === '' ? 1 : -1
+          return cmp(a, b) * dir
+        })
+        .map((i) => body[i])
+    }
+
+    /**
+     * 键控 toolview(preview_csv):从 meta 读取 { label, delimiter, rows,
+     * totalRows, totalCols, rowsShown, colsShown },渲染原生 <table>。
+     * rows[0] 为表头;数字单元格右对齐;表头点击循环排序(升→降→取消)。
+     */
+    function CsvToolView(props) {
+      const meta = metaOf(props)
+      const ok = meta !== null && typeof meta === 'object' && Array.isArray(meta.rows) && meta.rows.length > 0
+      // hooks 必须无条件调用,放在提前 return 之前。
+      const sortPair = React.useState(null) // null | { col, dir }
+      const sort = sortPair[0]
+      const setSort = sortPair[1]
+      if (!ok) {
+        return React.createElement('div', { className: 'dip-root', 'data-dip-preview': true },
+          React.createElement('span', { className: 'dip-missing' }, 'CSV 预览缺少数据(meta 缺失)'))
+      }
+      const label = typeof meta.label === 'string' && meta.label !== '' ? meta.label : 'CSV 预览'
+
+      const headerClick = (ci) => {
+        setSort((prev) => (prev !== null && prev.col === ci ? (prev.dir === 1 ? { col: ci, dir: -1 } : null) : { col: ci, dir: 1 }))
+      }
+
+      const thead = React.createElement('thead', null,
+        React.createElement('tr', null, meta.rows[0].map((c, i) => {
+          const indicator = sort !== null && sort.col === i ? (sort.dir === 1 ? ' ▲' : ' ▼') : ''
+          return React.createElement('th', {
+            key: i,
+            onClick: () => headerClick(i),
+            title: String(c),
+          }, String(c) + indicator)
+        })))
+      const bodyRows = sort !== null ? sortBodyRows(meta, sort.col, sort.dir) : meta.rows.slice(1)
+      const tbody = React.createElement('tbody', null, bodyRows.map((r, ri) =>
+        React.createElement('tr', { key: ri }, r.map((c, ci) => {
+          const s = String(c)
+          return React.createElement('td', {
+            key: ci,
+            className: NUMERIC_RE.test(s) ? 'num' : undefined,
+            title: s,
+          }, s)
+        }))))
+      return React.createElement('div', { className: 'dip-root', 'data-dip-preview': true },
+        React.createElement('span', { className: 'dip-label' }, label),
+        React.createElement('div', { className: 'dip-table-wrap' },
+          React.createElement('table', { className: 'dip-table' }, thead, tbody)),
+        React.createElement('span', { className: 'dip-csv-note' }, csvNote(meta)))
+    }
+
     // ── 服务接入 ─────────────────────────────────────────────────────────────
     const inject = []
     function apply(ctx) {
       const slots = ctx.get('slots')
       if (slots === undefined) return
-      const dispose = slots.inject('tool.call.toolview', () => slots.register(
-        { name: 'tool.call.toolview', key: 'preview_image' },
-        PreviewToolView,
-      ))
-      return () => { dispose() }
+      const disposals = [
+        slots.inject('tool.call.toolview', () => slots.register(
+          { name: 'tool.call.toolview', key: 'preview_image' },
+          PreviewToolView,
+        )),
+        slots.inject('tool.call.toolview', () => slots.register(
+          { name: 'tool.call.toolview', key: 'preview_csv' },
+          CsvToolView,
+        )),
+      ]
+      return () => { for (const dispose of disposals) dispose() }
     }
 
     exports.apply = apply

package/lib/index.js

@@ -4,10 +4,12 @@
  * 单条 Loader 行(见 cordis.patch.yml)挂载本模块。职责:
  *  1. 注册 `preview_image` 工具:给定一个文件路径(或内联 SVG),读取文件、
  *     推断 MIME、base64 编码为 data-URI;
- *  2. 把该 data-URI 通过工具结果的 `presentationMeta` 投递出去,浏览器端
- *     键控 toolview 据此渲染原生 <img> —— 绕过聊天渲染器对图片的过滤;
- *  3. `execute` 返回紧凑的模型可读摘要(尺寸/字节/说明),真正的图片字节
- *     只走 meta,不进模型上下文。
+ *  2. 注册 `preview_csv` 工具:读取 CSV/TSV(磁盘路径或内联文本),嗅探分隔符、
+ *     有界解析(输入体积/行数/列数/单元格四重截断),产出可序列化的表格 meta;
+ *  3. 两者都把展示数据通过工具结果的 `presentationMeta` 投递出去,浏览器端
+ *     键控 toolview 据此渲染原生 <img> / <table> —— 绕过聊天渲染器的过滤;
+ *  4. `execute` 返回紧凑的模型可读摘要,真正的图片字节/表格数据只走 meta,
+ *     不进模型上下文。
  *
  * 注意:`output.presentationMeta` 必须**同步**返回 lossless JSON(它是展示
  * 期别名,在结果落地时就读取,不能返回 Promise),因此这里用同步 fs 读取;
@@ -36,6 +38,15 @@ const MIME_BY_EXT = {
   '.avif': 'image/avif',
 }
 
+/** 从 args.label 取标题;空/缺省回退 fallback。 */
+function labelOf(args, fallback) {
+  return typeof args === 'object' && args !== null && typeof args.label === 'string' && args.label !== ''
+    ? args.label
+    : fallback
+}
+
+// ── 图片预览 ────────────────────────────────────────────────────────────────
+
 /** 从路径扩得 MIME;未知回退 octet-stream。 */
 function mimeOf(path) {
   const dot = path.lastIndexOf('.')
@@ -54,8 +65,7 @@ function svgDimension(svg) {
 }
 
 /** 模型可读的单行摘要。 */
-function svgSummary(mime, bytes) {
-  const size = bytes < 1024 ? `${bytes} B` : bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / (1024 * 1024)).toFixed(2)} MB`
+function imageSummary(mime) {
   return mime === 'image/svg+xml' ? 'SVG 矢量图' : mime.replace('image/', '').toUpperCase() + ' 位图'
 }
 
@@ -67,7 +77,7 @@ function buildPreviewSync(args) {
   if (typeof args !== 'object' || args === null) {
     throw new Error('preview_image 需要对象参数(带 path 或 content)。')
   }
-  const label = typeof args.label === 'string' && args.label !== '' ? args.label : '预览'
+  const label = labelOf(args, '预览')
 
   // 优先:磁盘文件路径。
   if (typeof args.path === 'string' && args.path !== '') {
@@ -81,7 +91,7 @@ function buildPreviewSync(args) {
       mime,
       label,
       bytes: st.size,
-      summary: svgSummary(mime, st.size),
+      summary: imageSummary(mime),
     }
   }
 
@@ -158,12 +168,244 @@ export function createPreviewTool() {
       }
     },
     presentCall(args) {
-      const label = typeof args === 'object' && args !== null && typeof args.label === 'string' && args.label !== '' ? args.label : '预览图片'
-      return { card: 'generic', title: `预览「${label}」`, kind: 'other' }
+      return { card: 'generic', title: `预览「${labelOf(args, '预览图片')}」`, kind: 'other' }
+    },
+    presentResult(args) {
+      return { card: 'generic', title: `预览「${labelOf(args, '预览图片')}」` }
+    },
+  }
+}
+
+// ── CSV 预览 ────────────────────────────────────────────────────────────────
+
+/** 候选分隔符(嗅探顺序即平局优先级)。 */
+const CSV_DELIMITERS = [',', ';', '\t', '|']
+/** 单次预览允许读入的最大体积,超过直接拒绝,保护宿主进程。 */
+const CSV_MAX_INPUT_BYTES = 8 * 1024 * 1024
+const CSV_MAX_ROWS_DEFAULT = 50
+const CSV_MAX_ROWS_LIMIT = 500
+const CSV_MAX_COLS = 40
+const CSV_CELL_CAP = 200
+
+function fmtBytes(n) {
+  return n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} KB` : `${(n / (1024 * 1024)).toFixed(2)} MB`
+}
+
+/**
+ * 分隔符嗅探:统计前 4 KB 内引号外各候选出现次数,取最多者;全 0 回退逗号。
+ * 遍历顺序即平局优先级(, ; Tab |)。
+ */
+function detectDelimiter(text) {
+  const counts = new Map(CSV_DELIMITERS.map((d) => [d, 0]))
+  let inQuotes = false
+  const end = Math.min(text.length, 4096)
+  for (let i = 0; i < end; i++) {
+    const ch = text[i]
+    if (ch === '"') inQuotes = !inQuotes
+    else if (!inQuotes && counts.has(ch)) counts.set(ch, counts.get(ch) + 1)
+  }
+  let best = CSV_DELIMITERS[0]
+  let bestN = -1
+  for (const d of CSV_DELIMITERS) {
+    const n = counts.get(d)
+    if (n > bestN) { best = d; bestN = n }
+  }
+  return bestN > 0 ? best : ','
+}
+
+/**
+ * RFC 4180 风格的有界 CSV 解析:引号字段、"" 转义、引号内换行、CRLF。
+ * 只保留前 maxRows 行(有界内存),但完整统计总行数与最大列数,摘要可用。
+ * 跳过空行;返回 { rows, totalRows, totalCols }。
+ */
+function parseCsvBounded(text, delimiter, maxRows) {
+  const rows = []
+  let row = []
+  let field = ''
+  let inQuotes = false
+  let totalRows = 0
+  let totalCols = 0
+  const endRow = () => {
+    row.push(field)
+    field = ''
+    if (row.length === 1 && row[0] === '') { row = []; return } // 空行不计
+    if (row.length > totalCols) totalCols = row.length
+    totalRows++
+    if (rows.length < maxRows) rows.push(row)
+    row = []
+  }
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') { field += '"'; i++ }
+        else inQuotes = false
+      } else {
+        field += ch
+      }
+    } else if (ch === '"') {
+      inQuotes = true
+    } else if (ch === delimiter) {
+      row.push(field)
+      field = ''
+    } else if (ch === '\n') {
+      endRow()
+    } else if (ch !== '\r') {
+      field += ch
+    }
+  }
+  if (field !== '' || row.length > 0) endRow()
+  return { rows, totalRows, totalCols }
+}
+
+function clampMaxRows(v) {
+  const n = Math.floor(Number(v))
+  if (!Number.isFinite(n) || n < 1) return CSV_MAX_ROWS_DEFAULT
+  return Math.min(n, CSV_MAX_ROWS_LIMIT)
+}
+
+/** 显式分隔符 → 生效值;null 表示走嗅探(.tsv 扩展名直接判 Tab)。 */
+function resolveDelimiter(args) {
+  const d = args.delimiter
+  if (typeof d === 'string' && CSV_DELIMITERS.includes(d)) return d
+  if (typeof args.path === 'string' && args.path !== '' && args.path.toLowerCase().endsWith('.tsv')) return '\t'
+  return null
+}
+
+function capCell(c) {
+  return c.length > CSV_CELL_CAP ? c.slice(0, CSV_CELL_CAP) + '…' : c
+}
+
+/**
+ * 同步构建 CSV 预览 meta,返回 { label, delimiter, rows, totalRows, totalCols,
+ * rowsShown, colsShown };有错抛 Error。rows 含表头行,已被列数/单元格截断并
+ * 补齐成规则矩形,浏览器可直接渲染。
+ */
+function buildCsvPreviewSync(args) {
+  if (typeof args !== 'object' || args === null) {
+    throw new Error('preview_csv 需要对象参数(带 path 或 content)。')
+  }
+  const label = labelOf(args, 'CSV 预览')
+
+  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')
+  } 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)},请先截取再预览。`)
+    }
+    text = args.content
+  } else {
+    throw new Error('preview_csv 需要 path 或 content 参数。')
+  }
+
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1) // 剥 BOM
+
+  const auto = resolveDelimiter(args)
+  const delimiter = auto ?? detectDelimiter(text)
+  const parsed = parseCsvBounded(text, delimiter, clampMaxRows(args.maxRows))
+  if (parsed.totalRows === 0) throw new Error('CSV 内容为空,没有可预览的数据行。')
+
+  const colsShown = Math.min(parsed.totalCols, CSV_MAX_COLS)
+  const rows = parsed.rows.map((r) => {
+    const view = r.slice(0, CSV_MAX_COLS).map(capCell)
+    while (view.length < colsShown) view.push('')
+    return view
+  })
+  return {
+    label,
+    delimiter,
+    rows,
+    totalRows: parsed.totalRows,
+    totalCols: parsed.totalCols,
+    rowsShown: rows.length,
+    colsShown,
+  }
+}
+
+/** 模型可读的行列摘要(含截断信息)。 */
+function csvSummaryText(r) {
+  const d = r.delimiter === '\t' ? 'Tab' : r.delimiter
+  let s = `CSV 表格 ${r.totalRows} 行 × ${r.totalCols} 列,分隔符 "${d}"`
+  if (r.rowsShown < r.totalRows) s += `;显示前 ${r.rowsShown} 行`
+  if (r.colsShown < r.totalCols) s += ` / 前 ${r.colsShown} 列`
+  return s + '。'
+}
+
+/**
+ * 构建 preview_csv 工具定义。模型传 CSV 路径/文本发起一次「表格预览」:
+ * 宿主有界解析后把表格投递到 meta,浏览器端 toolview 渲染原生 <table>。
+ */
+export function createCsvTool() {
+  return {
+    name: 'preview_csv',
+    description:
+      '在聊天里预览 CSV/TSV 表格——用浏览器原生 <table> 渲染,粘性表头、控件限高局部滚动。'
+      + ' 传 path 读取磁盘文件(.csv/.tsv 等),或传 content(内联 CSV 文本)。'
+      + ' 分隔符自动嗅探(, ; Tab |),可用 delimiter 指定;默认只投递前 '
+      + `${CSV_MAX_ROWS_DEFAULT} 行(可用 maxRows 调大,上限 ${CSV_MAX_ROWS_LIMIT})。`
+      + ' 表格数据只走 meta 投递到浏览器,不进入模型上下文;返回的是行列摘要。'
+      + ' 生成/修改 CSV 时先调用它给用户预览,等用户确认后再做真正的写入/修改。',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: '要预览的 CSV/TSV 文件路径。优先用绝对路径。',
+        },
+        content: {
+          type: 'string',
+          description: '备选:内联 CSV 文本。与 path 二选一。',
+        },
+        delimiter: {
+          type: 'string',
+          enum: [...CSV_DELIMITERS],
+          description: '字段分隔符;缺省时自动嗅探,.tsv 文件默认 Tab。',
+        },
+        maxRows: {
+          type: 'number',
+          description: `预览的最大行数(含表头行),默认 ${CSV_MAX_ROWS_DEFAULT},上限 ${CSV_MAX_ROWS_LIMIT}。`,
+        },
+        label: {
+          type: 'string',
+          description: '表格标题,显示在预览上方。',
+        },
+      },
+      additionalProperties: false,
+    },
+    output: {
+      schema: { type: 'string', description: '单行预览摘要,给模型看。' },
+      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}`
+      }
+    },
+    presentCall(args) {
+      return { card: 'generic', title: `CSV 预览「${labelOf(args, 'CSV 表格')}」`, kind: 'other' }
     },
     presentResult(args) {
-      const label = typeof args === 'object' && args !== null && typeof args.label === 'string' && args.label !== '' ? args.label : '预览图片'
-      return { card: 'generic', title: `预览「${label}」` }
+      return { card: 'generic', title: `CSV 预览「${labelOf(args, 'CSV 表格')}」` }
     },
   }
 }
@@ -180,6 +422,7 @@ export function apply(ctx) {
     const tools = value ?? ctx.reflect.get('tools', false)
     if (tools === undefined) return
     tools.register(createPreviewTool())
+    tools.register(createCsvTool())
     registered = true
   }
   tryRegister(undefined)

package/lib/types/index.d.ts

@@ -15,6 +15,17 @@ export interface PreviewToolDefinition {
   presentResult(args: unknown): { card: string; title: string } | undefined
 }
 
+/** The `preview_csv` tool definition (a dsh ToolDefinition object). */
+export interface CsvToolDefinition {
+  name: 'preview_csv'
+  description: string
+  parameters: Record<string, unknown>
+  output: Record<string, unknown>
+  execute(args: unknown): Promise<string>
+  presentCall(args: unknown): { card: string; title: string; kind: string } | undefined
+  presentResult(args: unknown): { card: string; title: string } | undefined
+}
+
 /** Cordis plugin exported by the host half (lib/index.js). */
 export interface ImagePreviewPlugin {
   readonly name: 'csv-and-image-preview'
@@ -28,5 +39,16 @@ export interface PreviewMeta {
   label: string
 }
 
+/** A keyed bounded table payload carried on tool result meta (rows[0] = header). */
+export interface CsvPreviewMeta {
+  label: string
+  delimiter: string
+  rows: string[][]
+  totalRows: number
+  totalCols: number
+  rowsShown: number
+  colsShown: number
+}
+
 declare const plugin: ImagePreviewPlugin
 export default plugin

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jetecho/dsh-csv-and-image-preview",
-  "version": "0.1.0",
-  "description": "Preview images / SVG (and prepare CSV) in the DeepSeek Harness chat, rendered as real browser <img> elements. Preview-first workflow: show the user the asset, wait for approval, then apply the real change.",
+  "version": "0.1.1",
+  "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",
   "types": "lib/types/index.d.ts",
@@ -42,6 +42,8 @@
     "dsh-plugin",
     "image",
     "svg",
+    "csv",
+    "table",
     "preview",
     "visual"
   ],