adegams/dsh-explore-button

🧭 dsh-explore-button

Version
License
Node
[DSH]()

插件 DSH (DeepSeek Harness) — 浮动栏 文件夹浏览器，带模态文件浏览器。

满足许多用户的需求：直接从 DSH Web 界面可视化浏览文件夹、读取并修改文件，无需通过 shell 命令。

✨ 功能

- 浮动快捷访问栏位于右上角，与 Chat / Trajectory 标签页对齐（top: 52px）。
- 可配置的项目文件夹快捷方式（/var/www、/var/www/sieasset4all 等）。
- 点击快捷方式后打开模态 / 文件浏览器：
- 读取并显示文件夹的树形结构（文件 + 子文件夹）。
- 通过面包屑导航（返回上级）以及点击子文件夹导航。
- 点击即可打开文件：在文本查看器中显示其内容（白色背景、深色文字）。
- ✏️ 修改 + 💾 保存（v1.2.0 新增）：
- 任何文本文件上的 « ✏️ 修改 » 按钮 → 在大型等宽文本区域中编辑。
- « 💾 保存 » 将文件重新写入磁盘；查看器自动重新加载更新后的内容（带字节数的确认提示）。
- « ↩ 取消 » 返回查看器而不写入。
- 检测二进制文件（显示专用消息，不提供编辑）。
- 操作按钮：↩ 返回、📋 复制路径、💬 发送到聊天。
- DSH 聊天中可点击的文件路径：消息中提到的文件引用
（例如 AGENTS.md、database/seeders/CatalogueUpdate.php）
会被识别（蓝色下划线），点击后直接在查看器中打开。
- 通过 MutationObserver 检测（对新消息也有效）。
- 从项目根目录 /var/www/sieasset4all 解析；任何 /var/www 之外的路径都会被拒绝。
- 自动在子文件夹中搜索：如果文件在根目录不存在，插件会自行找到它（例如 session_memory.md → .agent/workflows/session_memory.md），通过 /api/fs/resolve（v1.3.0）。
- 非侵入式方法：绝不拦截 GUI 的其他点击。
- ✓ 任务（task edit）（v1.5.0 新增）：
- 浮动栏中的 « ✓ 任务 » 项 → 编辑项目 TODO.md 文件的模态框。
- ➕ 添加任务（输入框 + 按钮或回车键）。
- ☑️ 划掉已完成任务（点击复选框：- [x] → 文字加删除线）或恢复它。
- ✕ 删除任务。
- 在 文件 TODO.md 中持久化，使用 markdown 复选框格式（- [ ] / - [x]）——可在查看器中读取和修改；« 📂 Ouvrir le fichier » 按钮用于手动查看/编辑。
- 计数器 « N tâche(s) — X à faire »；每次操作都有确认提示。
- 2 个新端点：GET /api/tasks/read（列表）和 POST /api/tasks/save（重写，若文件不存在则创建）。
- 🕒 已修改文件监控器（v1.4.0 新增）：
- 浮动栏中的 « 🕒 Monitor » 项 → 弹出模态框，列出项目中已修改的文件
（/var/www/sieasset4all），按从最新到最旧排序，
并显示 相对时间（« il y a 2 min »、« hier »、日期/时间）和大小。
- 时间段筛选：1 h / 24 h / 7 j / Tout。
- « 🔴 Suivi » 按钮：每 5 s 自动监控——每次变更时提示
« 🔔 N fichier(s) modifié(s) » + 在列表顶部插入。
- 点击文件 → 在查看器中打开（使用现有的 view/edit/save）。
- 新端点 GET /api/fs/recent?root=&since=&limit=&depth=：对目录树进行
有界且安全的遍历（忽略 node_modules/vendor/… 等大型文件夹，
跳过符号链接），结果在服务端缓存 4 秒以吸收轮询请求。
- 4 个服务端 API 端点（不触碰 DSH 的 directory-picker）：

| 方法 | 路由 | 描述 |
|---|---|---|
| GET | /api/fs/list?path= | JSON 列表（名称、类型、大小、隐藏、截断至 1000 条） |
| GET | /api/fs/read?path= | 以 UTF-8 返回文件内容 + 行数 |
| GET | /api/fs/resolve?name= | 在项目中搜索文件（优先 doc 文件夹，有界遍历）→ { found, path, via } |
| GET | /api/fs/recent?root=&since=&limit= | 已修改文件（有界遍历，4 秒缓存）→ { root, scannedAt, count, files: [{ path, mtime, size }] } |
| POST | /api/fs/write | Body { "path": "", "content": "" } → { ok, path, bytes } |
| GET | /api/tasks/read | TODO 任务 → { path, content, exists }（markdown 复选框） |
| POST | /api/tasks/save | Body { "content": "" } → 重写 TODO.md（不存在则创建）→ { ok, path, bytes } |

📦 安装

快速方法（install.sh）

Depuis le dossier du plugin
./install.sh               # installe dans le profil DSH "web"
PROFILE=mon-profil ./install.sh   # autre profil

然后 重启 DSH 服务器：

pkill -f 'dsh web'  &&  dsh web

⚠️ Gotcha：请从没有项目 .env 的目录启动 dsh（例如 cd ~）——
如果当前 .env 定义了 DEEPSEEK_BASE_URL 等保留变量，
dsh 会拒绝启动。

