stelmakhdigital/dsh-web-automation

dsh-web-automation

🇬🇧 英语 | 🇷🇺 俄语

一个 DeepSeek Harness 插件，为本地模型提供本地优先的 Web 技术栈——无需付费搜索 API，无需第三方数据代理，关键引擎无需云端。

它将四项能力打包成一个可安装的插件：

| 能力 | 功能 | 无需密钥？ |
|---|---|---|
| 多引擎搜索 | web_search 工具，在 DuckDuckGo + Bing（无需密钥）以及 Exa / DeepSeek / Jina（可选启用，需存在其 API 密钥）之间路由。支持回退或融合（并行 + RRF）路由、冷却时间、BM25 增强。 | ✅ DDG + Bing |
| 缓存抓取 | web_fetch 工具，由带 ETag/Last-Modified 重新验证的 SQLite 页面缓存支持。在 TTL 内重复请求不会发起网络请求。 | ✅ |
| Web 平台 | web_platform_search 工具：通过特定平台（GitHub、Reddit、YouTube、Bilibili、V2EX、RSS 等）自身的公开端点进行搜索。新平台可无需代码通过配置或版本化规则包（热重载）添加。 | ✅ |
| 历史 / 统计 / 缓存 | web_history、web_search_stats、web_cache_clear——读取共享的本地存储；无网络。 | ✅ |

所有状态均为本地：存储位于 $DSH_HOME/web.db。关键引擎的出站流量仅限于 DuckDuckGo 和 Bing。

快速开始

前置条件：

- Node.js 22.19+ 或 24+——与 DSH 本身的要求相同；该插件使用内置的 node:sqlite 存储。
- DeepSeek Harness——可通过 npx @deepseek-ai/dsh（无需安装）或源码检出（pnpm install && pnpm run build，然后 pnpm dsh ...）。

1. 将插件安装到某个 profile（bundle overlay 会自动应用）：

dsh plugin --profile web add git+https://github.com/stelmakhdigital/dsh-web-automation.git

2. 启动该 profile：

dsh web              # Web UI 位于 http://127.0.0.1:3080
dsh --profile tui    # TUI（如果你安装到了 tui 而非 web）

启动时插件随宿主一起加载：web seam 被固定为 multi 搜索 / cached-http 抓取提供程序，web_fetch 已启用，并且 web_platform_search 以及历史工具均已注册。无需额外配置——每个字段都有默认值（无需密钥的 DuckDuckGo + Bing）。

3. 验证——在 DSH 会话中运行冒烟测试（例如 web_search "hello world"）。

将 web 替换为你的 profile 名称。要查看组合后的 profile 树：dsh --profile web --dump-config。

安装

插件通过 dsh plugin 安装到 DSH profile 中——每个 profile 都是 $DSH_HOME/profiles/ 下自己的 pnpm 工作区。启动时，DSH 会将宿主的 @deepseek-ai/ 包符号链接到该 profile 的 node_modules 中，因此插件的 peer 依赖会解析到宿主自身的副本。
这个包是一个 DSH bundle：它的 package.json 声明了 dsh.bundle，因此安装它会自动应用随附的 local-web.cordis.yml 覆盖层——它将 web 接缝固定到该插件的提供者，在宿主 tool-web 行中启用 web_fetch，并注册该插件。无需手动 --patch：

dsh plugin --profile web add git+https://github.com/stelmakhdigital/dsh-web-automation.git

（将 web 替换为你的 profile 名称。接缝固定是必需的：没有它，接缝会看到两个可用的搜索提供者（部署默认值加上 multi），并会以 WEB_PROVIDER_AMBIGUOUS 失败。）

手动替代方案——如果你想在应用前调整配置，可以自行应用覆盖层：

dsh --profile web --patch "$PWD/local-web.cordis.yml"

可选：浏览器自动化

