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 安装（推荐）

dsh plugin --profile web add dsh-filescope

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

方式二：从本地目录安装

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。

重启生效

# 停掉当前 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