全盘文件浏览栏 Clearchenpro/dsh-file-browser

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'）：

dsh plugin --profile add "dsh-file-browser@file:"
或先 pnpm pack，再安装 tarball（依赖同样提升进 profile）
dsh plugin --profile add ./dsh-file-browser-0.1.0.tgz

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

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

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

- 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。

开发与测试

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. 面板宽度可拖，刷新/隐藏文件开关生效，关闭面板不丢排序偏好。