# Agent.md — dsh-csv-and-image-preview 行为契约

这份文档定义当你(agent)使用 `dsh-csv-and-image-preview` 时应遵守的**预览式工作流**。可将这些规则加入会话指令。

## 核心原则:先预览,后落地

凡涉及**生成或修改图片 / 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 全文/大段表格数据塞进回复文本或工具输出 —— 插件通过独立快照通道展示,你只需拿到紧凑摘要。
- 返回“预览数据已生成”只表示快照保存成功。如果用户报告没有显示,按失败信息排查或重新预览,不要坚持声称已经显示。
- 不要用 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 |
| 聊天正文预览 | 回答结束后在正文末尾直接显示已生成的预览，不需要用户点击侧栏；刷新历史时重放调用并读取快照 |
| 快照通道 | 按会话 ID 和调用 ID 保存快照,经 DSH 认证的 RPC 通道给浏览器读取;直接调用和 `run_code` 均支持;旧 meta 仍兼容 |

预览本身会在插件数据目录保存快照,不修改目标文件。新建目标文件仍需遵循用户的预览确认约定。

## 为什么

聊天渲染器不渲染 markdown 或 genui 里的图片(白名单里也没有 `image` 组件)。`React.createElement('img')` 生成的是浏览器原生 `<img>`,不经过那套过滤,所以能真实显示;CSV 同理,原生 `<table>` 键控 toolview 直接渲染,模型只拿行列摘要。预览式工作流让用户**先看到结果再决策**,避免"生成即覆写"的返工。