dsh-web-browser 子包在 browser_ 工具（browser_open、browser_navigate、browser_snapshot、browser_click、browser_type、browser_screenshot）背后添加了本地 Chromium（Playwright）自动化。它之所以单独存在，是因为它会引入 Playwright + 一次 Chromium 下载。

它是本仓库的一个子目录，而 pnpm 无法直接安装 git 仓库的子目录。请从本地克隆以tarball（npm pack）方式安装它：与 link: 安装不同，tarball 会被解包到 profile 的 node_modules 中，因此该包自身的依赖（playwright）会被安装，并且其 @deepseek-ai/ 导入会解析到宿主的包：

git clone --depth 1 https://github.com/stelmakhdigital/dsh-web-automation.git ~/dsh-plugins/dsh-web-automation
cd ~/dsh-plugins/dsh-web-automation
npm pack ./browser  # → dsh-web-browser-0.3.0.tgz (lib/ is prebuilt in the repo)
dsh plugin --profile web add ./dsh-web-browser-0.3.0.tgz
one-time: install the Chromium binary
dsh plugin --profile web exec playwright install chromium

浏览器包也是一个 bundle——它的补丁（tarball 中的 cordis.patch.yml）会自动注册浏览器插件行。更新方式：在克隆中执行 git pull，再次运行 npm pack ./browser，然后对新的 tarball 执行 dsh plugin add。

配置

向你的部署的 cordis.yml（或通过 dsh --patch ... 应用的覆盖层）添加一行。完整参考请见 cordis.yml.example。

- id: web-automation
name: 'dsh-web-automation'
config:
search:
engines: [ddg, bing, exa, deepseek, jina]   # tried in order
mode: fallback            # fallback | fuse
region: ''                # region/market hint (DDG kl, Bing setmkt)
exa:      { apiKeyEnv: EXA_API_KEY }      # or apiKey: '...'
deepseek: { apiKeyEnv: DEEPSEEK_API_KEY }
jina:     { apiKeyEnv: JINA_API_KEY }
fetch:
revalidate: true          # conditional revalidation for fresh-but-expired pages
platforms:
tool: true                # register web_platform_search
maxResults: 20
platforms:              # 按 id 覆盖内置平台，或添加新平台
- id: my-site
name: My Site
format: json
searchUrl: 'https://my-site.example/search?q={query}'
fields: { items: 'data.results', url: 'link', title: 'title' }
history:
history: true             # web_history
cacheClear: true          # web_cache_clear
stats: true               # web_search_stats

每个字段都有默认值，因此空的 config: {}（或完全没有 config）即可启用完整的本地 Web 栈以及无密钥引擎。

与 DSH 内置 Web 包的关系

本插件是 DSH 内部 Web 包（web-search-multi、web-fetch-cached、web-platforms、web-store、web-browser、tool-web-history）的外置独立副本，目前领先于上游（SearXNG 引擎、新闻模式时效性、嵌入重排序、LRU 淘汰、SSRF 防护、内联截图）。

- 互斥：本插件与内置包注册相同的提供者 id（multi、cached-http）和工具名称。同时加载两者的部署会在启动时因 WEB_DUPLICATE_PROVIDER 而失败——请保留其中一个。如果你使用本插件，请不要应用 DSH 的 examples/web-local 覆盖层（或其预设副本），反之亦然。
- 工具来自宿主：web_search 和 web_fetch 由宿主的 tool-web 插件注册；本插件注册它们背后的提供者（以及 web_platform_search 和历史工具）。上面的覆盖层在 tool-web 行中启用了 web_fetch。
- 上游漂移：由于本插件独立演进，其行为可能随时间与内置包产生分歧。src/ 中的模块头注释标明了每个模块所对应的上游包。

API 密钥（可选）

无密钥引擎（DuckDuckGo、Bing）无需任何配置即可使用。若要启用 Exa / DeepSeek / Jina，请通过以下任一方式提供其 API 密钥：

