对话内联图片zehenk/dsh-tu4-inline-images

dsh-tu4-inline-images

license: MIT
version

对话内联图片 DSH 插件 — 在 DeepSeek Harness (DSH) Web GUI 的对话中,出现本地图片路径即直接渲染为图片。

一个 DSH 插件,可在 DeepSeek Harness (DSH) Web 对话中将本地图片路径渲染为内联图片。安全优先:仅限回环路由、强进程级令牌、多根 realpath 白名单。

What it does / 功能

当以下三个位置出现本地图片路径时,直接显示图片(展示尺寸受用户可选档位上限约束,不生成缩略图文件):

1. 输入框 / Input box — 在输入框中粘贴或输入路径,其上方会出现预览行(路径文本仍保留在你的草稿中)
2. 用户消息 / User message(发送后用户消息气泡) — 发送包含路径的消息,图片会渲染在你的气泡内
3. LLM 输出 / LLM output — 当助手回复中引用路径时,图片会内联渲染在回复中

支持的格式:png / jpg / jpeg / webp / gif / svg / avif / bmp / ico(9 种)。裸路径(D:\pics\photo.png、/home/me/pics/photo.png、\\server\share\photo.png)和 markdown(alt)均可识别。

展示尺寸三档(CSS 上限,保宽高比):小 320×240 / 中 640×420(默认)/ 大 960×600。

How it works / 工作原理

- 宿主端(Node) 在 DSH Web 服务器上注册回环路由 GET /plugins/dsh-tu4-inline-images/image?t=&p=,并注册一个同源的 GET .../state 路由,用于向客户端提供令牌。宿主端会将 LLM 流式输出中的本地图片路径重写为该路由 URL(仅用于展示;路由处理器仍是唯一的文件读取强制执行点)。
- 客户端(浏览器,纯展示) 提供输入框预览行(标准 DSH 插槽 conversation.input.dock)、用户气泡 DOM 后处理(保守策略:单一文本节点 + 用户行 + 代码块之外)以及 DSH 设置 UI 中的设置卡片(尺寸档位 + 额外白名单根目录)。
- 安全链(每个图片请求都必须通过):令牌 → 扩展名白名单 → 多根 realpath 包含检查(默认根目录:会话工作区 + DSH 粘贴根目录;外加用户在设置中添加的根目录)→ 常规文件 stat → 字节大小限制(与宿主端的 attachments.imageLimits 保持一致)。
- 错误响应为固定的短字符串 — 路径绝不回显。

Requirements / 前置条件

- 带 web profile(Web GUI)的 DSH (DeepSeek Harness),例如 dsh web
- GUI 应运行在回环上(默认)。插件仅通过回环路由提供图片;参见 已知边界。

Install / 安装

方式 A — 从 Releases 获取预构建的 tgz:

bash / zsh
dsh plugin --profile web add file:$(pwd)/dsh-tu4-inline-images-1.1.0.tgz

PowerShellbash
dsh plugin --profile web add file:D:\path\to\dsh-tu4-inline-images-1.1.0.tgz

方案 B — 从源码构建：
bash
git clone https://github.com/zehenk/dsh-tu4-inline-images.git
cd dsh-tu4-inline-images
pnpm install
pnpm run check      # build + security gate + tests (74 tests)
pnpm pack           # → dsh-tu4-inline-images-1.1.0.tgz
dsh plugin --profile web add file:$(pwd)/dsh-tu4-inline-images-1.1.0.tgz

宿主插件在 web 服务器启动时加载：安装后需重启 dsh web（卸载后同样如此）。安装/卸载后需重启 dsh web 生效。

安装遵循 DSH 标准 profile 安装（~/.dsh/profiles/web/）：插件被记录在 profile 的依赖与 dsh.profile.bundles 中，其 node_modules 产物由 pnpm 解析。无需环境变量，无需自定义目录，无工作区耦合——切换会话工作区时依然有效。

安装遵循 DSH 标准 profile 安装，不依赖任何环境变量或自定义目录，切换会话工作区不失效。

卸载 / Uninstall
bash
dsh plugin --profile web remove dsh-tu4-inline-images
then restart dsh web

移除依赖、bundle 注册以及 node_modules 产物——已验证清理干净。

使用 / Usage

1. 输入预览： 在输入框中粘贴或键入图片路径——输入框上方会出现预览行。路径文本保留在你的草稿中（纯展示，无删除按钮）；发送时，图片会出现在你的消息气泡中。
2. LLM 输出： 让助手引用某个图片路径（或让它报告一个路径），图片会在回复中内联渲染。
3. 设置卡片： GUI → 设置 → 插件设置 → 对话内联图片 (inline images)：
- 展示尺寸 / size：小 / 中（默认）/ 大——立即应用于全部三个界面
- 追加图片目录 / extra roots：可添加任意数量的绝对目录路径，使其中的图片可被渲染；随时可移除。默认根目录（会话工作区 + DSH 粘贴根目录）为内置，不可移除。

使用内置示例进行冒烟测试：docs/test.png——将其放入白名单根目录（或添加其所在目录）并粘贴路径。

安全 / Security

安全是前提；功能是目标。设计不变量：

