前言¶
在 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 安全上下文。非安全上下文下，插件会自动进入兼容模式。
完整模式与兼容模式的能力差异如下：
| 能力 | 完整模式 | 兼容模式 |
|---|---|---|
| 目录选择 | 通过安全上下文下的目录授权 | 提供只读“选择目录”或“选多个文件”能力 |
list / read |
支持 | 支持 |
write |
支持 | 不支持 |
| 授权持久化 | 支持 | 无句柄持久化，刷新后需重新选择 |
安装与启用¶
先执行安装命令：
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。
典型用法¶
下面是一个常见流程。
- 打开 dsh web 页面，在右下角的
browser-fs卡片点击“授权目录”，选择一个本地目录。 - 在卡片内浏览授权目录，搜索文件名或路径，并复制相对路径。
- 让 agent 调用工具操作文件，例如：
browser_fs_list { path: "docs", recursive: true }
browser_fs_read { path: "docs/hello.txt" }
browser_fs_write { path: "docs/hello.txt", content: "hello" }
- 在目录树中点文件名，打开预览窗，查看图片或文本内容。完整模式下可编辑文本并保存。
- 如果通过局域网或手机经
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
