dsh-filescope

Readme

# FileScope · 文件视界

<p align="center">
  <img src="docs/screenshot.png" alt="FileScope 文件视界 预览" width="460">
</p>

把当前工作区的完整目录树搬进 DeepSeek Harness Web 页面的右侧抽屉：任意层级展开、
点击文件实时预览、切换会话自动跟随对应工作区、抽屉宽度与目录树高度均可拖拽调整。
**只读浏览，不修改任何文件。**

> 🔖 关联 topic：`dsh-plugin` · `deepseek-harness` · `file-explorer` · `workspace`

## 功能

- 📁 **抽屉式文件浏览器**：右侧全高抽屉滑入滑出，三个入口（侧边栏底部 / 会话顶部操作栏 / 遮罩点击收起）
- 🔗 **会话跟随**：切换会话自动把目录树切到该会话所属工作区（读取当前会话 cwd 匹配已注册工作区），手动浏览不受干扰
- 🌲 **完整目录层级**：无限层级展开/折叠，「全部展开」递归加载所有子孙层级（上限 3000 节点）、目录优先排序、文件大小标注、「隐藏点文件」开关
- ⚡ **实时渲染**：文本带行号（前 2000 行）、二进制文件 hex 摘要、超大文件提示
- 🔄 **实时刷新**：当前打开文件每 2s 检测版本变化自动重读；已展开目录每 5s 刷新
- ↔️ **拖拽调整**：抽屉左边缘竖条调宽度（320px–85vw），目录树与预览区之间横条调高度
- 🖥️ **路径自由**：工作区下拉选择 + 绝对路径输入回车
- 🔒 **只读安全**：GET-only JSON API，不提供任何写操作

## 安装

### 方式一：从 npm 安装（推荐）

```bash
dsh plugin --profile web add dsh-filescope
```

`dsh plugin` 会自动安装依赖并把包名登记进该 profile 的 `dsh.profile.bundles`。

### 方式二：从本地目录安装

```bash
dsh plugin --profile web add file:/绝对路径/dsh-filescope-plugin
```

### 方式三：手动接入 profile

1. 进入 profile 目录：`cd $DSH_HOME/profiles/web`（没有则先运行一次 `dsh --profile web` 触发初始化）；
2. 在 profile 的 `package.json` 中：

   ```json
   {
     "dependencies": { "dsh-filescope": "0.1.2" },
     "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-filescope"] } }
   }
   ```

3. 在 profile 目录执行 `pnpm install`。

### 重启生效

```bash
# 停掉当前 dsh web 进程后重新启动
dsh --profile web
```

Host 组合在进程启动时加载，新行需要重启才会挂载；重启后刷新浏览器页面
（`Cmd+Shift+R`）即可看到入口。

## 使用

- 侧边栏底部 / 会话顶部操作栏的「📁 文件视界」按钮打开抽屉；
- 切换会话时目录树自动跟随该会话所属工作区；
- 顶部下拉选择工作区，或输入任意绝对路径回车；
- 「全部展开」递归加载所有层级（上限 3000 节点）；「隐藏点文件」过滤 `.` 开头条目；
- 点击文件实时预览（文本带行号 / 二进制 hex 摘要 / 超大文件提示）；
- 「实时刷新」开启时每 2s 检测当前文件变化、每 5s 刷新已展开目录；
- 拖拽抽屉左边缘调宽度，拖拽目录树与预览区之间的分隔条调高度。

## 环境要求

- dsh 版本与本包构建时的源码树一致（浏览器端依赖 shell 模块表中的
  `react`、`ui-slots` 等平台模块，与 Host 的 `webServer` 行）；
- Web profile 已挂载 `dsh-web-app` 层（`@deepseek-ai/dsh-web-app`）。

## 接口（只读 JSON API）

| Endpoint | 返回 |
| --- | --- |
| `GET /filescope/workspaces` | `{ workspaces: [{ id, title, path, status }] }` |
| `GET /filescope/dir?path=<abs>` | `{ entries: [{ name, type, path, size? }] }` |
| `GET /filescope/stat?path=<abs>` | `{ exists, type, version, size? }` |
| `GET /filescope/file?path=<abs>` | `{ kind: text\|binary\|too-large, content?, size, version, hex? }` |

## 目录结构

```
dsh-filescope-plugin/
├── package.json          # 包清单（dsh.bundle 补丁 + dsh.client 浏览器声明）
├── cordis.patch.yml      # 组合补丁：把 filescope 宿主行插入 profile
├── docs/
│   ├── screenshot.png    # 效果图
│   └── preview.html      # 效果图源文件
├── lib/
│   ├── index.js          # Host 半（/filescope 只读 API，零运行时依赖）
│   ├── client.js         # 浏览器半（抽屉 UI，预构建 bundle）
│   └── types/            # TypeScript 声明（供接入方类型检查）
├── src/                  # 源码（参考/二次开发用）
├── LICENSE
└── README.md
```

## 许可

[MIT](LICENSE) © 2025 zhangkun