DSH 文件工作台插件（Vue 3 + Vite）

🌐 简体中文 | English

在 DSH 会话视图的右侧面板内提供三个能力，共用同一个工作区根：

• 🗂 文件工作台（tab kind workbench）：Win11 资源管理器风格的文件管理器
• 📝 文件编辑器（tab kind vscode）：CodeMirror 多标签代码编辑器 + 项目树
• ▶ 终端：node-pty（ConPTY）常驻 shell，全局单例，跨面板常驻不重建

在此之上还有：Git / SVN 管理面板、把文件作为官方 @路径 引用送进会话输入框、 后台任务面板、用子代理处理选中文件。

文件查看统一改道到 DSH 右侧原生查看器（Markdown / 代码高亮 / 图片 / PDF / HTML / 纯文本）； 需要就地编辑时用文件编辑器，或在列表右键「编辑」打开内置记事本。

面板与入口

| 面板 | tab kind | guide 入口 | 说明 | | --- | --- | --- | --- | | 文件工作台 | workbench | order 100 | 右侧栏 guide 区点击打开，首次自动定位当前会话工作区目录 | | 文件编辑器 | vscode | order 101 | 同上，排在文件工作台下方 | | 终端 | — | — | 工具栏终端按钮，或在目录右键「在终端打开」 |

入口只有右侧栏 guide 卡与标签，不再有输入框按钮 / 顶部抽屉。

功能一览

🗂 文件工作台（资源管理器）

• 单窗口 Win11 树：主页 / 图库 / 此电脑盘符 / 回收站 / 收藏 / 会话文件； 可拖拽分隔条（默认 3:7），命令栏 + 状态栏，目录优先 + 大小写不敏感排序。
• 盘符真实卷标：读取系统卷标显示为 卷标 (C:)，无卷标回退本地化的「本地磁盘 (C:)」。
• 视图档位：超大 / 大 / 中 / 小图标、列表、详情、内容、平铺共 8 档； 详情视图列宽可拖拽；可切换是否显示扩展名。
• 搜索：聚焦当前目录递归检索文件名与内容，支持区分大小写 / 正则、虚拟滚动； 支持对内容命中做跨文件批量替换。
• CRUD：新建文件 / 目录、重命名、删除（带确认）、复制 / 剪切 / 粘贴、 鼠标拉框多选、批量操作、外部拖拽上传、压缩 / 解压。
• 回收站：与文件列表共用同一套 UI（8 档视图 / 排序 / 多选 / 拉框一致）， 操作换成 还原 / 永久删除 / 清空回收站。
• Git 徽标：文件状态（? / A / M / D）徽标 + 右键 Git 操作。
• 记事本：右键「编辑」打开内置文本编辑器（另存 / 剪贴板 / 未保存二次确认）。
• 后台任务：上传、压缩等长任务在后台任务面板显示进度与结果，可查历史归档。
• 子代理：右键「用子代理处理」，就选中文件 / 目录发起官方子代理会话。
• 导航：后退 / 前进 / 上级 / 回到会话目录、面包屑地址栏、收藏、会话触碰文件（SSE 实时）。

📝 文件编辑器

• 项目树：展开状态与滚动位置持久化；单击选中、双击打开；右键 新建文件 / 文件夹、重命名、删除、刷新、添加到会话。
• 多标签编辑：CodeMirror 6，语言按扩展名动态加载（TS/JS/JSON/HTML/CSS/Markdown/YAML/XML/ Python/SQL/Java/C++/Rust/Go/PHP，以及 C#/shell/Ruby 等 legacy 模式；无匹配回退纯文本）。
• 标签栏右键菜单：关闭 / 保存并关闭 / 关闭其他 / 关闭右侧标签页 / 关闭全部。
• 编辑器右键：格式化内容、保存；Ctrl+S 保存；未保存关闭时二次确认；只读文件有明确标识。
• 打开文件夹：两栏选择器（左栏「我的电脑 + 快捷方式」，右栏对应文件夹）， 支持双击下钻、单击选中，另可新建文件夹或直接输入路径。
• 与文件工作台共用同一个全局终端。

