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 <目标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，全部有默认值）

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