ywleeo/dsh-image-preview

dsh-image-preview

让 DeepSeek Harness（dsh）Web 对话正文直接显示本地图片与视频的插件：助手回复里写出的本地图片/视频绝对路径会自动变成内联图片或可播放的视频，媒体下方附一行可点击的本地地址（点击用系统默认应用打开）。

- host 侧（index.js）：包装 llm/stream，把助手文本中的本地媒体路径改写为同源回环 URL；注册 /image（读图）、/video（读视频，支持 HTTP Range 分段响应）与 /open（本地打开）三条路由。
- 客户端（client.js）：极简模块（__ModuleLoader__.load 工厂格式），负责把「▶ 播放视频」链接替换成  播放器、链接小字号样式、收紧间距、拦截点击（只触发本地打开，不开新 tab）。

支持格式：

- 图片：png / jpg / jpeg / webp / gif / svg / avif / bmp / ico（单张上限 20MB，或附件服务的 maxImageBytes）
- 视频：mp4 / m4v / webm / mov / ogv（单文件上限 512MB，浏览器原生可播放的编码；不支持 mkv/avi 等非浏览器格式）

截图

对话中本地图片路径自动内联为大图，图下附一行小字本地地址（点击用系统图片工具打开）：

dsh-image-preview 对话内联图片

对话中本地视频路径自动内联为播放器（，可拖动进度条）：

dsh-image-preview 对话内联视频

特性

- ✅ 本地图片路径 → 对话内联显示
- ✅ 本地视频路径 → 对话内联播放器（支持拖动进度条，HTTP Range 206 分段响应）
- ✅ 跨重启媒体不消失（持久 token 存于 $DSH_HOME/plugins/dsh-image-preview.token）
- ✅ 点击地址行 → 系统默认应用打开（macOS open / Windows start / Linux xdg-open）
- ✅ 点击不开新 tab（客户端拦截；无客户端模块时降级：图片新 tab 显示原图，视频新 tab 直接播放）
- ✅ 媒体下方地址行：小字号、紧贴媒体（两侧 margin 2px）
- ✅ 零构建、纯 ESM；只处理助手回复文本，工具结果卡片不改写（设计边界）

安装

在 dsh 的 profile 目录安装为普通依赖（不声明 dsh.bundle，不会进入 bundles 层）：

cd ~/.dsh/profiles/web
pnpm add github:ywleeo/dsh-image-preview

然后在 ~/.dsh/profiles/web/cordis.patch.yml（用户 patch 层）追加：

- insert:
- id: dsh-image-preview
name: dsh-image-preview

重启 dsh web 后刷新页面即可。

工作原理

1. 改写：llm/stream 文本块结束时，扫描真实存在的本地媒体绝对路径（POSIX /…、Windows 盘符、UNC），验证文件存在后改写为：

图片：

preview

