# dsh-web-search-pro

> 为 DeepSeek Harness 扩展网页搜索能力，支持多引擎路由与融合、20 平台搜索、SQLite 持久化缓存、脚本猫式按站提取与 Playwright 渲染。

## Metadata

- Author: [@anweat](https://github.com/anweat)
- Repo: <https://github.com/anweat/dsh-web-search-pro.git>
- GitHub: [anweat/dsh-web-search-pro](https://github.com/anweat/dsh-web-search-pro)
- Stars: 29
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `plugin`, `web-search`
- Forks: 1
- Open Issues: 4
- Last push: 2026-08-14T08:07:39.000Z
- Added: 2026-08-14T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:anweat/dsh-web-search-pro
```

## Wiki

## 一句话定位
给 DeepSeek Harness 加一套"网页搜索 + 抓取 + 快照"合一的工具集，把单后端原生搜索换成多引擎路由 + 持久缓存 + 20 平台搜索 + 脚本猫式按站提取 + Playwright 兜底渲染。

## 核心能力
- 多引擎路由与融合：DeepSeek 原生、Exa、DuckDuckGo、Bing、Jina 之间按顺序回退，并行时可做 RRF 倒排融合排序
- 20 平台搜索：GitHub / B站 / YouTube / V2EX / 小红书 / Twitter / Reddit / IG / FB / RSS，加 知乎 / 微博 / 豆瓣 / 贴吧 / 抖音 / 快手 / arXiv / PubMed
- 持久化缓存：搜索结果、页面快照、按站提取规则全部存入 SQLite，跨重启复用，热数据走进程内 LRU
- 可读化抓取：Jina Reader → HTTP+规则抽取 → Playwright 兜底三段式，失败自动晋级
- 持久化页面快照：headless 浏览器截图 + HTML + 文本落盘到本地目录
- 查询历史与回放：按关键词/引擎/平台过滤历史，按 queryId 回放，支持导出 JSON
- 自定义平台：settings.yaml 写一份 URL 模板 + 结果选择器即可新增站点，无需改代码

## 技术实现
- **语言**: TypeScript
- **关键依赖**: @deepseek-ai/cordis（Hook 容器）, @deepseek-ai/dsh-tools & dsh-web（工具定义与 ctx.web 抽象）, @deepseek-ai/dsh-settings（settings.yaml 热重载段）, jsdom（HTML 解析）
- **架构模式**: Cordis bundle 插件，通过 cordis.patch.yml 同时挂载本插件行与 dsh-browser 行；inject 依赖 `tools / systemPrompt / browser` 三个服务
- **入口文件**: src/index.ts:apply(ctx, config)

## 适用场景
想让 DSH 真正能"上网做研究"的场景：写代码时查最新 API 文档、查开源项目 issue、追踪学术论文、做选题调研、翻中文社区讨论。普通 DSH 用户遇到"模型回答过时/查不到最新资料"时，这套插件会显著提升信息密度和新鲜度。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH Harness | 0.1.0-rc.6+ | 依赖的 @deepseek-ai/* 系列运行时均为 rc.6 |
| @anweat/dsh-browser | ^0.1.2 | 同伴插件，提供 browser 服务（本插件的 cordis.patch 会自动挂载） |
| Node.js | >=22.19.0 | 来自 package.json#engines |
| 平台 | 跨平台 | 未声明特定平台限制 |
| 原生模块 | 无 | 仅使用 Node 内置模块与纯 JS 依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:anweat/dsh-web-search-pro
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| engines | 字符串数组 | 多引擎按顺序回退（或并行融合），可用 id：seam, exa, ddg, bing, jina, github, bilibili, v2ex, youtube, arxiv, pubmed | `["ddg","bing","exa","seam","jina"]` |
| parallelEngines | 布尔 | 启用后所有引擎并行查询并用 RRF 融合结果 | `false` |
| ttlSeconds | 数字 | 搜索结果与页面快照的有效期（秒） | `3600` |
| memoryCacheEntries | 数字 | 进程内 LRU 缓存条目上限 | `128` |
| searchMaxResults | 数字 | 单次搜索返回结果数上限 | `8` |
| timeoutMs | 数字 | 单次调用协同超时（毫秒） | `30000` |
| rrfConstant | 数字 | RRF 融合常数 k | `60` |
| freshnessBoost / freshnessDays | 数字 | 对新近内容的额外打分权重（0..1）与衰减天数 | `0.2` / `30` |
| authorityBoost / authorityDomains | 数字 / 字符串数组 | 对权威域名（.edu/.gov/.org 等）的额外打分 | `0.25` / `[]` |
| exaApiKey / jinaApiKey | 字符串 | 启用 Exa / Jina 时填写；也可走环境变量或 .credentials.yaml | 未设置 |
| exaApiKeyEnv / jinaApiKeyEnv | 字符串 | 引用环境变量名 | `EXA_API_KEY` / `JINA_API_KEY` |
| registerProvider / providerId | 布尔 / 字符串 | 启用后接管 DSH 内置 web_search 工具，路由走本插件 | `false` / `web-search-pro` |
| enableCliBackends | 布尔 | 是否允许调用 gh / bili / yt-dlp / opencli / agent-reach 等外部 CLI | `true` |
| opencliEnabled / agentReachEnabled | 布尔 | 单独开关 opencli 与 agent-reach 后端 | `true` |
| platformRules | 字典 | 按平台 id 覆盖结果选择器（站点改版后无需改代码） | `{}` |
| customPlatforms | 字典 | 用户自定义站点：URL 模板 + 选择器 + 可选 Cookie | `{}` |
| playwright.enabled | 布尔 | 是否启用 Playwright 兜底抓取与快照 | `true` |
| playwright.snapshotDir | 字符串 | 快照落盘目录 | `<dbDir>/snapshots` |
| dbPath | 字符串 | SQLite 数据库路径 | `$DSH_HOME/data/web-search-pro/store.db` |
| verbose | 布尔 | 启动时把本次加载信息追加到 dbPath 旁的 apply.log | `false` |

## 常见问题

**Q: 跟 DSH 内置的 web_search 有什么区别？**

A: 内置工具只走 ctx.web 一个后端；本插件把它升级为多引擎路由、自动回退、可融合排序，并加 SQLite 持久化缓存、查询历史、20 平台搜索、脚本猫式按站提取、Playwright 兜底抓取与快照。

**Q: 一定要用 API Key 吗？**

A: 不必须。默认引擎 ddg / bing / seam 都不需要 Key；只有启用 Exa 或 Jina 时才需要，可在 settings.yaml 或环境变量 EXA_API_KEY / JINA_API_KEY 填写。

**Q: 知乎、小红书、B 站这些要怎么搜？**

A: 通用搜索引擎能搜到结果，但中文社区（知乎/微博/豆瓣/贴吧/抖音/快手/小红书）走 Playwright 驱动的登录态浏览器，需要先用 `scripts/save-login.mjs` 登录一次保存 cookies，再在 settings.yaml 设 `playwright.storageStatePath`。

**Q: 安装后还需要装什么外部工具？**

A: 开箱即用即可搜通用网页。若要用 GitHub / B站 / YouTube / agent-reach 等专属后端，先用 web_deps 工具检测，再用检测出的安装命令补齐。

**Q: 数据存在哪里？**

A: 默认在 `$DSH_HOME/data/web-search-pro/` 下：store.db 存历史与缓存、snapshots/ 存网页快照。改 dbPath 或快照目录可在 settings.yaml 的 web-search-pro 段重设。

**Q: 怎么卸载？**

A: 用 `dsh plugin --profile web remove dsh-web-search-pro` 即可。SQLite 数据库与快照默认留在仓库目录，按需手动删除。

## 上手难度
入门 — 开箱即用装好即可搜通用网页；只有启用 Exa/Jina Key、抓取中文社区、想自定义平台时才需要进一步配置。

## 已知问题与限制
- 选择器是"尽力而为"：中文社区平台的结果选择器写死在代码里，站点改版后可能取不到结果，可通过 settings.yaml 的 platformRules 覆盖，无需改代码。
- 登录态依赖外部脚本：知乎/微博/豆瓣/贴吧/抖音/快手/小红书需要用户先运行 scripts/save-login.mjs 登录一次保存 cookies，否则返回结果为空。
- 依赖外部 CLI 的后端需自装：GitHub / B站 / YouTube / agent-reach 后端需系统安装 gh / bili-cli / yt-dlp / agent-reach；opencli 和 playwright 由 dsh-browser 插件捆绑，无需手动装。
- 默认关闭注销外挂：registerProvider 默认 false，DSH 内置 web_search 不会自动切到本插件；想接管需手动设为 true 或设环境变量 DSH_WEB_SEARCH_PROVIDER=web-search-pro。

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-web-search-pro](https://deepseek-plugin.org/plugins/anweat/dsh-web-search-pro)
Wiki generated by AI (model: `MiniMax-M3`)