loyalchiiina/dsh-chat-image-lightbox

DSH 聊天图片灯箱 🖼

对话里的图，值得被认真看。

Images in chat deserve a proper look.

📦 npm 包名 / npm package name：@loyalchiiina/dsh-chat-image-lightbox
GitHub 仓库名是 dsh-chat-image-lightbox，但 npm 上带 scope 前缀，安装时请用完整名。
The GitHub repo is dsh-chat-image-lightbox; the npm package is scoped — use the full name when installing.

dsh plugin --profile desktop add @loyalchiiina/dsh-chat-image-lightbox

图片灯箱全屏查看

灯箱全屏态：原图完整显示（自动适配屏幕高度），右上角是「⬇ 下载」与「✕ 关闭」按钮；同一条消息里的其他图片可用方向键连续浏览。
Full-screen lightbox: the image auto-fits the viewport, with ⬇ download and ✕ close in the top-right; arrow keys page through the other images in the same message.

功能总览 · At a glance（中英对照 / Bilingual）

灯箱查看 · Lightbox viewer

| 中文 | English |
|---|---|
| 点击任意对话图片进入全屏灯箱 | Click any chat image for a full-screen lightbox |
| 滚轮缩放、拖拽平移 | Wheel zoom, drag to pan |
| 工具栏缩放按钮 ⊕ ⊖ 与 1× 复位 | Toolbar ⊕ / ⊖ zoom buttons with 1× reset |
| 方向键平移视角（按住连续移动） | D-pad moves the view (press-and-hold repeats) |
| 左右翻页：按钮 / 键盘 / 触屏滑动 | Prev/next via toolbar, keyboard or swipe |
| 下载原图（自动识别扩展名） | Download original (extension auto-detected) |
| 复制图片文件绝对路径 | Copy the image's absolute local path |
| 在文件夹中显示（资源管理器定位） | Reveal in folder (file manager locates the file) |

会话级图片控制 · Conversation-wide controls

| 中文 | English |
|---|---|
| 一键把整个会话图片收成缩略图网格 | Collapse every image in the conversation into a thumbnail grid |
| 网格列数可调（1–12，设置被记住） | Configurable columns per row (1–12, remembered) |
| 一键隐藏 / 展开所有图片 | Hide / restore all images at once |
| 跳图定位：左键上一张、右键下一张、三连最远/最近 | Jump: left = prev, right = next, triple = farthest / nearest |
| 落点闪一下高亮 | Landing block flashes briefly |

格式与清晰度 · Formats & fidelity

| 中文 | English |
|---|---|
| TIFF/TIF、HEIC 自动转换显示 | TIFF/TIF, HEIC auto-transcode for display |
| TIFF/PNG/BMP 无损原像素（逐像素零误差） | TIFF/PNG/BMP lossless, native pixels (bit-exact) |
| 2 亿像素大图流畅显示 | 200-megapixel images display smoothly |
| 11 种格式实测支持（JPG/PNG/WebP/GIF/AVIF/SVG/BMP…） | 11 formats verified (JPG/PNG/WebP/GIF/AVIF/SVG/BMP…) |

宿主侧工具 · Host-side tool (display_image)

| 中文 | English |
|---|---|
| 关键词搜网图（花瓣/Bing/搜狗 3 源回退） | Keyword image search (Huaban / Bing / Sogou fallback) |
| 搜图自动过滤广告与他人面孔 | Auto-filters adverts & other celebrities |
| 本地文件/目录直读（TIFF/HEIC 转码） | Read local files/dirs (TIFF/HEIC transcoded) |
| 网图落地保存到本地目录 | Save remote images to a local folder |
| 代理自动探活（无需手配） | Auto proxy discovery (TCP probe) |

隐私与安全 · Privacy & safety

| 中文 | English |
|---|---|
| 一切本地服务仅回环（loopback-only） | All local services are loopback-only |
| 打开文件夹用参数化调用，绝不拼接 shell 命令 | "Show in folder" spawns argv, never a shell string |
| 保存说明不回显本机路径 | No local paths echoed in confirmations |

English
一个 DeepSeek Harness 插件，可在聊天中内联显示图片，并带有灯箱覆盖层——支持缩放、下载（另存为对话框）以及上一张/下一张导航。

来自你的 agent 的图片在气泡里显示得很小——要查看细节，你必须把它们保存下来再到别处打开。有了这个插件，只需点击一下即可全屏打开任意聊天图片：缩放、拖动平移、下载，并翻阅同一条消息中的其他图片。

