dsh-web-browse

Readme

# dsh-web-browse · 网页浏览

DSH 的通用网页浏览插件：在 **DshDesktop** 桌面壳与 **Edge/Chrome 等通用浏览器** 中，
都能把网页以**独立标签页**打开。

- **DshDesktop**：打开的是桌面网页标签页，网页顶部由 **WebView2 扩展**注入地址/搜索栏，
  不再使用 iframe，彻底解决站点禁止内嵌的问题；
- **通用浏览器**：没有 `window.dshDesktop` 桥，直接 `window.open` 新开浏览器标签页，
  仅保留「新标签页打开」能力。

## 功能特性

| 功能 | 说明 |
| --- | --- |
| 侧边栏快速入口 | 侧边栏「🌐 网页浏览」按钮：**左键**打开默认网址；**右键**弹出悬浮搜索框 |
| 悬浮搜索框 | 输入网址直接访问；输入文字按所选引擎搜索；确认后在新标签页打开；Esc 或点击框外关闭 |
| 选中文本搜索 | 页面选中文本后右键，原生菜单「复制」下方出现「🔍 搜索选中文本」，点击即搜（仅 DshDesktop） |
| 新标签页打开 | DshDesktop 中为桌面网页标签页；通用浏览器中为浏览器新标签页 |
| 网页顶部栏 | WebView2 扩展为网页标签页注入顶部地址/搜索栏（仅 DshDesktop） |
| 网页浏览设置 | 默认网址、启动自动打开、搜索引擎（内置 + 自定义） |

## 架构

```
dsh-web-browse/
├── lib/          harness 插件：侧边栏按钮、悬浮搜索框、「网页浏览设置」（localStorage）
├── extension/    WebView2 扩展（MV3 内容脚本）：网页顶部地址/搜索栏（仅 DshDesktop）
├── dsh.plugin.json
├── cordis.patch.yml
└── package.json
```

### harness 插件（lib/）

- **侧边栏按钮**
  - **左键**：打开默认网址——DshDesktop 调用 `window.dshDesktop.openWebTab(url)`
    新开/激活一个**桌面网页标签页**（不占用聊天区）；通用浏览器直接
    `window.open(url, '_blank')` 新开浏览器标签页；
  - **右键**：弹出**悬浮搜索框**——输入网址回车直接访问；输入普通文字用所选
    搜索引擎（内置/自定义）搜索；确认后在新标签页打开；Esc 或点击框外关闭。
- **右键菜单搜索（不重写右键）**：DshDesktop 宿主在 WebView2 **原生右键菜单
  「复制」正下方**追加「🔍 搜索选中文本」项（见宿主 `Form1.OnContextMenuRequested`），
  点击即以选中文本打开悬浮搜索框（可换引擎后再确认）；无选中文本等其余情况原生菜单
  **原样保留**。通用浏览器中宿主菜单不可用——原生菜单不可由页面修改。
- **网页浏览设置**（harness 设置 →「网页浏览设置」）：默认网址（默认
  `https://chat.deepseek.com`）、启动时自动打开、搜索引擎（内置 Bing / 百度 /
  Google，可自定义含 `{q}` 的 URL 模板）。设置保存在本机 localStorage；DshDesktop
  中经 `window.dshDesktop.setWebSettings()` 同步给桌面宿主，由宿主分发给所有网页
  标签页的顶部栏；通用浏览器中该同步为 no-op。

### WebView2 扩展（extension/）

- **自动加载**：DshDesktop 启动时（及每 30 秒）自动扫描 harness 的 `plugins`
  目录，识别其中的 WebView2 扩展（插件目录本身含 `manifest.json`，或含
  `extension/` / `web-extension/` / `ext/` 子目录）并加载；
- **顶部栏**：在非 harness 页面（排除 `127.0.0.1:3080` 与本地设置页）注入固定
  顶部栏——后退/前进/刷新、地址栏（输入网址直接访问；输入文字用所选引擎搜索，
  回车前显示将访问的网址/引擎与查询词）、搜索引擎下拉、新标签页、最小化（隐藏、
  切回主页、页面保活）、关闭（关闭标签页）；
- **与宿主通信**：内容脚本运行在隔离世界，经 `window.postMessage` 把命令转发给
  宿主注入的主世界桥 `window.dshDesktop`，再经 `chrome.webview.postMessage` 到达
  宿主；宿主回执按原路返回。无 background/service worker，不依赖 `chrome.storage`，
  设置全部来自宿主缓存。

## 使用说明

- **DshDesktop**：完整能力——侧边栏入口、桌面网页标签页、顶部地址/搜索栏、
  右键菜单搜索、设置同步到所有网页标签页；
- **通用浏览器（Edge / Chrome 等）**：所有「打开标签页」操作（左键 / 右键搜索 /
  选中文本搜索 / 设置页「立即打开」/ 启动自动打开）都回退为
  `window.open(url, '_blank')` 直接新开浏览器标签页；顶部栏注入与右键菜单搜索
  不可用。非用户手势触发的打开（如启动自动打开）可能被浏览器弹窗拦截，失败时
  以轻提示告知。

## DshDesktop 配套接口

| 类别 | 接口 | 说明 |
| --- | --- | --- |
| 桥接脚本 | `openWebTab(url)` / `newWebTab(url)` / `setWebSettings(settings)` | 打开/新建网页标签页、同步设置；对每个标签页（含网页标签页）注入 |
| 右键菜单 | `Form1.AddSearchSelectionMenuItem` | 「复制」下方追加「🔍 搜索选中文本」，经 `ExecuteScriptAsync` 调用页面 `__dshWebBrowseSearch(text)` 打开悬浮搜索框（`__dshChatWebSearch` 保留为兼容别名）；插件侧不再接管右键菜单 |
| 宿主命令 | `tab.open` / `tab.new` / `tab.switch{main}` / `ext.ping` / `ext.getSettings` / `ext.settings` | 顶部栏所需；网页标签页允许外部站点导航，「新窗口」请求转为新标签页 |
| 扩展发现 | 扫描 `harnessDir/plugins` | 识别插件内含 `manifest.json` 的扩展目录并加载，与配置目录 `%LOCALAPPDATA%\DshDesktop\Extensions` 合并生效 |

## 已知限制

- **通用浏览器**：无 `window.dshDesktop` 桥，顶部地址/搜索栏注入与右键菜单搜索
  不可用（原生菜单不可由页面修改）；
- **个别站点**（如 Google）禁止第三方注入或被反爬限制时，顶部栏按钮可能不可用，
  可改用侧边栏按钮、标签条或「新标签页」按钮操作；
- 扩展经 WebView2 扩展机制加载（`CoreWebView2Profile.AddBrowserExtensionAsync`），
  所有标签页共享，需 WebView2 Runtime 支持 MV3 扩展（新版 Evergreen 均可）。

## License

[MIT](LICENSE)