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