BXY-Create/dsh-plugin-workspace-explorer

dsh-plugin-workspace-explorer

DeepSeek Harness Web 工作台的只读文件资源管理器。它保留 DSH 自带的 Workspace/Session 会话树，在左栏底部增加一个入口，并通过 shell.overlay 提供可调宽的完整目录树与文件预览。

Workspace Explorer Markdown preview

这是 DeepSeek Harness（DSH）原生插件，不是 Codex 插件。目前已针对 DSH 0.1.0-rc.6 验证。

功能

- 懒加载目录树：目录优先、自然排序、多层展开、全部折叠、手动刷新与 8 秒自动刷新；
- 当前会话工作区自动跟随，也可从已注册 Workspace 中切换；
- 隐藏文件显示开关，偏好保存在浏览器本地；
- 递归文件名/路径搜索，结果可一键在树中定位；
- 文本和 Markdown 预览，以及图片、PDF、音频、视频的浏览器原生预览；
- 二进制文件识别、大文本截断、Range 流媒体和安全下载；
- 双击、右键菜单、方向键、Home/End、Enter/Space 操作；
- 复制绝对路径，并可调用 DSH 的 workspaces.openPath() 交给宿主系统默认应用打开；
- 面板默认开启，可拖动调宽；开关状态、宽度、隐藏文件和自动刷新偏好均持久化；
- 窄屏布局、中英文界面、基础 ARIA 语义与 reduced-motion 适配。

快捷键：

- Ctrl/⌘ + E：打开或关闭资源管理器；
- Ctrl/⌘ + P：面板打开时聚焦搜索；
- Esc：依次关闭右键菜单、预览或清空搜索。

安全边界

插件宿主端只接受已注册 Workspace id 或真实 Session id。每次请求都会重新解析授权根目录，并执行以下检查：

- API 只接受工作区内的相对路径，拒绝绝对路径、NUL 和 .. 目录穿越；
- realpath 后再次校验边界，工作区外部软链接可见但不可展开、预览或下载；
- 只注册 GET/HEAD 路由，不提供新建、修改、移动或删除文件的能力；
- 原始文件响应附带 nosniff、sandbox CSP、私有 no-store 缓存策略和安全的 Content-Disposition；
- 搜索和文本预览有明确上限，流媒体支持单段 Byte Range；
- 面板不会替换独占的 sidebar、sidebar.workspaces 或 root slot。

“用系统应用打开”会启动宿主系统程序，但不会由本插件写文件；是否修改文件取决于用户随后在该程序中的操作。

安装

热部署脚本

首次部署到本地 profile 时：

bash scripts/deploy-hot.sh /path/to/dsh/profile

脚本会先执行语法、身份和测试检查，再把发布文件复制到 profile/vendor，通过 pnpm 写入依赖快照，并向 cordis.patch.yml 添加：

- insert:
- id: workspace-explorer
name: 'dsh-plugin-workspace-explorer'

DSH 会监听 patch 并热应用，不需要重启。若宿主机没有 node，可显式指定 DSH 容器里的 Node：

DSH_NODE_BIN=/proc//root/usr/local/bin/node \
bash scripts/deploy-hot.sh /path/to/dsh/profile

若一次部署在 pnpm 阶段安全中止、尚未写入 node_modules 和 patch，可检查保留下来的 vendor 快照后用 --resume 继续。脚本会识别容器路径与宿主路径不同的 pnpm store，并临时改写安装元数据后恢复；也可用 DSH_PNPM_STORE_DIR 显式指定同一个物理 store。

同一包名的宿主 ESM 一旦被当前 DSH 进程加载，后续宿主端源码更新不会因重复热挂载而刷新。脚本因此拒绝覆盖已部署的同名快照；升级宿主逻辑时应使用新包名，或等 DSH 自然重启后更新。仅修改浏览器端时，可同步 lib/client.js 后硬刷新页面。

手动安装

将仓库复制到 profile/vendor/dsh-plugin-workspace-explorer，在 profile 目录执行：

corepack pnpm add "dsh-plugin-workspace-explorer@file:./vendor/dsh-plugin-workspace-explorer" --save-exact --ignore-scripts

再把上面的 insert 条目加入 cordis.patch.yml。不要同时把插件放进 bundle 和 patch。

配置

配置均可省略：

- insert:
- id: workspace-explorer
name: 'dsh-plugin-workspace-explorer'
config:
maxTextPreviewBytes: 2097152
maxSearchEntries: 50000
searchLimit: 200

searchLimit 最大为 500。无效或非正整数会回退到内置默认值。

HTTP 接口

所有接口位于 /plugins/workspace-explorer，并要求 sessionId 或 workspaceId 查询参数：

| 路径 | 用途 |
| --- | --- |
| /context | 已授权工作区和能力信息 |
| /tree?path=...&hidden=0|1 | 单层目录内容 |
| /search?q=... | 递归文件名/路径搜索 |
| /preview?path=... | 文本内容或媒体元数据 |
| /raw?path=... | 内嵌预览、HEAD 与 Range 流 |
| /download?path=... | attachment 下载 |

在线冒烟测试：

node scripts/smoke-live.mjs --base-url http://127.0.0.1:3080 --workspace-id
或：--session-id
不传授权 id 时，脚本仍会验证 boot manifest、客户端 bundle 和接口路由是否已挂载。

真实 Chromium 自动验收脚本位于 scripts/accept-browser.mjs。它使用 playwright-core 驱动用户指定的 Chromium，不下载或捆绑浏览器：

PLAYWRIGHT_CORE_PATH=/path/to/node_modules/playwright-core \
node scripts/accept-browser.mjs \
--chrome /path/to/chrome \
--output artifacts/browser-acceptance

开发与测试

要求 Node.js 22 或更高版本：

npm run check
npm test

测试覆盖目录穿越、软链接越界、隐藏文件、深层搜索、文本/媒体/二进制预览、HEAD、Range、下载，以及 Workspace/Session 授权。完整实机验收清单见 docs/ACCEPTANCE.md。

DSH 0.1.0-rc.6 + Chromium 的最新实机验收结果见 docs/ACCEPTANCE-2026-08-24.md（39 项浏览器断言，附截图）。

License

MIT