▶ 终端

• ConPTY 常驻 shell（node-pty）：真实控制台语义——退格逐字符删除、回车即时执行、 全屏 TTY 程序与中文输出正常；cmd / powershell 可切换。
• 多标签（上限 9），每个标签一个独立后端会话；会话跨面板关闭存活，重连即续传输出。
• 浮窗：可拖动、右下角缩放、双击复位；最小化收进右下角 dock 栏（跨面板常驻，可还原）。
• 关闭即清理：Windows 下以 taskkill /T 终结整棵进程树，避免 npm / python / node 孤儿残留。
• 搜索与显示：Ctrl+F 搜索输出（区分大小写）、字号增减、清屏。
• 键位：Ctrl+C 有选区时复制（无选区放行 SIGINT）、Ctrl+V 粘贴、Ctrl+F 搜索、Ctrl± / Ctrl+0 字号。
• 权限徽标：显示当前终端是「管理员」还是「普通权限」，见下文权限模型。
• 官方终端后端：本机 shell 的进程层（PTY 创建 / 重连 / 清理）在宿主官方 ctx.webTerminals 服务可用时委托给官方实现，不可用时自动回退插件自建后端；SSH 终端始终走插件自建 SSH 通道。

🌿 Git / SVN 管理面板

两个面板都可从文件工作台与文件编辑器中打开（右键 → 打开管理面板），均按左侧窄栏分区：

Git（7 个分区）

| 分区 | 能力 | | --- | --- | | 变更 | 暂存区 / 未暂存 / 未跟踪三组；行内暂存、取消暂存、忽略、还原；全部暂存；提交（含快捷提交） | | 历史 | 提交图（全部 / 当前分支）+ 提交详情（hash / 作者 / 时间 / parents / refs / 文件清单 / 补丁）；reset（soft / mixed / hard）、revert、cherry-pick | | 分支 | 新建并切换、重命名、本地与远程分支列表、切换、合并到当前、推送、删除、检出远程分支 | | 标签 | 新建、拉取全部、发布 Release、查看、拉取远程标签、推送、删除 | | 远程 | 新增、修改 URL、删除 | | 贮藏 | 新建、查看、应用 / 删除 | | 命令行 | 内置 git CLI，直接跑任意 git 子命令并显示输出 |

另有文件级 diff 视图 / 文件历史 / blame，以及分支上下游 ↑ahead ↓behind 显示。

SVN（3 个分区：变更 / 日志 / 输出）

• 更新、清理、检出（URL + 目标目录）、加入版本控制、还原、解决冲突、提交（选中或全部）。
• 文件级 diff / blame；工作副本 URL 与仓库根展示。
• 忽略走 svn:ignore（目录属性，作用在父目录，先读后幂等追加）。
• 未装 svn CLI 或当前目录不是工作副本时，给出明确提示与引导。

右键菜单统一由 composables/domain/repoMenu.ts 生成（单一来源），Git 提供 暂存 / 提交 / 差异 / 还原 / 忽略（写入仓库根 .gitignore），SVN 提供 打开管理面板 / 更新 / 加入版本控制 / 忽略。

🧩 外部视图注入（Activity Bar）

文件编辑器与文件工作台都支持外部插件 / 脚本注册自定义视图，经由一套框架无关的 Activity Bar 注册表实现——不要求 Vue/React，原生 JS 即可。完整作者文档见 docs/activity-bar-plugin.md。

• 两个相互独立的注册表，以 window 全局暴露：
  • 文件编辑器：window.__dshFileWorkbenchVSCode__.activityBar.register(view)
  • 文件工作台：window.__dshFileWorkbenchWorkbench__.activityBar.register(view)