[](http://127.0.0.1:/plugins/dsh-image-preview/open?t=&p=)

视频：

▶ 播放视频

[](http://127.0.0.1:/plugins/dsh-image-preview/open?t=&p=)

2. 读图：/image 路由校验 token 后经 ctx.fs 读取文件字节，按扩展名返回 Content-Type。
3. 读视频：/video 路由校验 token 后按扩展名返回视频 Content-Type，解析 Range 头返回 206 分段响应（Content-Range/Accept-Ranges: bytes），播放器可拖动进度条；无 Range 时返回完整字节。
4. 打开：/open 路由校验 token 后 spawn 系统默认应用，302 到对应媒体路由（无客户端时的降级展示）。
5. 客户端：client.js 注入 CSS（播放器样式 + 小字号 + 间距）、把「▶ 播放视频」链接替换成  播放器（MutationObserver 兜底），并拦截对 /open 链接的点击（preventDefault → fetch 触发本地打开）。

文件分工与启动壳

| 文件 | 作用 |
|---|---|
| index.js | 启动壳。不 import 任何 dsh 核心模块，运行时动态加载 host.js 并挂成子插件；失败只丢功能，不影响 dsh 启动。 |
| host.js | 上面第 1–4 条的全部逻辑（llm/stream 改写 + 三条路由）。 |
| client.js | 上面第 5 条（样式、播放器、点击拦截）。 |

为什么拆：dsh 的 loader 条目一旦激活失败，boot 的激活审计（assertEntriesActivated）会把整棵插件树判死、进程非零退出。本插件包装 llm/stream、注册三条路由，正是最容易挨核心升级刀的那一类，于是壳把会坏的部分挪出启动路径：

- 壳不声明 inject，所以它的 loader 条目永远 ACTIVE，boot 审计永远通过；
- host.js 自己的 inject: ['webServer', 'fs'] 在子 fiber 上照常生效，服务没就绪就先挂起，就绪后自动激活；
- host.js 导入失败、同步抛错、异步 reject，一律只记一条日志，插件停用，dsh 照常启动；
- 子 fiber 挂在壳下面，壳被卸载时宿主逻辑照常回收。
约束（改 index.js 前必读）：package.json 的 main 必须继续指向 index.js，loader 条目名必须继续是裸包名 dsh-image-preview。客户端那一半靠 dsh.client + exports["./client"] 从 loader 条目名反查包，条目名换成子路径会导致客户端半边再也不被扫描到。

升级改坏 host.js 时的预期表现：dsh 正常启动，日志出现

[dsh-image-preview] host.js 加载失败，插件功能已停用，dsh 继续运行。原因：…

对话里的本地图片/视频路径不再内联，其余功能不受影响。照着日志改 host.js 即可，index.js 不用动。

设计边界

- 只处理助手回复的流式文本（llm/stream），工具结果卡片里的路径文本不改写。
- 只处理真实存在的本地绝对路径；远程 http(s)/data:/file: 链接、相对路径不改写。
- 视频仅支持浏览器原生可播放的容器/编码（mp4(H.264/AAC)、webm、mov、ogv）；mkv/avi 等不在预览范围内，但地址行点击仍可用系统播放器打开。
- 视频读取为整读后按 Range 切片（本地预览场景可接受，单文件上限 512MB）。
- token 持久化在 $DSH_HOME/plugins/dsh-image-preview.token（600 权限）：任何能读该文件的本地进程都可访问三条路由 —— 仅限本机使用，勿暴露到公网。

开发与维护

改动后需同步到 profile 的 node_modules 拷贝（file: 依赖是拷贝/硬链接，编辑工具原子写入会断开硬链接）：

bash scripts/sync.sh   # 或手动：cp index.js host.js client.js package.json ~/.dsh/profiles/web/node_modules/dsh-image-preview/

启动壳契约校验（无外部依赖）：

node test-shell.mjs    # host.js 坏掉时不抛、只报告

生效方式：

- index.js / host.js（host 逻辑）→ 重启 dsh web
- client.js（样式/播放器/点击）→ 刷新浏览器页面

卸载

cd ~/.dsh/profiles/web
pnpm remove dsh-image-preview

并删除 cordis.patch.yml 里对应 insert。

发布更新

仓库内置两条脚本（scripts/）：

本机开发时同步（不发布）

file: 依赖的 node_modules 是拷贝/硬链接，改完源码后同步到所有已安装的 profile：

pnpm run sync

然后按改动类型生效：index.js → 重启 dsh web；client.js → 刷新页面。

一键发布（提交 + 打 tag + 推送）

pnpm run release          # 递增 patch 版本
pnpm run release minor    # 递增 minor
pnpm run release major    # 递增 major

脚本自动完成：升版本 → 同步本机拷贝 → git commit → git tag vX.Y.Z → git push。

其它机器/重装后更新

- 首次：pnpm add github:ywleeo/dsh-image-preview#vX.Y.Z（按 tag 安装，可复现）
- 已安装：pnpm update dsh-image-preview（重新拉取默认分支最新代码）后重启 + 刷新

已知边界

- 路径含 ( ) [ ] 等特殊字符时 markdown 链接语法可能破损（日常路径不受影响）。
- Windows/Linux 打开命令已实现但仅在 macOS 实测。

License

MIT