dsh-web-search-pro 0.1.4 → 0.1.6

package/LOGIN.md

@@ -1,108 +1,161 @@
-# 中文社区平台登录态（复用你已登录的浏览器）
-
-知乎 / 微博 / 豆瓣 / 贴吧 / 抖音 / 快手 / 小红书的搜索页都有反爬与登录墙，
-免登录的公开接口基本都被风控。所以这些平台走 **Playwright 驱动登录态浏览器** 的路径：
-在你已登录的浏览器里打开搜索页、读渲染结果——不需要逆向任何签名。
-
-## 方式一：登录一次保存登录态（推荐）
-
-运行插件包里的脚本，按提示逐个平台登录一次（扫码/账号密码），
-脚本会把所有 cookies 合并保存成一个 storageState JSON：
-
-```bash
-cd dsh-web-search-pro
-node scripts/save-login.mjs all login-state.json
-# 或只登录一个平台：
-node scripts/save-login.mjs zhihu login-state.json
-```
-
-然后在 dsh-browser 的部署配置中创建命名、按域名授权的 AuthProfile：
-
-```yaml
-# cordis.yml 中的 dsh-browser 插件行
-- id: browser
-  name: '@anweat/dsh-browser'
-  config:
-    authProfiles:
-      china-community:
-        storageStatePath: 'D:/secrets/login-state.json'
-        allowedDomains: [zhihu.com, weibo.com, douban.com, baidu.com, douyin.com, kuaishou.com]
-        persistState: false
-
-# $DSH_HOME/settings.yaml
----
-web-search-pro:
-  browserBindings:
-    zhihu: { authProfile: china-community }
-    weibo: { authProfile: china-community }
-```
-
-> storageState 是 Playwright 的标准登录态文件（cookies + origins），
-> 同一份文件可含多个站点登录态，但每个 AuthProfile 必须显式给出 `allowedDomains`；访问其他域名会被拒绝。`persistState` 默认 false，只有明确开启才会原子回写新 Cookie/localStorage。
-
-## 方式二：用 Cookie 插件导出
-
-如果你更习惯手动导出：
-
-1. 在浏览器装 Cookie-Editor（或 EditThisCookie）。
-2. 在目标站点导出 cookies（JSON）。
-3. 组装成 storageState 格式：
-
-```json
-{ "cookies": [ ...导出的 cookies... ], "origins": [] }
-```
-
-每个 cookie 至少需要 `name` `value` `domain` `path`（可补 `expires` `httpOnly` `secure`）。
-
-不要把 Cookie JSON 作为模型工具参数传入；导入到本地 storageState 文件后只在配置中引用路径。
-
-## 受控脚本增强（RulePack V2）
-
-dsh-browser 可配置命名 RulePack。它支持有界的 `waitFor` / `click` / `scroll` / `wait` 步骤；可选 init script 只能引用本地文件，必须提供 SHA-256，且文件不超过 64KB。RulePack 同样按 `matches` 限域，不接受模型直接提交任意 JavaScript。
-
-```yaml
-rulePacks:
-  zhihu-enhanced:
-    matches: [zhihu.com]
-    initScriptPath: 'D:/dsh/rules/zhihu-init.js'
-    initScriptSha256: '<64位sha256>'
-    steps:
-      - { type: waitFor, selector: '.SearchResult-Card', timeoutMs: 10000 }
-      - { type: scroll, deltaY: 1600, repeat: 2, waitMs: 300 }
-```
-
-## OpenCLI 社区平台
-
-Reddit / 小红书 / Twitter / Instagram / Facebook 走 OpenCLI Browser Bridge，使用当前 Chrome 扩展会话，不读取或导出 Cookie。`dsh-browser` 已包含 OpenCLI CLI，但 Chrome 扩展必须已安装并连接：
-
-```bash
-opencli doctor
-opencli reddit search "DeepSeek Harness" -f yaml
-```
-
-若 `doctor` 显示 daemon 正常但 extension disconnected，请启动安装了 OpenCLI 扩展的 Chrome profile；不要把 Quark 或禁用扩展的 Playwright 临时 profile 当作替代。只有需要在终端独立诊断时，才需要额外全局安装 `@jackwener/opencli`。
-
-## 结果选择器可配置
-
-站点改版后如果提取不到结果，不用改代码——在 `settings.yaml` 按平台覆盖选择器：
-
-```yaml
-web-search-pro:
-  platformRules:
-    zhihu:
-      item: '.SearchResult-Card'
-      title: '.ContentItem-title'
-      link: '.ContentItem-title a'
-      text: '.Highlight'
-    weibo:
-      item: '.card-wrap'
-      title: '.txt'
-      link: '.from a'
-```
-
-## 安全与合规提醒
-
-- 仅做**单次、低频**的搜索调用，不要批量爬取；遵守目标平台的服务条款与 robots.txt。
-- 登录态文件包含你的登录凭据，请勿提交到公开仓库或分享给他人。
-- 本能力借鉴 MediaCrawler 的思路（登录态浏览器驱动搜索页），
-  但为 MIT 许可的独立实现，未使用其 NON-COMMERCIAL 许可下的签名算法代码。
+# 中文社区平台登录态（复用你已登录的浏览器）
+
+知乎 / 微博 / 豆瓣 / 贴吧 / 抖音 / 快手 / 小红书的搜索页都有反爬与登录墙，
+免登录的公开接口基本都被风控。所以这些平台走 **Playwright 驱动登录态浏览器** 的路径：
+在你已登录的浏览器里打开搜索页、读渲染结果——不需要逆向任何签名。
+
+## 方式一：登录一次保存登录态（推荐）
+
+运行插件包里的脚本，按提示逐个平台登录一次（扫码/账号密码），
+脚本会把所有 cookies 合并保存成一个 storageState JSON：
+
+```bash
+cd dsh-web-search-pro
+node scripts/save-login.mjs all login-state.json
+# 或只登录一个平台：
+node scripts/save-login.mjs zhihu login-state.json
+```
+
+然后在 dsh-browser 的部署配置中创建命名、按域名授权的 AuthProfile：
+
+```yaml
+# cordis.yml 中的 dsh-browser 插件行
+- id: browser
+  name: '@anweat/dsh-browser'
+  config:
+    automationMode: standard # read-only | standard | autonomous | unrestricted
+    authProfiles:
+      china-community:
+        storageStatePath: 'D:/secrets/login-state.json'
+        allowedDomains: [zhihu.com, weibo.com, douban.com, baidu.com, douyin.com, kuaishou.com]
+        persistState: false
+
+# $DSH_HOME/settings.yaml
+---
+web-search-pro:
+  browserBindings:
+    zhihu: { authProfile: china-community }
+    weibo: { authProfile: china-community }
+```
+
+> storageState 是 Playwright 的标准登录态文件（cookies + origins），
+> 同一份文件可含多个站点登录态，但每个 AuthProfile 必须显式给出 `allowedDomains`；访问其他域名会被拒绝。`persistState` 默认 false，只有明确开启才会原子回写新 Cookie/localStorage。
+> `scripts/save-login.mjs` 优先复用 `@anweat/dsh-browser` 自带的 Playwright；默认启动其 bundled Chromium。如需显式使用已安装的 Chrome，可临时设置 `DSH_BROWSER_CHANNEL=chrome`。
+
+## 方式二：用 Cookie 插件导出
+
+如果你更习惯手动导出：
+
+1. 在浏览器装 Cookie-Editor（或 EditThisCookie）。
+2. 在目标站点导出 cookies（JSON）。
+3. 组装成 storageState 格式：
+
+```json
+{ "cookies": [ ...导出的 cookies... ], "origins": [] }
+```
+
+每个 cookie 至少需要 `name` `value` `domain` `path`（可补 `expires` `httpOnly` `secure`）。
+
+不要把 Cookie JSON 作为模型工具参数传入；导入到本地 storageState 文件后只在配置中引用路径。
+
+## 受控脚本增强（RulePack）
+
+dsh-browser 可配置命名 RulePack。它适合由部署者长期维护的站点增强，支持有界的 `waitFor` / `click` / `scroll` / `wait` 步骤；可选 init script 只能引用本地文件，必须提供 SHA-256，且文件不超过 64KB。RulePack 同样按 `matches` 限域。
+
+```yaml
+rulePacks:
+  zhihu-enhanced:
+    matches: [zhihu.com]
+    initScriptPath: 'D:/dsh/rules/zhihu-init.js'
+    initScriptSha256: '<64位sha256>'
+    steps:
+      - { type: waitFor, selector: '.SearchResult-Card', timeoutMs: 10000 }
+      - { type: scroll, deltaY: 1600, repeat: 2, waitMs: 300 }
+```
+
+## 模型生成 Recipe
+
+临时、多步骤操作不必先写持久 RulePack。模型可调用 `browser_recipe_run`，每次最多 25 步：
+
+```json
+{
+  "url": "https://example.com",
+  "steps": [
+    { "type": "wait", "condition": "selector", "value": "h1" },
+    { "type": "extract", "selector": "h1", "mode": "text" }
+  ]
+}
+```
+
+`wait`、`extract`、`assert`、`screenshot` 是只读路径；一旦包含 `click`、`fill`、`type`、`press`、`select`、`check`、`hover` 或 `scroll`，`standard` 会发起一次性审批，`autonomous` / `unrestricted` 直接执行，`read-only` 拒绝。
+
+## 外部模型生成 UserScript
+
+外部模型可以输出油猴格式脚本，但需要走“先验证、后执行”两步：
+
+```text
+browser_script_validate({ url, source })
+browser_userscript_run({ url, source, authProfile? })
+```
+
+```javascript
+// ==UserScript==
+// @name Read page heading
+// @match https://example.com/*
+// @grant none
+// ==/UserScript==
+return { heading: document.querySelector('h1')?.textContent || '' }
+```
+
+限制与边界：
+
+- 必须声明 HTTP(S) `@match`，`@exclude` 生效；目标 URL 不匹配时拒绝。
+- 只允许 `@grant none`，拒绝 `@require`，源码上限 64KB，输出与运行时间有界。
+- 验证结果包含 SHA-256 和静态能力提示，但能力提示不是安全证明。
+- 脚本运行在目标页主世界，能读写页面并使用该页已有登录态；除 `unrestricted` 外，`browser_userscript_run` 会进入 DSH 原生一次性审批。无审批测试也不要让脚本回传 Cookie、令牌、表单值等秘密。
+
+常见只读任务优先用 `browser_script_catalog` 中的内置 `article-clean`、`links`、`jsonld`、`forms`，无需提交任意脚本。
+
+## OpenCLI 社区平台
+
+Reddit / 小红书 / Twitter / Instagram / Facebook 走 OpenCLI Browser Bridge，使用当前 Chrome 扩展会话，不读取或导出 Cookie。`dsh-browser` 已包含 OpenCLI CLI，但 Chrome 扩展必须已安装并连接：
+
+```bash
+opencli doctor
+opencli reddit search "DeepSeek Harness" -f yaml
+opencli browser research open https://example.com --window background
+opencli browser research state
+opencli browser research extract
+opencli browser research close
+```
+
+每个 `opencli browser` 子命令都必须显式给出 session 名（上例为 `research`），同名会话复用标签页状态。优先使用已有站点 adapter；没有 adapter 时优先 `network` / `extract`，最后再使用 `state` / `find` / `click` / `fill` 等 DOM 操作。
+
+模型内先用 `browser_opencli_status` 检查 daemon、扩展和 profile；高级调用使用 `browser_opencli_run({ args: [...] })`。argv 示例：`["browser", "research", "state"]`。这个通用入口可能触发发帖、删除等站点 adapter，所以除隔离测试用的 `unrestricted` 外都要求一次性审批。
+
+若 `doctor` 显示 daemon 正常但 extension disconnected，请显式启动安装了 OpenCLI Browser Bridge 的 Chrome；不要把 Quark 或禁用扩展的 Playwright 临时 profile 当作替代。只有需要在终端独立诊断时，才需要额外全局安装 `@jackwener/opencli`。
+
+## 结果选择器可配置
+
+站点改版后如果提取不到结果，不用改代码——在 `settings.yaml` 按平台覆盖选择器：
+
+```yaml
+web-search-pro:
+  platformRules:
+    zhihu:
+      item: '.SearchResult-Card'
+      title: '.ContentItem-title'
+      link: '.ContentItem-title a'
+      text: '.Highlight'
+    weibo:
+      item: '.card-wrap'
+      title: '.txt'
+      link: '.from a'
+```
+
+## 安全与合规提醒
+
+- 仅做**单次、低频**的搜索调用，不要批量爬取；遵守目标平台的服务条款与 robots.txt。
+- 登录态文件包含你的登录凭据，请勿提交到公开仓库或分享给他人。
+- 本能力借鉴 MediaCrawler 的思路（登录态浏览器驱动搜索页），
+  但为 MIT 许可的独立实现，未使用其 NON-COMMERCIAL 许可下的签名算法代码。

