dsh-file-preview

DSH（DeepSeek Harness）文件预览插件：在 GUI 中浏览工作区文件、预览 Markdown / PDF / 图片 / CSV / 代码，展示当前会话产出/修改过的文件，并可将文件/文件夹拖入对话（插入单行路径）。

English: README.en.md

功能

• 左侧边栏入口：边栏底部「📁 文件」按钮，文件列表以右侧停靠的侧边栏列展示（对话保持可见，主列自动让位；窄屏降级为覆盖）
• 宽度可调：拖动面板左缘手柄调整宽度（320–900px，随视口收缩），自动记忆；双击恢复默认
• 会话产出/修改文件：面板顶部列出当前会话中 AI 产出或修改过的文件（从会话事件日志提取），点击即预览
• 默认定位会话目录：自动定位到当前会话所在工作区与目录；多会话可在顶部切换
• 拖拽到对话：文件/文件夹拖到会话界面任意位置，即在输入框光标处插入单行纯路径（不粘贴内容）
• 预览：Markdown 渲染 / PDF 内嵌 / 图片 / CSV 表格 / 代码文本 / 其他类型新标签页打开
• 安全：只能访问已注册的工作区，禁止路径穿越；文本读取 5 MiB 上限

安装

方式一：本地源码（当前推荐，npm 尚未发布）

⚠️ 本插件尚未发布到 npm，dsh plugin add 暂不可用；当前请使用本方式安装。

git clone https://github.com/ld-1101/dsh-file-preview.git
# 将目录链接进 profile 的 node_modules，并在 profile 的 package.json 中：
# 1) dependencies 添加 "dsh-file-preview": "file:<路径>"
# 2) dsh.profile.bundles 数组追加 "dsh-file-preview"
# 然后重启 DSH

安装后完全退出并重新启动 DSH 应用（宿主端插件在启动时加载）。

方式二：npm 发布后（推荐）

# 安装到指定 profile（web 或 desktop）
dsh plugin --profile web add dsh-file-preview
dsh plugin --profile desktop add dsh-file-preview

安装后完全退出并重新启动 DSH 应用（宿主端插件在启动时加载）。

使用说明

1. 点击左侧边栏底部的 「📁 文件」 按钮，右侧展开文件列表面板；再点一次或点「✕ 关闭」收起
2. 顶部「📌 本会话产出 / 修改」列出当前会话 AI 产出/修改的文件，点击预览；下拉框可切换会话，切换后自动定位到该会话目录
3. 下方为工作区目录树：面包屑导航、目录优先排序、多工作区切换
4. 拖拽：把文件或文件夹拖到会话界面任意位置（无需对准输入框）→ 输入框光标处插入一行路径（如 C:\Users\...\简历.md），发送即可让 AI 读取
5. 调整宽度：拖面板左缘手柄；双击手柄恢复默认宽度
6. 预览：点击任意文件 → 面板内渲染（Markdown/PDF/图片/CSV/代码），「新标签页打开」可脱离面板查看

会话产出文件说明

「会话产出」列表的数据来自会话事件日志：宿主读取 tool/result 事件中工具结果 JSON 的 locations[].path（与 DSH 自带 deliverables 同源）。注意：若 Agent 通过 run_code 一类的包装工具执行文件操作（不产生 locations），该列表为空——这是平台行为，与原生 deliverables 一致。

工作原理

宿主端（Node.js）                         客户端（Web 壳内 React bundle）
──────────────                            ────────────────────────────
/file-preview 路由（prefix 注册）  ◄─fetch─  面板组件（__ModuleLoader__ 注入）
  roots           工作区列表                        ├─ 目录树 / 面包屑 / 多工作区切换
  list            目录枚举（目录优先 + 中文排序）    ├─ 顶部「本会话产出 / 修改」列表
  read            文本读取（5 MiB 上限，截断标记）   ├─ 预览视图（MD/PDF/图片/CSV/代码）
  raw             二进制原样返回（MIME 识别）       └─ 拖拽：dragstart 写自定义类型
  session-files   会话产出文件提取                         → drop 解析 → 光标处插入路径
      └─ 遍历会话事件日志 tool/result 的 locations[].path
         （与 DSH 原生 deliverables 同源）