| 项 | 设计 |
|---|---|
| 网络端点 | 仅回环；URL 前缀运行时取自 webServer.host/port，源码零 URL 字面量（test/gate.mjs 构建门禁强制）；host 为 0.0.0.0 时 URL 强制 127.0.0.1 |
| 文件读取 | 扩展名白名单 → 多根 realpath 包含校验（拦截 .. 穿越与符号链接/junction 逃逸）→ 常规文件 stat → 字节限流（对齐宿主 attachments.imageLimits.maxImageBytes） |
| token | crypto.randomBytes(32).toString('hex')（256 bit），进程级单 token；响应 Cache-Control: private, no-store + X-Content-Type-Options: nosniff；SVG 另附 Content-Security-Policy: sandbox |
| 流改写 | 仅针对本地图片路径模式介入；跳过带 purpose（compaction/session-title）的辅助调用；路由 handler 是唯一执行点，改写纯展示，任何异常原样透传 |
| 客户端 | 零文件系统访问；无 innerHTML 拼用户数据；无全局监听；网络仅同源 |
| 错误响应 | 统一短文案，绝不回显路径 |

- 构建门禁（test/gate.mjs，每次构建时运行）：零 URL 字面量、零 Math.random、发布代码中零 install 类型生命周期脚本。
- 4 阶段安全自审计记录：docs/SELF-AUDIT.md（零高危发现；7 项已记录的残余风险，均评估为可接受）。
- 报告漏洞：见 SECURITY.md。

已知边界 / Known boundaries

-  请求不携带 Origin 头——token 是唯一的门禁；token 出现在消息 DOM 中（），且作用域限定为同源。
- 使用 --host 0.0.0.0 部署 DSH 会将路由暴露到局域网（token 仍作为门禁）；建议使用回环地址部署。
- 表面 ②（用户气泡）是保守的 DOM 后处理：跨多个 DOM 文本节点拆分的路径不会在此处被替换（路径文本保留；表面 ③ 不受影响）。同一条消息中同一路径重复出现时：第一处会渲染，其余保持为文本。
- 表面 ② 依赖稳定的产品 DOM 标记（用户行上的 data-time-hover-root）；在 DSH GUI 重大升级后，需重新验证（见 docs/PLAN-v3.md §3.2）。
- 计划中（v2）：点击放大灯箱。

开发 / Development
bash
pnpm install
pnpm run check   # = node build.mjs && node test/gate.mjs && node --test "test/*.test.mjs"

- src/ —— host 半部分（index.ts、path-guard.ts、scan.ts、rewrite.ts、index-style.ts、settings.ts、state-route.ts）+ 客户端半部分（client.ts）+ 共享常量（paths.ts）。TypeScript；测试运行于 Node ≥ 22 原生 TS 类型剥离（.mjs 测试直接导入 .ts），因此 src 相对导入使用显式的 .ts 扩展名。
- build.mjs —— esbuild 双 bundle：lib/index.js（node ESM，host）和 lib/client.js（浏览器 CJS，包装在 DSH 的 window.__ModuleLoader__.load({id, factory}) 模块表契约中——见 docs/PLAN-v3.md §3.5）。
- test/ —— 74 个单元/集成测试 + gate.mjs 安全门禁。
- 贡献时需保持的不变量：路由处理器作为唯一读取点、零 URL 字面量、无 Math.random、无生命周期脚本、任何读取前先进行多根包含检查、错误响应绝不回显路径。见 CONTRIBUTING.md。

仓库布局 / Repository layout

├── src/            插件源码(host 半 + 客户端 half + 共享模块)
├── test/           单测/集成测试 + 安全门禁(gate.mjs)
├── docs/           设计与安全文档(见 docs/README.md)
├── build.mjs       esbuild 双 bundle 构建
├── cordis.patch.yml    DSH bundle 挂载(host 插件,仅 insert)
├── dsh.plugin.json     社区兼容清单(DSH 实际读取 package.json)
├── package.json    DSH 权威清单(dsh.bundle.patch + dsh.client + exports)
├── CHANGELOG.md
├── SECURITY.md
└── CONTRIBUTING.md

致谢 / Credits

图像路径扫描算法受社区插件 dsh-inline-images（Asher-2000）启发。本项目是一次完全重写，修复了其审计中的每一项安全发现（硬编码外部端点、无路径白名单、弱 token、安装型生命周期脚本），并新增了三表面显示、多根白名单和设置功能。
路径扫描算法参考社区插件 dsh-inline-images;本项目为完全重写,修复其审计发现的全部安全问题,并新增三位置展示、多根白名单与设置。

License / 许可证

MIT

English summary (for quick scan)

DSH web-profile plugin. Renders local image paths as inline images in (1) the input box preview, (2) sent user-message bubbles, and (3) LLM replies. Loopback-only image route with a 256-bit per-process token; multi-root realpath whitelist (workspace + paste root + user-added roots via settings); display size tiers small/medium/large via a settings card; 9 image formats; zero runtime dependencies; 74 tests + build-time security gate; MIT. Install: dsh plugin --profile web add file: (see above). Uninstall: dsh plugin --profile web remove dsh-tu4-inline-images. Restart dsh web after changes.