dsh-file-tree-panel

DSH（DeepSeek Harness）文件树面板插件：在 Web 界面右侧栏显示当前会话工作文件夹的树形文件结构。

• 📁 子文件夹点击展开/折叠（懒加载，不预扫全树）
• 📄 点击文件在面板内直接预览内容：
  • 文本 / 代码 / JSON / Markdown / 日志 → 等宽字体源码预览
  • HTML → 默认网页渲染预览，可切换到「代码」查看源码（iframe 沙箱隔离）
  • 图片（png/jpg/gif/webp/svg 等）→ 内嵌显示
  • 音频 / 视频 → 内嵌播放器
  • PDF → 面板内嵌渲染
  • 其他二进制 → 大小 + 下载链接（另有「打开」按钮调系统默认应用）
• 超大文件自动降级提示，不阻塞面板
• 深/浅色主题自适应（使用 DSH 主题变量）

包结构

dsh-file-tree-panel/
├── package.json          # dsh.bundle.patch + dsh.client 声明 + exports（. / ./client / ./typert）
├── cordis.patch.yml      # 插件组合层：挂载 fileTree 服务行（dsh plugin add 自动应用）
├── lib/
│   ├── index.js          # 宿主插件：fileTree Remote 服务（fs 读取逻辑）
│   ├── typert.js         # 宿主 TYPERT 清单（typert-loader 注册，网关校验用）
│   ├── schemas.js        # 共享 zod 线格式
│   ├── remote-client.js  # 客户端 Remote contribution（ctx.remote.$mount 挂载）
│   └── client.js         # 客户端模块：details 栏 UI + 会话头部按钮

原理（为什么这样设计）

• DSH 的组合（preset / 宿主）只能加载 npm 包，不能内联代码；浏览器端 UI 通过包的 dsh.client 声明被发现并打进 Web bundle。
• 官方插件安装命令 dsh plugin --profile <name> add <pkg> 会在 profile 目录执行 pnpm add，并把声明了 dsh.bundle.patch 的包自动加入 dsh.profile.bundles 组合层（本包的 cordis.patch.yml 即该层，挂载 fileTree 服务行）。
• 静态包没有动态插件的 harness.handle / host.call 私有 RPC，宿主能力改走 typert Gateway：宿主注册 @Remote 服务（lib/index.js 用纯 JS 复刻装饰器）， 客户端 ctx.remote.$mount(contribution) 挂载命名空间后调用 ctx.remote.fileTree.list({ path }) 等，两端由 zod 严格 codec 校验。

一、发布（发布者）

官方生态的发布位置就是 npm 官方 registry（https://registry.npmjs.org/）， 命名惯例为 dsh-* 或 @<scope>/dsh-*（参考 dsh-code、@dsh-feishu/dsh-feishu 等 社区包）。发布前请确认 lib/typert.js 的 TYPERT.package 与包名一致。

cd dsh-file-tree-panel
npm publish            # 发布到 npm（或改用私有 registry / Git 仓库）

二、安装（使用者）——官方一条命令

dsh plugin --profile web add dsh-file-tree-panel

该命令会：初始化 profile（如需要）→ 在 ~/.dsh/profiles/web 执行 pnpm add → 把本包自动加入 dsh.profile.bundles 组合层。之后重启 dsh（启动时 typert-loader 读取 exports["./typert"] 注册 fileTree 清单，clientModules 发现 dsh.client 包并重建客户端 bundle），打开页面（必要时强刷一次），右侧栏即出现 「📂 文件」面板——所有会话自动生效，无需任何手动改配置、创建或批准流程。

卸载：dsh plugin --profile web remove dsh-file-tree-panel 查看：dsh plugin --profile web list / dsh plugin --profile web why dsh-file-tree-panel 手动安装（不经过 dsh plugin 时）：pnpm add 到 profile + 在 cordis.patch.yml 加一行 - id: file-tree-panel / name: dsh-file-tree-panel，效果相同。

验证

• 右侧出现文件树，根目录 = 当前会话的工作目录（useSessions 快照的 cwd， 缺失时回退到 sandboxPolicy.workspaceRoot）。
• 展开子文件夹、点击文件预览；HTML 文件默认网页预览、可切「代码」。
• 会话标题栏出现「📂 文件」按钮，右侧栏被关闭时可重新打开。

三、故障排查

| 现象 | 原因 / 处理 | | --- | --- | | 启动报 Cannot find package 'dsh-file-tree-panel' | 包没装进 ~/.dsh/profiles/web 的依赖，重跑 pnpm add | | 报 TYPERT manifest names package ... | lib/typert.js 的 package 字段与包名不一致（改名发布时记得同步） | | 页面没有右侧栏 | 重启后 bundle 未重建：清缓存强刷；确认组合行已加且无 disabled | | 面板出现但树为空 / 报错 | 检查宿主日志中 fileTree 服务是否注册（service "fileTree" 相关报错多为清单未加载） | | 预览 HTML 空白 | 文件内引用的相对资源（图片/CSS/JS 文件）在 data URL 下无法加载——单文件 HTML 正常 |

四、从动态插件迁移的对照

| 动态插件（cordis_define） | 静态包（本仓库） | | --- | --- | | harness.handle('fs-list', ...) | FileTreeService.list() + @Remote 标记 | | host.call('fs-list', { path }) | ctx.remote.fileTree.list({ path }) | | Client styles.insert(css) 内置 | 受控 <style> 注入（ensureStyles()） | | 每次会话需 define + 批准 | 组合行安装后永久生效 |