dsh-file-preview

Readme

# dsh-file-preview

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

> English: [README.en.md](./README.en.md)

## 功能

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

## 安装

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

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

```bash
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 发布后（推荐）

```bash
# 安装到指定 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              # 一键运行全部测试（可移植，基于脚本自身定位仓库根）
```

## 开发

```bash
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](https://github.com/HubaKing/dsh-community-plugins) 生态指南

## 致谢

- **UI 交互模式**（侧边栏入口、主区/侧列布局、slot 注册方式）借鉴自 [dsh-ssh-ops](https://github.com/caoyiwei850/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](./LICENSE)