路径悬停打开器whw19761006/path-click

path-click

一个 DeepSeek Harness（DSH）Web 界面插件：把鼠标悬停到文件路径或网址上，会弹出一个气泡菜单，一键在「资源管理器」中显示，或用默认浏览器打开——任何文件类型都能在浏览器里打开，效果等同于把 file:// 地址粘贴到浏览器地址栏。

🇨🇳 中文 | 🇬🇧 English

功能

- 悬停消息里的文件路径（行内代码、产物 chips、文件提及）→ 气泡菜单：
- 📁 在资源管理器中显示：文件打开其所在文件夹，文件夹直接打开
- 🌐 用浏览器打开：无论什么文件类型，都在默认浏览器中打开（HTML、JS、图片、日志……）
- 悬停网址（http/https/file/mailto 链接）→ 用默认浏览器打开
- 工具调用卡片里的文件路径（含相对工作区的路径）同样支持
- 气泡采用纵向布局，鼠标可以放心从路径移到按钮上，不会中途消失

工作原理

插件分两部分，通过一个包同时加载：

| 部分 | 文件 | 职责 |
|---|---|---|
| 宿主端 | lib/index.js | 注册 /path-click HTTP 路由，执行打开动作；作为 bundle 被 loader 加载 |
| 浏览器端 | lib/client.js | 悬停检测与气泡 UI；通过 dsh.client 声明被 dsh-client-modules 自动发现并注入页面 |

打开机制（Windows）

- 资源管理器：直接 explorer.exe （文件 → 打开其所在文件夹；不依赖 explorer 的 /select, 开关，该开关跨进程传递时极不可靠）
- 浏览器（文件路径）：从注册表 http\UserChoice 关联探测默认浏览器程序（Chrome / Edge / Firefox 等），把 file:// URL 作为命令行参数交给它——绕开文件类型关联，所以 .js、.lnk 等无关联类型也能在浏览器中打开，且不会弹出"选择打开方式"
- 浏览器（http/https）：同一机制；mailto: 走 rundll32 url.dll,FileProtocolHandler

为什么不直接用 ShellExecute / start？ShellExecute 对 file:// 链接会走文件类型关联：HTML 能打开，但 .js 这类会弹"选择打开方式"，且 explorer.exe 拿到 file:// 会自己在资源管理器中导航。直接调用浏览器程序是最可控的方案。

安全设计

- 路由不在 /api 前缀下（该前缀由 DSH 的固定路由表把持，第三方插件无法扩展），因此自带信任围栏：
- 仅接受 POST + application/json（强制浏览器预检，防跨站请求）
- Origin 必须等于 http://，且 Host 必须是回环地址（127.0.0.1 / localhost / ::1）——同时防跨站 CSRF 与 DNS rebinding
- 打开动作仅在回环部署（本机访问）下启用
- URL 协议白名单：仅 http: / https: / file: / mailto:；拒绝含引号/换行的值
- 路径含 % 字符时拒绝用浏览器打开（避免 cmd 环境变量展开问题）
- 浏览器端对所有请求的路径做存在性校验后再调用系统

已知问题与设计取舍

- 相对路径（如工具卡片里的 plugins/foo/bar.js）按宿主进程 cwd 解析；默认部署中 cwd 即工作区根，所以正确；若工作区不是宿主启动目录，相对路径会解析错位
- 路径尾部反斜杠会被剥掉再传给 explorer（path\" 会破坏命令行引号解析，导致 explorer 回退打开默认文件夹）
- 思考过程（Think）等大段纯文本里嵌着的路径不支持悬停（为避免误匹配，只对"元素内容恰好是路径"的文本生效）
- macOS / Linux 分支（open -R / xdg-open）已实现但未在真机验证

安装

前置：已安装 DSH（dsh 命令可用）与 pnpm。

从 git 仓库安装

dsh plugin --profile web add github:harmony520/path-click

从本地目录安装

dsh plugin --profile web add /path/to/path-click

Windows 注意：路径含空格（如用户名 "Mo Haowei"）时，dsh plugin 的 pnpm 转发会拆坏参数。可改用直接 pnpm：

cd %USERPROFILE%\.dsh\profiles\web
pnpm add C:\path\to\path-click

然后把 "path-click" 手动追加到该目录 package.json 的 dsh.profile.bundles 列表。

安装后重启 DSH（关闭控制台窗口，重新启动），浏览器页面按 F5 刷新。

客户端模块（lib/client.js）的改动支持热更新：DSH 每 500ms 轮询一次模块文件，改了保存即可在当前窗口生效，无需重启。宿主端（lib/index.js）与包名/配置改动需要重启。

使用

1. 打开 DSH Web（默认 http://127.0.0.1:3080）
2. 把鼠标悬停到任意文件路径或网址上
3. 点击气泡里的按钮

卸载

dsh plugin --profile web remove path-click

开发与测试

语法检查
node --check lib/index.js
node --check lib/client.js

宿主逻辑单元测试（校验、信任围栏、路径规范化；不会真正打开任何窗口）
node test-host.mjs

诊断日志：%TEMP%\path-click.log（每次打开动作记录命令与结果，排查问题用）。

目录结构

path-click/
├── lib/
│   ├── index.js      # 宿主端：/path-click 路由、信任围栏、打开逻辑、默认浏览器探测
│   └── client.js     # 浏览器端：悬停检测与气泡工具条（dsh.client 模块）
├── cordis.patch.yml  # bundle patch：注册 loader 行
├── package.json      # dsh.bundle + dsh.client 声明
├── test-host.mjs     # 宿主逻辑单元测试
└── README.md

兼容性

- 针对 DSH 0.1.0-rc.6 开发
- Windows 为主要目标平台；macOS / Linux 分支存在但未验证
- 依赖浏览器默认关联可读（reg.exe），否则回退到 cmd start / rundll32

License

MIT