人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载导读web_scrape是 Hive 多 Agent 生产框架hive_toolsMCP 工具集中负责网页内容抓取与提取的核心工具它通过 Playwright 驱动无头 Chromium 渲染 JavaScript 页面、借助 playwright-stealth 规避机器人检测再用 BeautifulSoup 剥离噪声元素、提取正文并将提取结果落盘供 Agent 按需读取。本文以 web_scrape_tool/README.md 为主体骨架结合 web_scrape_tool.py 源码与 test_web_scrape_tool.py 测试用例从参数语义、安装配置、工作流程、错误处理到 SSRF 防护原理逐一展开帮助你完整掌握该工具的能力边界与正确用法。一、工具定位Agent 的网页阅读器web_scrape的定位非常明确——当 Agent 需要读取某个具体 URL 的内容、从网站提取数据、或阅读文章与文档时使用它源码 docstring 中的描述见 web_scrape_tool.py。它与同目录下的web_search形成互补web_search负责找到相关页面web_scrape负责把找到的页面读进上下文。在 tools/README.md 的 Web Search 工具清单中web_scrape与web_search、search_wikipedia、exa_*等并列共同构成 Agent 的联网信息获取能力。该工具支持三类典型场景读取指定 URL 的正文内容如阅读一篇技术文章、一份产品文档从网站提取结构化数据如抓取列表页的条目、标题、链接阅读 JavaScript 渲染的动态页面SPA、带懒加载的内容普通 HTTP 请求拿不到必须由无头浏览器渲染。工具不要求任何环境变量README 明确说明但会依赖HIVE_STORAGE_PATH/HIVE_HOME来决定提取文本的落盘目录详见下文落盘机制。二、参数详解五个入参与返回结构2.1 参数表工具共接受 5 个参数均通过 FastMCPmcp.tool()装饰器暴露见 web_scrape_tool.py参数类型必填默认值说明urlstr是无待抓取的网页 URLselectorstr否NoneCSS 选择器用于只提取指定区域如article、.main-contentinclude_linksbool否False是否在响应中附带提取到的链接列表max_lengthint否50000提取文本的最大长度取值范围 1000-500000respect_robots_txtbool否TrueREADME 声明值是否遵守目标站点的 robots.txt 规则版本差异说明README 表格中respect_robots_txt默认值为True而当前源码签名中默认值为Falseweb_scrape_tool.pydocstring 也注明默认 False——操作者已获授权进行这些一次性的低量抓取如需为单次调用重新启用检查可传 Trueweb_scrape_tool.py。这说明实现上默认放行、按调用显式开启合规检查。同样README 中的max_length参数在当前源码中并未实现——实际实现是将全文不截断写入磁盘见下文落盘机制与测试 test_web_scrape_tool.py。引用该工具时请以实际源码签名为准。2.2 返回值结构成功时返回一个元数据字典web_scrape_tool.pyurl请求的原始 URLfinal_url重定向后的最终 URL链接解析以此为基准title页面title文本descriptionmeta description缺失时回退到 Open Graphog:descriptionpage_typearticle|listing|page见下文页面类型启发式total_length落盘文本的总字符数saved_to正文文件的绝对路径headingsH1-H6 标题大纲最多 100 条每条含level与textstructured_data可选json_ld数组与open_graph字典links可选仅include_linksTrue最多 50 条{text, href}链接。注意正文文本本身不会出现在 JSON 响应中而是写入磁盘文件响应只携带saved_to路径与total_length元数据。三、安装与注册Chromium 与可选依赖3.1 依赖安装README 给出了两条命令READMEuv pip install playwright playwright-stealth uv run playwright install chromiumplaywright-stealth用于规避机器人检测Chromium 是实际渲染引擎。从 tools/src/aden_tools/tools/init.py 的导入逻辑可以看到playwright是可选依赖未安装时register_web_scrape被置为None该工具会从 MCP 工具集中优雅降级移除不影响其他工具注册。因此在实际部署中若 Agent 不需要网页抓取能力可以跳过上述安装。3.2 MCP 注册方式工具通过register_tools(mcp: FastMCP)函数注册web_scrape_tool.py在tools/src/aden_tools/tools/__init__.py中被统一汇总后注册进hive_toolsMCP server。该 server 在 tools/mcp_servers.json 中声明为 stdio 传输、由uv run python mcp_server.py --stdio启动描述为提供 web_search、web_scrape、send_email 与数据工具。上层 Agent 框架通过 core/framework/loader/mcp_client.py 等 MCP 客户端机制加载此 server 即可获得web_scrape调用能力。四、核心工作流从 URL 校验到文本落盘从源码web_scrape_tool.py可以还原完整的执行管线4.1 第一步URL 规范化与 SSRF 检查无协议 URL 自动补全https://前缀web_scrape_tool.py对应测试 test_web_scrape_tool.py。随后在发起任何网络请求之前包括 robots.txt 请求执行 SSRF 防护检查_check_url_targetweb_scrape_tool.py解析主机名缺失则报错IP 字面量走快速路径命中内网段直接拦截域名走 DNS 解析5 秒超时上限任一解析结果命中内网地址即拦截判断逻辑_is_internal_addressweb_scrape_tool.py非全局单播地址含环回、私有网段、链路本地、多播一律判为内部地址解析失败则fail closed。测试 test_web_scrape_tool.py 的参数化用例覆盖了127.0.0.1、10.0.0.1、192.168.1.1、169.254.169.254AWS 元数据地址等敏感目标端到端测试也验证了对这些地址返回blocked_by_ssrf_protection: Truetest_web_scrape_tool.py。4.2 第二步robots.txt 检查仅当respect_robots_txtTrue时执行用 httpx5 秒超时、跟随重定向拉取目标站点/robots.txt经urllib.robotparser.RobotFileParser解析后用浏览器 UA 判断是否允许抓取web_scrape_tool.py。被禁止时返回Blocked by robots.txt错误并附skipped: True与提示测试见 test_web_scrape_tool.py。robots.txt 获取失败HTTP 错误、超时等则放行继续。4.3 第三步无头浏览器渲染启动 Chromium 无头浏览器携带四个启动参数--no-sandbox、--disable-setuid-sandbox、--disable-dev-shm-usage、--disable-blink-featuresAutomationControlled以 1920x1080 视口、浏览器 UAChrome/131与en-USlocale 创建上下文并应用Stealth().apply_stealth_async(page)web_scrape_tool.py。渲染阶段有两个关键机制导航级 SSRF 拦截注册page.route(**/*, ...)处理器只检查document级导航请求跳过 CSS/JS/图片等子资源避免误伤与多余 DNS 查询命中内网地址即route.abort(blockedbyclient)并记录错误web_scrape_tool.py——这防止了通过重定向绕过 SSRF 检查超时分层page.goto用domcontentloaded等待策略、30 秒内部超时随后wait_for_load_state(networkidle)只等 3 秒超时则拿已加载的内容继续。注释明确解释goto 的内部超时控制在 Agent 循环 60 秒预算内先触发避免外层超时泄漏浏览器子进程[web_scrape_tool.py](https://link.gitcode.com/i/5696f479f5571eb30eb40b14e0c20da5#L242-L249, L280-L284)。4.4 第四步响应校验goto返回None→Navigation failed: no response received状态码非 200 →HTTP status: Failed to fetch URL并对 401/403/429 附带站点可能需要认证、封禁机器人或限流的提示web_scrape_tool.pyContent-Type非 HTML → 直接跳过web_scrape_tool.py对应测试 test_web_scrape_tool.py。这些错误都在等待networkidle之前返回测试专门验证了wait_for_load_state不会被调用test_web_scrape_tool.py。4.5 第五步结构化数据与正文提取拿到渲染后的 HTML 后交给 BeautifulSoup 处理web_scrape_tool.py先提取结构化数据再清理JSON-LD 藏在script typeapplication/ldjson中这些 script 随后会被清除Open Graph 从og:*的 meta 标签收集清除噪声元素script、style、nav、footer、header、aside、noscript、iframe全部decompose()提取标题与描述title文本、meta description缺失时回退 OG 描述标题大纲收集 H1-H6 文本上限 100 条页面类型启发式article数量 ≥ 3 →listing恰 1 个或存在main→article否则pageweb_scrape_tool.py定位目标子树指定selector时用soup.select_one(selector)未匹配返回No elements found matching selector并提示改用更宽泛选择器或走自动检测未指定时按main→rolemain→article→ 常见内容类名content/post/entry/article-body→body的顺序自动回退web_scrape_tool.py结构保真清洗块级元素p、h1-h6、li、tr、div、section、article、blockquote前后插入换行br转为换行然后get_text(separator )提取最后压缩行内空白、折叠连续空行web_scrape_tool.py。测试验证段落/标题/列表的换行结构得以保留test_web_scrape_tool.py链接处理include_linksTrue时正文中的a先被替换为text形式的 Markdown 内联链接这样 Agent 读正文就能直接拿到目标地址并单独收集最多 50 条links列表。相对链接一律基于final_url重定向后地址用urljoin转成绝对链接web_scrape_tool.py测试覆盖了相对路径、根相对路径、绝对链接、重定向后基准、锚点与查询参数保持等六类场景test_web_scrape_tool.py。4.6 第六步正文落盘而非内联返回这是该工具最具 Agent 友好性的设计决策。源码注释明确指出把多 KB 页面文本 JSON 包裹进响应会对每个换行和引号做转义污染 Agent 上下文web_scrape_tool.py。因此正文被完整写入磁盘不截断、不分页文件名格式为web_scrape_unix毫秒_sanitized-host.txtUTF-8 纯文本无 JSON 包装落盘目录解析逻辑见_resolve_scrape_artifact_dir设置了HIVE_STORAGE_PATH→ 写入HIVE_STORAGE_PATH/data与 Agent 溢出文件同目录由框架 tool_registry 注入 MCP 子进程环境否则写入HIVE_HOME/tool-artifacts浏览器检查工具共用目录HIVE_HOME缺省为~/.hiveweb_scrape_tool.py。docstring 建议 Agent 通过terminal_exec(cat saved_to)大输出用terminal_output_get或terminal_rg按需读取正文web_scrape_tool.py。测试断言响应中不包含content/length/truncated等内联字段且total_length与磁盘文件长度一致test_web_scrape_tool.py。五、错误处理速查表README 列出的错误字典与源码一一对应错误消息触发条件源码位置HTTP status: Failed to fetch URL服务器返回非 200 状态码web_scrape_tool.pyNavigation failed: no response received浏览器无法导航到 URLgoto 返回 Noneweb_scrape_tool.pyNo elements found matching selector: selectorCSS 选择器未匹配任何元素web_scrape_tool.pyRequest timed out页面加载超过 60 秒PlaywrightTimeoutweb_scrape_tool.pyBlocked by robots.txt: url目标 URL 被站点 robots.txt 禁止web_scrape_tool.pyBrowser error: errorPlaywright/Chromium 底层异常web_scrape_tool.pyScraping failed: errorHTML 解析或其他异常web_scrape_tool.pyBlocked: ... internal address/DNS resolution failedSSRF 防护拦截或 DNS 解析失败5 秒超时web_scrape_tool.pySkipping non-HTML content (Content-Type: ...)目标返回非 HTML 内容类型web_scrape_tool.py多处错误附带hint字段如 401/403/429 提示站点可能需要认证、封禁机器人或限流404 提示资源可能不存在或服务器宕机robots.txt 拦截提示如你获授权可传respect_robots_txtFalseAgent 可直接据此调整策略。六、使用建议与注意事项综合 README 的 Notes 与源码实现整理出以下实战要点JS 渲染能力工具会等networkidle最多 3 秒再提取SPA 与动态加载页面可正常提取若页面持续有网络活动也会用已加载内容继续不会无限等待URL 补全不带协议的 URL 自动加https://但建议显式写全协议正文读取方式响应中只有元数据正文在saved_to指向的文件里请用终端工具cat/rg读取勿期望响应内联正文链接绝对化include_linksTrue时正文内链接会变成textMarkdown 格式且基于重定向后的最终 URL 解析无需担心相对路径失效合规与安全SSRF 防护默认开启且无法关闭内网/环回/元数据地址一律拦截robots.txt 检查按 README 声明默认开启但当前源码默认False如需合规抓取请在调用时显式传respect_robots_txtTrue可选依赖未安装 playwright 时工具自动从工具集移除不会破坏 MCP server 启动测试参考完整的 Mock 测试套件位于 test_web_scrape_tool.py覆盖参数行为、链接转换、结构化数据、错误处理、robots.txt 与 SSRF 防护可作为理解工具行为边界的权威参考。七、源码速览文件作用web_scrape_tool/README.md工具官方文档本文主体web_scrape_tool/web_scrape_tool.py工具完整实现含 SSRF、robots、提取、落盘web_scrape_tool/init.pyregister_tools导出tools/init.py工具批量注册与 playwright 可选依赖降级test_web_scrape_tool.py行为测试套件mcp_servers.jsonhive_toolsMCP server 声明tools/README.md工具总览Web Search 分类赞分享人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载相关推荐探秘Playwright Stealth无痕浏览的Python神器探秘Playwright Stealth无痕浏览的Python神器 在数字世界的隐蔽战线每一个请求都可能暴露你的踪迹。但今天我们有了一个新的秘密武器——网页爬虫Lightdash UnfurlService 深度解析基于 Playwright 的无头浏览器截图与截图就绪指示器架构Lightdash UnfurlService 深度解析基于 Playwright 的无头浏览器截图与截图就绪指示器架构 导读 本文聚焦 Lightdash后端前端数据分析数据可视化人工智能AI Agent无头浏览器服务如何防SSRF攻击Browserless私有网络拦截机制深度剖析无头浏览器服务如何防SSRF攻击Browserless私有网络拦截机制深度剖析 Browserless 是一个可在 Docker 中部署的无头浏览器自动化服务后端API网关上一篇突破llama.cpp启动瓶颈从原理到实践的全链路优化指南下一篇如何高效定制iTerm2终端会话从标题管理到工作流优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
