DSH Web Client 的 VSCode 风格文件树侧栏插件：dsh-ymc-sidebar

前言¶

DeepSeek Harness (DSH) Web Client 原生的文件浏览通常依赖于 details 面板。这种方式在空白会话或需要独立布局时存在局限。dsh-ymc-sidebar 插件通过挂载在 document.body 上的方式，为 Web Client 提供了一个独立的右侧文件树侧栏。它不占用 DSH 原生的 details slot，因此即使是在无上下文的 blank 会话中也能正常工作，并实现了类似 VSCode 的布局体验。

核心功能¶

该插件主要包含三个核心视图和一个文件树系统。

视图与布局¶

Activity Bar 图标栏：侧栏最右侧提供常驻的 VSCode 风格 Activity Bar，包含“文件资源管理器”、“Git 追踪”和“浏览器”三个视图。点击当前视图图标可收起/展开侧栏。
拖拽调整宽度：侧栏左侧边缘支持拖拽调整宽度，最小宽度为 280px，且状态会持久化存储。
布局 push：插件通过 --dsh-sidebar-width 属性让原生的 #root 元素让出右侧空间，形成“真占位”效果，而非覆盖。

文件资源管理器¶

虚拟化懒加载：以当前会话的工作区目录（cwd）为根展示文件树。目录和树结构均采用虚拟化懒加载，防止大目录导致性能问题。
文件预览：点击文件后，在右栏下方预览内容。支持文本/代码（带行号与语法高亮）、Markdown 渲染/源码切换，以及常见图片格式预览。二进制文件会显示为二进制提示。
多标签页：支持同时打开多个文件，具备横向滚动和关闭功能。

Git 追踪视图¶

功能子页：提供“改动”、“历史”和“分支”三个子页。
- 改动：查看当前分支、暂存区、工作区未暂存改动及未跟踪文件，支持行级高亮的 diff 预览。
- 历史：查看提交记录、提交信息及单次提交 diff。
- 分支：管理本地/远端分支列表，支持切换分支或检出远端分支。
操作与刷新：面板头部提供 Pull 和 Push 操作（带确认框）。所有状态、diff、历史和分支会随文件变化和 Git 元数据变化自动刷新。

浏览器视图¶

Loopback 路由：支持在文件树中选择 .html / .htm 文件，自动切换到浏览器视图并打开。插件提供自身的 Loopback HTTP 路由，使得本地 HTML 引用的相对资源（CSS / JS / 图片等）能正确加载。
网页浏览：提供自绘搜索首页（默认为必应搜索）和地址栏。支持多标签页浏览，标签页保留各自的导航历史。
HTML 快捷菜单：浏览器面板头部提供当前工作区 HTML 文件的快捷菜单，可快速跳转打开本地文件。

安装与启用¶

环境要求¶

DeepSeek Harness (DSH): 0.1.2-alpha.2 或更新版本。
Node.js: 20+
pnpm: 10+
Git: 本地 git 命令（用于 Git 追踪功能）。

安装命令¶

插件已发布至 npm，可直接通过 DSH 插件命令安装：

dsh plugin --profile web add @kaijia/dsh-sidebar

安装完成后，重启 dsh web 即可看到右侧的侧栏。确认配置生效可执行：

dsh --profile web --dump-config

输出中应包含 # == @kaijia/dsh-sidebar 层。

配置¶

安装后，可以在 cordis.yml 配置文件中通过 insert 配置项调整插件行为。默认配置如下：

- insert:
    - id: dsh-sidebar
      name: '@kaijia/dsh-sidebar'
      config:
        maxTextBytes: 2097152
        maxImageBytes: 8388608
        maxEntriesPerDirectory: 2000
        maxTreeRows: 100000
        watchEnabled: true
        watchDebounceMs: 200
        watchIgnored:
          - '**/node_modules/**'
          - '**/.git/**'

配置项	默认值	说明
`maxTextBytes`	`2097152`	单次文本预览上限（UTF-8 字节）。
`maxImageBytes`	`8388608`	单张图片预览上限（字节）。
`maxEntriesPerDirectory`	`2000`	单目录最多返回的条目数，超出时截断。
`maxTreeRows`	`100000`	客户端展开后可扁平化的最大树行数。
`watchEnabled`	`true`	是否开启文件监听实时刷新（依赖 chokidar）。
`watchDebounceMs`	`200`	触发通知的等待时间（毫秒）。
`watchIgnored`	`['/node_modules/', '/.git/']`	文件监听忽略的 glob 路径列表。

使用示例¶

调整侧栏：在侧栏展开状态下，拖拽左侧边缘调整宽度；点击最右侧的 Activity Bar 图标收起侧栏。
浏览文件：在文件树中选择文件查看预览；在“浏览器”视图输入网址或使用搜索框。
本地 HTML：在文件树中点击 .html 文件，侧栏会自动切换至“浏览器”视图并打开该文件。
Git 操作：在“Git 追踪”视图头部点击 Pull 或 Push，或在“分支”页面切换分支。

依赖与注意事项¶

Blank 会话：插件不依赖 DSH 原生的 details slot，因此可以在无上下文的 blank 会话中打开。
工作区依赖：文件树内容依赖于当前会话的工作区目录（cwd）。如果当前会话没有 cwd，右栏会显示提示信息。
Git 依赖：Git 追踪功能依赖本机已安装的 git 命令，且当前工作区目录必须是 Git 仓库。
图片支持：仅支持 png / jpg / jpeg / gif / webp / bmp / ico / avif 格式。

开发与维护¶

插件采用 Host/Browser 分离架构。源码位于 src/index.ts（Host 入口，负责 RPC、文件系统、Git）和 src/client.tsx（Browser 入口，负责 React 组件与样式）。

本地开发：克隆仓库后，执行 pnpm install 和 pnpm build，再使用 dsh plugin --profile web add . 安装。
样式：使用 Tailwind CSS，直接消费 DSH 的主题 alias token（--dsw-alias-*），支持明暗主题切换。

结尾¶

dsh-ymc-sidebar 为 DSH Web Client 提供了一套完整的文件管理、代码预览和 Git 追踪方案，且不侵入原生界面。适合需要在 Web 端获得类似 VSCode 开发体验的用户。

目录页: kaijia323/dsh-ymc-sidebar
GitHub: kaijia323/dsh-ymc-sidebar