dsh-search-tools

dsh-search-tools

简体中文 · English

为 DeepSeek Harness（DSH）提供 adapter-first 的网页搜索与正文抓取。所有配置都在 DSH Web GUI 的 设置 → 搜索工具 完成，不要求用户手改 YAML。

仓库版本：0.1.9（2026-10-24）。 本版为 Local Direct 增加 Brave Search 与 360 Search 两个可选 HTML 引擎，并把执行模型改为每引擎独立 worker：一个慢引擎不会吞掉另一个引擎的成功结果。默认引擎仍是 DuckDuckGo + Bing；解析、去重、RRF 融合、域名多样性和缓存都在本地完成，不需要 SearXNG、API key、Reader、浏览器或第三方聚合服务。查询会直接发往启用的公网搜索引擎，但不会经过 SearXNG/Reader；不执行页面 JavaScript。默认搜索仍是 searxng，稳定 provider id 和工具 schema 不变。详细边界见 Local Direct 搜索配置 与 v0.1.9 发布清单。

目录

• 它解决什么问题
• 功能一览
• 工作原理
• 环境要求
• 安装与升级
• 快速开始
• 设置页说明
• 配置参考
• 配置存放位置
• SearXNG 搜索配置
• Local Direct 搜索配置
• Readability HTTP 抓取配置
• Wire HTTP 抓取配置
• Jina Reader 抓取配置
• web_research 配置
• 接管配置
• 模型工具
• 安全模型
• 适配器开发
• 本地开发
• 发布流程
• 故障排查
• 已知限制
• 许可证与第三方组件

它解决什么问题

DSH 自带 web_search 和 web_fetch，但默认后端不一定适合每个人：有人已经有自己的 SearXNG，有人需要把搜索请求走代理，有人希望抓取结果直接是干净的正文，而不是整页 HTML。

dsh-search-tools 把“搜索/抓取后端”从 DSH 核心中解耦出来：

• 用户可以在 Web 设置页选择后端、填写实例、测试连接；
• 插件向 DSH 注册稳定 provider id，切换后端不会改变 DSH 的 web.searchProvider；
• 新增后端只需要注册 adapter，设置页按 manifest 自动渲染，不需要改页面代码；
• 额外提供 web_research：一次调用完成“搜索 + 抓取前 N 条正文”，适合需要页面内容而非只拿链接的模型回合。

它不做这些事：不提供公共搜索 API，不绕过目标站点的登录/付费墙，也不替代 DSH 的权限与沙箱模型。渲染能力取决于抓取 adapter：readable-http 不执行页面 JavaScript；可选的 wire-http 在本地做浏览器级 HTTP/TLS 指纹和 PDF 文本提取，但同样不执行页面 JavaScript；可选的 jina-reader 会把公网 URL 交给 Reader 服务做浏览器渲染（自托管时留在本机），三者都不登录、不绕过付费墙、不破解验证码。

界面预览

以下截图使用 demo 数据（https://searxng.example.com，无真实凭据）：

功能一览

能力 · 说明 稳定的搜索/抓取 provider · dsh-search-tools、dsh-search-tools-fetch 永不随后端变化 内置搜索 adapter · SearXNG：多实例、顺序/轮询、故障转移、JSON/HTML、GET/POST、Bearer/Basic、代理、缓存、分页、域名过滤 本地直连搜索 adapter（可选） · Local Direct：本机直接查询 DuckDuckGo + Bing HTML 首页，可选 Brave Search / 360；本地解析/去重/RRF 融合/域名多样性/缓存；不需要服务、Key、Reader 或浏览器，不执行 JS 内置抓取 adapter · Readability HTTP：复用 DSH 安全 HTTP，Readability 提取正文，失败可回退原文 本地强抓取 adapter（可选） · Wire HTTP：impit 本地浏览器级 TLS/HTTP2 指纹、逐跳公网出口 pinning、Readability、PDF 文本；不需要 Reader/Key/浏览器/容器，不执行 JS 可选渲染抓取 adapter · Jina Reader：浏览器渲染、PDF/Office、CSS 选择器、iframe/Shadow DOM、代理选项；目标必须是公网地址，Reader 可托管或自托管 研究工具 · web_research：搜索、按并发抓取前 N 页、按页/总预算截断、返回来源与正文 Web 设置页 · 概览、搜索、抓取、研究、诊断五个页签；Connection / Search behavior 子页、实例卡、内联测试、正文 reader、预算条、字段级错误、诊断、缓存清理、键盘保存 凭据隔离 · 搜索 token 写入 DSH credentials，不落 YAML、不进日志、不出现在诊断文本 接管与恢复 · 可选让内置 web_search / web_fetch 使用本插件；关闭时恢复之前的 provider 外部 adapter · 通过 ctx.searchTools 注册新后端；设置页自动渲染 manifest 字段

工作原理

