工作区文件浏览器dgadelha1/dsh-explorer-plugin

dsh-explorer-plugin

DSH 文件浏览器 — 工作区文件树 + 带 VS Code 真实 TextMate 语法的 Monaco 编辑器，内嵌于 DeepSeek Harness 的 Web GUI 中。

版本 许可证 网站

- 作者： dgadelha1
- 仓库： https://github.com/dgadelha1/dsh-explorer-plugin
- 许可证： MIT
- 网站： https://dgadelha1.github.io/dsh-explorer-plugin/
- 相关文档： 安装指南（脚本） · 技术规范（葡语） · 规范（英语） · 营销摘要（葡语） · 营销（英语）

这是什么

这是一个 DeepSeek Harness (DSH) 插件，为 Web GUI 添加了 VS Code 风格的文件浏览器 + 代码编辑器面板：会话工作区文件树，支持完整的 CRUD 操作；Monaco 编辑器，支持多标签页；使用 VS Code 真实 TextMate 语法进行语法高亮（28 种语言）；Seti + codicon 图标主题；Dark+/Light+ 主题；与智能体集成（“分析”/“修复”快捷操作）；以及跟随 GUI 的语言区域（pt/en/zh）。

该面板作为应用网格的真实列嵌入——可打开/关闭、调整聊天区域大小、可折叠、可调整大小、可移动（左侧/右侧）。

File Explorer 面板 + 带 TextMate 高亮的 Monaco 编辑器截图，内嵌于 DSH Web GUI 中

功能

- 📂 完整的浏览器：打开、创建、重命名、复制、移动和删除文件/文件夹；按需加载；可选显示隐藏文件
- ✏️ Monaco 编辑器：行号、标签页、撤销/重做、带外部冲突检测的 Ctrl+S、可选自动换行、大文件（最大 50 MB）和二进制文件处理
- 🎨 VS Code 真实 TextMate 高亮，支持 28 种语言 + 跟随 GUI 主题的 Dark+/Light+ 主题
- 🔄 实时监视器（SSE）：当智能体创建/编辑文件时，文件树自动更新
- ⚡ 快捷操作：“分析”/“修复”会向智能体发送指令，要求分析文件、给出报告/诊断，并在修改前请求确认（未经批准不会更改任何内容）
- 🌐 多语言：pt / en / zh，跟随 GUI 的语言区域
- 🛡️ 安全性：所有操作都限制在会话工作区内（沙箱）；防止路径遍历和符号链接逃逸；根目录在服务端验证

完整细节见规范（SPEC.md）。

要求

| 要求 | 版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 0.1.0-rc.7（已测试） | PATH 中可用 dsh CLI |
| pnpm | ≥ 8（已用 9.15.9 测试） | dsh plugin 命令需要在 PATH 中可用 |
| Node.js | ≥ 20 | 由服务端部分使用（递归 fs.watch） |
⚠️ 在此工作区中，pnpm 不在系统 PATH 中。请使用本地 shim（.bin/pnpm），在以下命令中为 PATH 添加前缀：
PATH="$PWD/.bin:$PATH" dsh plugin ...

npm/pnpm 的缓存位于工作区内（.npm-cache），因为 ~/.npm 处于只读挂载状态。

安装（经过验证的分步指南）

以下说明已针对 DSH 0.1.0-rc.7 + pnpm 9.15.9 进行了端到端测试。dsh plugin 命令会将参数转发给在 profile 目录（$DSH_HOME/profiles/）内运行的 pnpm，安装该包，并自动协调 profile 的 dsh.profile.bundles 列表。

快速安装（现成脚本）

以下脚本自动化了本节中的步骤 1–2，并打印出步骤 3：它们会验证前置条件（node、dsh 和 pnpm —— 当 pnpm 不在 PATH 中时使用本地副本 .pnpm-home/），执行 dsh plugin add -w，并展示如何重启 dsh web。

| 平台 | 安装 | 验证 | 移除 |
|---|---|---|---|
| Windows | scripts\install.bat | scripts\install.bat --check | scripts\install.bat --remove |
| Linux | scripts/install.sh | scripts/install.sh --check | scripts/install.sh --remove |
| macOS | scripts/install-macos.sh | scripts/install-macos.sh --check | scripts/install-macos.sh --remove |

Profile 可通过 DSH_PROFILE 配置（默认为 web）。详细信息、环境变量和故障排除请参阅 INSTALL.md。

⚠️ Windows： dsh（npm shim）必须在 .bat 内使用 call 调用 —— 脚本已经这样做了。验证已端到端完成：实际安装、bundles 协调以及移除（DSH 0.1.1-rc.2 + pnpm 9.15.9，通过 .pnpm-home/）。

步骤 1 —（可选）确保运行时资源

资源（vendor/ —— Monaco、Oniguruma、语法、主题、图标）已提交到仓库中：全新克隆就已包含所有内容，不需要此步骤。

仅当你想要将资源更新/重新 vendor 化到固定版本（需要网络）时，才执行 node scripts/vendor.mjs：

