dsh-file-browser
给 DeepSeek Harness (DSH) 的可视化文件浏览插件。不用启动桌面环境,直接在网页里浏览当前对话工作目录的文件树、阅读代码、选中文本向 AI 提问。
设计初衷:在平板 / 低功耗设备上通过网页使用 DSH 时,不启动 xfce 等桌面环境也能随时查看项目文件。
✨ 功能
- 📁 会话头部按钮:右上角图标按钮,点击从右侧滑出文件浏览抽屉(无阴影、可拖动调宽)
- 🌲 文件树:目录懒加载展开、目录/文件图标、git 状态徽标(
M 修改 / A ?? 新增 / D 删除)
- 📑 Tab 阅读:
- 单击文件 = 替换当前 Tab(不堆积标签)
- 双击文件 = 新增一个 Tab
- 点击已打开的文件 = 直接切换
- 💬 选中提问:在文件内容里选中文本 → 点「💬 提问」→ 输入问题 → 追加到聊天输入框。自动携带文件路径、起止行号、选中内容,支持连续追加多个问题,最后自己回车发送
- ↔ 双拖动手柄:抽屉左边缘调总宽度,中间分隔条调文件树/内容区比例(鼠标、触摸通用)
- 💾 跨会话进度:按项目目录分片保存浏览状态(展开目录、打开的 Tab),切换会话自动跟随、切回自动恢复
- 🔒 安全:只允许浏览当前对话工作目录;
../ 路径穿越与符号链接逃逸均被拦截(含 realpath 复核)
- 🛡 防护:二进制不预览、>5MB 拒读、超大文本截断提示、超大 git 仓库限量
📦 安装
🤖 方式一:把这段话发给你的 AI(最简单)
复制下面整段,发给你的 AI 助手,让它代你安装:
请帮我在 DeepSeek Harness 中安装 npm 包 dsh-file-browser 插件。
安装步骤:
1. 找到 DSH 的 profile 目录(通常是 ~/.dsh/profiles/web/,以 dsh 实际启动时使用的 profile 为准),
打开其中的 package.json 文件;
2. 在 "dsh" 字段下的 "profile.bundles" 数组末尾追加 "dsh-file-browser"
(没有这个数组就新建,保留原有条目);
3. 在 "dependencies" 对象中追加 "dsh-file-browser": "^0.1.0";
4. 在该 profile 目录下执行 pnpm install;
5. 重启 dsh web 进程;
6. 完成后告诉我,并说明如何验证(刷新网页后,会话右上角应出现 📁 按钮)。
👨💻 方式二:手动安装
- 找到 DSH 的 profile 目录(通常为
~/.dsh/profiles/web/),打开它的 package.json;
- 改两处:
{
"dsh": {
"profile": {
"bundles": [
"…原有的 bundle 保持不变…",
"dsh-file-browser"
]
}
},
"dependencies": {
"dsh-file-browser": "^0.1.0"
}
}
- 在 profile 目录下执行安装:
pnpm install
- 重启 DSH:
# 停掉正在运行的 dsh web,再重新启动
dsh web
- 刷新网页,右上角出现 📁 按钮即安装成功。
本地开发/调试也可以把依赖换成 "dsh-file-browser": "file:/path/to/dsh-file-browser",其余步骤相同。
✅ 验证安装
- 界面:刷新网页后,会话右上角出现 📁 图标按钮(在日志下载按钮旁)
- 接口:命令行执行,返回 JSON 即正常:
curl "http://127.0.0.1:3080/api/file-browser/list?cwd=$HOME"
- 故障排查:
- 按钮没出现 → 确认 bundles 数组里加了
"dsh-file-browser" 且 pnpm install 成功,然后重启了进程并强制刷新网页(Ctrl+Shift+R)
- 点按钮树是空的 → 确认 host 端已重启(host 代码只在进程启动时加载)
🧭 使用
| 操作 | 效果 |
|---|
| 点 📁 | 打开/关闭文件浏览抽屉 |
| 点目录 | 展开 / 收起子目录 |
| 单击文件 | 替换当前 Tab 打开 |
| 双击文件 | 新增 Tab 打开 |
| 选中代码 → 💬 提问 | 输入问题,追加到聊天输入框 |
| 拖抽屉左边缘 | 调整抽屉宽度 |
| 拖中间分隔条 | 调整文件树/内容区比例 |
| 切换左侧会话 | 浏览进度自动跟随新项目 |
🏗 架构
浏览器(client 半身) 电脑(host 半身)
┌──────────────────────┐ HTTP ┌───────────────────────────┐
│ 按钮(header.utilities)│ ──────────→ │ GET /api/file-browser/list │
│ 抽屉(shell.overlay) │ ←────────── │ GET /api/file-browser/read │
│ 状态仓库(按 cwd 分片) │ JSON │ GET /api/file-browser/git- │
└──────────────────────┘ │ status │
└───────────────────────────┘
- host 端(
lib/index.js):3 个只读接口 + 路径安全校验(工作区锁定、resolveInside 字符串检查 + realpath 符号链接复核)
- client 端(
lib/client.js):注册 conversation.session.header.utilities(按钮)与 shell.overlay(抽屉)两个官方 Slot;浏览状态按项目目录分片存储(带 LRU 上限),组件卸载不丢失
- 通信:浏览器
fetch 直连 host HTTP 接口,无需额外中间层
🔧 开发
git clone git@github.com:Liuxin4950/dsh-file-browser.git
cd dsh-file-browser
- 改 host 端(
lib/index.js)后需重启 DSH 进程
- 改 client 端(
lib/client.js)后只需刷新网页(DSH 的 bundle rev 机制自动生效)
- 目录结构:插件包 = 一个 package.json + 一个 cordis.patch.yml + lib 下两个 js 文件,零第三方依赖
❓ FAQ
为什么文件旁没有 git 徽标?
只有"当前目录是 git 仓库"且"有未提交变更"的文件才显示徽标,干净仓库不显示任何标记。
为什么是浮层抽屉而不是分栏?
DSH 布局是固定三栏,没有"对话区旁再加一栏"的官方插槽,浮层抽屉(方案 A)是最稳定、侵入性最小的实现。
单击文件为什么有 200ms 延迟?
用于区分单击(替换 Tab)与双击(新增 Tab),保证双击时不会先触发两次单击。
📄 License
MIT
