dsh-workspace-view

简体中文 · English

dsh-workspace-view 是一个面向 DeepSeek Harness Web GUI 的工作区文件浏览插件。它在页面右侧提供一个默认展开的文件树抽屉，用于查看当前会话所属工作区的目录与文件。

功能特性

• 在页面右侧显示全高文件树抽屉
• 根据当前 Session 自动切换工作区
• 按需加载目录内容，避免启动时递归扫描整个仓库
• 目录优先、文件随后，并按名称排序
• 支持展开和折叠文件夹
• 支持刷新当前文件树
• 支持显示或隐藏点文件
• 关闭后收缩为页面右侧的窄把手
• 提供中文和英文界面文案
• 使用 DSH Theme Token，自动适配宿主主题
• 包含加载、空目录、无会话、截断和错误状态

运行要求

• Node.js 版本应符合 DeepSeek Harness 的运行要求
• pnpm
• 用于安装和运行插件的 DeepSeek Harness 环境

插件自身的安装、测试和构建使用已发布的依赖版本，不要求源码仓库与 deepseek-harness checkout 并列放置。只有将本地包安装到 DSH 或使用临时 Patch 启动时才需要提供 Harness 路径。

设计与架构

本插件遵循 DSH 的 Cordis 插件模型，由 Host 和 Client 两部分组成。

Host

Host 插件注入以下服务：

• webServer：注册只读目录查询接口
• sessions：根据 Session id 获取由 Host 管理的权威工作区路径

Host 不接受客户端指定工作区根目录。每次目录查询都会：

1. 根据 Session id 从 Session Store 获取 cwd。
2. 对工作区根目录和目标目录执行 realpath。
3. 使用 relative 验证目标目录没有越出工作区。
4. 打开目录后再次校验真实路径，拒绝验证与打开阶段之间发生的路径替换。
5. 按配置限制扫描量和返回条目数。
6. 只向客户端返回稳定的公共错误信息。

该流程可阻止 .. 路径穿越和符号链接逃逸。

Client

Client 插件注册到 additive shell.overlay Slot，在页面右侧渲染文件抽屉。它不会注册或替换以下 Slot：

• sidebar
• sidebar.workspaces
• sidebar.settings

因此不会移除或覆盖 DSH 原有的工作区、会话和设置界面。

当前 Session 和工作区路径来自 Slot 提供的 useSessions 标准属性。目录在用户展开时按层请求，并会取消已经失效或被刷新取代的请求。

安装

安装到 Web Profile

先完成依赖安装和构建：

cd /path/to/dsh-workspace-view
pnpm install
pnpm run build

使用 DSH 插件管理命令将本地包安装到 Web Profile：

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-workspace-view

检查最终配置：

pnpm dsh --profile web --dump-config

启动 Web GUI：

pnpm dsh web

默认访问地址：

http://127.0.0.1:3080

如果 Web GUI 已经运行，需要重启原进程才能加载新的 Host 插件和 Client manifest。

移除插件

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web remove dsh-workspace-view

本地开发

临时 Patch 方式

如不希望写入 Web Profile，可以将本包链接到 Harness 的依赖解析目录，并通过临时 Patch 启动：

cd /path/to/deepseek-harness
mkdir -p node_modules
ln -sfn /path/to/dsh-workspace-view node_modules/dsh-workspace-view
pnpm dsh web --patch /path/to/dsh-workspace-view/cordis.patch.yml

常用命令

# 安装依赖
pnpm install

# TypeScript 类型检查
pnpm run typecheck

# 运行测试
pnpm test

# 构建 Host 和 Client 产物
pnpm run build

# 验证已提交的 lib 产物与源码一致
pnpm run check:dist

# 检查发布内容；prepack 会先重新构建
pnpm pack --dry-run

重新加载说明

本项目是 Harness checkout 之外的外部插件，不属于 Harness 自带 pnpm run dev:web 的 workspace 扫描范围。