node scripts/vendor.mjs

步骤 2 — 将插件安装到 web profile

从插件的 checkout 目录中：

dsh plugin --profile web add -w .

或者，从任意目录使用绝对路径：

dsh plugin --profile web add -w /绝对路径/到/dsh-explorer-plugin

⚠️ -w 标志是必需的。 没有它，pnpm（≥ 9）会失败并报错 ERR_PNPM_ADDING_TO_ROOT：profile 是一个 workspace root，pnpm 要求对 root 的安装必须通过 -w/--workspace-root 显式声明。以下是你在没有该标志时会看到的错误示例：
ERR_PNPM_ADDING_TO_ROOT  Running this command will add the dependency to the
workspace root, which might not be what you want - if you really meant it, make
it explicit by running this command again with the -w flag (or --workspace-root).

以下是幕后发生的事情（已在 dsh CLI 的源代码和实际测试中验证）：

1. 首次使用：profile 会在 $DSH_HOME/profiles/web 中初始化（创建 package.json、cordis.patch.yml、pnpm-workspace.yaml，其中包含模板的 bundles）。
2. pnpm add 在 profile 目录中运行；相对路径（.、../plugin）会锚定到你调用 dsh 时所在的目录——因此 add -w . 在 checkout 内部可以正常工作。
3. 协调：由于该包在 package.json 中声明了 dsh.bundle.patch，它会自动被添加到 profile 的 dsh.profile.bundles 列表中。

$DSH_HOME/profiles/web/package.json 中的预期结果：

{
"name": "dsh-profile-web",
"private": true,
"dependencies": {
"dsh-explorer-plugin": "link:/caminho/absoluto/para/dsh-explorer-plugin"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-explorer-plugin"   // ← adicionado automaticamente
]
}
}
}

第 3 步 — 重启 dsh web

插件扫描和 loader 的组装发生在启动时——需要重启 Web 服务器，新的 bundle 才能进入层级树：

pare o dsh web atual e suba novamente
(neste ambiente, o script do projeto faz isso de forma destacada):
scripts/restart-web.sh

🔄 仅客户端的更改（lib/client.js、vendor/）会以 Cache-Control: no-cache 实时提供——这种情况下只需刷新浏览器页面，无需重启。

第 4 步 — 验证

1. 打开 DSH 的 GUI（例如 http://127.0.0.1:3080）。
2. File Explorer 面板应出现在侧边（可折叠/可在左右之间移动）。

dsh-explorer-plugin instalado na GUI do DSH — painel File Explorer em uso

3. 有活动会话时，树会显示工作区；没有会话时，会出现“打开文件夹”流程。

Plugin instalado na GUI do DSH — painel File Explorer na lateral

移除方法

dsh plugin --profile web remove dsh-explorer-plugin

协调过程会自动将该包从 dsh.profile.bundles 列表中移除。随后重启 dsh web。

快速使用

| 操作 | 方法 |
|---|---|
| 打开/关闭面板 | 屏幕边缘的切换按钮 |
| 移动面板 | 翻转按钮（左/右） |
| 调整大小 | 拖动面板边缘 / 树-编辑器分隔条 |
| 新建文件/文件夹、复制、重命名、移动、删除 | 树项目悬停时的操作 |
| 保存 | Ctrl+S（带外部冲突检测） |
| 关闭标签页 | 标签页上的 ×、中键点击或 Ctrl+W |
| 用 agent 分析 / 修复 | 编辑器状态栏中的 Analisar / Corrigir 按钮（agent 会分析、展示报告/诊断，并在修改前请求确认） |
| 切换自动换行 | 状态栏中的 Quebra 按钮 |

项目结构

dsh-explorer-plugin/
├── package.json            # 元数据 + dsh.bundle.patch + dsh.client + exports
├── cordis.patch.yml        # bundle 补丁层（插入服务端插件）
├── LICENSE                 # MIT
├── INSTALL.md              # 安装脚本指南（用法、模式、故障排除）
├── SPEC.md / SPEC.en.md    # 技术规范（葡/英）
├── MARKETING.md / MARKETING.en.md  # 营销摘要（葡/英）
├── lib/
│   ├── index.js            # 服务端插件（ESM）：RPC、静态路由、SSE/watcher
│   └── client.js           # 客户端 bundle（__ModuleLoader__ 格式）——无需构建
├── src/                    # 源码副本（通过 ./src/* 导出）；与 lib/ 同步
├── scripts/
│   ├── install.bat         # Windows 安装程序（cmd）：--check / --remove / --help
│   ├── install.sh          # Linux 安装程序（POSIX sh）：--check / --remove / --help
│   ├── install-macos.sh    # macOS 安装程序（bash）：--check / --remove / --help
│   ├── vendor.mjs          # 下载资源到 vendor/（幂等，版本固定）
│   ├── merge-themes.mjs    # JSONC → 严格 JSON + 合并主题的 include 链
│   ├── sync.mjs            # 复制 src/ → lib/（--check 在二者不一致时失败；在 prepack 中运行）
│   ├── server-test.mjs     # 服务端回归测试
│   ├── smoke-client.cjs    # bundle 冒烟测试（在 Node 中 stub loader）
│   ├── syntax-test-driver.cjs  # TextMate 管道的无头测试（Puppeteer + Firefox）
│   └── restart-web.sh      # 重启 dsh web（在此环境中很有用）
└── vendor/                 # 运行时提供的资源（提交到仓库）
├── monaco/             # monaco-editor（AMD 最小构建）
├── onig/               # vscode-oniguruma（onig.wasm + loader）
├── textmate/           # vscode-textmate
├── grammars/           # 28 个官方 .tmLanguage.json 语法 + manifest
├── themes/             # dark_plus.json / light_plus.json（严格 JSON）
├── codicon/            # codicon 字体（UI/文件夹）
└── seti/               # seti 字体 + 图标主题（文件）