功能

- 内联显示：AI 回复中的图片直接在聊天中渲染（通过 markdown alt）
- 点击缩放：点击任意图片即可打开全屏灯箱；再次点击可缩小还原
- 滚轮缩放与平移：放大后，可使用鼠标滚轮进一步缩放，并拖动以平移查看图片
- 下载：点击下载按钮 ⬇ 保存图片（对于同源图片会触发浏览器另存为对话框；文件名经过清理，扩展名根据图片类型推导）
- 导航：左/右箭头按钮、键盘方向键，或在触屏设备上左右滑动，可在多张图片之间切换
- 说明文字：查看器会显示当前图片的文件名/说明文字
- 无障碍：灯箱是一个规范的 role="dialog"，带有 aria-modal、按钮 aria-label，并具备焦点管理（关闭时焦点返回到触发元素）
- 流畅：相邻图片会被预取，因此导航感觉即时
- 关闭：点击背景、按 Escape 或点击 ✕ 即可关闭
- ZCode 风格渲染：聊天图片就地设置样式——绝不移动、调整大小或重新挂载父节点——因此绝不会与 DSH 的 React 虚拟列表冲突（不再出现图片消失/重复或控制台 removeChild 错误）
- 限制高度，而非裁剪：每张聊天图片都按其宽高比渲染，高度上限为 min(460px, 64vh)（ZCode 外观）；图表和示意图保持完全可读
- 响应式图片行：当一条消息在一个容器中包含多张图片时，它们会以响应式 CSS 网格行布局——仅通过在容器上添加类实现，不移动任何节点
- 打开时显示高清原图：点击任意图片会以全分辨率原图打开灯箱——放大后显示真正的高分辨率文件
- 简洁 UI：灯箱工具栏（下载/关闭）、上一张/下一张箭头、计数器和说明文字在灯箱关闭时始终隐藏——它们只在你实际查看图片时出现，因此绝不会干扰聊天布局
- 缩放/平移控制板：灯箱还提供用于手势操作的显式控件——⊖ ⊕ 1× 用于缩放，并带有实时百分比读数，还有一个方向键用于移动视图（按住可连续移动）。滚轮、拖动以及 +/-/Shift+方向键 仍然可用
- 在一个弹出面板中提供整个对话的图片控制：一个紧凑的 「🖼 图片」 触发器位于访问模式控件旁边，滑出面板中包含全部四项操作——不再有一排按钮挤占输入区
- 可配置列数的缩略图网格：一键将对话中的每一个图片块折叠成由小图块组成的 CSS 网格（说明文字横跨整行）。一个数字字段用于设置每行列数（1–12），并在重新加载后保留
- 隐藏 / 显示整个块：一键隐藏所有图片（每个块折叠成一条细条），再次点击即可将它们完好地恢复
- 跳转到图片：一个用于定位图片的按钮——左键单击跳到上一张图片，右键单击跳到下一张；左键三击跳到距离视口中心最远的图片，右键三击跳到最近的图片。落点所在的块会闪烁。步进是相对于上一次落点的块进行的，并在两端停止
- 自动增强：MutationObserver 会自动增强添加到聊天中的新图片，并重新接管那些被 React 重新渲染覆盖掉 class 的图片
- 将图片带入聊天（display_image 工具，宿主侧）：一个工具可接收本地 path（文件或目录——TIFF/HEIC 会被转码，可选降采样）、远程 url 或 query（关键词图片搜索：优先花瓣，Bing 作为后备），并返回可直接粘贴的 Markdown。本机上的任何文件都可以通过 /images/?abs=（仅限回环）就地提供，无需复制到图库根目录

安装

方法 1：npm（推荐）

dsh plugin --profile desktop add @loyalchiiina/dsh-chat-image-lightbox

方法 2：手动

1. 将 lib/ 文件夹和 cordis.patch.yml 复制到你的 DSH 配置文件的 node_modules/@loyalchiiina/dsh-chat-image-lightbox/
2. 将 @loyalchiiina/dsh-chat-image-lightbox 添加到你的配置文件的 package.json → dsh.profile.bundles 数组中
3. 重启 DSH Desktop

用法

1. 将图片放入 ~/.dsh/uploads/（或你的 DSH 实例所服务的任何目录）
2. 在你的 AI 回复中，使用 markdown 图片语法：
Description