• 修改 Client 代码后：先运行 pnpm run build。对于外部插件，可靠的生效方式仍是重启当前 DSH Web 进程，再刷新页面。
• 只有在已确认 pnpm run dev:web watcher 正在重建本插件，并且其 HMR receiver 连接到当前 DSH 进程时，才能依赖自动更新。
• 修改 Host 代码、插件配置或 package.json 中的 dsh.client 元数据后：必须重启 DSH Web。
• 单独启动另一个 Vite server 不会重算当前进程的 Client manifest，也不会更新已经运行在 127.0.0.1:3080 的 GUI。

配置

插件配置位于 cordis.patch.yml：

- insert:
    - id: workspace-view
      name: dsh-workspace-view
      config:
        maxEntries: 500
        maxScannedEntries: 10000
        maxConcurrentScans: 8
        ignoredNames:
          - .git
          - node_modules

字段	类型	默认值	约束	说明
maxEntries	number	500	1–5000	每层最多返回给 Client 的条目数
maxScannedEntries	number	10000	1–50000	Host 每层最多扫描的目录项数量，用于限制超大目录的 CPU 与内存消耗
maxConcurrentScans	number	8	1–64	Host 同时执行的目录扫描上限；超出时返回 HTTP 429
ignoredNames	string[]	['.git', 'node_modules']	—	Host 完全忽略的文件或目录名称

ignoredNames 与隐藏文件开关的行为不同：

• 被 ignoredNames 匹配的条目不会由 Host 返回。
• 其他点文件仍会返回，但默认在界面中隐藏，可通过抽屉工具栏切换显示。

当扫描或返回结果超过上限时，Client 会在对应目录层级显示截断提示。

安全模型

插件只提供工作区范围内的只读目录列表能力，不提供文件写入、删除、重命名或执行功能。

主要安全约束：

• 工作区根目录由 Host Session Store 决定
• 客户端不能自行指定根目录
• 常规路径和静态符号链接解析必须位于工作区的真实路径之下
• 打开目录后再次验证真实路径，降低验证与枚举之间的并发路径替换风险
• 受 Node.js 跨平台目录 API 限制，该检查不是 openat 式原子能力边界；不应把可由不受信任本地进程并发改写的工作区作为强隔离沙箱
• Host 对单次扫描、返回数量和并发扫描数均设有明确上限
• HTTP 客户端中断请求后，Host 会停止对应扫描
• 原始文件系统错误不会直接暴露给浏览器

项目结构

.
├── assets/
│   └── dsh-workspace-view-logo.png       # 仓库 Logo
├── cordis.patch.yml
├── package.json
├── README_en.md
├── src/
│   ├── index.ts                         # Host 插件与目录查询接口
│   └── client/
│       ├── index.ts                     # Client Slot 注册
│       ├── controller.ts                # 抽屉状态控制器
│       ├── locales.ts                   # 中英文文案
│       ├── WorkspaceFiles.tsx           # 文件树与抽屉界面
│       └── WorkspaceFiles.module.css    # 组件样式
├── tests/
│   ├── client.spec.tsx                  # 请求取消、状态保留和焦点测试
│   └── host.spec.ts                     # 路由、排序、截断和路径边界测试
├── .github/workflows/ci.yml             # 类型、测试、构建和发布检查
├── LICENSE
├── tsconfig.json
└── tsdown.config.ts

构建产物输出到 lib/。package.json 通过 dsh.bundle.patch 声明随包安装的 Cordis Patch，并通过 dsh.client 声明 Web Client bundle 及其依赖图。

已知限制

• 当前版本只浏览文件树，不读取或预览文件内容。
• 文件系统发生变化后需要手动刷新。
• 大型目录达到配置上限时只显示部分条目。
• 抽屉通过 shell.overlay 实现，会覆盖页面最右侧区域，而不会参与 DSH 核心列宽求解。
• 对可由恶意本地进程并发替换的工作区路径，仍需未来的原子 Host 文件系统能力才能提供强隔离。
• 外部插件开发模式不具备 Harness workspace package 的完整自动重建体验。

License

MIT