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"
  }
}

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 [email protected]: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

dsh-file-browser

安装

源码

标签

作者

说明文档

dsh-file-browser

✨ 功能

📦 安装

🤖 方式一:把这段话发给你的 AI(最简单)

👨💻 方式二:手动安装

✅ 验证安装

🧭 使用

🏗 架构

🔧 开发

❓ FAQ

📄 License