description: "在 DeepSeek Harness Web profile 中浏览工作区文件树与只读源码。" kind: "package-bundle"

@tawny/dsh-client-ui-file-explorer

English | 中文

概要

在「对话」「轨迹」旁的「文件」Tab 中浏览工作区目录并预览文本与代码。

文件页填满常驻聊天输入区上方的可用区域，提供文件树、行号、换行、复制和手动刷新。

浏览状态属于工作区，不属于 Session。DSH 只在有内容的 Session 中显示此 Tab。

文件只读；标记语言仅显示源码，浏览文件不会调用模型。

目录

• 使用本包
• 实现说明
• 进一步阅读
• 模型可见影响
• 已知限制与后续范围
• 开发备注

使用本包

环境与兼容性

使用 Node.js ^22.19.0 || >=24.0.0 和 DSH Web profile。已验证的 DSH 发布版本为 0.1.2-rc.1。本第三方包从 0.1.0 首发，自身版本号独立于 DSH 发布版本。

安装到 Web profile

安装预构建的 npm bundle：

npx @deepseek-ai/dsh plugin --profile web add @tawny/dsh-client-ui-file-explorer

安装后重启 DSH Web。打开一个有内容的 Session 并选择「文件」。安装命令会添加依赖与 bundle 层，不替换已有 profile 设置。

npm 包包含构建好的入口，安装不需要源码构建或 DSH 源码补丁。无需额外添加 ui-conversation 覆盖包或 patchedDependencies。

浏览文件

在文件页选择工作区，展开目录并选择文件。工具栏支持收起文件树、刷新、换行和原样复制。在窄屏上，通过「返回文件树」从预览返回目录。

• 通过 DSH 侧栏添加工作区；文件页不能读取客户端任意指定的根目录。
• 展开的目录、选中文件、滚动、换行和文件树显示偏好按工作区保存在内存中。
• 切换 Session 会保留工作区浏览状态。DSH 按 Session 记住活动 Tab，因此另一 Session 可能先显示「对话」。
• 打开另一工作区中的 Session 时，文件页跟随切换工作区。在文件页手动选择工作区不会修改 Session 的工作区归属。
• 离开文件页会取消未完成的读取；已完成的预览与偏好在 Tab 卸载后保留。刷新页面或卸载插件会清空浏览状态。
• 重连会使内容缓存失效并按需重读；工作区被移除或根路径改变时，会清空对应浏览状态。

读取边界

Host 将已登记的工作区 ID 解析为根目录，并只接受相对路径。它拒绝路径穿越、工作区相对路径上的符号链接，以及规范化后位于所选根目录之外的路径。本包不提供写入、删除或执行操作。

单个 UTF-8 预览最多 256 KiB。二进制、非 UTF-8、超大文件和特殊文件显示说明。HTML、SVG 和 Markdown 保持源码文本。隐藏文件也会列出：仅向有权读取相应工作区的用户开放此 profile。

每个目录响应最多包含 500 项，目录优先排列，并在省略条目时提示。文件系统 provider 仍扫描该层目录，这不是后端分页。路径检查不能抵御具有本机写权限的恶意进程在检查与读取之间替换目录。

从 profile 移除

npx @deepseek-ai/dsh plugin --profile web remove @tawny/dsh-client-ui-file-explorer

重启 DSH 以卸载 bundle。移除插件不会删除工作区文件。

实现说明

cordis.patch.yml 插入 workspace-files 插件行。包清单 声明 Host 入口与 Web 客户端模块。bundle 安装在 profile 层级，不放入单个 Session preset。

Client 在 conversation.view 中追加一个条目。插件生命周期持有的控制器在 Tab 组件之外保存工作区状态。Host 读取通过现有已认证 Connection RPC 和文件系统 provider 完成；文件内容不会进入对话。

按钮、菜单、图标和剪贴板处理使用 DSH 提供的官方 UI primitives。局部 CSS 使用 DSH 主题与字体变量。最小 pre/code 预览保留原样文本、行号和换行控制，不修改官方内容组件的私有选择器。

全尺寸视图在自己的包装节点使用当前轨迹页的 data-conversation-composer-overlay 标记，并通过 --dsh-composer-height 为原生输入区预留空间。该标记触发宿主现有布局并隐藏聊天宽度拖柄。它不是正式 Slot 配置项；升级 SDK 时必须运行原生布局兼容性测试和真实浏览器回归。

在本 monorepo 中开发

在仓库根目录执行：

pnpm install --frozen-lockfile
pnpm check
pnpm --dir plugins/client-ui-file-explorer check:dsh

只读版本检查会将全部 DSH 开发 SDK 与启动器的 npm latest 发布版比较，不安装包或更新 profile。所有 DSH SDK 依赖使用同一个经过验证的精确版本，第三方库保留各自的版本体系。

静态检查覆盖注册、生命周期、文件系统边界和原生布局兼容性。浏览器回归还必须验证全尺寸布局、多行草稿、工作区隔离、滚动恢复、键盘焦点和窄屏导航。构建成功不能证明运行时已加载。

进一步阅读

• DSH 插件打包与安装
• 反馈问题

模型可见影响

本 bundle 不注册模型工具、不添加模型可见的提示文本，也不把预览内容复制到 Session 消息中。浏览文件不会触发模型调用。

已知限制与后续范围

• 已验证的运行时为 DSH Web 0.1.2-rc.1。未来 DSH 版本以及 Pawforge 等独立打包的桌面客户端需要另行验证。
• 空白或未选择的 Session 没有文件 Tab；本 bundle 不添加替代入口。
• 预览仅显示源码，不渲染 Markdown、HTML、SVG、图片或 PDF。
• 不包含编辑、终端、审查面板、语法高亮、多文件标签、搜索或文件变化监听。
• 浏览状态不持久化。源码构建依赖本 monorepo，不支持独立 GitHub 源码安装。

开发备注

无。