{"skill":{"slug":"lobster-web-tools","displayName":"Web Tools Guide","summary":"MANDATORY before calling web_search, web_fetch, browser, or opencli. Contains required error-handling procedures (web_search failure → must guide user to con...","description":"---\nversion: 1.0.0\nname: web-tools-guide\ndescription: \"MANDATORY before calling web_search, web_fetch, browser, or opencli. Contains required error-handling procedures (web_search failure → must guide user to configure API), fallback chain (opencli CLI covers 70+ sites as structured fallback before browser), and site-specific login URLs. Without reading this skill, you WILL handle failures incorrectly and miss available tools. Trigger on: 搜索/上网/查资料/打开网站/抓取网页/新闻/热点/web search/fetch/browser/opencli.\"\n---\n\n<!-- baseDir = /root/.openclaw/workspace/skills/web-tools-guide -->\n\n# Web 工具策略\n\n遵循 ReAct 范式。**四个工具不是层级关系，是分支决策**：\n\n```\n┌─ 没有 URL，需要搜索 ──────→ web_search   （关键词搜索）\n│\n├─ 已知 URL，静态内容 ──────→ web_fetch    （直取页面）\n│\n├─ 以上失败 / 不适用 ──────→ opencli      （CLI 结构化访问，70+ 站点）\n│\n└─ 全都不行 ───────────────→ browser      （浏览器自动化，兜底）\n```\n\n先按场景选 web_search 或 web_fetch；失败时先试 opencli，最后才上 browser。\n每次切换工具告知用户原因，不要静默降级。\n\n---\n\n## 决策流程\n\n```\n有明确 URL？\n├─ YES → 静态内容（文章/文档/API/RSS）？\n│        ├─ YES → web_fetch\n│        │        失败（空白/403/CAPTCHA）？→ opencli → browser\n│        └─ NO（需要 JS/登录/交互/截图）→ opencli → browser\n└─ NO  → web_search\n         ├─ 成功 → 对结果 URL 按上述逻辑选 fetch/opencli/browser\n         ├─ 失败（API 错误）→ 引导配置（见\"web_search 失败处理\"）\n         └─ 无结果/不适用 → opencli → browser\n```\n\n---\n\n## web_search\n\n**何时用**：没有明确 URL，需要搜索信息（新闻、热点、查资料、比较信息）。\n\n**怎么用**：直接调用 `web_search`，传入搜索关键词。\n\n**结果处理**：返回的 URL 按决策流程选 `web_fetch`、`opencli` 或 `browser` 深入获取。\n\n**失败时**：见下方\"web_search 失败处理\"。\n\n---\n\n## web_fetch\n\n**何时用**：已知 URL，页面为静态内容——新闻文章、博客、技术文档、API 端点、RSS 源。\n\n**怎么用**：直接调用 `web_fetch`，传入 URL。\n\n**失败信号**：返回空白页、403、CAPTCHA、骨架 HTML → 尝试 `opencli`，仍不行再升级到 `browser`。\n\n---\n\n## opencli（Fallback，优先于 browser）\n\n**何时用**：web_search / web_fetch 失败或不适用时，先试 opencli 再考虑 browser。覆盖 70+ 主流网站，秒级返回结构化数据。\n\n**首次使用前**：如果执行 `opencli` 提示 command not found，需要先运行安装脚本（幂等，可重复运行）：\n```bash\nbash {baseDir}/scripts/setup-opencli.sh\n```\n该脚本会自动完成：安装 opencli CLI → 编译 Browser Bridge 插件 → 重启浏览器加载插件。\n\n**渐进式发现（不需要记命令）**：\n```bash\nopencli --help                    # 有没有这个站？\nopencli <site> --help             # 这个站能做什么？\nopencli <site> <command> --help   # 这个命令怎么用？\n```\n\n**详细用法**：`read {baseDir}/references/opencli-guide.md`\n\n**失败时**：告知用户 opencli 失败原因，降级到 browser。\n\n---\n\n## browser（最后手段）\n\n这是最重量级的工具，也是当前问题最多的场景。以下是详细操作指引。\n\n### 何时用\n\n- **JS 渲染页面**：SPA、动态加载内容（微博 feed、知乎回答、小红书瀑布流）\n- **需要登录态**：登录后才可见的内容、管理后台\n- **页面交互**：点击按钮、填写表单、翻页、滚动加载更多\n- **截图需求**：需要页面视觉信息\n- **其他工具全部失败的兜底**\n\n### 操作流程\n\n**信息获取（只读）：**\n1. 导航到目标 URL\n2. 等待关键元素出现（不要用固定时间等待）\n3. 提取所需内容（文本、链接、图片等）\n4. 返回结果给用户\n\n**登录操作：**\n1. 查找登录页 URL → `read {baseDir}/references/well-known-sites.json`\n2. **告知用户即将执行登录操作，获取确认**\n3. 导航到登录页\n4. 填写凭证（用户提供）或提示用户扫码\n5. 等待登录成功，确认后继续后续操作\n\n**页面交互：**\n1. 导航到目标页面\n2. 使用 CSS 选择器定位元素（辅以文本内容匹配）\n3. 执行交互：点击、输入、选择、滚动\n4. 等待响应/页面变化\n5. 提取结果或截图\n\n### 关键注意事项\n\n- **登录操作必须获得用户授权** — 任何涉及账号登录的操作前，先告知用户并等待确认\n- **敏感操作必须二次确认** — 发帖、删除、支付等不可逆操作\n- **优先 CSS 选择器** — 比 XPath 更稳定，辅以文本匹配\n- **智能等待** — 等待目标元素出现，而非 `sleep(3)` 式固定等待\n- **CAPTCHA/验证码** — 无法自动处理时告知用户需手动介入\n- **页面加载超时** — 设置合理超时，失败时告知用户并建议重试\n- **多步操作保持状态** — 登录后的后续操作复用同一浏览器上下文，不要重新打开\n\n---\n\n## web_search 失败处理\n\n**当 `web_search` 返回错误时，不要静默降级，必须引导配置：**\n\n1. **`read {baseDir}/references/web-search-config.md`**\n2. 按文件中 Step 1 **原样输出**配置引导给用户（不要改写表格或省略内容）\n3. 等待用户回复：\n   - 用户提供 API Key → 再次 `read {baseDir}/references/web-search-config.md`，按 Step 2-5 执行\n   - 用户说\"暂不配置\" → 进入降级方案\n   - 其他回复 → 正常响应\n4. **降级方案**（仅在用户明确拒绝配置后）：\n   - `read {baseDir}/references/well-known-sites.json` 获取常用网站 URL\n   - 用 `web_fetch` 直接获取目标网站内容\n   - 仍不行 → 升级到 `browser`\n\n---\n\n## 常用网站\n\n需要常用网站 URL 时（登录页、搜索引擎、热搜榜等）：\n\n```\nread {baseDir}/references/well-known-sites.json\n```\n\n通过 key 查找（如 `social.weibo.login`、`search.baidu`）。带 `{query}` 的 URL 替换为实际搜索词。\n","tags":{"ai":"1.0.0","latest":"1.0.0","lobster-army":"1.0.0"},"stats":{"comments":0,"downloads":297,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778256189525,"updatedAt":1778492880688},"latestVersion":{"version":"1.0.0","createdAt":1778256189525,"changelog":"🦞 龙虾兵团自研融合技能 v1首发","license":"MIT-0"},"metadata":null,"owner":{"handle":"freeman88-tch","userId":"s175vqzthvtcgmgawcp7vz2q3d85s636","displayName":"Freeman88-tch","image":"https://avatars.githubusercontent.com/u/212022282?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090762719}}