web-tools-guide

核心机制

本技能定义了四类Web工具的分支决策架构（非层级），遵循ReAct范式：

• web_search：无URL时的关键词搜索入口
• web_fetch：已知URL的静态内容直取
• opencli：70+主流网站的CLI结构化访问，作为优先fallback
• browser：JS渲染/登录态/交互场景的最后兜底

显著优点

1. 渐进式降级：明确失败信号（空白/403/CAPTCHA→opencli→browser），避免静默跳过
2. 效率优先：opencli秒级返回结构化数据，比browser轻量
3. 规范化流程：登录操作强制用户授权、敏感操作二次确认、CSS选择器优先、智能等待替代固定sleep
4. 故障自愈：web_search失败时引导API配置（含Step-by-step表格），非直接降级

潜在局限

• opencli需预装脚本（含Browser Bridge插件编译），首次使用有准备成本
• browser作为兜底工具，仍依赖CAPTCHA人工介入提示
• 未内置请求频率限制与反爬策略，高频场景需用户自行控制

适合人群

AI Agent开发者、自动化工作流搭建者、需平衡成功率与执行成本的爬虫替代方案用户

常规风险

• 配置泄露风险：web_search API Key需用户手动配置，存在误粘贴至对话的泄露可能
• 账号安全风险：登录态操作需明确授权，但用户可能误判场景必要性
• 服务依赖风险：70+站点CLI适配随目标网站改版可能失效

核心用法

web-tools-guide 是一个纯文档型 Skill，提供 Web 工具选择的决策框架而非直接执行能力。核心在于 ReAct 分支决策逻辑：

| 场景 | 首选工具 | 回退链 |

|------|---------|--------|

| 无URL，需搜索 | `web_search` | 失败→配置引导→降级 `opencli` → `browser` |

| 有URL，静态内容 | `web_fetch` | 403/CAPTCHA→`opencli`→`browser` |

| JS渲染/登录/交互 | `opencli`（70+站点结构化访问） | 失败→`browser`（兜底） |

关键执行原则：

• opencli 优先于 browser：覆盖 70+ 主流站点，秒级结构化返回
• 失败必须告知用户：禁止静默降级，每次切换工具需说明原因
• web_search 失败强制配置引导：读取 web-search-config.md 按 Step 1 原样输出，等待用户确认

显著优点

1. 清晰的决策树：用流程图明确四工具关系，解决"该用哪个工具"的混乱
2. 防御性设计：web_search API 失败不直接降级，而是引导用户配置，避免无限循环
3. 渐进式工具暴露：opencli --help 层层递进，降低记忆负担
4. 明确的权限边界：登录操作必须用户确认，敏感操作二次确认
5. 完整的降级链路：从轻量级搜索→直取→CLI→浏览器，覆盖全场景

潜在局限

• 依赖外部 CLI 安装：opencli 需首次运行 setup-opencli.sh，网络/GitHub 访问失败时失效
• T3 来源风险：个人开发者维护（fmls），虽平台审核但长期维护能力存疑
• 无内置执行能力：纯指导文档，实际调用仍依赖用户环境的工具可用性
• Browser 兜底重量大：最终 fallback 为完整浏览器自动化，资源消耗高

适合人群

• AI Agent 开发者：需要标准化 Web 工具调用决策逻辑
• 复杂网页自动化用户：频繁处理 SPA、登录态、动态加载场景
• 多工具协同场景：需要明确 web_search / web_fetch / opencli / browser 分工的团队

常规风险

| 风险点 | 缓解措施 |

|-------|---------|

| setup 脚本执行风险 | 建议审查后再执行，从 GitHub Releases 下载（可信源） |

| API Key 配置流程 | 5步确认设计，不静默存储，符合 GDPR 最小化原则 |

| Browser Bridge 权限 | 建议使用专用浏览器配置文件运行 |

| PATH 修改（低危） | 仅函数内生效，用户目录下的 pnpm 路径，常规做法 |

安全认证评分 CLS A 级（85分），无危险函数，风险已充分披露。