本地 Chrome 搜索tabsp/dsh-web-search-chrome

dsh-web-search-chrome

npm version
CI
License
Node

一个免费的搜索提供程序，用于 DeepSeek Harness 的 Web 能力接缝（ctx.web）。它通过 agent-browser CLI 驱动你本地的 Chrome——默认无头模式，并使用持久化的 --profile 目录——并且不需要付费搜索 API，也不需要 API 密钥。

- 提供程序 id：local-chrome
- 搜索引擎：默认 Bing（engine: bing），可通过 engine: google 使用 Google（在 VPN/数据中心网络上，Google 经常被基于 IP 信誉的反机器人墙拦截；Bing 对它们的容忍度要高得多——参见 docs/decisions-010.md §D7）
- 面向模型的 web_search 工具：零改动——切换接缝的 searchProvider 只需一行补丁。
- 每个结果都带有 url + title + snippet（+ 尽力而为的 publishedAt），正是 dsh-web 定义的结构。

⚠️ 隐私（请先阅读）： 搜索词会从你的机器发送到搜索引擎，进入本地 Chrome 配置文件的历史记录，并受该引擎常规跟踪的约束。搜索会在一个专用的新标签页中运行，并在搜索完成后关闭；你现有的标签页绝不会被触碰。0.1 中没有登录状态——使用的是全新的专用配置文件目录。

工作原理

dsh agent's web_search tool (unchanged)
↓ ctx.web.search()
dsh-web-search-chrome  (provider id: local-chrome)
↓ serialized subprocess calls
agent-browser CLI  (≥ 0.34.0)
↓ --profile   [--headed]
local Chrome  →  bing.com/search?q=&count=&setlang=   (engine: google → google.com/search)
↓ SERP extraction (in-page JS, per-engine selectors)
title / url / snippet / publishedAt  →  WebSearchSource[]

每次搜索：打开一个新的带标签的标签页 → 等待 DOM → 提取 SERP → 关闭标签页。搜索被严格串行化（一个浏览器实例，一次只进行一次搜索）。结果会被缓存：会话内（相同查询会立即返回）和磁盘上（JSON + TTL，默认 24 小时）。

安装

前提条件：已安装 DeepSeek Harness（dsh）。 这是一个 dsh 插件——
它运行在 dsh 的 ctx.web 接缝内，所以如果你还没有安装 dsh，请先安装：
npm install -g @deepseek-ai/dsh（或通过 npx @deepseek-ai/dsh 临时运行）。

两种方式——任选其一：

- 手动（下文 §1–§3）：显式命令，适合固定确切的选项。
- 通过 dsh agent 自动化（§4）：把任务交给 dsh agent；它会安装
所有内容，并使用你的真实路径写入补丁（无需编辑占位符）。
1. 安装 CLI 和浏览器

agent-browser 是唯一的运行时依赖（它自身会捆绑/安装 Chrome for Testing）：

npm install -g agent-browser        # ≥ 0.34.0
agent-browser install               # 下载 Chrome for Testing

- Windows（原生或 WSL）：在 Windows 上用 npm 安装 agent-browser；WSL 也可以通过互操作自动使用它（参见下方的跨平台注意事项）。
- Linux：agent-browser install 会下载 Chrome for Testing。如果 Chrome 启动失败，请运行 agent-browser install --with-deps（系统库）——在精简发行版上安装 nss/nspr/alsa-lib，并确保加载器能找到它们（参见下方的启动检查）。
- macOS：安装 Chrome 或运行 agent-browser install。

🔍 验证 Chrome 是否真的能启动——仅靠 agent-browser doctor 是不够的。
Doctor 只检查 CLI 和浏览器二进制文件是否存在；它不会加载
浏览器，因此缺失的共享库直到第一次搜索才会被发现。
在配置 dsh 之前做一次真正的启动——确保没有 agent-browser 守护进程
在运行（重启之后，或执行 pkill -f agent-browser-linux）：

agent-browser open example.com      # 必须打印 URL，而不是 "Chrome exited early"
agent-browser close --all