- 在启动环境中（EXA_API_KEY、DEEPSEEK_API_KEY、JINA_API_KEY），或
- 在插件配置中（search.exa.apiKey 等），或
- 通过 DSH 凭据域（写入凭据存储的密钥会在每次搜索时生效，无需重启）。

用法

安装并配置后，模型可以：

- 搜索网络 — web_search "query"（多引擎，增强摘要）。
- 抓取页面 — web_fetch （带缓存；在 TTL 内重复请求不会产生网络请求）。
- 搜索平台 — web_platform_search { platform: "github", query: "..." }。
- 查看历史 / 统计 — web_history、web_search_stats、web_cache_clear。
- 驱动浏览器（配合 dsh-web-browser）— browser_open、browser_navigate、browser_snapshot、browser_click、browser_type、browser_screenshot。

隐私模型
- 查询仅发送到已配置的搜索引擎——这对任何搜索引擎来说都是不可避免的。使用默认引擎列表且无 API 密钥时，出站流量仅限于 DuckDuckGo 和 Bing；推理保持在本地。
- 基本使用无需凭据。
- 所有状态均为本地：存储位于 $DSH_HOME/web.db，不会向其他任何地方发送任何内容。
- 注意事项：抓取公开的 SERP 可能违反搜索引擎的服务条款；该提供程序会发送明确的产品 User-Agent，对自身进行速率限制（默认每个引擎 1 请求/秒），并对被封锁的引擎进行冷却。请负责任地使用。

安全

- SSRF 防护（默认开启）：对回环、私有、链路本地以及其他保留网络目标（IPv4 0/8、10/8、127/8、172.16/12、169.254/16、192.168/16；IPv6 ::1、::/128、fe80::/10、fc00::/7）的请求会被阻止。该检查针对字面主机以及 DNS 解析之后运行（以防重绑定），并且对于 web_fetch/enrichment，它会在每个重定向跳转时重新检查（最多 5 次）。受防护的路径及其标志：
| 路径 | 标志 |
|---|---|
| web_fetch（缓存获取提供程序） | fetch.allowPrivateNetworks |
| 搜索增强（为片段获取页面） | search.allowPrivateNetworks |
| web_platform_search 获取（包括 RSS 源 URL） | platforms.allowPrivateNetworks |
| browser_navigate（Playwright） | dsh-web-browser 配置中的 allowPrivateNetworks |

仅在受信任且网络隔离的环境中，才将相关标志设置为 true。
- 浏览器审批（故障关闭）：browser_open/browser_navigate 需要根据 dsh-web-browser 的 approval 设置（never | navigate | all——navigate 控制导航和脚本评估，all 增加点击和输入）进行审批。如果审批服务不可用，或调用没有可路由的代理，该操作会被拒绝，而不是被静默允许。
- 缓存逐出（按使用情况的 LRU）：存储最多保留 fetch.cacheMaxPages 条页面记录（默认 500）和 search.cacheMaxSearches 条搜索记录（默认 1000），在每次写入后逐出超出上限的最久未访问项。这使 web.db 随时间保持有界。

已知限制

- HTML SERP 解析很脆弱；标记变化会降级为零结果，直到解析器更新（封锁检测会将静默空结果转换为冷却）。
- 该插件以宿主权限在宿主 DSH 进程中运行（受信任的静态包）；它未被沙箱化。请以普通用户身份运行 DSH，并且如果该插件可能访问敏感目标，请在网络隔离的容器/虚拟机中运行。
- 浏览器自动化：每个代理会话一个标签页。截图默认保存到文件；向 browser_screenshot 传递 inline: true 以在模型上下文中获取 base64。

示例

仅无密钥（无 API 密钥，无 SearXNG）
yaml
dsh-web-automation:
search:
engines: [ddg, bing]   # keyless only
enrich: true

完整（所有引擎 + SearXNG）
yaml
dsh-web-automation:
search:
engines: [ddg, bing, exa, deepseek, jina, searxng]
searxng:
endpoint: http://localhost:8080   # 你的 SearXNG 实例
embedding:
endpoint: http://localhost:11434  # Ollama（或任何 /embeddings 服务器）
model: nomic-embed-text

