dsh-file-browser

Readme

# dsh-file-browser

DSH（deepseek-ai/deepseek-harness）插件：在聊天界面右端加一个**全盘文件浏览栏**。

- 逐层浏览所有盘符（Windows 枚举 `A:`–`Z:`，POSIX 为 `/`）与主目录，面包屑导航
- 按 **名称 / 大小 / 修改时间** 排序，支持升/降序，文件夹默认分组置顶
- 服务端流式扫描 + 有界 Top-K 截断（默认每层 1000 条），大目录不卡顿
- **拖文件进聊天框**：
  - 图片（png/jpg/jpeg/gif/webp，≤ `readMaxBytes`）→ 变成真正的图片附件
  - 其他文件/目录 → 在草稿中插入绝对路径（反引号包裹）
- 行内快捷操作：插入路径 / 直接发送路径给 Agent / 复制路径 / 用系统默认应用打开
- 会话头部“文件”按钮开合面板；面板可拖宽（280–560px）
- 文案中/英双语（通过 harness `locale` 服务注册 `file-browser` 命名空间，无服务时回退中文）

## 兼容性

按 harness **`@deepseek-ai/*@0.1.0-rc.6`** 的实际 API 编写（slot 插槽 `shell.overlay`、
`conversation.session.header.actions`；`ctx.webServer` 路由；`dsh.client` 客户端插件机制）。

## 安装（在你的目标环境执行）

推荐用 `file:` 协议安装，保证依赖提升进 profile（`link:` 会让 ESM 从插件工程
目录解析依赖，工程自身没有 `node_modules` 时会报
`Cannot find package '@deepseek-ai/schemastery'`）：

```sh
dsh plugin --profile <目标profile> add "dsh-file-browser@file:<本目录绝对路径>"
# 或先 pnpm pack，再安装 tarball（依赖同样提升进 profile）
dsh plugin --profile <目标profile> add ./dsh-file-browser-0.1.0.tgz

dsh plugin --profile <目标profile> list          # 应看到 dsh-file-browser
dsh --profile <目标profile> --dump-config        # 应看到 file-browser 行
dsh --profile <目标profile>                      # 重启后生效（已运行的实例需重启）
```

开发期用 `--patch` 指向构建产物时注意：源码路径条目没有可解析的
`package.json`，**client 半不会加载**；本地联调 client 半请用上面的
`dsh plugin add`。

## 配置（cordis.yml，全部有默认值）

```yaml
- insert:
    - id: file-browser
      name: dsh-file-browser
      config:
        maxEntries: 1000          # 单层返回条目上限（隐藏项计入）
        statConcurrency: 32       # 扫描时并发 stat 数
        readMaxBytes: 16777216    # 拖入图片的字节上限（16 MiB）
        allowedRoots: []          # 空 = 全盘；非空 = 只允许这些根（如 ["C:\\work"]）
        trustedHosts: []          # 除 loopback 外额外信任的 Host，如 ["192.168.1.20"]
        defaultPath: ""           # 面板初始目录；空 = 用户主目录
```

## HTTP API（host 半，只读 GET + JSON）

| 路由 | 说明 |
|---|---|
| `GET /file-browser/roots` | `{ roots, home, defaultPath }` |
| `GET /file-browser/list?path=...&sortKey=name\|size\|mtime&direction=asc\|desc` | `{ path, crumbs, entries, truncated, total }` |
| `GET /file-browser/read?path=...` | `{ name, path, size, base64 }`（普通文件，≤ `readMaxBytes`） |

错误统一 `{ code, message, path? }`。安全：该路由不在 `/api` 信任围栏内，因此自守
**Host 头 loopback 校验**（`127.0.0.1`/`localhost`/`[::1]`，可用 `trustedHosts`
扩展），只接受 GET、不设 CORS、`Cache-Control: no-store`。

## 开发与测试

```sh
npm run build    # 零依赖构建：host ESM 复制到 lib/，client 包 __ModuleLoader__ 壳
npm test         # node --test，15 个用例（含执行构建产物 client.js 的冒烟测试）
```

### 目录

```
src/index.js         host 入口（Config schema + /file-browser 路由注册）
src/fs.js            roots / 排序截断列表 / base64 读取（纯函数，可单测）
src/http.js          路由 handler（Host 校验、参数校验、错误映射、abort）
src/client/index.js  client 单文件 bundle 源（面板/按钮/拖拽/草稿写入）
scripts/build.mjs    构建脚本
types/               手写 d.ts
```

### 为什么不是 TS + esbuild

计划阶段原定 TS + esbuild；实施时发现 npm registry 上的 dsh 类型包只发布到
`0.0.1-rc.1`，而 harness 实际运行 `0.1.0-rc.6`，按 npm 类型编译会得到错误的
API 契约。最终改为 **host 纯 ESM JS + client 手写 module-loader bundle**
（与本机已装外部插件 `@dsh-external/dsh-plugin-tts` 同款落地方式），零构建依赖，
产物直接适配 rc.6；`types/` 提供手写 `.d.ts` 供消费者类型检查。

## 已知限制

- 仅对 web 版 harness 有意义，且浏览的是 **host 进程所在机器** 的磁盘。
- 单层截断：超出 `maxEntries` 时按当前排序保留最靠前的条目，请用排序/导航缩小范围。
- 目录大小不递归统计（显示 `—`），目录在大小排序时按名称排。
- 隐藏文件按 dot 前缀判断（与 harness 既有约定一致），面板内可开关显示。
- 拖拽默认把路径写进草稿，而不是把任意二进制上传为附件（DSH 会话只有图片附件
  语义；其他文件由 Agent 的 fs 工具按路径读取）。
- 若 harness 以 LAN 地址访问且 Host 头不是 loopback，需在 `trustedHosts` 中列明，
  否则该面板返回 403（这是刻意的 DNS-rebinding 防护）。

## 验收清单（目标环境）

1. `--dump-config` 出现 `file-browser` 行，启动日志无 FAILED。
2. 会话头部出现“文件”按钮，点击后右端出现文件栏。
3. 盘符/主目录芯片、面包屑、上/下级导航正常。
4. 名称/大小/时间排序与升降序正确；大目录出现截断提示且不卡。
5. 拖 txt/py → 草稿插入 `` `路径` ``；拖 png → 出现图片附件；无会话时拖拽有提示。
6. 行内“发送”按钮 → Agent 收到路径消息；“复制”“打开”可用。
7. 面板宽度可拖，刷新/隐藏文件开关生效，关闭面板不丢排序偏好。