path-click

Readme

# path-click

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

🇨🇳 中文 | [🇬🇧 English](README.en.md)

## 功能

- 悬停消息里的文件路径（行内代码、产物 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>`，且 `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](https://pnpm.io/)。

### 从 git 仓库安装

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

### 从本地目录安装

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

> **Windows 注意**：路径含空格（如用户名 "Mo Haowei"）时，`dsh plugin` 的 pnpm 转发会拆坏参数。可改用直接 pnpm：
>
> ```powershell
> 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. 点击气泡里的按钮

## 卸载

```bash
dsh plugin --profile web remove path-click
```

## 开发与测试

```bash
# 语法检查
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](LICENSE)