📁 子文件夹点击展开/折叠（懒加载，不预扫全树）
📄 点击文件在面板内直接预览内容：
- 文本 / 代码 / 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 + 批准	组合行安装后永久生效