前言¶
在 DeepSeek Harness（DSH）里和智能体协作时，对话里经常出现三类「看得见却不好立刻打开」的内容：助手给出的本地路径、会话附件文件名、以及 http(s) 外链。默认界面里它们多半是普通文本或链接，要确认内容往往得切到资源管理器、另开浏览器标签，或自己拼 file:// 路径。
dsh-file-preview 是维护者 dadgrand 发布的客户端类 DSH 插件（当前版本 0.1.0，MIT 许可证）。它在 Web UI 里拦截聊天中的相关点击，在对话上方弹出模态窗口，就地预览图片、PDF、Office 文档、文本与代码等，并提供复制、在浏览器中打开、在文件管理器中显示、用系统默认应用打开等操作。插件托管于社区目录 SkillHub，与 DeepSeek / 幻方无官方从属关系；DSH 生态奉行「一切皆插件」，可按需从目录或 GitHub 获取源码核对后再安装。
这是什么¶
一句话：dsh-file-preview 为 DSH Web 界面提供会话内文件与链接预览能力——点击路径、附件名或外链即可打开预览模态框，而不必离开当前聊天页。
实现上分为两半（见项目 README）：
- Host（
index.js与lib/host/）：在 DSH 的webServer上注册/api/dsh-file-preview/*，从磁盘读文件、按需把 Office 转为 PDF、拉取链接元数据、执行系统级打开/定位等动作。 - Client（
lib/client.js）：在浏览器侧捕获点击、渲染模态框，文本与图片的剪贴板复制由客户端完成。
package.json 要求 Node >=20，DSH 引擎 >=0.2.0-rc.2；客户端配置为 platform: web、immediately: true，加载后即可参与点击拦截。
核心功能¶
预览与内容类型¶
Host 通过 GET /meta 判断文件类型，preview 字段可为 image、pdf、text、markdown、code、html、office、video、audio 或 none。常见能力包括：
- 二进制与流式读取：
GET /raw（支持Range，适合 PDF/音视频）。 - 文本抽取：
GET /text（UTF-8，异常字节时 Windows 上可回退 Windows-1251）。 - Office：
GET /office-pdf依赖组合里是否挂载officeToPdf服务（桌面配置里常见office-to-pdf插件）；未挂载时返回501 office-unavailable，客户端可退化为「用默认应用打开」。 - 外链：
GET /link在 5 秒超时、最多 512 KiB 响应体内抓取标题、描述、站点名等元数据（仅http/https）。
转换得到的 PDF 缓存在 $DSH_HOME/cache/file-preview/；除该目录外插件不向磁盘写入其他位置。
模态框中的操作¶
模态框内动作与 Host POST /action 对应（需 Content-Type: application/json）：
| action | 含义 |
|---|---|
open |
用系统默认应用打开文件 |
reveal |
在文件管理器中定位文件 |
browser |
在系统浏览器中打开 URL |
copy-file |
将文件本身放入系统剪贴板（Windows / macOS；Linux 返回 action-unavailable） |
纯文本、图片、链接的「复制」不在 Host 实现，由客户端通过浏览器剪贴板 API 处理。
聊天里会拦截哪些点击¶
README 说明客户端在 window 上注册捕获阶段 click 监听，典型来源包括：
- Markdown 里的本地路径链接（
fileLink按钮，路径在title或文本中）； - 助手图片
img[src*="api/file?path="]； - Deliverable 卡片、
data-changed-files中的绝对路径； - 普通
a[href^="http"]外链； - 用户附件
[data-message-attachments]：DOM 里往往只有文件名，因此会调用GET /resolve，优先在$DSH_HOME/attachments按 basename 找最新文件，否则在请求cwd下搜索。
无需修改 DSH 核心或其它插件包即可工作。
安全边界（loopback fence）¶
所有 API 仅对 loopback 调用方响应：校验 remoteAddress、Host、可选的 sec-fetch-site / Origin，并对跨站请求返回 403。若环境中挂载了 connection 服务，还会走 connection.requestRejection，与 dsh-host-open-in-app 同类。
读文件范围由配置 readScope 控制：
- 默认
readScope: any：在桌面场景下，经上述校验的本机 DSH 页面可预览机器上任意已存在路径（含工作区外、UNC 等）。请求仍只来自本机 loopback，属于产品上的显式取舍。 readScope: roots：路径必须落在请求cwd、$DSH_HOME、os.homedir()、os.tmpdir()以及allowRoots之内，否则403 outside-allowed-roots。
注意：/action 对用户指定的已存在路径不做 roots 限制（README 明确说明），安装前应结合权限与配置评估风险。
Host 进程在 Desktop 下以 ELECTRON_RUN_AS_NODE=1 运行，不能 require('electron')；打开文件与 file-drop 剪贴板通过系统命令（如 xdg-open、explorer.exe）完成。
安装与启用¶
官方说明：仅通过 DSH 的 Plugin Manager 安装，使用 install_bundle 并传入插件目录的绝对路径（例如你本地克隆或解压后的 .../plugins/dsh-file-preview）；不要手改 profile。资料中未提供 dsh plugin add github:... 一类 CLI 一键命令，请勿凭插件名拼接。
安装完成后 profile 中会出现：
package.json的dependencies["dsh-file-preview"] = "link: <路径>"；dsh.profile.bundles包含dsh-file-preview；- Cordis 树中的
file-preview行。
启用 / 禁用：在 Plugin Manager 中切换 file-preview 行（或 set_plugin / set_bundle）。Host 侧 ESM 需重启 DSH Host 进程；客户端脚本需刷新页面（有 watcher 时可 HMR）。
回滚：先禁用 file-preview，再对 dsh-file-preview 执行 remove_bundle；PDF 缓存需手动清理 $DSH_HOME/cache/file-preview/。
环境要求：engines.node >= 20，dsh.engines.dsh >= 0.2.0-rc.2。
配置项¶
在 Cordis 中 file-preview 行的 config 可调整（未知键会被忽略并回退默认值）：
config:
readScope: any
allowRoots: ['D:/projects', '\\\\server\\share']
officeTimeoutMs: 120000
copyFileTimeoutMs: 3000
linkTimeoutMs: 5000
linkMaxBytes: 524288
resolveMaxDepth: 8
resolveMaxEntries: 20000
若希望限制可读路径，将 readScope 设为 roots 并配置 allowRoots，例如：
config:
readScope: roots
allowRoots: ['D:/projects', '\\\\server\\share']
典型用法¶
用法以「在聊天里点击」为主，无需额外命令：
- 让助手在回复里写出可点击的本地路径，或上传附件；点击路径或附件名，应弹出预览模态框。
- 对 PDF、图片、Markdown/代码文本，在模态框内直接查看；对
.docx等 Office 文件，在已安装office-to-pdf且服务可用时内嵌 PDF 预览。 - 需要落地到系统时，使用模态框中的「在资源管理器中显示」「默认应用打开」或「在浏览器中打开」（外链）。
开发与自检（来自 README，需在插件源码目录执行）：
cd plugins/dsh-file-preview
node --check index.js
node scripts/check-bundle.mjs
node scripts/unit-host.mjs
客户端会在 GET 请求上附带 ?seat=...（如 overlay-mounted），可通过 GET /api/dsh-file-preview/status 查看 lastClientSeat 与请求计数，确认浏览器侧 bundle 已挂载。
适用场景与注意¶
适合谁：日常在 DSH Web / Desktop 聊天里频繁核对生成文件、日志片段、PDF 或 Office 交付物的开发者；希望少切换窗口、在会话内完成「看一眼再决定要不要打开」的场景。
平台差异：README 写明 Windows 为首要目标；macOS / Linux 通过 open / xdg-open 等通用启动方式支持。Linux 上 copy-file 不可用；WSL 路径互转未实现（与 dsh-native-command 不同）。
权限与信任：插件以当前 DSH Host 进程的系统权限读文件、执行打开命令。默认 readScope: any 时可读本机任意存在路径。安装前请阅读 GitHub 仓库 源码与 MIT 许可证，并在不信任环境下改用 readScope: roots。
依赖：Office 内嵌预览依赖组合中的 officeToPdf 服务；无服务时仍可走系统打开，但无法在模态框内转 PDF。
结尾¶
dsh-file-preview 把「路径、附件、外链」从聊天里的死文字变成可预览、可一键落到系统的交互，Host 与 Client 分工清晰，并通过 loopback 与可配置的 readScope 界定读盘范围。若要查看简介与版本信息，可打开社区目录页 dadgrand/dsh-file-preview；实现细节与 API 表以 GitHub README 为准。
