dsh-v-explorer · V 文件探索器
简体中文 | English
DeepSeek Harness Web 的官方右侧栏扩展插件：以 extension 接管官方 files 页型提供增强文件树，新增书签页型与行区间引用摘录。纯增量——卸载/降级即恢复官方树。最低 DSH 版本：0.1.5-rc.2。
功能
- files tab（接管官方文件树）：目录懒加载、点文件
openResource 进官方预览、点目录仅展开；右键菜单——打开所在目录 / 复制路径 / 插入到会话 / 加书签★ / 默认浏览器打开 HTML；. 开头隐藏段照常显示（不提供书签）
- bookmarks tab（新增页型）：会话作用域书签列表，每个书签是子树虚拟根（懒加载、展开状态独立）；失效书签保留并删除线标记；与 files 树身共享同一仓库（★ 角标 + 右键 toggle 双入口）；持久化
<cwd>/.dsh-v-explorer/bookmarks.json（上限 100、幂等去重），多标签页经 SSE 实时同步
- 变更流自动刷新：经官方 ChangeFeed 语义自建托管流，500ms 去抖静默重拉展开目录；可见性 / focus 兜底；目录读取由官方 workspaceFiles Remote 承担
- 新会话自动展开官方右侧栏（低频轮询观测，仅存续期运行）
- 「引用」摘录：
引用<路径>#起-止 语法把文件区间索引进提示词；agent/pre-step 捕获即定格，失败只降级不失败整轮；会话框选发送，composer chip 条实时管理（经官方 input facade 读写草稿）
- 预览渲染器：Markdown Reader Pro 主题与 JSON 美化，供官方预览渲染
安装
dsh plugin --profile web add "github:victor10035445/dsh-v-explorer" # 直装（推荐）
dsh plugin --profile web add "github:victor10035445/dsh-v-explorer#<sha>" # 锁定版本
本地开发：
git clone https://github.com/victor10035445/dsh-v-explorer.git
dsh plugin --profile web add "link:<克隆路径>"
装完重启 dsh web，刷新页面生效。已装环境也可在 ~/.dsh/profiles/web/cordis.patch.yml 加 - insert: [{id: dsh-v-explorer, name: dsh-v-explorer}] 热重载（patchReload: live）。
从源码构建
pnpm install
pnpm build # esbuild: src/client.jsx → lib/client.js
pnpm check # 语法检查 + externals 漂移检查（check-externals.mjs）
架构
| 模块 | 内容 |
|---|
宿主 lib/index.js | /api/dsh-v-explorer/* 保留路由（open / open-browser / snapshot / bookmarks / events）+ agent/pre-step 摘录捕获；路径安全：词法 + realpath 双重包含校验，越界一律 403 |
客户端 src/ | 官方侧栏 tab 接管（files / bookmarks）+ 变更流枢纽 + 引用摘录 + 预览渲染器；按职责拆分为独立模块 |
check-externals.mjs | 构建期 externals 漂移检查：bundle 的全部裸 require 必须命中平台模块表（seed word 或已声明），dsh.client 声明不得悬空 |
build.mjs | esbuild 打包成 factory 形式；react 等 seed 依赖 external |
安全
- 保留路由与摘录读取限定会话 cwd 内：词法 + realpath 双重校验，逃逸 403；10MB 上限 + 二进制检测
- 数据目录
.dsh-v-explorer/ 经项目 .git/info/exclude 对 git 完全隐身（幂等、失败静默、零工作区改动）
- SSE 只广播书签变更事件，不携带文件路径等会话信息
文件与校验
package.json / cordis.patch.yml 插件清单与 loader 插入条目
lib/ 宿主端 + 客户端 bundle + 共享模块（随仓库提交）
src/ 客户端源码（tab / 变更流 / 引用 / 渲染器等模块）
tests/ 可运行校验（Node，无浏览器）
pnpm check # 语法检查 + externals 漂移检查
node tests/check-externals-smoke.mjs # externals 检查器自验证
node tests/auto-open-smoke.mjs # 侧栏自动展开冒烟
node tests/workspace-path-smoke.mjs # 会话资源地址/路径工具冒烟
node tests/renderer-logic-smoke.mjs # 预览渲染器逻辑冒烟
node tests/css-transform-smoke.mjs # 主题作用域变换冒烟
node tests/host-smoke.cjs # 宿主端路由 + 摘录捕获 + SSE 冒烟
node tests/bookmarks-smoke.mjs # 书签存储/API/SSE 冒烟
node tests/ref-shared-smoke.mjs # 引用语法解析/切片冒烟
node tests/verify-install.cjs # 安装发现校验（需 profile 已装本包）
License
MIT