• 契约：每个视图是 { id, title, icon?, order?, mount(el, ctx), when? }；mount(el, ctx) 把 UI 渲染进 el，可返回清理函数（切走该视图 / 卸载时调用）。ctx 提供 projectDir / theme / activeFile getter、onProjectChange / onThemeChange / onDidChangeActiveFile 订阅， 以及 openFile / listOpenFiles / openDiff / toast。
• 命令贡献点（编辑器，apiVersion ≥ 2）：插件还能通过 window.__dshFileWorkbenchVSCode__.commands （register / execute / unregister / list / has）注册可被调用的动作——对标 VS Code 的 commands.registerCommand。注册的命令在被按 id 触发前保持惰性，不会擅自改动编辑器行为。
• 状态栏项（编辑器，apiVersion ≥ 2）：用 window.__dshFileWorkbenchVSCode__.statusbar.register({ id, text, commandId, tooltip?, order?, when? }) 把某个命令暴露成编辑器底部状态栏的可点击按钮，点击即以 { path, projectDir } 上下文自动执行该命令 —— 这是命令的内置触发面，无需自己找地方放按钮。
• 后台任务（工作台，apiVersion ≥ 3）：用 window.__dshFileWorkbenchWorkbench__.backgroundTasks （start(label, opts?) → { step, updateLabel, done, fail }、clearFinished、clearAll）把工作台的 任务面板当作通用进度登记处复用——插件登记的耗时任务会出现在同一个底部任务按钮里，含历史 / 归档。 注入视图激活时，状态栏只置灰本地导航区（文件信息 / 视图切换），后台任务按钮仍可点击、可查看。
• 多语言标题：title 可为普通字符串或按 locale 的对象（{ zh, en }），随页面语言解析。
• 位置与可见性：工作台中注册的视图出现在回收站下方的「外部注入」导航分组，无任何注册时整组隐藏； 当某个注入视图处于激活态时，顶部工具栏（WinMenuBar）与资源管理器的命令栏会被禁用（inert + 置灰）， 底部状态栏则只置灰本地导航区（文件信息 / 视图切换），保留后台任务按钮可点击、可查看。
• 幂等：同 id 重复注册即覆盖（支持热更新），unregister(id) 干净移除；注册表在模块级， 面板卸载再挂载不会丢注册。

🔗 会话联动

• 会话文件：经 SSE 实时推送当前会话触碰过的文件，在导航树「会话文件」分组展示。
• 添加到会话：把文件 / 目录作为 DSH 官方结构化引用 chip（@路径，source: "reference"） 写入当前会话输入框草稿——不是拼纯文本。
• 打开改道：会话里点文件（工具行路径、产物行、正文提及）会改道到本插件； 工作台未挂载时自动回落到宿主原生行为。
• 跟随会话：切换会话或会话工作目录变化时，工作区根自动跟随。

🎨 设置

允许操作工作区根之外的文件（root 开关）、显示隐藏文件、强调色、界面字号、字体族、 主题（跟随宿主 / 深色 / 浅色）、默认视图。

快捷键

全局：

| 按键 | 功能 | | --- | ----------- | | ? | 打开快捷键帮助（全局） |

文件列表（焦点内）：

| 按键 | 功能 | | ---------------------- | ---------------- | | Ctrl/Cmd+A | 全选 | | Ctrl/Cmd+C / X / V | 复制 / 剪切 / 粘贴 | | Ctrl/Cmd+F | 聚焦筛选框 | | Ctrl+Shift+N | 新建文件夹 | | Delete / F2 / F5 | 删除（确认）/ 重命名 / 刷新 | | Enter | 打开文件 / 进入目录 | | ↑ ↓ Home End | 移动选中 | | Backspace / Alt+↑ | 返回上级 | | Alt+← / → | 浏览历史后退 / 前进 |

文件编辑器与终端：

| 按键 | 位置 | 功能 | | ---------------- | ----- | ------------------------ | | Ctrl/Cmd+S | 编辑器 | 保存当前标签 | | 标签栏右键 | 编辑器 | 关闭 / 保存并关闭 / 关闭其他 / 关闭右侧 / 关闭全部 | | Ctrl+C | 终端 | 有选区时复制；无选区放行 SIGINT | | Ctrl+V | 终端 | 粘贴 | | Ctrl+F | 终端 | 搜索终端输出 | | Ctrl± / Ctrl+0 | 终端 | 增大 / 减小 / 复位字号 |

项目结构

