dsh-image-viewer-pro

dsh plugin --profile web add dsh-image-viewer-pro

dsh-image-viewer-pro

       

聊天里的图片，按查看器来用，而不是一张图加一个关闭按钮。 缩放、平移、旋转、图集、下载、复制、拖动窗口，以及用这台电脑上已有的应用打开，都在同一个弹层里。滚轮、拖动和旋转每帧只更新合成层；下一张先解码再换上，避免切图时先闪到错误比例。它替换官方只有「关闭」的预览。

[English](README.md) | 中文

看一看

下面是真实查看器的截图和操作录像，样片是为这一页生成的。GitHub 上 GIF 会直接播放，MP4 链接是同一段录像。

<p>

<img src="docs/zoom.png" width="32%" alt="放大后的翅膀">

<img src="docs/rotate.png" width="32%" alt="旋转 90° 的静物">

<img src="docs/gallery.png" width="32%" alt="图集第 3 张">

</p>

缩放和平移。 滚轮以指针为中心放大，拖动画布移动画面。

[zoom.mp4](docs/zoom.mp4)

旋转。 每点一次转 90°，底栏显示当前角度。

[rotate.mp4](docs/rotate.mp4)

图集。 两侧圆按钮或 ← / → 在同一会话的图片之间切换，新图从那一侧滑入。

[gallery.mp4](docs/gallery.mp4)

拖动窗口。 按住标题栏拖动，弹窗停在遮罩里面。

[move.mp4](docs/move.mp4)

复制和下载。 复制会写入 PNG 并弹出提示；下载保存原图。

[actions.mp4](docs/actions.mp4)

为什么装它

DSH 0.2.1-rc.2 的图片预览只提供「关闭」：看不清小字、不能放大、不能平移、不能下载、不能旋转，也无法在同一个会话的多张图之间切换。本插件在捕获阶段接管内容图片的点击，用自绘弹层替换它 —— 不依赖官方 slot 契约，因此对官方图片位的调整不敏感。

