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

dsh-explorer-plugin

DSH File Explorer — 工作区文件树 + Monaco 编辑器，带 VS Code 真实 TextMate 语法，直接跑在 DeepSeek Harness 的 Web GUI 里。

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

这是什么

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

面板作为应用网格中的真实一列嵌入 —— 可开可关，会挤压聊天区，可折叠、可调宽、可移动（左/右）。

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

功能

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

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

环境要求

| 要求 | 版本 | 说明 |
| DeepSeek Harness | 0.2.0-rc.2（已验证） | 命令行 dsh（桌面应用里是 resources\runtime\cli\bin\dsh.cmd） |
| pnpm | ≥ 8（已在 9.15.9 和 11.7.0 上测试） | dsh plugin 命令需要 |
| Node.js | ≥ 20（已在 24.x 上测试） | 服务端部分使用（递归 fs.watch） |
⚠️ 在这个 workspace 里，pnpm 不在系统 PATH 中。请使用本地 shim（.bin/pnpm），在下面的命令前加上 PATH：
PATH="$PWD/.bin:$PATH" dsh plugin ...

npm/pnpm 的缓存放在 workspace 内部（.npm-cache），因为 ~/.npm 是只读挂载。

安装（逐步验证）

下面的说明已经端到端验证过，环境为 DSH 0.2.0-rc.2 + pnpm 11.7.0（Desktop 应用的运行时）。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.2.0-rc.2 + pnpm 11.7.0，Desktop 应用运行时）。

ℹ️ Profile desktop（Desktop/Electron 应用使用的那个）： 由应用自己管理。dsh plugin --profile desktop add -w <路径> 可以正常工作（安装并协调 dsh.profile.bundles），但在这个 profile 下服务器不能通过命令行启动（profile "desktop" is managed exclusively by the Electron application）：要加载插件请重启应用。Profile web 仍可通过 dsh web 重启。

第 1 步 ——（可选）确保运行时资产就位

资产（vendor/ —— Monaco、Oniguruma、语法、主题、图标）已经提交到仓库里：全新 clone 下来就什么都有，不需要这一步。

只有想更新/重新 vendor 资产到锁定版本时才执行 node scripts/vendor.mjs（需要网络）：

node scripts/vendor.mjs

第 2 步 —— 把插件安装到 profile web

在插件的 checkout 目录下执行：

dsh plugin --profile web add -w .

或者在任何目录下，用绝对路径：

dsh plugin --profile web add -w /caminho/absoluto/para/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 命令行源码和实际测试中验证）：

1. 首次使用：profile 在 $DSH_HOME/profiles/web 初始化（创建 package.json、cordis.patch.yml、pnpm-workspace.yaml，其中带上模板的 bundle）。
2. pnpm add 在 profile 目录下运行；相对路径（., ../plugin）锚定在你调用 dsh 时所在的目录 —— 所以在 checkout 里执行 add -w . 是有效的。
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 组装都发生在 boot 阶段 —— 必须重启 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. 有活跃会话时，树会显示 workspace；没有会话时，会出现「打开文件夹」的流程。

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 |
| 用智能体分析 / 修复 | 编辑器状态栏上的 分析 / 修复 按钮（智能体先分析，给出报告/诊断，修改前请求确认） |
| 切换自动换行 | 状态栏上的 换行 按钮 |

项目结构