开发

该项目没有构建步骤：src/ 是唯一来源，lib/ 由脚本同步（在 prepack 中作为门禁）。

同步 src/ → lib/
node scripts/sync.mjs

检查 src/ 和 lib/ 是否不一致（CI）
node scripts/sync.mjs --check

测试（服务端回归 + bundle 冒烟测试）
npm test

重新 vendor 资源（需要网络）
node scripts/vendor.mjs

TextMate 管道的无头测试（scripts/syntax-test-driver.cjs，Puppeteer + Firefox）不属于 npm test —— 需要下载浏览器。

架构概要
- 服务端（lib/index.js，Cordis 插件）：RPC 通道 /explorer，带有 fs/ 端点（stat、list、read、write、create、rename、move、delete）——直接读写，不经过 LLM；静态路由 /explorer-assets（Monaco、语法、主题）；SSE /explorer/events，带有 fs.watch 监视器（心跳、自动恢复且不会导致进程崩溃）。
- 客户端（lib/client.js）：手写的 bundle，格式为 window.__ModuleLoader__.load({id, factory})，仅依赖 react；其余部分来自 DSH 运行时服务（slots、layout、connection、sessions、workspaces、locale、theme）。颜色 100% 通过设计系统令牌（--dsw-）。

安全

- 限制在工作区内：path.resolve + 前缀校验；对最深层祖先的 realpath 阻止通过符号链接逃逸
- 每次调用都在服务端验证根目录：仅允许活跃会话的规范 cwd 或工作区注册表中的路径（不能通过 loopback API 访问 /、/etc、~）
- CSRF 由平台保护（isTrustedApiRequest）；二进制文件检测；负载限制（内联 2 MB，读/写 50 MB）

发布（GitHub Pages）

docs/index.html 中的落地页是自包含的（纯 HTML/CSS，无需构建，无外部依赖），可发布到 GitHub Pages：

1. 推送代码和发布标签
git push -u origin main --tags

2. 在 GitHub 上：Settings → Pages → Source → "Deploy from a branch"
branch: main · 文件夹: /docs  （docs/ 中的 .nojekyll 可跳过 Jekyll）

3. 完成——页面位于：
https://dgadelha1.github.io/dsh-explorer-plugin/

- 更新： 只需推送到 main——GitHub Pages 会自动重新发布。
- 截图： 通过相对路径引用（./screenshot-0.20.png）；如需更换，请替换 docs/ 中的 PNG（页面框架会自动适应图片尺寸）。
- 版本： 保持徽章 v0.2.0（docs/index.html 的页眉和页脚）与 package.json 同步。
- 本地验证： node scripts/render-check.cjs 会在无头 Firefox 中打开页面，并验证加载、图片和框架适配（需要 puppeteer-core + Firefox）。

故障排除

| 症状 | 原因 / 解决方案 |
|---|---|
| 'pnpm' 无法识别 / pnpm not found on PATH | 脚本会自动使用本地 shim .pnpm-home/；如果没有，请安装 pnpm（corepack enable / npm install -g pnpm） |
| 未找到 CLI 'dsh' | 使用 npm install -g @deepseek-ai/dsh 安装（在 Windows 上，脚本还会查找 %APPDATA%\npm\dsh.cmd） |
| ERR_PNPM_ADDING_TO_ROOT | 缺少 -w 标志：请使用 dsh plugin --profile web add -w  |
| 安装后面板未出现 | 重启 dsh web（bundle 组合在启动时进行）并重新加载页面 |
| 编辑器没有颜色 | TextMate provider 会在语法加载后注册；如果仍然存在，请重新加载页面（资源带有 no-cache） |
| 树不会反映代理的文件 | 检查监视器：递归 fs.watch 需要 Node ≥ 20；SSE 有 25 秒的心跳 |
| 工作区外的写入被阻止 | 预期行为（沙箱）——服务器以 bad-request 拒绝 |

许可证

MIT — 版权所有 (c) 2026 dgadelha1。可自由用于个人和商业用途，但须保留版权声明。本软件按“原样”提供，不附带任何担保。请参阅完整的 LICENSE。