⚠️ 为什么要“先停止守护进程”： Chrome 是由 agent-browser
守护进程启动的，而该守护进程会继承最先启动它的进程的环境。
常驻的守护进程可能会掩盖缺失库的问题（搜索会一直正常工作，
直到守护进程死亡或机器重启），因此上述检查只有在冷启动守护进程时才
具有决定性。

如果它失败并报 error while loading shared libraries: libnspr4.so（或
类似错误），请安装这些库（nss/nspr/alsa-lib；例如
Debian/Ubuntu 上执行 apt install libnss3 libnspr4 libasound2，
Arch 上执行 pacman -S nss nspr alsa-lib，或使用 Homebrew 执行 brew install nss nspr
alsa-lib）并确保启动 dsh 的进程能找到它们——
守护进程会在第一次搜索时由 dsh 进程首次启动。请在启动 dsh 的 shell 中
导出库路径，或使用一个包装脚本：

~/bin/dsh-web — 用于库不在加载器路径上的发行版的包装脚本
#!/bin/sh
export LD_LIBRARY_PATH=":$LD_LIBRARY_PATH"   # 例如 $(brew --prefix nss)/lib:$(brew --prefix nspr)/lib:$(brew --prefix alsa-lib)/lib
exec npm exec @deepseek-ai/dsh web "$@"

2. 将插件安装到 dsh 配置文件中

dsh plugin --profile  add dsh-web-search-chrome

3. 修补配置文件（一行即可切换接缝）

在 /profiles//cordis.patch.yml 中（例如 ~/.dsh/profiles/web/cordis.patch.yml）：

- insert:
- id: web-search-chrome
name: dsh-web-search-chrome
config:
profilePath: /home/you/.dsh-web-search-chrome/profile   # ⚠️ 将 /home/you 替换为你的真实主目录

- id: web
config:
searchProvider: local-chrome        # ← 这一行开关（PRD §8.1）
⚠️ profilePath 必须是您机器上一个真实、可写的路径。 随附的
docs/enable-local-chrome.patch.yml 使用了占位符
/home/you/... —— 在应用前请替换它（字面量 /home/you
目录将不存在，每次搜索都会失败并报
Chrome profile not found）。

profilePath 在 0.1 中是必需的。请使用一个专用目录 —— 它会在首次使用时创建。将其指向您真实的 Chrome 配置文件（例如 Default）可以启用登录状态复用，但风险自负；该路径正式支持是在 v1.1。

⚠️ 该开关在下次配置文件启动时生效。 配置文件的补丁
监视器会将 cordis.patch.yml 热应用到正在运行的进程，但插件
模块是按进程缓存的 —— 实时切换到 local-chrome 无法加载
到已经运行的进程中。一个可直接应用的补丁文件随附于
docs/enable-local-chrome.patch.yml：将其复制到
/profiles//cordis.patch.yml，然后重启该配置文件。

无需启动即可验证组合：

dsh --profile  --dump-config | grep -A3 searchProvider   # → local-chrome

✅ 最终冒烟测试（在重启后执行此操作）： 让 agent 运行一次
web_search，并确认它返回真实结果（例如“使用 web_search 搜索 'deepseek harness' 并报告 URL”）。这会检验完整链路
（工具 → 接缝 → 提供方 → Chrome → 引擎）；之前的检查只能证明
配置接线正确。要求该配置文件有一个 agent 会话（Web GUI 或
一个已配置为无头模式的配置文件均可）。

4.（替代方案）让 dsh agent 为您安装

无需执行上述手动步骤，将以下任务交给 dsh agent —— 在
Web GUI 聊天中，或一次性无头模式：

dsh --profile headless "Install and enable dsh-web-search-chrome for a dsh profile.