• 客户端插件机制：宿主扫描声明 dsh.client 的插件包，将其 client bundle 注入 Web 壳（与官方插件同机制，桌面与 Web 通用）
• 拖拽：自定义 DataTransfer 类型（application/x-dsh-file-preview）+ document 捕获阶段 dragover/drop 拦截（dragover 必须 preventDefault 浏览器才允许 drop），原生 setter 写入输入框草稿（React 可控组件兼容），只插入单行路径、不拉取文件内容
• 会话产出：ctx.sessions.get(id).events 遍历 tool/result，解析 locations，去重、过滤工作区、按修改时间倒序、上限 200 条
• 路径安全：safeJoin 先规范化 root 再拼接相对路径，逃逸工作区根即拒绝；只读注册工作区

仓库结构

dsh-file-preview/
├── lib/
│   ├── index.js   # 宿主端：/file-preview 路由（roots/list/read/raw/session-files）
│   └── client.js  # 客户端：__ModuleLoader__ bundle（React 组件 + Markdown/CSV 渲染）
├── cordis.patch.yml
├── package.json   # dsh.client 声明（platform: web，注入 client-runtime + ui-slots + locale）
├── LICENSE        # MIT
├── README.md / README.en.md
└── test/
    ├── unit-client.mjs          # 客户端纯函数单元测试（25 项）
    ├── smoke.mjs                # 基础路由冒烟测试
    ├── smoke-session.mjs        # 会话产出路由测试
    ├── integration-real-log.mjs # 真实会话日志集成测试
    └── run-all.cjs              # 一键运行全部测试（可移植，基于脚本自身定位仓库根）

开发

node test/run-all.cjs          # 全部测试（语法检查 + 25 项单测 + 冒烟 + 集成）
node test/unit-client.mjs      # 仅单元测试（25 项，纯函数，不依赖浏览器）
node test/smoke.mjs            # 仅冒烟：基础路由
node test/smoke-session.mjs    # 仅冒烟：会话产出路由

改源码后：客户端 bundle 通过 HMR 热更新；宿主端需重启 DSH 应用。

常见问题

问题	解决
「本会话产出 / 修改」列表为空	数据来自会话事件日志中 tool/result 的 locations；若 Agent 经 run_code 等包装工具写文件（不产生 locations），列表为空——平台行为，与原生 deliverables 一致
预览中文乱码 / 显示不全	文本读取上限 5 MiB，超限会截断并在面板提示；PDF/图片走 raw 原样返回，请确认文件本身编码
拖拽没反应	需拖到会话界面（非输入框也可），且 dragover 已被插件拦截；若被其他元素抢走 drop，先点一下会话区域再拖
看不到某个目录	只能访问已注册的工作区，工作区外的路径（含路径穿越）一律拒绝
面板宽度不记得	宽度记忆存于 localStorage；双击面板左缘手柄可恢复默认
其他类型文件打不开	预览支持 MD/PDF/图片/CSV/代码文本；其余类型点击后新标签页打开（浏览器决定展示方式）

版本记录

版本	日期	说明
v0.1.0	2026-08-17	首个发布版：工作区文件浏览 + 多格式预览 + 会话产出文件 + 拖拽到对话（插入单行路径）+ 25 项单元测试

发布与 DSH 插件生态

• npm：npm publish（需先 npm login）。发布后任何机器可用 dsh plugin --profile <name> add dsh-file-preview 安装
• GitHub：本仓库带 dsh-plugin topic，社区目录（Oh-My-DSH 等）会自动同步收录
• 详见 dsh-community-plugins 生态指南

致谢

• UI 交互模式（侧边栏入口、主区/侧列布局、slot 注册方式）借鉴自 dsh-ssh-ops（MIT License，作者 caoyiwei850）
• 客户端插件架构与 API 用法参考了官方 @deepseek-ai/* 包（dsh-client-ui-deliverables、dsh-client-runtime、dsh-client-ui-sidebar、dsh-session* 等）
• 其余部分（宿主路由与路径安全、会话产出提取、拖拽到对话、Markdown/CSV 渲染、预览视图）为本插件原创

许可证

MIT