新闻模式（按时间过滤）
yaml
dsh-web-automation:
search:
engines: [bing]   # Bing 支持时效性过滤
freshness: 24h    # 24h | week | month | year

冒烟测试

安装并应用 overlay 后，端到端验证整个技术栈（在 DSH 会话中）：

1. web_search "hello world" — 返回来源（DDG/Bing 无需密钥）。
2. web_fetch https://example.com 两次 — 第二次调用命中缓存（无网络请求；检查 web_search_stats）。
3. web_platform_search { platform: "github", query: "schemastery" } — 返回 GitHub 来源。
4. web_history — 显示上述搜索/抓取记录。
5. web_fetch http://127.0.0.1/ — 失败并返回 WEB_SSRF_BLOCKED（SSRF 防护）。
6. （配合 dsh-web-browser）browser_open → browser_navigate https://example.com → browser_screenshot → browser_close — 截图文件出现在临时目录中。

开发者工作流

针对插件本身进行开发（构建、测试、类型检查、本地安装）：
sh
git clone https://github.com/stelmakhdigital/dsh-web-automation.git
cd dsh-web-automation
npm install --legacy-peer-deps   # @deepseek-ai/ peer 依赖由宿主 DSH 在运行时提供
npm run build && npm run build --prefix browser   # 打包 src/ → lib/（两个包）
npm test                          # vitest（106 个测试）
npm run typecheck                 # 针对本地 @deepseek-ai/* 桩进行 tsc 检查
DSH_HOST=/path/to/deepseek-harness npm run typecheck:host   # 针对真实宿主类型进行严格检查

lib/ 和 browser/lib/ 已提交，CI 会强制要求它们与 src/ 保持同步，因此通过 git/tarball 安装无需 esbuild 即可正常工作。要在 profile 中试用本地副本：
sh
npm pack                                   # → dsh-web-automation-0.3.0.tgz
dsh plugin --profile web add ./dsh-web-automation-0.3.0.tgz

故障排查

| 症状 | 原因 | 修复方法 |
|---|---|---|
| 安装时出现 ERESOLVE peer 冲突 | 在 DSH 部署之外缺少 peer 依赖 | npm install --legacy-peer-deps |
| Cannot find module '@deepseek-ai/...' | 安装插件时未安装 DSH 的包 | 先安装 DSH（peer 依赖会解析到宿主的版本） |
| does not provide an export named 'installSettingsSection' | 插件是针对旧版 DSH 设置 API 构建的 | 更新插件（当前 DSH 使用 ctx.settings.installSection）并重新安装 |
| 启动时出现 WEB_PROVIDER_AMBIGUOUS | web seam 看到两个可用的搜索提供方 | 添加 web seam 固定行（searchProvider: multi、fetchProvider: cached-http）——参见 overlay |
| 启动时出现 WEB_DUPLICATE_PROVIDER | 插件和 DSH 内置的 web 包同时被加载 | 保留一个——移除内置行（或插件行）；参见“与 DSH 内置 web 包的关系” |
| web_fetch 被阻止（SSRF） | 目标是回环/私有/链路本地地址 | 设置 fetch.allowPrivateNetworks: true（仅限可信环境） |
| SearXNG 返回非 JSON | 实例上未启用 JSON API | 将 search.formats: [html, json] 添加到 SearXNG 的 settings.yml |
| 嵌入重排序回退到 BM25 | 嵌入端点不可达 | 检查端点 URL + 模型名称；BM25 是回退方案 |
| 浏览器：Chromium not found | 未安装 Playwright 浏览器 | npx playwright install chromium |
| web.db 变得很大 | 缓存驱逐上限过高 | 调低 fetch.cacheMaxPages / search.cacheMaxSearches |

许可证

MIT — 参见 LICENSE。