1. Detect the platform (WSL vs native, Linux/macOS/Windows).
2. Install the agent-browser CLI if missing: 'npm install -g agent-browser', then
'agent-browser install' (add --with-deps on Linux if Chrome fails to launch).
VERIFY CHROME CAN ACTUALLY LAUNCH (doctor is not enough — it misses missing
shared libraries): run 'agent-browser open example.com' then 'agent-browser
close --all'. If it fails with 'error while loading shared libraries',
install nss/nspr/alsa-lib and make sure the dsh process finds them (export
LD_LIBRARY_PATH in the shell that starts dsh, or use a wrapper script).
3. Install the plugin: 'dsh plugin --profile  add dsh-web-search-chrome'.
4. Write \$DSH_HOME/profiles//cordis.patch.yml (default \$DSH_HOME is
~/.dsh). Use the CURRENT USER'S REAL home directory in profilePath — never a
literal /home/you:

- insert:
- id: web-search-chrome
name: dsh-web-search-chrome
config:
profilePath: /.dsh-web-search-chrome/profile
- id: web
config:
searchProvider: local-chrome

5. Verify without booting: 'dsh --profile  --dump-config' must show
web-search-chrome 行和 'searchProvider: local-chrome'。
6. 向用户报告：该切换在下次 profile 启动时生效（插件模块按进程缓存），因此他们必须重启 profile；重启后，web_search 应返回结果。
除非用户要求，否则不要自行重启 profile。”

该 agent 通过 shell 访问执行所有步骤，并自行解析真实的
profilePath，因此避免了 /home/you 占位符陷阱。要求
该 profile 的 agent 预设已启用 shell 工具（标准预设
已启用）。

⚠️ 并发注意事项。 一次性无头形式会在与任何正在运行的 profile 相同的 $DSH_HOME 上启动第二个 dsh
进程。如果 Web GUI 已
启动，请优先将任务粘贴到 GUI 聊天中；如果你在 GUI 运行时
使用 dsh --profile headless，共享存储写入可能会
发生竞争（观察到会导致正在运行的 GUI 崩溃）。请先停止 GUI，或为
无头运行提供隔离的 DSH_HOME（例如 DSH_HOME=/tmp/… dsh --profile
headless "…"）。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| agentBrowserPath | agent-browser | 可执行文件：通过 PATH 解析的裸名称，或完整路径（例如从 WSL 使用的 Windows 侧 exe）。 |
| profilePath | 必填 | 传递给 --profile 的 Chrome profile 目录。如果不存在则创建。 |
| engine | bing | 搜索引擎：bing 或 google。Bing 是默认值（对 VPN/数据中心 IP 的容忍度高得多）；google 在可用时可用。 |
| headed | false | 显示 Chrome 窗口（--headed）而不是无头模式。 |
| hl | en | 引擎界面/结果语言（Google 使用 hl，Bing 使用 setlang）。 |
| num | 10 | 向引擎请求的结果数上限。 |
| timeoutMs | 20000 | 每次搜索的硬超时。 |
| cacheTtlMs | 86400000 | 磁盘缓存 TTL；0 禁用磁盘缓存（会话缓存始终开启）。 |
| queueConcurrency | 1 | 串行队列 — 0.1 仅支持 1。 |
| cachePath | 操作系统缓存目录 | 磁盘缓存文件覆盖路径（POSIX 上为 ~/.cache/dsh-web-search-chrome/cache.json，Windows 上为 %LOCALAPPDATA%\dsh-web-search-chrome\cache.json）。 |

完整参考：docs/configuration.md · docs/README.md（文档索引）。

错误（英文，可操作 — 无回退引擎）

| 情况 | 消息（示例） |
|---|---|
| agent-browser 缺失 | agent-browser CLI not found. Install with: npm install -g agent-browser (>= 0.34.0) |
| 版本过旧 | agent-browser 0.33.0 is too old; 0.34.0 or newer is required. Upgrade with: npm install -g agent-browser@latest |
| profile 不可用 | Chrome profile not found at "" and could not be created: … / … is not writable. Fix permissions … |
| Chrome 已在 profile 上运行 | Chrome is running. Close all Chrome windows before searching, or point profilePath at a dedicated profile directory. |
| 引擎验证码/反机器人 | Bing 返回了验证码/同意页面。请在此网络上的浏览器中打开并完成一次验证，或启用有头模式（headed: true）。 |
| 引擎同意 | Bing 返回了同意页面。请在此网络上的浏览器中接受一次同意对话框，或启用有头模式（headed: true）。 |
| 超时 | 搜索在 20000ms 后超时。 |
| 无结果 | 未找到查询的搜索结果。 |

