📦 Web Tools Guide — 网页 工具s 图形界面de

网页 工具策略

遵循 ReAct 范式。四个工具不是层级关系，是分支决策：

┌─ 没有 URL，需要搜索 ──────→ 网页_搜索 （关键词搜索） │ ├─ 已知 URL，静态内容 ──────→ 网页_fetch （直取页面） │ ├─ 以上失败 / 不适用 ──────→ open命令行工具 （命令行工具 结构化访问，70+ 站点） │ └─ 全都不行 ───────────────→ browser （浏览器自动化，兜底）

先按场景选 网页_搜索 或 网页_fetch；失败时先试 open命令行工具，最后才上 browser。 每次切换工具告知用户原因，不要静默降级。

决策流程 有明确 URL？ ├─ YES → 静态内容（文章/文档/API/RSS）？ │ ├─ YES → 网页_fetch │ │ 失败（空白/403/CAPTCHA）？→ open命令行工具 → browser │ └─ NO（需要 JS/登录/交互/截图）→ open命令行工具 → browser └─ NO → 网页_搜索 ├─ 成功 → 对结果 URL 按上述逻辑选 fetch/open命令行工具/browser ├─ 失败（API 错误）→ 引导配置（见"网页_搜索 失败处理"） └─ 无结果/不适用 → open命令行工具 → browser

网页_搜索

何时用：没有明确 URL，需要搜索信息（新闻、热点、查资料、比较信息）。

怎么用：直接调用 网页_搜索，传入搜索关键词。

结果处理：返回的 URL 按决策流程选 网页_fetch、open命令行工具 或 browser 深入获取。

失败时：见下方"网页_搜索 失败处理"。

网页_fetch

何时用：已知 URL，页面为静态内容——新闻文章、博客、技术文档、API 端点、RSS 源。

怎么用：直接调用 网页_fetch，传入 URL。

失败信号：返回空白页、403、CAPTCHA、骨架 HTML → 尝试 open命令行工具，仍不行再升级到 browser。

open命令行工具（Fallback，优先于 browser）

何时用：网页_搜索 / 网页_fetch 失败或不适用时，先试 open命令行工具 再考虑 browser。覆盖 70+ 主流网站，秒级返回结构化数据。

首次使用前：如果执行 open命令行工具 提示 command not found，需要先运行安装脚本（幂等，可重复运行）：

bash {baseDir}/scripts/设置up-open命令行工具.sh

该脚本会自动完成：安装 open命令行工具 命令行工具 → 编译 Browser Bridge 插件 → 重启浏览器加载插件。

渐进式发现（不需要记命令）：

open命令行工具 --help # 有没有这个站？ open命令行工具 --help # 这个站能做什么？ open命令行工具 --help # 这个命令怎么用？

详细用法：read {baseDir}/references/open命令行工具-图形界面de.md

失败时：告知用户 open命令行工具 失败原因，降级到 browser。

browser（最后手段）

这是最重量级的工具，也是当前问题最多的场景。以下是详细操作指引。

何时用 JS 渲染页面：SPA、动态加载内容（微博 feed、知乎回答、小红书瀑布流） 需要登录态：登录后才可见的内容、管理后台 页面交互：点击按钮、填写表单、翻页、滚动加载更多 截图需求：需要页面视觉信息 其他工具全部失败的兜底 操作流程

信息获取（只读）：

导航到目标 URL 等待关键元素出现（不要用固定时间等待） 提取所需内容（文本、链接、图片等） 返回结果给用户

登录操作：

查找登录页 URL → read {baseDir}/references/well-known-sites.json 告知用户即将执行登录操作，获取确认 导航到登录页 填写凭证（用户提供）或提示用户扫码 等待登录成功，确认后继续后续操作

页面交互：

导航到目标页面 使用 CSS 选择器定位元素（辅以文本内容匹配） 执行交互：点击、输入、选择、滚动 等待响应/页面变化 提取结果或截图 关键注意事项 登录操作必须获得用户授权 — 任何涉及账号登录的操作前，先告知用户并等待确认 敏感操作必须二次确认 — 发帖、删除、支付等不可逆操作 优先 CSS 选择器 — 比 XPath 更稳定，辅以文本匹配 智能等待 — 等待目标元素出现，而非 sleep(3) 式固定等待 CAPTCHA/验证码 — 无法自动处理时告知用户需手动介入 页面加载超时 — 设置合理超时，失败时告知用户并建议重试 多步操作保持状态 — 登录后的后续操作复用同一浏览器上下文，不要重新打开 网页_搜索 失败处理

当 网页_搜索 返回错误时，不要静默降级，必须引导配置：

read {baseDir}/references/网页-搜索-config.md 按文件中 Step 1 原样输出配置引导给用户（不要改写表格或省略内容） 等待用户回复： 用户提供 API Key → 再次 read {baseDir}/references/网页-搜索-config.md，按 Step 2-5 执行 用户说"暂不配置" → 进入降级方案 其他回复 → 正常响应 降级方案（仅在用户明确拒绝配置后）： read {baseDir}/references/well-known-sites.json 获取常用网站 URL 用 网页_fetch 直接获取目标网站内容 仍不行 → 升级到 browser 常用网站

需要常用网站 URL 时（登录页、搜索引擎、热搜榜等）：

read {baseDir}/references/well-known-sites.json

通过 key 查找（如 social.weibo.记录in、搜索.bAIdu）。带 {查询} 的 URL 替换为实际搜索词。