package/README.md

@@ -1,156 +1,180 @@
-# dsh-web-search-pro
-
-增强型、可持久化的扩展网页搜索插件 for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）。
-
-一个 DSH **bundle 插件**，把多引擎网页搜索、平台搜索、持久化缓存、受控按站增强和 Playwright 渲染打包成模型可直接调用的 11 个工具。路由控制面借鉴 Agent-Reach 的后端探测、顺序选择和失败冷却思路，核心逻辑为本项目原生 TypeScript 实现。
-
-## 安装
-
-```bash
-dsh plugin --profile web add dsh-web-search-pro   # 自动装 dsh-browser（dependency）+ 自动挂载 browser 行（本 patch）
-# 或本地目录 / tarball：
-dsh plugin --profile web add ./dsh-web-search-pro
-# 重启（web profile 关闭了 HMR）：
-dsh --profile web
-```
-
-> npm 安装会解析 `@anweat/dsh-browser`；本地联调可用 `dsh plugin --profile web add ../dsh-browser ../dsh-web-search-pro` 一条命令显式列两个。
-> 依赖 `@deepseek-ai/*` 已发布到 npm（`^0.1.0-rc.6`，与社区 dsh-cc-tui 一致）。
-> 若你的 harness 是本地源码 checkout（如 `0.1.0-rc.5`），版本号可能有出入——用
-> `dsh plugin --profile web add ./<path>` 并在 profile 的 `pnpm-workspace.yaml`
-> 里对齐版本后重装即可。
-
-## 快速使用与适用情形
-
-安装并重启后，直接在 DSH 会话里要求模型调用工具即可：
-
-```text
-请调用 web_backend_status 检查后端，然后用 web_search_pro 搜索
-"DeepSeek Harness community feedback"，指定 exa、fresh=true、返回 8 条来源。
-```
-
-| 情形 | 推荐入口 | 说明 |
-|---|---|---|
-| 日常网页搜索 | `web_search_pro` | 默认按配置顺序回退；需要强制刷新时传 `fresh=true` |
-| 语义研究、社区观点 | `web_search_pro` + `exa` | 有 API Key 时走原生 Exa API；只有 Exa MCP 连接时自动经 `mcporter` 回退 |
-| 已知 URL 的批量正文 | `web_exa_contents` | 直接调用 Exa `/contents`，必须配置 `EXA_API_KEY` |
-| GitHub/B站/Reddit 等平台 | `web_platform_search` | Reddit 等 OpenCLI 平台需要 Chrome 扩展在线；中文受限站点使用 AuthProfile |
-| 登录后页面或私有论坛 | `browserBindings` + AuthProfile | Cookie 保存在本地 storageState，按域名授权，默认只读 |
-| 页面改版、懒加载 | `platformRules` 或 RulePack | 优先改选择器；需要等待/点击/滚动时再使用有界 RulePack |
-
-先运行 `web_backend_status` 判断后端是否 ready。指定单一引擎时失败会原样返回；不指定时才会按 `engines` 顺序自动回退。
-
-## 工具（11 个）
-
-| 工具 | 作用 |
-|---|---|
-| `web_search_pro` | 多引擎搜索 + RRF 融合 + 内存/SQLite 双层缓存 + 历史 |
-| `web_exa_contents` | 原生 Exa `/contents` 批量正文抓取（1-100 URL） |
-| `web_fetch_pro` | 可读化抓取（Jina → HTTP+规则抽取 → Playwright 兜底）+ 快照缓存 |
-| `web_platform_search` | 20 平台：GitHub/B站/YouTube/V2EX/小红书/Twitter/Reddit/IG/FB/RSS + 知乎/微博/豆瓣/贴吧/抖音/快手（Playwright 登录态） |
-| `web_snapshot` | Playwright 全页截图 + HTML + 文本落盘 |
-| `web_history` / `web_cache_clear` / `web_search_stats` | 持久历史 / 清缓存 / 存储统计 |
-| `web_rule` | 持久化按站提取规则（脚本猫式，list/upsert/remove） |
-| `web_backend_status` | 无副作用后端探测、失败/冷却诊断与 CLI 状态 |
-| `web_deps` | 检测/安装外部依赖（gh/bili/yt-dlp/opencli/agent-reach/mcporter/playwright） |
-
-## 配置
-
-三层，越靠前越日常：
-
-1. **`$DSH_HOME/settings.yaml` → `web-search-pro:` 段**（热重载，改完即生效）：
-
-   ```yaml
-   web-search-pro:
-     exaApiKeyEnv: EXA_API_KEY # 推荐：运行环境或凭据服务，不把密钥写入配置
-     jinaApiKeyEnv: JINA_API_KEY
-     engines: [ddg, bing, exa, seam, jina]
-     parallelEngines: false
-     ttlSeconds: 3600
-     searchMaxResults: 8
-     browserBindings:
-       zhihu:
-         authProfile: china-community
-         rulePack: zhihu-enhanced
-   ```
-
-2. **cordis.yml `config:`**（部署级默认值，见 `cordis.patch.yml`）。
-3. **环境变量 / 凭据**：`$EXA_API_KEY`、`$JINA_API_KEY`（`exaApiKeyEnv`/`jinaApiKeyEnv` 引用）。
-
-## 外部依赖（按需）
-
-多数后端需要系统额外安装的工具；插件提供 `web_deps` 工具检测与安装：
-
-| 依赖 | 用途 | 安装 |
-|---|---|---|
-| bili-cli | B站后端 | `uv tool install bili-cli` / `pipx install bili-cli` |
-| yt-dlp | YouTube 后端 | `uv tool install yt-dlp` / `pip install yt-dlp` |
-| opencli | 小红书/Twitter/Reddit/IG/FB | 由 dsh-browser 内置；扩展未连接时用 `opencli doctor` 诊断 |
-| agent-reach | agent-reach 后端 | `uv tool install agent-reach` / `pip install agent-reach` |
-| mcporter | 无裸 API Key 时的 Exa MCP 回退 | `npm i -g mcporter` |
-| playwright | 渲染/截图后端 | 由 dsh-browser 内置；缺 Chromium 时调用 `browser_install` |
-
-## 平台与引擎
-
-`seam`（ctx.web/DeepSeek 原生）· `exa` · `ddg` · `bing` · `jina` · `github`（REST 搜索 API，免 CLI；可选 `$GITHUB_TOKEN`/`githubToken` 提升限额并解锁代码搜索）· `bilibili` · `v2ex` · `youtube`。默认顺序 `ddg, bing, exa, seam, jina`（免费优先），失败自动回退；失败后短时冷却，`web_backend_status` 可查看原因；`multi` 并行融合。
-
-Exa 优先使用原生 API 客户端：`web_search_pro` 可传 `exaType`、域名包含/排除、发布时间范围和 category。若没有裸 API Key、但启用了 CLI 后端且 Exa MCP 已连接，搜索会自动通过 `mcporter` 完成；该兼容路径只支持 query + 结果数，高级筛选和 `web_exa_contents` 仍要求 `EXA_API_KEY`。不同选项、结果数、引擎顺序和单/多引擎模式使用不同缓存指纹。
-
-## 开发
-
-```bash
-pnpm install
-pnpm test
-pnpm build        # tsc src → lib
-```
-
-源码在 `src/`；`lib/` 为发布产物（已提交）。
-
-## License
-
-MIT
-
-
-## 中文社区平台登录态
-
-zhihu / weibo / douban / tieba / douyin / kuaishou 的免登录公开接口都被风控，
-所以走 **Playwright 驱动登录态浏览器**（借鉴 MediaCrawler 思路、MIT 独立实现，未用其签名算法）：
-
-1. 登录一次保存登录态：`node scripts/save-login.mjs all login-state.json`
-2. 在 dsh-browser 配置中声明按域名隔离的 `authProfiles`
-3. 在 `browserBindings` 把平台绑定到 profile；站点改版时用 `platformRules` 或 dsh-browser `rulePacks`
-
-详见 [LOGIN.md](./LOGIN.md)。
-
-
-## 历史管理
-
-web_history 支持：kind/query/engine/platform 过滤、replay（用 queryId 回放已存结果）、
-export（把过滤后的历史+结果写成 JSON 文件）。
-
-## 自定义平台
-
-在 settings.yaml 里定义任意站点（URL 模板 + 结果选择器），
-web_platform_search 就能直接搜它——不需要改代码：
-
-    web-search-pro:
-      customPlatforms:
-        mybili:
-          name: '我的B站'
-          url: 'https://search.bilibili.com/all?keyword={query}'
-          item: '.bili-video-card'
-          title: '.bili-video-card__info--tit'
-          link: 'a'
-        # 需要登录时优先通过 browserBindings 绑定命名 authProfile。
-        myforum:
-          name: '某论坛'
-          url: 'https://forum.example.com/search?q={query}'
-          item: '.thread'
-          title: '.thread-title a'
-          link: '.thread-title a'
-      browserBindings:
-        myforum:
-          authProfile: forum
-
-旧版 `customPlatforms.*.cookie` 仍兼容，但会让 Cookie 明文进入配置；新配置应使用 dsh-browser 的命名 AuthProfile，状态文件不要提交到仓库。
-
+# dsh-web-search-pro
+
+增强型、可持久化的扩展网页搜索插件 for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）。
+
+一个 DSH **bundle 插件**，把多引擎网页搜索、平台搜索、持久化缓存、受控按站增强和 Playwright 渲染打包成模型可直接调用的 11 个工具。路由控制面借鉴 Agent-Reach 的后端探测、顺序选择和失败冷却思路，核心逻辑为本项目原生 TypeScript 实现。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-web-search-pro   # 自动装 dsh-browser（dependency）+ 自动挂载 browser 行（本 patch）
+# 或本地目录 / tarball：
+dsh plugin --profile web add ./dsh-web-search-pro
+# 重启（web profile 关闭了 HMR）：
+dsh --profile web
+```
+
+> npm 安装会解析 `@anweat/dsh-browser`；本地联调可用 `dsh plugin --profile web add ../dsh-browser ../dsh-web-search-pro` 一条命令显式列两个。
+> 依赖 `@deepseek-ai/*` 已发布到 npm（`^0.1.0-rc.6`，与社区 dsh-cc-tui 一致）。
+> 若你的 harness 是本地源码 checkout（如 `0.1.0-rc.5`），版本号可能有出入——用
+> `dsh plugin --profile web add ./<path>` 并在 profile 的 `pnpm-workspace.yaml`
+> 里对齐版本后重装即可。
+
+## 快速使用与适用情形
+
+安装并重启后，直接在 DSH 会话里要求模型调用工具即可：
+
+```text
+请调用 web_backend_status 检查后端，然后用 web_search_pro 搜索
+"DeepSeek Harness community feedback"，指定 exa、fresh=true、返回 8 条来源。
+```
+
+| 情形 | 推荐入口 | 说明 |
+|---|---|---|
+| 日常网页搜索 | `web_search_pro` | 默认按配置顺序回退；需要强制刷新时传 `fresh=true` |
+| 语义研究、社区观点 | `web_search_pro` + `exa` | 有 API Key 时走原生 Exa API；只有 Exa MCP 连接时自动经 `mcporter` 回退 |
+| 已知 URL 的批量正文 | `web_exa_contents` | 直接调用 Exa `/contents`，必须配置 `EXA_API_KEY` |
+| GitHub/B站/Reddit 等平台 | `web_platform_search` | Reddit 等 OpenCLI 平台需要 Chrome 扩展在线；中文受限站点使用 AuthProfile |
+| 登录后页面或私有论坛 | `browserBindings` + AuthProfile | Cookie 保存在本地 storageState，按域名授权，默认只读 |
+| 页面改版、懒加载 | `platformRules` 或 RulePack | 优先改选择器；需要等待/点击/滚动时再使用有界 RulePack |
+| 模型生成多步页面操作 | `browser_recipe_run` | 只读步骤直接运行；页面交互按 dsh-browser 的 `automationMode` 决定拒绝/审批/直通 |
+| 外部模型生成油猴脚本 | `browser_script_validate` → `browser_userscript_run` | 强制 `@match`、`@grant none`、禁用 `@require`；仅 `unrestricted` 跳过审批 |
+| OpenCLI 站点适配器或浏览器桥 | `browser_opencli_status` / `browser_opencli_run` | 明确使用 Chrome；仅 `unrestricted` 跳过通用 argv 审批 |
+
+先运行 `web_backend_status` 判断后端是否 ready。指定单一引擎时失败会原样返回；不指定时才会按 `engines` 顺序自动回退。
+
+## 工具（11 个）
+
+| 工具 | 作用 |
+|---|---|
+| `web_search_pro` | 多引擎搜索 + RRF 融合 + 内存/SQLite 双层缓存 + 历史 |
+| `web_exa_contents` | 原生 Exa `/contents` 批量正文抓取（1-100 URL） |
+| `web_fetch_pro` | 可读化抓取（Jina → HTTP+规则抽取 → Playwright 兜底）+ 快照缓存 |
+| `web_platform_search` | 20 平台：GitHub/B站/YouTube/V2EX/小红书/Twitter/Reddit/IG/FB/RSS + 知乎/微博/豆瓣/贴吧/抖音/快手（Playwright 登录态） |
+| `web_snapshot` | Playwright 全页截图 + HTML + 文本落盘 |
+| `web_history` / `web_cache_clear` / `web_search_stats` | 持久历史 / 清缓存 / 存储统计 |
+| `web_rule` | 持久化按站提取规则（脚本猫式，list/upsert/remove） |
+| `web_backend_status` | 无副作用后端探测、失败/冷却诊断与 CLI 状态 |
+| `web_deps` | 检测/安装搜索后端的外部依赖（gh/bili/yt-dlp/agent-reach/mcporter）；浏览器依赖由 dsh-browser 管理 |
+
+## 浏览器脚本与自动化分层
+
+`dsh-browser >= 0.1.7` 提供三类脚本入口：
+
+1. **内置只读脚本**：`article-clean`、`links`、`jsonld`、`forms`，适合稳定抽取；先用 `browser_script_catalog` 查看。
+2. **Recipe**：最多 25 步的结构化 Playwright 操作，支持 wait/click/fill/type/press/select/check/hover/scroll/extract/assert/screenshot；交互步骤由自动化模式决定审批。
+3. **外部 UserScript**：适合外部模型生成站点专项逻辑。先 `browser_script_validate` 查看 SHA-256、域名范围与能力提示，再 `browser_userscript_run`；它在页面主世界运行，并非安全沙箱。
+
+工具自由度由 dsh-browser 的 `automationMode` 控制：`read-only` 仅暴露 10 个读取/校验工具；`standard`（默认）对交互、写 Recipe、外部脚本、OpenCLI 和安装操作审批；`autonomous` 直通页面交互和写 Recipe；`unrestricted` 为隔离测试 profile 提供完全无审批运行，但仍保留域名、参数、大小和步骤上限校验。
+
+OpenCLI 用于已有站点 adapter 或复用 Chrome 登录会话。推荐顺序是 **站点 adapter → network/extract → DOM 操作**；先运行 `browser_opencli_status`。`browser_opencli_run` 接受 argv 数组而非 shell 字符串，可覆盖 adapter、显式 session 的 `browser state/find/get/click/fill/type/select/keys/wait/extract/network` 等命令；仅 `unrestricted` 跳过审批。
+
+更完整的 AuthProfile、脚本元数据与 OpenCLI 示例见 [LOGIN.md](./LOGIN.md)。
+
+## 配置
+
+三层，越靠前越日常：
+
+1. **DSH 可视化面板**：打开 `设置 → 插件 → 插件配置 → Web Search Pro`。面板按搜索策略、服务凭据、运行时后端和高级规则分组；修改先保留为本地草稿，点击“保存”后写入 `settings.yaml` 并热更新，支持放弃修改和逐字段恢复部署值。
+
+   - Exa、Jina、GitHub 密钥通过 DSH Credentials 写入，面板只显示“已配置/未配置”，不会把明文密钥读回浏览器。
+   - `platformRules`、`customPlatforms`、`browserBindings` 与 Playwright 设置使用 JSON 对象编辑器；格式或数值范围无效时会阻止保存。
+   - 浏览器工具的审批自由度仍由 `dsh-browser.automationMode` 管辖；用 `browser_status` 查看当前模式。Web Search Pro 面板只管理搜索插件自己的后端开关，不会绕过 dsh-browser 的审批策略。
+   - 更新带客户端面板的插件版本后需要重启 Web profile，让 DSH 客户端模块扫描器重新装载 `client.js`。
+
+2. **`$DSH_HOME/settings.yaml` → `web-search-pro:` 段**（热重载，改完即生效）：
+
+   ```yaml
+   web-search-pro:
+     exaApiKeyEnv: EXA_API_KEY # 推荐：运行环境或凭据服务，不把密钥写入配置
+     jinaApiKeyEnv: JINA_API_KEY
+     engines: [ddg, bing, exa, seam, jina]
+     parallelEngines: false
+     ttlSeconds: 3600
+     searchMaxResults: 8
+     browserBindings:
+       zhihu:
+         authProfile: china-community
+         rulePack: zhihu-enhanced
+   ```
+
+3. **cordis.yml `config:`**（部署级默认值，见 `cordis.patch.yml`）。
+4. **环境变量 / 凭据**：`$EXA_API_KEY`、`$JINA_API_KEY`（`exaApiKeyEnv`/`jinaApiKeyEnv` 引用）。
+
+## 外部依赖（按需）
+
+多数后端需要系统额外安装的工具；插件提供 `web_deps` 工具检测与安装：
+
+| 依赖 | 用途 | 安装 |
+|---|---|---|
+| bili-cli | B站后端 | `uv tool install bili-cli` / `pipx install bili-cli` |
+| yt-dlp | YouTube 后端 | `uv tool install yt-dlp` / `pip install yt-dlp` |
+| opencli | 小红书/Twitter/Reddit/IG/FB | 由 dsh-browser 内置；扩展未连接时用 `opencli doctor` 诊断 |
+| agent-reach | agent-reach 后端 | `uv tool install agent-reach` / `pip install agent-reach` |
+| mcporter | 无裸 API Key 时的 Exa MCP 回退 | `npm i -g mcporter` |
+| playwright | 渲染/截图后端 | 由 dsh-browser 内置；缺 Chromium 时调用 `browser_install` |
+
+## 平台与引擎
+
+`seam`（ctx.web/DeepSeek 原生）· `exa` · `ddg` · `bing` · `jina` · `github`（REST 搜索 API，免 CLI；可选 `$GITHUB_TOKEN`/`githubToken` 提升限额并解锁代码搜索）· `bilibili` · `v2ex` · `youtube`。默认顺序 `ddg, bing, exa, seam, jina`（免费优先），失败自动回退；失败后短时冷却，`web_backend_status` 可查看原因；`multi` 并行融合。
+
+Exa 优先使用原生 API 客户端：`web_search_pro` 可传 `exaType`、域名包含/排除、发布时间范围和 category。若没有裸 API Key、但启用了 CLI 后端且 Exa MCP 已连接，搜索会自动通过 `mcporter` 完成；该兼容路径只支持 query + 结果数，高级筛选和 `web_exa_contents` 仍要求 `EXA_API_KEY`。不同选项、结果数、引擎顺序和单/多引擎模式使用不同缓存指纹。
+
+## 开发
+
+```bash
+pnpm install
+pnpm test
+pnpm build        # tsc src → lib
+```
+
+源码在 `src/`；`lib/` 为发布产物（已提交）。
+
+## License
+
+MIT
+
+
+## 中文社区平台登录态
+
+zhihu / weibo / douban / tieba / douyin / kuaishou 的免登录公开接口都被风控，
+所以走 **Playwright 驱动登录态浏览器**（借鉴 MediaCrawler 思路、MIT 独立实现，未用其签名算法）：
+
+1. 登录一次保存登录态：`node scripts/save-login.mjs all login-state.json`
+2. 在 dsh-browser 配置中声明按域名隔离的 `authProfiles`
+3. 在 `browserBindings` 把平台绑定到 profile；站点改版时用 `platformRules` 或 dsh-browser `rulePacks`
+
+详见 [LOGIN.md](./LOGIN.md)。
+
+
+## 历史管理
+
+web_history 支持：kind/query/engine/platform 过滤、replay（用 queryId 回放已存结果）、
+export（把过滤后的历史+结果写成 JSON 文件）。
+
+## 自定义平台
+
+在 settings.yaml 里定义任意站点（URL 模板 + 结果选择器），
+web_platform_search 就能直接搜它——不需要改代码：
+
+    web-search-pro:
+      customPlatforms:
+        mybili:
+          name: '我的B站'
+          url: 'https://search.bilibili.com/all?keyword={query}'
+          item: '.bili-video-card'
+          title: '.bili-video-card__info--tit'
+          link: 'a'
+        # 需要登录时优先通过 browserBindings 绑定命名 authProfile。
+        myforum:
+          name: '某论坛'
+          url: 'https://forum.example.com/search?q={query}'
+          item: '.thread'
+          title: '.thread-title a'
+          link: '.thread-title a'
+      browserBindings:
+        myforum:
+          authProfile: forum
+
+旧版 `customPlatforms.*.cookie` 仍兼容，但会让 Cookie 明文进入配置；新配置应使用 dsh-browser 的命名 AuthProfile，状态文件不要提交到仓库。
+

package/cordis.patch.yml

@@ -1,12 +1,12 @@
-# dsh-web-search-pro bundle patch.
-#
-# Install BOTH bundles (DSH activates only DIRECT dependencies' bundle layers):
-#   dsh plugin --profile <name> add @anweat/dsh-browser dsh-web-search-pro
-#
-# @anweat/dsh-browser is declared as a peerDependency: it provides the browser
-# service that this plugin injects (inject: ['browser']).
-- insert:
-    - id: web-search-pro
-      name: dsh-web-search-pro
-      config:
-        verbose: false
+# dsh-web-search-pro bundle patch.
+#
+# Install BOTH bundles (DSH activates only DIRECT dependencies' bundle layers):
+#   dsh plugin --profile <name> add @anweat/dsh-browser dsh-web-search-pro
+#
+# @anweat/dsh-browser is declared as a peerDependency: it provides the browser
+# service that this plugin injects (inject: ['browser']).
+- insert:
+    - id: web-search-pro
+      name: dsh-web-search-pro
+      config:
+        verbose: false