前言¶

在 DSH 这类插件式 harness 中，Agent 经常需要引用本机文件路径，但聊天界面本身不一定有方便浏览本机磁盘的入口。dsh-file-browser 是 Clearchenpro 维护的一个 DSH 插件，许可证为 MIT，面向 web 版 harness：它在会话头部提供“文件”按钮，点击后在聊天界面右端打开一个文件浏览栏，用来查看、排序本机目录，并把文件路径或图片附件送入聊天草稿。

这是什么¶

一句话定位：DSH 客户端插件，给 web 版 DSH 会话右侧加一个全盘文件浏览面板。

它解决的是“从聊天界面快速找到本机文件，并把路径交给 Agent”的入口问题。插件浏览的是 host 进程所在机器的磁盘，只对 web 版 harness 有意义。

核心功能¶

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

安装与启用¶

先确认目标 profile。下面命令用于把插件安装到指定 DSH profile：

dsh plugin --profile <目标profile> add "dsh-file-browser@file:<本目录绝对路径>"

如果已经打出 tarball，也可以用 tarball 安装：

dsh plugin --profile <目标profile> add ./dsh-file-browser-0.1.0.tgz

安装后，用下面命令确认插件已注册，并重启对应 DSH 实例：

dsh plugin --profile <目标profile> list
dsh --profile <目标profile> --dump-config
dsh --profile <目标profile>

已运行的实例需要重启后才生效。

开发期如果用 --patch 指向构建产物，源码路径条目没有可解析的 package.json，client 半不会加载。本地联调 client 半时，建议使用上面的 dsh plugin add 方式安装。

典型用法¶

会话头部出现“文件”按钮后，点击它，右端会出现文件浏览栏。

在目录列表中，可以切换名称、大小、修改时间排序，并切换升序、降序。超过每层 1000 条时，列表会按当前排序保留最靠前的条目，需要用排序或导航缩小范围。

把文件拖入聊天框：

• 拖入 txt、py 等普通文件，草稿中会插入 `路径`；
• 拖入 png、jpg、jpeg、gif、webp 图片，若大小满足 readMaxBytes，聊天框中出现图片附件；
• 无会话时拖拽会有提示。

行内操作可以直接完成常见动作：

• “发送”：把路径作为消息发给 Agent；
• “插入路径”：把路径写入草稿；
• “复制”：复制路径；
• “打开”：用系统默认应用打开该文件或目录。

兼容与依赖¶

插件按 harness @deepseek-ai/*@0.1.0-rc.6 的实际 API 编写。

已核实的依赖信息：

• 依赖：@deepseek-ai/schemastery ^3.18.1
• peer 依赖：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-web ^0.1.0-rc.6、react ^18.2.0

安全与限制¶

这个插件会读取 host 进程所在机器上的文件系统，并以当前 DSH 进程权限运行。安装前应检查源码、许可证和运行环境。

需要注意：

• 它仅对 web 版 harness 有意义。
• 浏览的是 host 进程所在机器的磁盘，不是浏览器所在机器的本地磁盘。
• 拖拽默认把路径写进草稿，而不是把任意二进制上传为附件；DSH 会话只有图片附件语义，其他文件通常由 Agent 的 fs 工具按路径读取。
• 目录大小不递归统计，显示为 —；目录在按大小排序时按名称排序。
• 隐藏文件按 dot 前缀判断，与 harness 既有约定一致；面板内可开关显示隐藏文件。
• 插件路由不在 /api 信任围栏内，因此执行 Host 头 loopback 校验，支持 127.0.0.1、localhost、[::1]，可用 trustedHosts 扩展。
• 路由只接受 GET，不设 CORS，并设置 Cache-Control: no-store。
• 如果 harness 以 LAN 地址访问且 Host 头不是 loopback，需要在 trustedHosts 中列明该 Host，否则文件面板相关请求会返回 403。

结尾¶

dsh-file-browser 的价值比较具体：给 web 版 DSH 会话提供一个本机文件入口，让 Agent 更容易拿到明确的路径或图片附件。适合需要频繁让 Agent 处理本机文件的开发者使用。

GitHub：https://github.com/Clearchenpro/dsh-file-browser
社区目录：https://www.skillhub.cn/plugins/Clearchenpro/dsh-file-browser