dsh-local-filetree

Readme

# dsh-local-filetree
（作者找到了更好的侧边栏，所以暂时不更新了）

DSH Web UI 右侧文件树插件（静态 bundle，本地安装）。

> **许可**：插件自身代码为 MIT（见 [`LICENSE`](LICENSE)）；内嵌的文件类型图标为第三方 MIT 许可作品，署名与完整声明见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)（发布到 GitHub 时请保留该文件）。

- **右侧栏**：侧边栏底部的「文件树」按钮打开 Web UI 右侧 `details` 栏（360px 起，可拖拽调宽），显示**当前会话工作区**的目录树。
- **懒加载**：逐层展开时经 `/filetree/list` 拉取一层（Host 的 `ctx.fs.listDir`，只读），不递归整盘。
- **可回滚**：文件树以 `priority: -1` **影子占用** `details` 插槽；面板内「恢复工具详情」或再次点击侧边栏按钮即取消注册，出厂的工具详情面板自动回归。
- **文件类型图标**：136 种扩展名 + 22 种文件名映射（js/ts/py/rs/go/json/md/html/css/…），目录用 Folder/FolderOpen；图标取自 OpenCode.app 内置的 vscode-icons sprite（MIT 许可），颜色内联、按需抽取内嵌（63KB），符号内部渐变 id 已重写防冲突。
- 支持：目录优先排序、文件大小显示、隐藏文件开关、手动刷新、错误就地展示（权限/不存在/IO）。

## 结构

| 文件 | 作用 |
| --- | --- |
| `cordis.patch.yml` | bundle patch：挂载 `filetree` 行（`dsh.client` 清单同时使其进入浏览器 roster） |
| `lib/index.js` | Host 半：`ctx.fs` + `webServer.register('/filetree')`，`GET /filetree/root`、`GET /filetree/list?path=` |
| `lib/client.js` | Client 半：`window.__ModuleLoader__.load` 格式 bundle，`sidebar.footer.action` 按钮 + `details` 影子占用 + 内嵌图标 sprite |
| `scripts/build-icons.mjs` | 图标生成器：从 vscode-icons 布局的 sprite 抽取 symbol、重写内部 id、注入 `@file-icons-start/end` 标记区（用法见 THIRD_PARTY_NOTICES） |
| `test/smoke-host.mjs` / `test/smoke-client.mjs` | 冒烟测试 |
| `LICENSE` / `THIRD_PARTY_NOTICES.md` | 插件 MIT 许可；图标第三方声明（发布必须保留） |

## 安装

1. 将本包放入你的 workspace（或任意外部目录），并在 DSH web profile 中安装为 bundle：
   - 把包目录链接/安装进 profile 的 node_modules（`dsh plugin --profile web add <路径或包名>`）；
   - 在 `.dsh-home/profiles/web/package.json` 的 `dsh.profile.bundles` 中加入包名（示例见下）。
2. **重启生效**：静态 bundle 变化需要重启 `dsh web`（加载器在启动时扫描）。重启后：
   - 侧边栏底部出现「文件树」按钮；
   - 点击后右侧栏打开文件树，根为当前会话工作区；
   - 面板内「恢复工具详情」还原出厂右侧栏。

```jsonc
// .dsh-home/profiles/web/package.json
{
  "dependencies": { "dsh-local-filetree": "file:<本包路径>" },
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-local-filetree"] } }
}
```

## 验证

- `curl 'http://127.0.0.1:8787/filetree/root'` → `{"ok":true,"path":...}`
- `curl 'http://127.0.0.1:8787/filetree/list?path=<abs>'` → `{"ok":true,"entries":[{"name","type","path","size"},...]}`
- 浏览器 DevTools → Network：`/plugins/dsh-local-filetree/client.js?rev=...` 200。

## 已知限制

- 动态插件才有的 `harness.handle`/`host.call` 包私有 RPC 不适用于静态 bundle；本插件用同源 HTTP 路由（`webServer.register`）作为数据通道，信任边界与 agent 的 fs 工具一致（localhost 任意进程可读路径/元数据）。
- `details` 是 single 插槽：文件树激活期间，工具调用详情面板被影子替换（点工具行会打开文件树而不是详情），「恢复工具详情」按钮可随时还原。与详情并存需要改 layout bundle（新增独立右栏插槽），超出本插件范围。
- 无文件监视（fs 接口无 watch 原语），手动「刷新」。
- 目录一次最多展示 host 返回的全部条目（`fs.listDir` 单层无分页）；超大目录由浏览器滚动承载。