DSH ctx.web
  searchProvider = "dsh-search-tools"         （稳定）
  fetchProvider  = "dsh-search-tools-fetch"   （稳定）
        │
        ▼
  SearchDispatcher / FetchDispatcher
        │ 读取 config.search.adapter / config.fetch.adapter
        ▼
  ctx.searchTools（adapter 注册表）
    ├── searxng         内置搜索 adapter（默认）
    ├── local-direct    内置搜索 adapter（本机直连 DDG + Bing）
    ├── readable-http   内置抓取 adapter（默认，DSH 安全 HTTP）
    ├── wire-http       内置抓取 adapter（可选，本地浏览器级 HTTP + PDF）
    ├── jina-reader     内置抓取 adapter（可选，Reader 渲染）
    └── 未来由独立包注册的 adapter

关键设计：

1. provider id 稳定，adapter 可换。 加一个后端不会改 web.searchProvider，也不会要求 DSH 重启后重新注册 provider。
2. 配置按 section 开放。 search.adapters 和 fetch.adapters 是开放字典，adapter 自己拥有默认值与校验逻辑；核心 schema 不需要为每个后端加字段。
3. manifest 驱动设置页。 Host 路由把 adapter manifest 发给浏览器，页面按 fields 通用渲染。新增 adapter 不需要改 React 代码。
4. 配置在调用时解析。 Dispatcher 每次按当前配置选择 adapter；切换后不需要重新注册 provider。

架构细节见 docs/architecture.md。

环境要求

项目 · 要求 DSH · >=0.2.1-rc.2 =24.0.0 搜索后端 · Local Direct（不需要部署，直接查 DDG/Bing）或一个可访问的 SearXNG 实例；也可暂时保持 DSH 默认搜索 抓取后端 · 公网 http(s) 页面；readable-http 由 DSH SSRF 防护拦截内网，wire-http 在本地逐跳 pin 公网地址，jina-reader 在发出前做公网目标守卫 Reader（可选） · r.jina.ai 的 API key，或一个可访问的自托管 Jina Reader 端点；不配置时继续用 readable-http 或 wire-http 浏览器 · DSH Web GUI（设置页只在 Web 端注册）

DSH 本身仍是 preview 软件，接口可能变化。插件把 peer 范围锁在已验证的 0.2.1-rc.2 线，升级 DSH 前请先看 CHANGELOG。

安装与升级

方式一：Web UI（推荐）

1. 打开 DSH Web GUI。
2. 进入 插件（Plugins）。
3. 点击 添加插件（Add plugin）。
4. 输入包名：

dsh-search-tools

1. 安装完成后启用这个 bundle。
2. 打开 设置 → 搜索工具。

设置页出现，说明 Host 与浏览器两半都已加载。

方式二：CLI

dsh plugin --profile <profile> add dsh-search-tools

`` 换成实际 profile 名。安装后启动该 profile：

dsh --profile <profile>

方式三：离线 tarball

从 GitHub Releases 下载最新可用的 dsh-search-tools-.tgz，然后：

dsh plugin --profile <profile> add ./dsh-search-tools-<version>.tgz

发布资产与 npm 产物字节一致，适合内网或无法访问 npm 的环境。

升级

DSH 插件目前不支持自动更新。升级步骤：

1. 先在 设置 → 搜索工具 → 概览 关闭搜索/抓取接管（如果已开启）。
2. 在 插件 页卸载旧版本。
3. 重新添加 dsh-search-tools 或新的 tarball。
4. 重新启用，检查设置页配置是否保留（配置在 profile 的 YAML patch 中，通常不会因重装丢失）。
5. 重新测试搜索与抓取。

CLI 对应：

dsh plugin --profile <profile> remove dsh-search-tools
dsh plugin --profile <profile> add dsh-search-tools

不要在接管仍开启时直接卸载。内置 web_search 会指向一个不存在的 provider，直到你重装插件或手动恢复 web.searchProvider。

安装后检查

• 设置 → 搜索工具 能看到五个页签。
• 诊断 里能看到版本号、配置文件路径、抓取/研究运行状态和缓存统计。
• 如果模型工具已启用，会话里应能看到 web_research。
• 搜索测试通过后，才建议开启搜索接管。

快速开始

1. 准备搜索来源

有两条零代码路径：

• Local Direct（推荐先试）：不需要准备任何服务。它在本机直接请求 DuckDuckGo 和 Bing 的公开 HTML 结果页，解析和融合都在本机完成。可额外启用 Brave Search 或 360；Brave 内部使用 Firefox HTTP 指纹，其他引擎遵循 profile 设置。查询会离开本机发往启用的引擎；首次使用请确认所在网络能访问它们。
• SearXNG：需要一个可访问的 SearXNG 实例。实例地址是 http(s) 绝对 URL，例如 https://searx.example.com；JSON API 需要 search.formats 包含 json，HTML-only 也可以；有认证时准备 Bearer token 或 username:password；有限流时准备多个实例或代理。插件会自动去掉末尾 /search、query 和 hash，实例 URL 里不能带用户名/密码。

2. 在设置页配置