3. 图片将以内联方式显示，并带有灯箱增强效果

注意：要让下载按钮触发另存为对话框，图片必须与你的 DSH 实例同源提供（例如通过 /images/ 路由）。跨源图片将在新标签页中打开。

排查图片显示问题（重要）

当图片显示为空白、一团文字，或灯箱打开后为空时，请按以下顺序检查：

① 图片必须使用 http(s) URL——base64/data-URI 和附件不会被渲染

DSH 只会从 http(s) URL 将图片渲染为 。它不会内联渲染 data:image/png;base64,...，也不会渲染“文件投递/附件”消息（那些会显示为工具调用文本，而不是图片）。

- ✅ 正确——markdown + http URL：
Description

- ✅ 正确——任何未受防盗链保护的外部图片：
Description

- ❌ 不会渲染——base64 内联：
Description

② 空白图片 / 空灯箱 = 图片主机的防盗链保护（源站限制，非本插件问题）

某些主机（例如 新浪微博 sinaimg、部分 CDN）会强制执行 Referer 检查：不带预期 Referer 的请求会返回 403，因此图片框架会渲染，但不会加载任何像素（点击仍会打开灯箱，但没有图片）。

- 任何普通网页都无法直接盗链这些图片（包括除微博以外的所有网站）——这不是任何插件能解决的问题。
- 变通方法：将图片下载到 ~/.dsh/uploads/（使用正确的 Referer 抓取，或直接从浏览器保存），然后通过 /images/ 提供访问。

示例——抓取受防盗链保护的图片（Windows）：
curl -e "https://weibo.com" -o image.jpg "https://wx1.sinaimg.cn/.../xxx.jpg"

③ 支持的图片格式

| 格式 | 是否显示 | 说明 |
|--------|-----------|-------|
| jpg / jpeg / png / gif / webp / bmp / svg / ico / avif | ✅ 直接显示 | 主流格式——显示 + 灯箱均正常，字节不变 |
| tiff / tif | ✅ 通过服务器转换 | 浏览器无法渲染 TIFF；插件服务器会以原始完整分辨率将其转换为 WebP（内置 sharp）——高清显示，下载时保留原始 .tif |
| heic | ✅ 通过服务器转换 | 与 TIFF 相同——以 WebP 显示，下载为原始 .heic |

文件放入 ~/.dsh/uploads/ 并通过 /images/ 显示——无需手动转换。

④ 更改后插件不工作——请完全重启

安装或编辑插件文件后，完全退出所有 DSH Desktop 进程（任务管理器 → 结束每一个 DSH Desktop.exe）并重新打开。仅关闭窗口不会退出（后台进程仍会保留）。否则旧代码/未加载的代码会使插件保持不活动状态。

⑤ 真的是插件的问题吗？快速检查清单

- 用通过 /images/ 提供的上传文件测试——如果它能显示并打开灯箱，则插件正常。
- 用非防盗链主机的图片测试（例如 https://picsum.photos/800/600）——如果这能正常工作，则插件是通用的。
- 如果上传和外部图片都无法打开灯箱 → 插件客户端未加载，通常是因为 DSH 未完全重启或安装不完整。

键盘与鼠标

| 操作 | 输入 |
|--------|-------|
| 打开灯箱 | 点击图片 |
| 放大 / 缩小 | 点击图片，或放大后使用鼠标滚轮 |
| 平移 | 放大后拖动图片 |
| 上一张 / 下一张 | ← / → 键、屏幕上的箭头，或滑动 |
| 关闭 | Esc、点击背景，或 ✕ |

HTTP API

| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| /images/ | GET | 提供上传的图片（仅限回环地址，带扩展名/安全防护） |
| /api/image-gallery/list | GET | 列出图库根目录下的图片；支持 ?limit=N |
| /api/image-gallery/root | GET | 返回配置的图库根路径 |

工作原理

| 组件 | 描述 |
|-----------|-------------|
| 宿主端（lib/index.js） | 在 ctx.webServer 上注册 /images/ 文件服务路由以及 /api/image-gallery/list + /api/image-gallery/root API |
| 客户端（lib/client.js） | 使用 MutationObserver 监听聊天中的  元素，添加显示类 + 点击处理器，打开 lightbox 遮罩层（仅类增强，不重构 DOM） |

要求

- DeepSeek Harness ≥ 2.0（带 webServer 服务）
- Node.js ≥ 22

许可证

MIT

中文

