# dock-files [English](README.en.md) > **面向 DSH 工作区的文件浏览插件。** dock-files 提供 VSCode 风格的文件树、拖放导入、剪贴板粘贴、传输任务管理和右键菜单。 dock 系列的文件浏览插件:在侧边栏挂载文件面板,浏览当前会话工作目录(通过自己的 `/wb-files` 主机路由),点击文件交给已注册的文件查看器打开(如 dock-editor)。 ## 效果预览 | 主界面 | 右键菜单 | | --- | --- | | ![dock-files 文件浏览主界面](assets/main-gui.png) | ![dock-files 右键菜单](assets/menu-zh.png) | ## 功能 - **目录树浏览**:惰性递归展开,目录优先、大小写不敏感排序(VSCode 资源管理器顺序);VSCode 风格文件树 UI(类型彩色图标、树形导引线、工具栏刷新/折叠全部、悬停操作按钮)。 - **会话隔离**:所有操作以会话工作目录为边界,路径经 realpath 规范化后必须位于会话工作区内,越界路径一律 403。 - **文件打开**:点击文件通过 `ctx.files.open` 分发给匹配的文件查看器(浮窗打开)。 - **对话路径打开**:设置中的 `dock-files.open-source` 默认值为 `dock`,可选 `dock` / `harness`。Harness 模式不包装 `sidebarRight.openResource()`,完全保留原生行为。dock 模式仅包装该 canonical carrier:识别 `dsh-resource://file/session/...` 和 `file/absolute/...`,按 b67 规则逐段解码并解析实际路径;存在、非目录且有查看器的文件交给 Workbench,否则原样调用 Harness,并保留 `options`。异步探测在设置切换或插件销毁后不会产生 stale Workbench 路由。 - **文件管理器操作**:右键菜单提供常用文件管理功能——新建文件 / 新建文件夹(自动去重命名,创建后直接进入行内重命名)、重命名(行内编辑,Enter 确认 / Esc 取消)、复制 / 剪切 / 粘贴(复制可重复粘贴,剪切项变灰、粘贴后清除)、粘贴图片(把系统剪贴板中的图片保存为文件,如 `image.png`,按 mime 类型自动命名去重;菜单项会探测剪贴板,仅在其中有图片时自动显示)、删除(确认后递归删除,不会覆盖同名文件)、复制路径、刷新;普通文件可通过右键菜单触发浏览器下载,软链接跳过下载;空白区域右键可对根目录执行新建 / 粘贴 / 粘贴图片 / 刷新。 - **打包下载(ZIP)**:右键文件夹(或根目录)选择「打包下载(ZIP)」,主机侧递归打包该目录为 ZIP 后下载,目录结构以顶层目录名为前缀保留(空目录、嵌套目录都保留),软链接一律跳过;单次上限 512MB / 10 万个条目,超出返回 413。下载同样进入传输任务中心(支持另存为、暂停、取消),非目录目标返回 400,越界路径仍按会话隔离返回 403。 - **拖放**:把系统里的文件拖进浏览器即可导入到目标文件夹(按原名自动去重,绝不覆盖);树内拖动文件 / 文件夹到其它文件夹(或空白区域 = 根目录)可移动,拖到文件上则移入该文件所在目录(落点不准也能成功),拖到自身或子孙目录会被拒绝。 - **粘贴本地文件**:在系统里复制文件后,点击面板使其获得焦点,按 Ctrl+V 即可粘贴导入(浏览器只通过 paste 事件暴露本地文件内容);粘贴目标为最近点击 / 右键过的文件夹,否则为根目录。 - **传输任务中心**:普通文件使用分块上传,以支持大文件传输。所有传输任务统一进入全局内存任务中心,可在浮窗和状态栏查看,也可在底部查看总进度;任务支持暂停、继续和取消。任务状态不跨重启保留,重启后任务会消失;清除历史只移除任务记录,不删除文件。 - **上下文菜单**:文件、文件夹与空白区域各自适配的菜单项,超出视口自动回拉;确认 / 提示使用与主题一致的应用内弹窗。暂不支持在 Windows 原生资源管理器中直接粘贴文件、复制文件内容或复制下载链接。 - **多语言**:界面文案(右键菜单、弹窗、提示、状态)跟随 DSH 语言设置(zh/en,随 `locale/change` 事件即时切换);新建文件 / 文件夹的默认名也随语言(`New File.txt` / `新建文件.txt`)。 - **文件域服务**:提供 `ctx.files`(`open` / `registerFileViewer` / `registerFileIcon`),其他插件可注册自己的查看器(`exts` 扩展名匹配或 `default` 兜底)及按扩展名的图标(`registerFileIcon`,一个插件可注册多组);注册时可附带 `icon`(主题色 + 可选自定义 SVG 图形),文件浏览器按扩展名渲染各插件注册的图标,未注册类型回退内置调色板。 ## 依赖 | 依赖 | 类型 | 说明 | | --- | --- | --- | | [dock-base](https://github.com/AKS1st/dock) >= 0.2.0 | peer(必需) | 工作台外壳:dock-files 的侧边栏面板、浮窗、`ctx.workbench` 都由它提供 | | DSH Web 环境 >= 0.1.3-alpha.2 | 运行时 | 必需;最低 Harness 版本为 `>=0.1.3-alpha.2`(b67),客户端平台为 Web | | `cordis` ^4.0.0-rc.7 | peer | 插件框架(DSH 自带);客户端注入的 `workbench` 为硬依赖 | | `react` ^18.2.0 | peer(可选) | 客户端渲染需要;未提供时面板 UI 不激活 | **可选查看器**(不装也能浏览,装了才能打开对应文件):`dock-editor`(文本)、`dock-images`(图片)、`dock-markdown`(Markdown)。 ## dock 系列插件 dock 生态是一组可组合的插件,本插件只提供其中一块能力。全部可选,按需安装: | 插件 | 作用 | | --- | --- | | [dock-base](https://github.com/AKS1st/dock) | 工作台基座:活动栏 / 侧边栏 / 编辑器区 / 状态栏与 `ctx.workbench` 注册表 | | [dock-files](https://github.com/AKS1st/dock-files) | 文件浏览器:会话工作区目录树、新建/重命名/删除、拖放与粘贴导入 | | [dock-editor](https://github.com/AKS1st/dock-editor) | 文本查看/编辑:撤销重做、Ctrl+S 保存、二进制检测 | | [dock-images](https://github.com/AKS1st/dock-images) | 图片查看:PNG/JPEG/GIF/WebP/BMP/SVG/ICO/AVIF | | [dock-markdown](https://github.com/AKS1st/dock-markdown) | Markdown 查看:GFM 渲染、大纲、相对路径资源 | | [dock-media](https://github.com/AKS1st/dock-media) | 音视频播放:HTTP Range 流式、纯音频播放器与全屏视频 | | [dock-git](https://github.com/AKS1st/dock-git) | Git 历史:泳道提交图、分支/标签、暂存与提交 | | [dock-spreadsheet](https://github.com/AKS1st/dock-spreadsheet) | 只读表格:XLSX/XLS/ODS/CSV/TSV | 本插件是 **dock-files**;完整组合建议见 dock-base 的「推荐搭配插件」一节。 ## 安装 需要 `dock` 基础插件: 推荐从 npm registry 安装: ```sh dsh plugin --profile web add dock-base dsh plugin --profile web add dock-files ``` 或通过 GitHub 安装(备选): ```sh dsh plugin --profile web add github:AKS1st/dock dsh plugin --profile web add github:AKS1st/dock-files ``` 配合查看器插件使用(可组合、按需):`dock-editor`(文本)、`dock-images`(图片)、`dock-markdown`(Markdown)。 ## 安全 主机路由只接受来自受信任来源(回环地址 / 配置的 trustedHosts + 同源检查)的 POST 请求,且任何目录访问都会先做 realpath 规范化再与会话工作区做前缀比较——`..` 逃逸、指向工作区外的符号链接、无关绝对路径都会被拒绝(403)。 ## License MIT