src/
  shared/
    types.ts             宿主 ↔ 客户端 ↔ Vue 共享类型
    locales.ts           中英文案字典（zh / en 两份都要同步改）
    session-files.ts     会话转写文件解析
  host/                  服务端（Cordis 插件）
    index.ts             apply：注册 /api/dsh-file-workbench 路由 + 静态资源 + 自更新
    updater.ts           启动后自更新
    fs/
      fs-tree.ts         列目录 / 排序 / 软链接 / containment 守卫
      fs-search.ts       递归搜索 + 跨文件替换
      fs-read.ts         打开 / 保存
      fs-zip.ts          压缩 / 解压
      fs-drives.ts       盘符与卷标（Win32_LogicalDisk，5 分钟 TTL 缓存）
      recycle.ts         系统回收站
    routes/
      routes.ts                资源分发表
      routes-fs.ts             文件系统（列表 / 搜索 / 读写 / 压缩 / 我的电脑）
      routes-git.ts            Git（status / diff / add / discard / log / branch / tag / remote / stash / 忽略）
      routes-svn.ts            SVN（info / status / run / 日志 / blame）
      routes-terminal.ts       终端：ConPTY 常驻 shell（SSE 流）+ 宿主提权探测 /term-env
      routes-recycle.ts        回收站
      routes-session-stream.ts 会话触碰文件 SSE
      routes-subagent.ts       子代理
      routes-task-archives.ts  后台任务归档
      routes-persist.ts        偏好持久化
      routes-util.ts           JSON 信封 / body 解析 / 静态资源 / 路径校验
    store/
      root-store.ts      工作区根
      workbench-store.ts prefs / favorites / layout 持久化
    subagent/subagent.ts 官方子代理会话
  client/                DSH 客户端桥接（TSX，注册进右侧栏，注入 Vue 产物 + 挂载）
    index.tsx            apply：注册两个右侧栏 tab、改道文件打开、注入 Vue 产物、引用通道
    RightPaneBridge.tsx  把 Vue 工作台 / 编辑器主体挂进右侧面板容器
    ComposerBridge.tsx   会话输入框引用座位（官方 `@路径` chip 写入）
    TabMenuBridge.tsx    右侧栏 tab 菜单追加项（新开编辑器 / 弹出浮窗）
    OfficialTerminalBridge.ts 官方终端桥：本机终端走宿主 ctx.webTerminals
    api.ts               「打开 tab」桥
  vue/                   Vue 3 + Vite 前端
    main.ts              入口：右侧面板挂载 + **全局终端常驻挂载**（挂 body）
    App.vue              文件工作台单窗口壳
    styles.css           全局主题变量与基础样式
    components/
      common/            WinMenuBar / NavPathBar / Icon / ContextMenu / ConfirmDialog / ShortcutHelpDialog
      business/explorer/ ExplorerPane（双栏 + 分隔条）、CommandBar、NavPane、FileListPane（列表 / 回收站）、
                         ThisPcPane、SearchPane、StatusBar、BgTaskPanel、TxtEditor
      business/vscode/   VSCodePane、ProjectTree、TabBar、CodeEditor、FolderPickerDialog、langResolver
      business/git/      GitPanel、GitDiffView、GitGraphList、SvnPanel、QuickCommit
      business/terminal/ TerminalHost（全局单例宿主）、TerminalDialog（浮窗 / 停靠）
      settings/          SettingsDialog
    composables/
      core/              useApi、settings、theme、i18n、dialog、fileTaskMeta
      domain/            git、gitGraph、svn、repoMenu（右键菜单单一来源）、terminalStore、
                         officialTerm（官方终端桥取用器）、driveName
      session/           sessionSse、tasks、listStatus
      ui/                icons、clipboard、dnd、virtual
    stores/              workbench、explorer、fileCommands、vscode、activityBar（外部视图注入注册表）
    types/               auto-imports.d.ts、components.d.ts

开发

前置：Node ≥ 20、npm（或 pnpm）。

