dsh-file-manager — DSH Web GUI 右侧文件管理面板 + @ 文件引用

English | 中文

为 DeepSeek Harness 桌面端（dsh web）开发的插件：聊天区右侧的 Explorer 文件面板 + Preview 预览面板（FileManager 风格，Apache-2.0 参考实现非抄录），以及输入框 @ 引用项目文件（树形多选弹窗 + 输入框内胶囊 + 行号）。数据全部来自真实文件系统与真实 git 仓库，无 mock。

功能

右侧面板

• Explorer（最右栏）：文件 / 变更 双 tab。
  • 文件树：整行点击展开/收起目录、打开文件；顶部文件名搜索（150ms 防抖，点击结果定位到树）。
  • Git 变更：读取真实 git status（porcelain v1 -z），支持 stage / unstage / discard（untracked 走删除、tracked 走 restore，批量放弃有确认）。
  • 文件树右键菜单：复制路径、复制名称、在文件管理器中显示、用默认应用打开、重命名、新建文件、新建文件夹、删除（二次确认）。
  • 拖拽文件行到聊天输入框，即把相对路径插入草稿。
• Preview（右二栏）：多 tab 预览，支持 markdown / html / code / diff / csv / pdf / word / excel / ppt / 图片 / 文本 / url。源码/预览切换、分屏编辑（比例持久化）、保存（mtime 冲突检测）、下载、刷新、中键关闭、右键批量关闭。
• Mermaid 图表：markdown 预览中的 ```mermaid 代码块渲染为图表，运行时打包在插件内（同源提供、离线可用、跟随主题）。
• 明暗主题跟随、偏好按项目隔离持久化、总开关（设置 → Web UI 插件）。

@ 文件引用（重点）

在聊天输入框输入 @ 打开 pi-desktop 风格树形多选弹窗（懒加载目录树 + 文件名搜索 + 复选框多选）：

• 选中文件/目录 → 输入框内出现胶囊（绿色 </> 图标 + 文件名 + 行号），引用文字隐藏，发送时才还原为 @相对路径:行号 纯文本发给模型。
• 行号：文件引用自动携带整个文件的行数（@path:1-N）；在预览面板选中代码片段再点「添加到对话」，胶囊只携带选中区域的行号（@path:start-end）。
• 胶囊是 dsh 原生引用对象（非文字装饰）：Backspace 整删、复制/粘贴保留语义、发送时经插件注册的 file 引用 codec 序列化。
• 目录引用为 @路径/ 纯文本（目录无行号概念）。

安装

# 从 npm（发布后）
dsh plugin --profile web add @lijian-ui/dsh-file-manager

# 从仓库直接 link（开发/联调，clone 即可用，lib 已构建入库）
git clone https://github.com/lijian-ui/dsh-file-manager.git
cd dsh-file-manager
dsh plugin --profile web add link:$(pwd)

安装后重启 dsh web，打开项目会话即可看到聊天区右侧面板；在输入框输入 @ 体验文件引用。

桌面壳（dsh-desktop）开发期以本地 symlink 联调：node_modules/@lijian-ui/dsh-file-manager → extensions/file-manager，源码改动后 npm run build 重新生成 lib/，重启 dev 生效。

架构

• host 半区（src/index.ts + src/host/）：cordis 插件，经 /filemgr/* HTTP 路由提供目录列举、文件读取（文本 80k 字符上限 / 图片 data URL）、写入（mtime 冲突检测）、文件名搜索、git status / stage / unstage / discard、SSE 变更流；所有操作过工作区门卫（realpath 规范化 + 前缀校验）且仅限 loopback。
• browser 半区（src/client/）：框架无关状态核心（store.ts）、拖拽引擎（drag.ts）、DOM 布局控制器（layout.ts，向 shell 三栏 grid 追加面板轨道）、React 组件（explorer / scm / preview / picker）。
  • picker/FilePickerModal.tsx — @ 树形多选弹窗（bridge + modal，监听输入框裸 @ 打开）。
  • file-source.ts — 注册 file 输入触发 source（仅提供引用 codec，惰性菜单参与者）。
  • reference.ts — 引用胶囊插入（slash/input-insert-reference bail，@path:lines 序列化）。
  • preview/selection.ts — 预览选区 → 行号区间换算。
  • styles/chip.module.css — 胶囊视觉（浅灰圆角 + 绿色 </> 图标，全局覆盖 [data-decoration="chip"]）。
• 工作流约定：改插件后必须 npm run build（重生成 lib/）再重启 dev，二者缺一不可。

构建

npm install
npm run build      # tsc -b + tsdown → lib/
npm run test       # vitest

署名

本项目是 FileManager（iOfficeAI/FileManager，Apache-2.0）右侧面板系统的复刻实现：尺寸、颜色、动效、交互参数来自对 v2.1.53 的实测调研，实现为全新代码，未大段抄录源码。上游版权归 FileManager 项目所有，本项目按 Apache-2.0 约定保留署名。