查看器只改善「看得清」，并不能让图片出现。怎么让智能体主动内联图片，见[让智能体真的发图：提示词建议](#让智能体真的发图提示词建议)。

功能

• 缩放：滚轮以指针为中心缩放。鼠标滚轮一格约 12%，并在几帧内滑到目标；触控板小步进当帧生效。底部 − [百分比] +，百分比可直接输入（回车生效，Esc 取消）。点按 ± 与滚轮一格相同；按住 ± 连续缩放（大约 0.7 秒放大一倍）。键盘 + / - 仍是 25%。倍率限制在 5%–4000%。
• 平移：拖动画布平移；双击在「适应窗口 / 原始大小」之间切换。
• 底栏：控件分成三组，组间用竖线隔开：缩放、适应窗口 / 1:1、旋转。
• 拖动窗口：按住弹窗标题栏拖动，位置限制在遮罩范围内（桌面端不进入原生标题栏/菜单栏区域）；窗口缩放时已拖动的弹窗自动收回边界内。
• 顶栏信息：标题行显示「宽 × 高 | 格式 | 文件大小」，只显示值；格式大写（JPG/PNG/SVG/BMP/WEBP…），大小按 B/KB/MB 自动换算（KB、MB 保留 1 位小数）。
• 旋转：左侧逆时针、右侧顺时针，每次 90°，中间显示当前角度。
• 下载原图：带进度提示，完成后保存到系统下载目录。
• 复制图片：写入剪贴板（非 PNG 自动转 PNG）。
• 图集浏览：同一会话里的多张图用左右圆形按钮或 ← / → 切换，显示 当前 / 总数。新图从所点的一侧推入，旧图向另一侧离开，大约 420ms，和弹窗打开同一条曲线。连点时先把正在播放的切换落到终点，再播下一次。系统开启「减少动态效果」时仍立即换图。
• 打开：本地图片是分体按钮。主按钮显示默认应用的图标，并用该应用打开；下拉列出 session.workspacePathApplications 返回的关联应用（默认项标注「默认」），底部是「显示文件位置」。远程 http(s) 仍是「新标签打开」。blob: 与 data: 不显示这个按钮。打开和显示位置都走 Host 的 session.openWorkspacePath。
• 原生观感：遮罩覆盖窗口内容区（含应用自己的顶部工具条），但桌面端会避开原生标题栏/菜单栏（Windows 下按 --dsh-frame-chrome-top 起始），原生菜单栏不会被压暗；弹窗只在遮罩内拖动；遮罩与弹层使用 DSH 主题令牌，跟随亮/暗主题；支持 prefers-reduced-motion。

覆盖范围

图片 · 是否接管

聊天正文的 Markdown 图（![](...)，http(s) / 本站文件路由） · ✅

用户与助手消息里的附件图（DSH 以 blob: URL 渲染） · ✅

read_image 等工具结果里的图片缩略图/大图（同样经附件通道） · ✅

小于 48px 的图标、头像、状态图 · ❌ 保持原生

插件弹层自身的图片（防递归） · ❌

接管只作用于点击行为：不修改消息内容、不写会话数据，关闭弹层后页面恢复原样。

让智能体真的发图：提示词建议

查看器只负责「看得清」；图片能不能出现，取决于智能体写了什么：DSH 会渲染回复正文里的 Markdown 图和工具结果里的图片附件，本插件只是在之后接管点击。大多数智能体把界面验证写成一句结论（「布局正常」），从不内联截图，所以这个功能很容易被忽略。

把下面的规则加进全局 AGENTS.md、项目的 AGENTS.md 或自定义指令里。措辞要下命令式：「一律内联」比「你可以附上截图」有效得多。

图片一律内联

## 图片

- 你产生、找到或提到的图片（包括截图）一律内联：`![说明](<D:/绝对/路径.png>)`。
- 不等用户开口就给图。不要只回一个路径，也不要只放 `present` 文件卡片——图片是回复的一部分。
- 用绝对路径、正斜杠，并用尖括号包住目标地址。相对路径只有当前查看的会话有 workspace root 时才解析得动，否则显示为裂图。
- 网络图片先下载到工作区，再内联本地文件。
- 只有图片这样内联；代码、文档、表格按各自工具的交付规则处理。

界面验证以截图收尾

## 界面验证与截图

- 界面/交互问题要实机验证：打开 → 快照/截图 → 操作 → 查 Console/Network；禁止用读代码或口头推断代替验证。
- 验证结束把关键截图内联到回复里，并说明每张图对应哪一步；不要只贴路径。
- 截图落盘到工作区，用 `![说明](<D:/绝对/路径.png>)` 内联。
- 本机 origin（`127.0.0.1`、`localhost`，含任意端口）写成行内代码，不要发可点击链接，并注明「请用系统浏览器打开」。

为什么要卡这几条：

• DSH 通过鉴权文件路由（GET /api/file?path=<绝对路径>，由会话媒体引用挂载）提供正文里的本地图片，接受 POSIX 绝对路径与 Windows 盘符路径；官方文档同时说明这条路由需要 HTTP(S) 页面，桌面端 dsh-app: 页面不支持。
• 相对聊天图片路径要求当前查看的会话有 workspace root，因此绝对路径才是可移植写法。
• read_image、浏览器截图等工具结果里的图片本身就以附件渲染，插件同样接管；但智能体仍应配一句说明，别让用户自己猜图里是什么。

想验证整条链路：对着一个能打开的页面说「截个图并内联出来」。回复里出现图片就点它——弹层打开即为插件生效。没有图时依次检查：是否用了 Markdown 语法而不是裸路径、是否绝对路径加正斜杠、文件是否真实存在。

快捷键

按键 · 作用

Esc · 关闭（输入框聚焦时先退出输入）

+ / = · 放大

- · 缩小

0 · 适应窗口

1 · 原始大小（1:1）

R · 顺时针旋转 90°

Shift+R · 逆时针旋转 90°

← / → · 上一张 / 下一张

双击 · 适应窗口 ↔ 原始大小

安装

本插件是纯 JavaScript 的 DSH bundle（package.json 声明 dsh.bundle），无需构建、无需授权构建脚本，装完刷新页面即可（首次加载新插件建议重启一次 DSH）。

方式一：DSH 插件页

1. 打开 插件 → 添加插件

2. 填入包名或地址：

github:NingYuanLee/dsh-image-viewer-pro

3. 按提示刷新或重启 DSH。

方式二：命令行

Web 端（dsh web 使用的 profile）：

dsh plugin --profile web add github:NingYuanLee/dsh-image-viewer-pro

桌面端：

dsh plugin --profile desktop add github:NingYuanLee/dsh-image-viewer-pro

把 --profile 换成你实际启动的 profile 名即可。GitHub 源安装拉取源码，本插件没有 prepare 脚本，因此不会触发 pnpm 的 allowBuilds 授权。

方式三：Release tarball

不想让包管理器拉源码时，可直接安装预打包产物：

dsh plugin --profile web add https://github.com/NingYuanLee/dsh-image-viewer-pro/releases/latest/download/dsh-image-viewer-pro.tgz

卸载

dsh plugin --profile web remove dsh-image-viewer-pro

或在插件页停用 / 移除。卸载后恢复 DSH 官方预览，不会删除任何会话或图片。

兼容性

• 已在 DSH 0.2.1-rc.2（Web GUI / 桌面端，同为 Web 渲染层）与 DSH 0.2.2-rc.1 实机验证。
• 声明 engines.dsh: >=0.2.1-rc.2 <0.3.0-0 || >=0.2.2-0 <0.3.0-0 与 engines.node: >=22.19.0，安装与启动时会校验。
• 依赖 Host 的 remote / remote.session 服务来打开本地文件或显示文件位置；服务不可用时该操作退化为提示，不影响其他功能。

与 DSH 插件规范的对齐

对照官方《

…(truncated)