前言¶
DeepSeek Harness (DSH) Web 是一个基于插件的架构，官方界面提供了基础的文件浏览能力。dsh-v-explorer 是一个官方右侧栏扩展插件，由用户 victor10035445 维护。它通过插件机制接管官方的 files 页型，提供增强的文件树体验，并新增了 bookmarks 页型与行区间引用摘录功能。该插件采用纯增量模式，卸载或降级即可恢复官方行为。
核心功能¶
1. Files Tab 接管¶
插件接管了官方的文件树页面，提供了目录懒加载、右键菜单和文件预览功能。
- 操作逻辑：点击文件会触发官方预览，点击目录仅展开折叠状态。
- 右键菜单：支持打开所在目录、复制路径、插入到会话、加书签（★）、默认浏览器打开 HTML。
- 文件显示：. 开头的隐藏文件照常显示（不提供书签功能）。
2. Bookmarks Tab 书签页¶
新增了一个书签页型，用于管理当前会话的文件引用。
- 会话作用域：书签与当前会话绑定，刷新或切换会话会重置书签状态。
- 持久化与同步：书签数据持久化存储在 <cwd>/.dsh-v-explorer/bookmarks.json，多标签页间通过 SSE 协议实时同步变更。
- 失效标记：当源文件被删除时，书签会保留并显示删除线。
- 限制：书签上限为 100 条，支持幂等去重。
3. 变更流自动刷新¶
插件利用官方的 ChangeFeed 机制构建了变更流，用于维护文件树和书签的同步状态。
- 重拉策略：目录展开时触发 500ms 去抖静默重拉。
- 摘除策略：当文件从目录中消失时，会即时摘除对应的书签或树节点。
4. 自动展开与布局¶
每次进入会话时，插件会自动展开官方右侧栏，并默认打开 files 和 bookmarks 两个页型。
- 宽度控制：默认宽度固定为 300px（此前官方视口 45% 过宽，插件通过接口做了契约修正）。
5. 行区间引用摘录¶
提供了一种引用文件特定区间的语法，方便将代码片段直接索引进提示词。
- 语法：<路径>#起-止。
- 机制：通过 agent/pre-step 捕获，发送时会生成对应的 composer chip。
6. 预览渲染器¶
接管了官方预览的渲染逻辑。
- 支持主题：Markdown Reader Pro 主题。
- 支持格式：JSON 美化渲染。
安装与启用¶
使用 DSH 命令行工具进行安装，需确保环境满足最低版本要求。
最低 DSH 版本：0.1.5-rc.2
# 安装插件
dsh plugin --profile web add "github:victor10035445/dsh-v-explorer"
数据目录说明：
插件会在工作区根目录创建 .dsh-v-explorer/ 目录，该目录被 .git/info/exclude 隐身，因此对 Git 工作区完全无感（幂等、零工作区改动）。
典型用法¶
安装后，在 Web 界面右侧栏即可看到新增的 bookmarks 页。
- 使用引用语法：在输入框中使用
<路径>#起-止语法，可以将文件中的特定行区间内容直接作为上下文发送。 - 管理书签：在
files树身或bookmarks子树上点击右键，选择“加书签 ★”或“切换展开状态”。失效的书签在书签页会显示删除线。 - 查看变更：文件树会自动跟随变更流刷新，消失的节点会即时摘除。
适用场景与注意¶
- 适用对象：DSH Web 用户，特别是需要频繁引用文件片段或管理本地代码书签的开发者。
- 权限与安全：插件运行在当前 DSH 进程的权限上下文中。读取文件路径时会经过词法 + realpath 双重校验，越界访问会被拦截（403），且文件读取上限为 10MB，包含二进制检测。
- SSE 说明：SSE 通信仅广播书签变更事件，不携带文件路径等会话敏感信息。
短结尾¶
dsh-v-explorer 通过插件形式补全了 DSH Web 在文件浏览、书签管理和代码片段引用上的短板。它通过接管官方组件而非重写界面，保持了与 DeepSeek Harness 生态的兼容性。更多细节与源码，可查阅插件目录或 GitHub 仓库。
