前言¶

在 DSH 的插件体系里，agent 经常需要访问本地文件。已有做法中，dsh 自带的文件工具通常作用于 dsh 宿主所在机器；如果 dsh 部署在远程环境，而用户浏览器在另一台机器上，agent 就无法直接操作浏览器所在机器的本地文件。

dsh-browser-fs 用来补上这个缺口：它让 dsh web 页面里的 agent 通过 File System Access API 获得用户对本地目录的授权，并通过插件提供的模型工具完成目录列表、文本读取和文本写入。

这是什么¶

whitefirer/dsh-browser-fs 是一个面向 dsh web 端面的客户端插件，核心目标是让 dsh 的 agent 读写浏览器所在机器的本地文件。

它主要做三件事：

• 注册 browser_fs_list、browser_fs_read、browser_fs_write 三个模型工具；
• 插件自建 WebSocket 通道，把工具调用转发到持有授权句柄的浏览器标签执行；
• 浏览器端在 shell.overlay 层注册浮动卡片，显示连接/授权状态并管理目录授权。

许可证为 MIT。仓库地址：

https://github.com/whitefirer/dsh-browser-fs

核心功能¶

授权目录与模型工具¶

插件允许用户通过 File System Access API 授权一个本地目录。完整模式下，选择目录需要 readwrite 权限。

授权后，agent 可以调用下面三个工具：

browser_fs_list { path?, recursive? }
browser_fs_read { path, maxBytes? }
browser_fs_write { path, content }

其中：

• browser_fs_list 用于列目录；
• browser_fs_read 用于读文本文件；
• browser_fs_write 用于写文本文件。

browser_fs_read 默认上限为 256 KiB，截断时会标注。agent 工具仅支持 UTF-8 文本读写，二进制写入不在范围内。

卡片浏览与文件预览¶

浏览器端的 browser-fs 卡片可以提供授权目录内容树浏览，并支持文件名/路径搜索、复制相对路径。

在目录树中点文件名可以打开预览窗，支持图片与文本预览。文本预览只取前 64KB。图片超过 8MB 时不拉取。

完整模式下，文本预览可编辑并保存。文本/代码预览支持语法着色，highlight.js 采用懒加载。

图片仅在卡片内预览，不提供 agent 工具读取二进制内容的完整支持。

多设备与连接状态¶

多台设备可以各自授权各自的本机目录。host 半维护执行者名单，并把工具调用路由到合适的浏览器标签执行。

客户端断线时会指数退避重连，并支持 abort 与浏览器 cancel 帧。

兼容模式¶

File System Access API 要求 HTTPS 或 localhost 安全上下文。非安全上下文下，插件会自动进入兼容模式。

完整模式与兼容模式的能力差异如下：

安装与启用¶

先执行安装命令：

dsh plugin --profile web add dsh-browser-fs

然后重启 dsh，使插件生效。

本地开发或从源码安装时，需要先构建，再用 file: 路径重装：

npm run build
dsh plugin --profile web add file:/abs/path/to/dsh-browser-fs

完成后重启 dsh。

安装时注意两点：

• host 半以 peerDependency 依赖 @deepseek-ai/dsh-tools；
• client 半默认固定连接 WebSocket 路径 /browser-fs/ws。如果 host 半修改 wsPath，client 半的 DEFAULT_WS_PATH 需要同步修改并重新 build。

典型用法¶

下面是一个常见流程。

1. 打开 dsh web 页面，在右下角的 browser-fs 卡片点击“授权目录”，选择一个本地目录。
2. 在卡片内浏览授权目录，搜索文件名或路径，并复制相对路径。
3. 让 agent 调用工具操作文件，例如：

browser_fs_list { path: "docs", recursive: true }

browser_fs_read { path: "docs/hello.txt" }

browser_fs_write { path: "docs/hello.txt", content: "hello" }

4. 在目录树中点文件名，打开预览窗，查看图片或文本内容。完整模式下可编辑文本并保存。
5. 如果通过局域网或手机经 http 访问，插件会自动进入兼容模式，可使用“选择目录”或“选多个文件”完成只读选择。

若需要完整模式，可以通过以下方式之一获得安全上下文：

• 将访问转发到 localhost；
• 在浏览器中把目标 origin 加入不安全 origin 白名单；
• 部署 HTTPS。

适用场景与注意¶

这个插件适合下面这类场景：

• dsh 部署在远程环境，agent 需要操作浏览器所在机器的本地文件；
• 用户希望授权一个本地目录，而不是把整个宿主文件暴露给 agent；
• 需要在浏览器端看到连接状态、授权状态、目录树和文件预览；
• 多设备各自授权各自本机目录，由 host 侧路由工具调用。

使用前需要注意：

• File System Access API 要求 HTTPS 或 localhost 安全上下文；纯 HTTP 远程访问页面时，授权按钮会报明确错误。
• 浏览器标签必须在线且已授权目录，否则工具调用会立即返回明确错误。
• agent 工具仅支持 UTF-8 文本读写；二进制写入不在范围内。
• browser_fs_read 默认上限为 256 KiB，截断会标注。
• 文本预览只取前 64KB；图片超过 8MB 不拉取。
• 兼容模式只读，无句柄持久化，刷新后需要重新选择。
• 插件以当前 dsh 进程权限运行。安装前应检查源码与许可证。

结尾¶

dsh-browser-fs 的价值在于把浏览器所在机器的本地文件接入 dsh agent 的工具链：用户通过浏览器授权目录，agent 通过明确工具完成目录列表、文本读取和文本写入，浏览器端保留状态卡片、目录浏览与预览能力。

仓库地址：

https://github.com/whitefirer/dsh-browser-fs

目录页线索：

https://www.skillhub.cn/plugins/whitefirer/dsh-browser-fs