DeepSeek Harness 插件：在对话框中直接显示图片，支持放大、下载（弹出另存为）、左右切换。

功能

- 内联显示：AI 回复中的图片直接在对话框渲染（通过 markdown 描述）
- 点击放大：点击任意图片打开全屏 lightbox，再点一次缩回
- 滚轮缩放 + 拖拽平移：放大后可用鼠标滚轮继续缩放，按住拖拽平移查看细节
- 下载：点击下载按钮 ⬇ 保存图片（同源图片弹出"另存为"对话框；文件名会清洗，扩展名按图片类型自动补全）
- 切换：左右箭头按钮、键盘方向键，或在触屏上左右滑动切换多张图片
- 文件名：查看器底部显示当前图片的文件名/标题
- 无障碍：lightbox 是标准的 role="dialog"（含 aria-modal、按钮 aria-label 与焦点管理，关闭后焦点回到触发元素）
- 预取：自动预取相邻图片，切换更顺滑
- 关闭：点击遮罩层、按 Esc 或点 ✕ 关闭
- ZCode 式渲染：聊天图片原地加样式——绝不搬移、改父级或重排 DOM 节点，不与 DSH 的 React 虚拟列表打架（不再出现图片消失/重复、控制台 removeChild 报错）
- 限高不裁剪：每张聊天图保持原始纵横比，高度封顶 min(460px, 64vh)（ZCode 的观感）；图表、流程图不再被裁得没法看
- TIFF/HEIC 直显：浏览器原生不渲染 TIFF——插件服务端用内置 sharp 将 TIFF/HEIC 按原始分辨率即时转 WebP 显示（本地图表导出照样高清直显），下载按钮保存的仍是原始 .tif/.heic 文件
- 多图九宫格：一条消息里有多张图时自动排成整齐网格（约 3 列），文字段落横跨整行排在网格上方——纯 CSS（display:contents），不搬任何节点
- 点开即高清：点击任意图片打开 lightbox 看全分辨率大图，放大看到每个像素；下载永远保存原始文件
- 界面干净：lightbox 的工具按钮（下载/关闭）、左右切换箭头、计数、标题在 lightbox 关闭时全部隐藏，仅在实际看图时才显示，不会在对话界面留下按钮干扰布局
- 灯箱缩放/平移面板：手势能做的都给了一组显式按钮——⊖ ⊕ 1× 缩放（带实时百分比），加一组方向键移动视角（按住可连续移动）；滚轮、拖拽、+/-/Shift+方向键 全部保留
- 会话内图片控制收进一个弹出面板：输入框旁的「完全权限」右侧只留一个紧凑的 「🖼 图片」 触发器，点它滑出面板，四个操作都在里面——不再让一排按钮占着输入区
- 可调列数的缩略图网格：一键把整个会话的图片收成小图网格（标题横跨整行）；面板里有「列」输入框可设每行几张（1–12），设置会被记住（刷新/重启后仍生效）
- 整块隐藏 / 展开：一键隐藏所有图片（每个图片块收成一条窄边），再点一下原样恢复——所有内联样式按块追踪并清理，图片不会丢
- 跳图定位：一个按钮定位图片——左键跳到上一张、右键跳到下一张；左键三连跳到离屏幕中心最远的一张、右键三连跳到最近的一张；落点会闪一下。步进是相对「上次落点」的，并且到头即止不回绕（回绕会让人以为方向反了）
- 自动增强：MutationObserver 自动增强新加入对话的图片；React 重渲染覆盖 class 后也会自动重新接管
- 把图带进对话（宿主侧 display_image 工具）：一个工具吃三种输入——本地 path（文件或目录，TIFF/HEIC 自动转码、可缩放）、网络 url 直链、query 关键词搜图（花瓣优先，Bing 回退），返回可直接粘贴的 Markdown。本机任意文件可通过 /images/?abs= 原地直读（仅限本机回环），无需先复制进图库目录

安装

方式一：npm（推荐）

dsh plugin --profile desktop add @loyalchiiina/dsh-chat-image-lightbox

方式二：手动安装

1. 把 lib/ 文件夹和 cordis.patch.yml 复制到 DSH profile 的 node_modules/@loyalchiiina/dsh-chat-image-lightbox/
2. 在 profile 的 package.json → dsh.profile.bundles 数组中添加 @loyalchiiina/dsh-chat-image-lightbox
3. 重启 DSH Desktop

使用方法