1. 打开 设置 → 搜索工具 → 搜索。
2. 在 后端 选择 Local Direct 或 SearXNG。
3. Local Direct：勾选 DuckDuckGo / Bing / Brave Search / 360 搜索 中至少一个，按需选市场、安全搜索、结果数；不需要实例或密钥。点 测试搜索引擎 可检查可达性。
4. SearXNG：点击 添加实例，填写实例地址；备注名可选；按需设置引擎、分类、语言、安全搜索、分页、结果数、超时；需要认证时选择 Bearer / Basic 并保存密钥。
5. 点击 测试，确认返回结构化来源；Local Direct 还会显示可达引擎。
6. 点击 保存并应用。

3. 配置抓取（可选）

1. 打开 抓取 页签。
2. 先保持 Readability HTTP，用默认值测试一个公网页面，例如 https://example.com。
3. 如果目标站点是 SPA、PDF/Office，或静态 HTTP 抓不到正文，改选 Jina Reader：

• 托管服务填 https://r.jina.ai/，在 Jina API key 保存密钥；
• 自托管填 http://127.0.0.1:3000/（仅 loopback 允许明文 HTTP）或 HTTPS 反代地址；
• 需要动态内容时把 Fetch engine 设为 browser；需要新鲜内容时打开 Bypass Reader cache。

1. 保存前看 form 顶部的数据边界 warning；测试 通过后保存并应用。
2. web_fetch 工具默认 30 秒；把 Reader 超时调到 30 秒以上时，必须同时调高 DSH tool-web.fetchTimeoutMs，否则会先收到 TOOL_TIMEOUT。

4. 开启接管（可选）

在 概览：

• 接管内置搜索：让 DSH 的 web_search 使用本插件的搜索 provider。开启前会先用当前配置跑一次搜索测试，失败则不会接管。
• 接管内置抓取：让 DSH 的 web_fetch 使用本插件的抓取 provider。

接管状态会写入 DSH 的 web.searchProvider / web.fetchProvider。关闭时插件会恢复之前记录的 provider（activation.previousSearchProvider / previousFetchProvider）。

如果只想用 web_research，不一定要开启接管。web_research 调用的是当前 DSH 的搜索/抓取 provider；不接管时就使用 DSH 默认后端。

5. 使用模型工具

模型会话中可以直接使用：

• web_search：DSH 内置工具，接管后走本插件；
• web_fetch：DSH 内置工具，接管后走本插件；
• web_research：本插件注册的研究工具，不依赖接管，但会使用当前 provider。

web_research 示例参数：

{
  "query": "DeepSeek Harness release notes",
  "max_results": 8,
  "fetch_top": 3,
  "max_chars": 12000
}

返回内容包含 sources、fetched 和 truncated；会话卡片会显示来源数、成功抓取数、抓取详情和截断标记。

设置页说明

概览（Overview）

• 当前搜索 provider / 抓取 provider；
• 接管状态与快捷开关；
• 搜索后端是否可用、搜索来源数（SearXNG 实例或 Local Direct 引擎）、缓存条数；
• 快速搜索测试与抓取预览；
• 没有来源时的引导卡片。

搜索（Search）

• 卡片式 adapter picker：显示 adapter 描述、capabilities、配置状态；
• SearXNG 实例编辑器：添加、删除、上移、下移、启用/停用、单实例测试；
• Local Direct 引擎多选、市场、安全搜索、每站结果数；不需要实例；
• 测试搜索引擎：使用固定探测词，不写缓存，直接列出可达引擎，无实例也能用；
• 由 manifest 自动渲染的字段；
• 内联测试：显示耗时、来源标题/链接/摘要、Search notes（例如单个引擎被限流或解析为空）；
• 校验错误会定位到具体字段，搜索草稿的错误不会阻塞抓取测试。

抓取（Fetch）

• 抓取 adapter 选择与字段；
• 输入公网 URL 做一次抓取预览；
• 选择 wire-http 时显示本地边界 notice、浏览器指纹/超时/PDF 字段；它不需要 Key，也不执行页面 JavaScript；
• 选择 jina-reader 时显示数据边界 warning、API key 和浏览器/Reader 选项；readable-http 仍保留原有字段；
• 显示状态码、内容类型、字符数、截断标记和正文预览；
• 内网地址会被 readable-http 的 SSRF 防护或 jina-reader 的公网目标守卫拒绝，这是预期行为。

研究（Research）

• 启用/关闭 web_research；
• 默认结果数、最大抓取条数、默认抓取条数、单页/总字符预算、并发、超时；
• 模型看到的工具提示 预览：描述、参数名、默认值与范围都来自当前草稿；可一键复制；
• 关闭 web_research 后，保存后模型将看不到这个工具。

诊断（Diagnostics）

• 配置文件路径；
• 搜索后端、抓取后端、研究工具的真实运行状态（fetch.available / research.registered）；
• 缓存条数与命中/未命中统计；
• 清空缓存；
• 最近错误（环形缓冲）；
• 复制诊断信息（已脱敏）与清空错误；
• 当前版本。

键盘与状态

• Cmd/Ctrl+S：保存并应用当前草稿（仅在配置有效且有未保存更改时）。
• 页签支持 ← / → / Home / End。
• 保存状态、测试结果、诊断操作都通过 aria-live 播报。
• 配置被更高层覆盖时页面只读；配置在别处修改时提示冲突，需重新加载。

配置参考