dsh-explorer-plugin/
├── package.json # metadados + dsh.bundle.patch + dsh.client + exports
├── cordis.patch.yml # camada de patch do bundle (insere o plugin servidor)
├── LICENSE # MIT
├── INSTALL.md # guia dos scripts de instalação (uso, modos, solução de problemas)
├── SPEC.md / SPEC.en.md # especificação técnica (PT/EN)
├── MARKETING.md / MARKETING.en.md # resumo de marketing (PT/EN)
├── lib/
│ ├── index.js # plugin servidor (ESM): RPC, rotas estáticas, SSE/watcher
│ └── client.js # bundle cliente (formato __ModuleLoader__) — sem build ├── src/ # cópias-fonte (exportadas via ./src/); sincronizadas com lib/ ├── scripts/ │ ├── install.bat # instalador Windows (cmd): --check / --remove / --help │ ├── install.sh # instalador Linux (POSIX sh): --check / --remove / --help │ ├── install-macos.sh # instalador macOS (bash): --check / --remove / --help │ ├── vendor.mjs # baixa os assets para vendor/ (idempotente, versões pinadas) │ ├── merge-themes.mjs # JSONC → JSON estrito + merge da cadeia include dos temas │ ├── sync.mjs # copia src/ → lib/ (--check falha se divergirem; roda no prepack) │ ├── server-test.mjs # teste de regressão do servidor │ ├── smoke-client.cjs # smoke test do bundle (stub do loader em Node) │ ├── syntax-test-driver.cjs # teste headless do pipeline TextMate (Puppeteer + Firefox) │ └── restart-web.sh # reinicia o dsh web (útil neste ambiente) └── vendor/ # assets servidos em runtime (commitados no repo) ├── monaco/ # monaco-editor (build AMD min) ├── onig/ # vscode-oniguruma (onig.wasm + loader) ├── textmate/ # vscode-textmate ├── grammars/ # 28 gramáticas .tmLanguage.json oficiais + manifest ├── themes/ # dark_plus.json / light_plus.json (JSON estrito) ├── codicon/ # fonte codicon (UI/pastas) └── seti/ # fonte seti + tema de ícones (arquivos)

开发

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

sincronizar src/ → lib/
node scripts/sync.mjs

checar se src/ e lib/ divergem (CI)
node scripts/sync.mjs --check

testes (regressão do servidor + smoke test do bundle)
npm test

重新 vendor 化 assets（需要网络）

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 watcher（心跳、自动恢复，不会拖垮进程）。
- 客户端（lib/client.js）：手写 bundle，格式为 window.__ModuleLoader__.load({id, factory})，只依赖 react；其余来自 DSH 运行时服务（slots、layout、connection、sessions、workspaces、locale、theme）。颜色 100% 走设计系统 token（--dsw-*）。

安全

- 限定在 workspace 内：path.resolve + 前缀校验；对最深层祖先做 realpath，阻断 symlink 逃逸
- 服务端每次调用都校验根路径：只允许活跃会话的规范 cwd，或 workspace registry 里的路径（loopback API 拿不到 /、/etc、~）
- CSRF 由平台防护（isTrustedApiRequest）；二进制检测；payload 上限（内联 2 MB，读/写 50 MB）

发布（GitHub Pages）

docs/index.html 里的落地页自给自足（纯 HTML/CSS，无需构建，无外部依赖），可直接发布到 GitHub Pages： bash

1. 推送代码和 release tag

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/

- 更新： 只要 push 到 main —— GitHub Pages 会自动重新发布。
- 截图： 用相对路径引用（./screenshot-0.20.png）；要换图，替换 docs/ 里的 PNG 即可（页面框架会自动适配图片尺寸）。
- 版本： 让 badge v0.2.1（docs/index.html 的页头和页脚）与 package.json 保持同步。
- 本地校验： node scripts/render-check.cjs 会在无头 Firefox 里打开页面，校验加载、图片和框架贴合（需要 puppeteer-core + Firefox）。

故障排查

| 症状 | 原因 / 解决 |
| 'pnpm' não é reconhecido / pnpm not found on PATH | 脚本会自动使用本地 shim .pnpm-home/；没有的话，安装 pnpm（corepack enable / npm install -g pnpm） |
| CLI 'dsh' não encontrado | 用 npm install -g @deepseek-ai/dsh 安装（Windows 上脚本还会查找 %APPDATA%\npm\dsh.cmd） |
| ERR_PNPM_ADDING_TO_ROOT | 少了 -w 标志：用 dsh plugin --profile web add -w <caminho> |
| 安装后面板不显示 | 重启 dsh web（bundle 组合在启动时进行），然后刷新页面 |
| 编辑器没有配色 | TextMate 服务商在 grammar 加载后才注册；如果仍然没有，刷新页面（资源带 no-cache） |
| 目录树不反映智能体的文件 | 检查 watcher：递归 fs.watch 需要 Node ≥ 20；SSE 心跳为 25 秒 |
| 写入工作区之外被阻止 | 预期行为（沙箱）——服务端以 bad-request 拒绝 |

许可证

MIT — Copyright (c) 2026 dgadelha1。可自由用于个人和商业用途，需保留版权声明。软件按「原样」提供，不附带任何担保。完整内容见 LICENSE。