| 命令 | 作用 | | -------------------- | ------------------------------ | | npm run dev:vue | 单独跑 Vue 应用联调（自挂 #app，配合已运行的 host） | | npm run build:vue | 仅构建 Vue 产物（dist/） | | npm run typecheck | vue-tsc --noEmit | | npm run build | 完整构建：Vite(Vue) + esbuild(host/client) → lib/ | | npm run build:dev | 同上，--dev | | npm run sync | 把 lib/ 同步进 web profile | | npm run deploy | build:dev + sync |

API 基址默认 /api/dsh-file-workbench，可用环境变量 VITE_API_BASE 覆盖 （例如开发时指向 http://localhost:xxxx/api/dsh-file-workbench）。

改动生效范围（影响调试方式）：

• 只改 src/vue/**、src/shared/locales.ts → 构建 + 同步后硬刷新浏览器即可。
• 改了 src/host/** 或 src/client/**（例如新增路由）→ 必须重启 dsh web。

安装到 DSH（web 档）

npm run build && npm run sync   # 构建并把产物同步进 web profile

装好后在 profile 里执行 npm install（让 cordis.patch.yml 生效），重启 dsh web 并硬刷新浏览器 （Cmd/Ctrl+Shift+R）。

若 dsh web 未内置本插件的挂载行，可在 ~/.dsh/profiles/web/cordis.patch.yml 追加：

- insert:
    - id: dsh-file-workbench
      name: 'dsh-file-workbench'

使用

1. 在 DSH 右侧栏的 guide 区点「文件工作台」或「文件编辑器」打开面板 （首次会自动定位到当前会话的工作区目录）。
2. 工作台：左侧导航树选择位置；右侧列表双击文件夹进入、双击文件在 DSH 右侧查看器打开。
3. 编辑器：工具栏「打开文件夹」选定项目目录 → 项目树双击打开文件 → 多标签编写、Ctrl+S 保存。
4. 终端：工具栏终端按钮打开，最小化后收进右下角 dock 栏，点一下还原。
5. ? 查看快捷键帮助。

权限模型（终端管理员模式）

终端 shell 由宿主以 ConPTY 派生，子进程继承 dsh web 进程的令牌 —— 所以「终端里的命令有没有管理员权限」等于「dsh web 是不是以管理员启动」。

• 获得管理员终端：以管理员身份运行 dsh web（右键终端/快捷方式 → 「以管理员身份运行」），面板内所有终端即拥有管理员权限。
• 徽标：终端标签栏显示「管理员 / 普通权限」，鼠标悬停可看说明；点击给出获取指引。 探测由 host 的 GET /term-env 提供（Windows 用 whoami /groups 的完整性级别 SID 判定， POSIX 用 uid === 0）。
• 为什么不能在插件内单开一个提权终端：Windows 提权必须过 UAC，而走 ShellExecute / runas 的提权进程无法挂到 ConPTY 伪控制台上，因此插件无法对单个终端提权；可行路径只有让宿主整体提权。
• 备选方案（当前未实现）：以 sudo.exe 做单命令级提权（需先启用 Windows sudo 且设为 inline 模式）， 或宿主注册高权限助手经命名管道桥接（引入自建提权通道，安全面较大）。

安全

• 所有读写路径先经根目录 containment 守卫（含符号链接解析后的再检查），拒绝越权与路径穿越。
• 工作区根之外默认只读；需在设置中开启 root 开关才允许写操作。
• 搜索对符号链接目录不下钻（循环安全），并对访问数与命中数设预算。
• 终端工作目录同样过保护路径校验；终止会话时清理整棵进程树。
• 持久化仅写 {DSH_HOME|~/.dsh}/fileworkbench/ 白名单键（prefs / favorites / layout）。

依赖

• Vue 3 + Vite（前端）；React（DSH 右侧栏桥接，由宿主提供）；esbuild（host/client 构建）。
• element-plus（UI 组件）；@xterm/xterm + fit / search / web-links addon（终端渲染）。
• CodeMirror 6（编辑器：@codemirror/* 语言包按需动态加载）。
• node-pty（ConPTY 交互终端，原生模块，缺失时终端不可用）。
• fflate（压缩 / 解压）；fzstd（解压会话转写 zstd）。
• 复用 peer @deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver。

License

MIT