前言¶
用 dsh web 做智能体开发时，常有这样的时刻：agent 在工作区里写了一批文件，你想自己翻一翻目录、看一眼日志或截图，而不是让模型逐个描述。常见做法是另起一个静态文件服务——多一个进程、多一个端口要维护；或者退回终端敲 ls，文件一多效率就下来了。
DSH 的理念是「一切皆插件」。下面介绍的 @open-agfs/dsh-agfs 是这个思路下的一个具体实现：它把文件浏览器 Web 应用直接挂在 dsh web 的宿主 webserver 上，不开独立端口，也不起子进程。
这是什么¶
@open-agfs/dsh-agfs 由 openAGFS 维护，MIT 许可证，当前版本 0.1.9。它由三部分组成：
- 由宿主 webserver 提供的 React 前端与 REST API；
- 一个
/dsh-agfs对话框命令； browse_files与read_file两个模型工具。
分工很清楚：人在浏览器里浏览、搜索、预览和整理文件；模型通过工具列出、搜索和读取浏览根下的文本文件。双方面对同一个浏览根，不需要为「看文件」单独起服务。
核心功能¶
文件浏览¶
- 列表与搜索、文本预览（markdown、代码、日志）、图片预览；
- 文件夹的创建、重命名、复制、删除；
- 面包屑导航，逐级点回根目录；
- 视图切换（列表/卡片网格）与三种显示尺寸（窗口面板、整个视图、全屏）；
- 侧边栏提供项目目录、快速访问（Desktop/Downloads/Documents 等）、自定义根目录与驱动器；
- 工具栏搜索支持递归模式，上限 200 条命中。
前端随包离线分发：React/ReactDOM 打包在包内，启动无需 CDN，也不依赖 Babel（图标仍走 cdnjs，见后文已知限制）。
会话联动¶
- 本地打开（仅本地模式）：右下角浮动按钮可在系统文件管理器中打开当前目录；
- 一键 AI 分析（仅本地模式）：右键文件或文件夹输入需求，dsh 会创建工作区并唤醒新会话进行分析。
模型工具¶
插件注册两个模型工具：
browse_files（参数path、keyword、recursive）：列出目录，或按关键字搜索条目名，可选递归；read_file（参数path）：读取浏览器根下的文本文件内容。
有了这两个工具，模型可以直接查看目录结构和文件内容，而不只是文件名。
路径安全与响应头¶
浏览被限制在可浏览根内；strictRoot 开启后执行实路径检查，symlink/junction 逃逸会被拦截并返回 400 envelope；另有 readOnly 只读模式与 remoteMode。响应附带安全头 X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Referrer-Policy: no-referrer。
API 端点位于 ${basePath}/api/file_browser/ 下，路径同样限制在可浏览根内；search 支持 recursive=1，有 200 条命中上限和目录深度上限 5。
安装与启用¶
插件通过 dsh.bundle 一行安装，以 profile layer 激活。Node 版本要求 ^22.19.0 || >=24.0.0。
方式一：对话框安装¶
在 DeepSeek Harness 对话框里直接让 agent 安装，例如：
Install the file-browser plugin
dsh-agfs
agent 会调用 shell 工具执行：
dsh plugin --profile web add @open-agfs/dsh-agfs
这条链路要求 agent 的 shell 工具（bash/pwsh）可用。web profile 默认禁用 shell 工具，需要在 Settings → tools/permissions 里启用，或在 agent 请求批准时放行；不方便开 shell 工具就用方式二。
方式二：CLI 一行安装¶
dsh plugin --profile web add @open-agfs/dsh-agfs
升级到最新版：
dsh plugin --profile web add @open-agfs/dsh-agfs@latest
无论哪种方式，安装后都需要重启 dsh web 才能生效。
源码 overlay（开发调试）¶
从仓库 checkout 出发，可以通过 --patch 挂载源码：
- insert:
- id: dsh-agfs
name: 'file:///absolute/path/to/dsh-agfs/src/index.ts'
然后运行 dsh web --patch ./overlay.yml。
典型用法¶
经过上面的步骤，在对话框运行：
/dsh-agfs
系统默认浏览器会打开文件浏览器并报告 URL；当前会话带工作区目录（session cwd）时，浏览器直接定位到该工作区。
若配置了 openOnCommand: false，这一步只报告 URL，不自动打开浏览器。
配置¶
配置存于 profile 的 user patch 层（$DSH_HOME/profiles/<name>/cordis.patch.yml）：
- id: dsh-agfs
config:
fileRoot: 'D:/projects/my-project'
readOnly: true
常用配置项：
fileRoot：文件浏览器的根目录；readOnly：只读模式；strictRoot：实路径检查，拦截 symlink/junction 逃逸；remoteMode：远程模式；openOnCommand：/dsh-agfs是否自动打开系统默认浏览器。
适用场景与注意事项¶
适合的场景：在 dsh web 里做日常开发、需要人工核对 agent 产出的文件；希望模型具备列目录、搜条目名、读文本文件的能力，而不想为此单独维护一个文件服务。
使用前注意：
- 插件以当前 dsh 进程的权限运行。安装前建议阅读源码和许可证（MIT），确认符合自己的安全要求再装。
- Font Awesome 图标仍从 cdnjs 加载。无网络时应用本身可用（React/ReactDOM 已随包分发），只是没有图标。
- 搜索只匹配条目名，未实现递归内容搜索；递归模式有 200 条命中上限、目录深度上限 5。
- 缩略图直接传输原图，不做缩放。
openOnCommand触发的浏览器在运行 dsh 的主机上打开，对远程客户端来说这个行为可能出乎意料。
结尾¶
简单回顾：@open-agfs/dsh-agfs 把文件浏览器挂进 dsh web 的宿主进程，不开端口、不起子进程；/dsh-agfs 直达当前会话的工作区，browse_files 与 read_file 让模型能直接查看浏览根下的文件。如果你在用 DSH 做开发，值得一试。
- GitHub 仓库：https://github.com/openAGFS/dsh-agfs
- 社区目录收录页：https://www.skillhub.cn/plugins/openAGFS/dsh-agfs（社区独立维护的目录站点，与 DeepSeek / 幻方无官方从属关系）