这里刻意没有自动回退到其他引擎——失败会被报告出来，以便你采取相应措施（PRD §2）。

跨平台说明

- agent-browser 二进制的解析顺序：配置的完整路径 → PATH 查找 →（检测到 WSL）通过互操作使用 Windows npm 全局安装（/mnt/c/Users//AppData/Roaming/npm/agent-browser）→ 可操作的错误。
- Windows 原生：在 Windows 上使用 npm 安装 agent-browser；PATH 查找会找到 agent-browser.cmd。
- WSL：要么使用 PATH 上的 Linux agent-browser，要么通过互操作使用 Windows 版本（两者均可；agentBrowserPath 可固定完整路径）。
- macOS/Linux：直接使用 PATH 查找。

已测试范围（如实说明）

- 已测试（0.1）：WSL2（Linux）端到端——通过 agent-browser 使用 Chrome for Testing，无头模式 + --profile，针对 Bing（默认，已通过实时 E2E 验证：模型 → web_search → 真实结果）和 Google 的 SERP 提取流水线（已通过 fixture 验证；在 Google 不设限制的网络上可实时运行），缓存、队列、错误语义，以及完整的 ctx.web 接缝与面向模型的 web_search 工具；Windows 互操作二进制解析（本机的 PATH 命中了 Windows npm 全局安装）。还在实时 dsh web 配置文件中验证过（searchProvider 切换为 local-chrome，模型 web_search 通过插件返回真实的 Bing 结果）。
- 尚未端到端测试（按 PRD 为 v1.1）：原生 macOS/Linux 桌面和 Windows 原生 dsh。代码路径是平台中立的（spawn + PATH），但被标记为未测试。
- 反机器人：Bing 对 VPN/数据中心 IP 容忍度较高（已实时验证）；Google 可能会对被标记网络上的浏览器流量返回其“异常流量”插页——插件会将其报告为可操作的错误（engine: google 用户：将搜索间隔降低到 ≥ 30 秒，使用持久化配置文件，或通过住宅代理路由；在有头模式下完成一次插页验证也有帮助）。

开发

要求：Node.js ≥ 22 和 pnpm（工具链——tsdown、vitest 4、pnpm 11——不支持更旧的 Node）。

pnpm install
pnpm run build            # tsdown → single-file lib/index.js + lib/index.d.ts
pnpm run typecheck        # tsc --noEmit (strict)
pnpm run lint             # ESLint 9 + typescript-eslint
pnpm test                 # vitest unit tests (self-contained)
pnpm run test:live        # live engine test (needs agent-browser + browser)
pnpm run verify-extraction # runs the SERP extraction pipeline against local fixtures in real Chrome
node scripts/e2e-live.mjs bing   # live engine E2E through ctx.web (bing|google)
构建形态与 deepseek-harness 包保持一致：TypeScript 源码位于
src/，一个 tsdown 打包产物（fixedExtension: false → lib/index.js）外加
打包生成的 lib/index.d.ts；node 内置模块和 @deepseek-ai/ 保持外部依赖。

- SERP 提取选择器只存在于一个地方：src/serp.ts（EXTRACTION_SCRIPT，引擎自适应——Bing #b_results / Google #search a:has(h3)）。引擎 DOM 变更都在那里被吸收。
- 完整文档索引：docs/README.md —— 配置参考、§10 决策记录（包括 Bing 默认决策 §D7），以及 M3 验收记录。

许可证

MIT —— 参见 LICENSE。agent-browser 是一个外部 Apache-2.0 CLI；不存在许可证污染。