DSH 工作区通常需要通过特定的 API 调用来管理文件。dock-files 插件面向 DSH 工作区提供文件浏览功能，由 AKS1st 维护。它解决了在没有原生文件管理器的情况下，开发者需要通过命令行或 API 逐个操作文件的繁琐问题。
安装与依赖¶
安装 dock-files 需要依赖 dock-base 插件。
dsh plugin --profile web add dock-base
dsh plugin --profile web add dock-files
环境要求：
* DSH Web 环境：>=0.1.3-alpha.2
* dock-base：>=0.2.0
* 框架：cordis ^4.0.0-rc.7
* 渲染：react ^18.2.0（可选，用于渲染 UI）
核心功能¶
目录树浏览¶
插件提供 VSCode 风格的文件树界面。目录采用惰性递归展开，排序逻辑为目录优先、大小写不敏感（与 VSCode 资源管理器一致）。界面包含类型彩色图标、树形导引线、工具栏（刷新/折叠全部）以及悬停操作按钮。
会话隔离与安全¶
所有操作以会话工作目录为边界。路径经过 realpath 规范化后必须位于工作区内，越界路径会返回 403 错误。主机路由只接受来自受信任来源（回环地址 / trustedHosts + 同源）的请求。
文件打开与分发¶
点击文件时，插件通过 ctx.files.open 分发给已注册的文件查看器（如 dock-editor），以浮窗形式打开。
打开来源模式¶
在设置中配置 dock-files.open-source（默认 dock）：
* dock 模式：识别 dsh-resource://file/session/... 和 file/absolute/... 路径，按 b67 规则解码，将文件交给 Workbench。
* harness 模式：不包装 sidebarRight.openResource()，完全保留原生行为。
文件管理¶
右键菜单提供完整的文件管理操作：
1. 新建：新建文件/文件夹（自动去重，创建后进入行内重命名）。
2. 重命名：行内编辑，Enter 确认 / Esc 取消。
3. 复制/剪切/粘贴：复制可重复粘贴，剪切项变灰，粘贴后清除剪贴板。
4. 粘贴图片：检测系统剪贴板，仅在包含图片时显示，自动按 MIME 类型命名去重。
5. 删除：递归删除，不会覆盖同名文件。
6. 其他：复制路径、刷新、浏览器下载。
* 空白区域右键可对根目录执行新建、粘贴等操作。
拖放与粘贴¶
- 系统拖入：将系统文件拖入浏览器即可导入到目标文件夹（按原名自动去重）。
- 树内移动：拖动文件/文件夹到其它文件夹或空白区域（视为根目录）可移动文件。
- Ctrl+V：在系统复制文件后，点击面板使其获得焦点，按
Ctrl+V即可粘贴导入。
传输任务中心¶
普通文件使用分块上传以支持大文件。所有传输任务进入全局内存任务中心，支持在浮窗、状态栏或底部查看进度。任务支持暂停、继续和取消。注意：任务状态不跨重启保留。
多语言与扩展¶
界面文案跟随 DSH 语言设置（zh/en），新建文件/文件夹的默认名也随之切换。插件提供 ctx.files 服务，允许其他插件注册文件查看器（registerFileViewer）和图标（registerFileIcon）。
典型用法¶
- 挂载面板：通过
dock-base侧边栏挂载文件面板，浏览当前会话工作目录。 - 打开文件：点击文件，由已注册的查看器打开。
- 配置打开方式：在设置中修改
dock-files.open-source。 - 自定义扩展：在其他插件中调用
ctx.files.registerFileViewer注册扩展名匹配或默认的查看器。
注意事项¶
- Windows 限制：暂不支持在 Windows 原生资源管理器中直接粘贴文件、复制文件内容、复制下载链接或下载文件夹。
- 任务持久化：传输任务状态不跨重启保留，重启后任务会消失。
- 拖放限制：拖到自身或子孙目录会被拒绝。
- 安全：安装前应检查源码与许可证。