手动方法

1. 将 explore-button.js 复制到 ~/.dsh/profiles//plugins/。
2. 确保 ~/.dsh/profiles//plugins/package.json 存在，内容为 {"type":"module"}。
3. 在 ~/.dsh/profiles//cordis.patch.yml 中添加：

- insert:
- id: fs-browser
name: './plugins/explore-button.js'

⚠️ 不要在名称中添加 ?ver= / ?v=：自
@deepseek-ai/dsh 0.1.x 起，Cordis 加载器会对查询字符串进行 URL 编码
（explore-button.js%3Fver=…），并尝试导入一个不存在的文件
（启动时出现 ERR_MODULE_NOT_FOUND）。无论如何，该模块在每次服务器启动时
都会被重新导入：更新文件后，只需重启 dsh web 即可。

⚙️ 快捷方式配置

修改 explore-button.js 顶部的 QUICK_PATHS 数组——默认条目如下：

const QUICK_PATHS = [
{ label: "🏠 /var/www",      path: "/var/www" },
{ label: "🔧 sieasset4all",  path: "/var/www/sieasset4all" },
{ label: "🔐 apipki",        path: "/var/www/apipki" },
{ label: "⚙️  core",         path: "/var/www/core" },
{ label: "🌐 main",          path: "/var/www/main" },
{ label: "🔔 notifications", path: "/var/www/notifications" },
{ label: "📲 mobileedr",     path: "/var/www/mobileedr" },
{ label: "🔍 recherche",     path: "SEARCH" },
];

特殊值 "SEARCH" 会打开一个自由搜索快捷方式。

🗂️ 包内容

dsh-explore-button/
├── explore-button.js     # 插件（ESM 源码）
├── install.sh            # 安装脚本
├── package.json          # ESM 导出 + 元数据
└── README.md             # 本文件

🛠️ 技术原理

- 该插件监听 webserver/index-inject 事件，在每次渲染时将 CSS、HTML（工具栏 + 模态框）和 JS 注入到 index.html 中。
- 它在 DSH Web 服务器上注册三个 HTTP 路由（ctx.webServer.register）：/api/fs/list、/api/fs/read 和 /api/fs/write（按路径分发，方法由处理器管理——非 POST 时返回 405）。
- 无额外依赖：使用 Node 原生模块（node:fs/promises、node:path、node:os）。
- POST /api/fs/write 仅写入已存在的文件（绝不创建），采用 UTF-8 编码。

🔒 安全性——启用编辑前必读

- POST /api/fs/write 会覆盖已存在的文件且不进行备份：您保存的内容会
立即替换磁盘上的内容（在代码仓库场景下，可使用 SVN/Git 日志进行回滚）。
- 该端点与读取端点具有相同的信任级别：
它以 DSH 进程的权限运行。请勿在多用户或公共服务器上
暴露它，除非有访问控制。
- 二进制文件永远不会被提供用于编辑。
- 若要将写入锁定在特定区域（例如仅 /var/www），
请在 handleWriteFile 中添加防护（resolve(...) 根路径 → 预期前缀）。

📋 更新日志

v1.4.1 (2026-09-03)
- 🐛 关键修复：注入的 JS 中的撇号（\'）被吞掉
服务器端模板字面量 → 在浏览器中脚本无效（插件点击后失效）。
已替换为弯引号 ’，注入文本通过执行测试验证
（加载 + 点击 « Monitor »）。
- 🏷️ 项目标签重命名为 « 🕒 Monitor »（原为 « Modifiés »）。

v1.4.0 (2026-09-03)
- 🕒 已修改文件监控：工具栏中的 « Monitor » 项目，列表视图带相对时间 + 大小，筛选 1 小时 / 24 小时 / 7 天 / 全部，每 5 秒自动跟踪 🔴（toast + 插入到顶部），在查看器中直接打开，端点 GET /api/fs/recent（有界遍历 + 4 秒缓存）。

v1.3.0 (2026-09-03)
- 🔎 文件路径自动解析：根目录中找不到引用 → 通过新端点 GET /api/fs/resolve 在项目中进行有界搜索（优先文档文件夹）→ toast « 📂 Résolu » + 直接打开正确的文件（例如 session_memory.md → .agent/workflows/session_memory.md）。

v1.2.0 (2026-09-03)
- ✏️ 从查看器编辑 + 保存文本文件（修改 / 保存 / 取消按钮）。
- 高编辑区（最小 1080 px），带 toast 确认（已写入字节数）和自动重新加载。
- 新端点 POST /api/fs/write。

v1.1.0
- 浮动工具栏，模态文件浏览器，只读查看器，端点 GET /api/fs/list 和 GET /api/fs/read。
- 聊天中可点击的文件路径（MutationObserver）。

❓ 依赖 / 兼容性

- DSH Web profile（在某个端口上提供的 Web GUI）。
- Node.js ≥ 18（仅原生模块 — 无需 npm install）。
- 已在 DSH 服务器 dsh web（web profile）、Node 24 上测试。

📄 许可证

MIT — 参见仓库中的 LICENSE 文件。可自由使用、修改和再分发（需署名）。