1. 把图片放到 ~/.dsh/uploads/ 目录（或 DSH 实例提供的任意目录）
2. AI 回复中使用 markdown 图片语法：
描述

3. 图片会内联显示并自动带 lightbox 增强

注意：下载按钮要弹出"另存为"对话框，图片必须从 DSH 同源路由提供（如 /images/ 路由）。跨域图片会在新标签页打开。

图片显示常见问题排查（重要）

遇到"图片显示不出来 / 点开是空白 / 只看到一串文字"时，按以下顺序排查：
① 图片必须用 DSH 能识别的 URL 显示，不能依赖 base64 或附件

DSH 对话只对 http(s) 图片 URL 渲染成 ，不支持 data:image/png;base64,... 内嵌，也不支持以“附件/文件交付”方式直接显示（那只会显示成工具调用文字）。

- ✅ 正确：markdown 图片语法 + http URL
描述

- ✅ 正确：任意无防盗链的外链图片
描述

- ❌ 错误：base64 内嵌（DSH 渲染不出，只看到一串 iVBORw0...）
描述   ← 不会显示

② 图片空白 / 点开灯箱没图案 = 图源防盗链（图床限制，非插件问题）

部分图床（如新浪微博 sinaimg、部分 CDN）强制 Referer 校验：请求不带特定 Referer 就返回 403，导致图片加载不出（有  框但内容空白，点击能弹灯箱但没图）。

- 这类图任何普通网页都无法直接外链显示（包括微博自己以外的所有站点），不是本插件能解决的。
- 解决办法：把图下载到本地 ~/.dsh/uploads/（可用带 Referer 的脚本抓取，或直接用浏览器保存），再通过 /images/ 路由显示。

示例：抓取带防盗链的图（Windows 下用带 Referer 的 curl 或脚本下载后放入 uploads）：
curl -e "https://weibo.com" -o 图.jpg "https://wx1.sinaimg.cn/.../xxx.jpg"

③ 支持哪些图片格式

| 格式 | 显示 | 说明 |
|------|------|------|
| jpg / jpeg / png / gif / webp / bmp / svg / ico / avif | ✅ 直接显示 | 主流格式，直接显示 + 灯箱，字节原样不动 |
| tiff / tif | ✅ 服务端转码显示 | 浏览器不能渲染 TIFF，插件服务端用内置 sharp 按原始分辨率转 WebP 显示——高清直显，下载仍是原始 .tif 文件 |
| heic | ✅ 服务端转码显示 | 同 TIFF——显示为 WebP，下载保存原始 .heic |

图片放到 ~/.dsh/uploads/，用 /images/ 显示——无需手工转码。

④ 彻底重启后插件不生效

改过插件文件或刚安装后，必须彻底退出 DSH 进程再重开（任务管理器结束所有 DSH Desktop.exe 进程），否则旧代码/未加载状态不生效。仅“关闭窗口”不算退出（后台进程残留）。

⑤ 判断是不是插件问题的清单

- 用 /images/ 上传图测：如果上传图正常显示 + 灯箱，说明插件正常
- 换无防盗链图床（如 picsum.photos）的图测：正常则插件通用
- 若上传图、外链图都不亮灯箱 → 插件 client 未加载，多半是没彻底重启或没装正确

键盘与鼠标

| 操作 | 输入 |
|------|------|
| 打开 lightbox | 点击图片 |
| 放大 / 缩小 | 点击图片，或放大后滚动滚轮 |
| 平移 | 放大后按住拖拽 |
| 上一张 / 下一张 | ← / → 方向键、屏幕箭头、或滑动 |
| 关闭 | Esc、点击遮罩层、或 ✕ |

HTTP 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| /images/ | GET | 提供上传图片（仅本机回环，带扩展名/安全校验） |
| /api/image-gallery/list | GET | 列出图库根目录下图片，支持 ?limit=N |
| /api/image-gallery/root | GET | 返回配置的图库根目录路径 |

工作原理

| 组件 | 说明 |
|------|------|
| Host (lib/index.js) | 在 ctx.webServer 上注册 /images/ 文件服务路由和 /api/image-gallery/list + /api/image-gallery/root 接口 |
| Client (lib/client.js) | 用 MutationObserver 监听对话中的  元素，添加展示样式与点击处理器打开 lightbox（只加 class，不改 DOM 结构） |

环境要求

- DeepSeek Harness ≥ 2.0（需要 webServer 服务）
- Node.js ≥ 22

许可证

MIT