Unbrowse：将网站逆向为API，实现智能体高效Web交互

1. 项目概述将网站转化为智能体可用的API接口如果你正在开发一个需要与网站交互的智能体Agent比如让它帮你抓取新闻、查询天气、或者自动填写表单你大概率会遇到一个头疼的问题如何让智能体稳定、高效地“理解”并操作一个为人类设计的网页传统的做法是让智能体模拟浏览器操作点击、滚动、等待页面加载这个过程不仅慢动辄几十秒而且脆弱页面结构一变就失效成本还高消耗大量计算资源。今天要聊的unbrowse就是为了彻底解决这个问题而生的。简单来说unbrowse是一个能将任何网站“反向工程”成一套标准化、可复用 API 接口的工具。它不再让智能体去笨拙地操作浏览器界面而是直接捕获和分析网站背后的真实网络请求API 调用将这些请求逻辑封装成一个个可执行的“技能”Skill。更妙的是这些技能会被发布到一个共享的“市场”Marketplace中。这意味着只要有一个智能体成功“学会”了如何与某个网站交互后续所有的智能体都可以直接复用这个成果实现“一次学习处处使用”。想象一下这就像是为整个互联网的交互逻辑建立了一个“Waze”导航地图。第一个探索某条路线的用户贡献了数据后来的所有用户都能享受到最优、最快的路径。unbrowse做的正是这件事只不过它导航的对象是网站背后的 API 接口。对于开发者而言这意味着你的智能体项目在接入新网站时开发成本、运行时间和费用都可能呈数量级下降——官方数据是相比传统的浏览器模拟方案速度提升约30倍成本降低约90%。2. 核心设计思路与工作原理拆解2.1 从“模拟点击”到“调用API”的范式转变要理解unbrowse的价值首先要明白传统智能体与网站交互的痛点。主流方案例如agent-browser或OpenClaw本质上是让智能体控制一个无头浏览器如 Puppeteer、Playwright通过执行一系列模拟人类操作的指令如“点击这个按钮”、“在那个输入框输入文字”来完成任务。这个过程存在几个根本性问题性能瓶颈每个操作都需要等待页面渲染、JavaScript 执行、网络请求完成耗时极长。稳定性差前端 UI 的任何微小改动一个 CSS 类名变化、一个按钮位置调整都可能导致脚本失效。资源消耗大运行一个完整的浏览器实例需要可观的内存和 CPU 资源。逻辑复杂需要编写大量针对特定页面结构的定位和操作逻辑代码冗长且难以维护。unbrowse采用了截然不同的思路绕过 UI 层直击数据源。它认为绝大多数现代网站尤其是 Web 2.0 以来的动态网站的数据交互都是通过后台的 API 接口完成的。前端页面只是一个用于展示和触发这些 API 调用的“壳”。因此unbrowse的核心工作流是启动一个浏览器去访问目标网站但目的不是操作它而是监听并记录下浏览器与服务器之间所有的网络通信即 HTTP 请求和响应。然后它分析这些通信记录HAR 文件从中逆向推导出网站的核心 API 端点Endpoint、请求参数、认证方式以及数据结构。2.2 技能Skill的生成与生命周期管理unbrowse将逆向工程得到的 API 调用逻辑封装成一个结构化的“技能”。一个技能通常包含以下信息意图Intent用自然语言描述这个技能能做什么例如“获取今日头条热榜”、“在 GitHub 上搜索仓库”。目标域名Domain技能所针对的网站。API 端点具体的请求 URL、方法GET/POST、必需的头部信息Headers、查询参数Query Parameters或请求体Body。参数映射如何将用户的自然语言指令转化为具体的 API 调用参数。响应解析如何从 API 的返回结果中提取出用户关心的结构化数据。当一个智能体通过unbrowse请求执行某个任务如“帮我看看 Reddit 上 r/programming 的热门帖子”时unbrowse会启动一个智能的解析管道缓存查询首先检查本地是否有最近5分钟内解析过相同意图的结果有则立即返回实现瞬时响应。市场搜索如果缓存未命中则向共享市场发起语义搜索。搜索算法综合考虑了技能描述的语义相似度40%、历史执行的可靠性评分30%、技能的新鲜度15%和验证状态15%返回最匹配的现有技能。实时捕获如果市场上没有找到足够可信的现有技能unbrowse就会启动“学习模式”。它打开一个无头浏览器访问目标网站引导智能体或根据指令模拟执行相关操作全程录制网络流量随后逆向工程并生成一个新的技能。DOM 回退对于极少数纯静态或服务端渲染SSR的网站可能没有清晰的 API 接口。此时unbrowse会从渲染后的 HTML DOM 中提取结构化数据作为备选方案。新生成的技能会被自动发布到共享市场供全球所有unbrowse用户使用。这就形成了一个强大的网络效应飞轮用户越多贡献的技能越多覆盖的网站越广整个平台对每个用户的价值就越大。为了确保市场技能的质量unbrowse设计了一套技能生命周期管理机制活跃Active技能可被查询和执行。弃用Deprecated当技能在后台自动验证中连续多次执行失败例如因为网站 API 变更其可靠性评分会下降最终被自动标记为弃用在搜索结果中排名靠后或隐藏。禁用Disabled当技能对应的端点完全无法访问时会被禁用。一个后台验证服务每6小时会运行一次对技能中的安全端点主要是 GET 请求进行健康检查及时发现失效或发生模式漂移Schema Drift的技能。2.3 本地优先与安全架构尽管技能市场是共享的但unbrowse坚持“本地优先”原则最大程度保障用户安全和隐私本地服务器核心的unbrowse服务运行在你的本地机器上默认localhost:6969所有的网络流量捕获、反向工程、技能执行都发生在本地。凭证本地加密存储从网站捕获的认证信息如 Cookies、API Keys、Authorization Headers会被加密后存储在本地 vault 目录~/.unbrowse/vault/中。执行技能时直接从本地 vault 读取并注入请求你的登录凭证永远不会离开你的机器。选择性发布只有技能的“元数据”如端点 URL 模式、参数结构会被发布到共享市场。你的个人数据和认证信息绝对私密。3. 实战部署与核心配置详解3.1 环境准备与安装unbrowse提供了几种安装方式适用于不同的使用场景。我个人推荐从仓库克隆的方式开始因为它能确保环境的一致性。方案一从仓库克隆安装推荐这是最直接、可控性最高的方式特别适合开发者或希望紧跟最新版本的用户。# 克隆仓库使用 --depth 1 只克隆最新提交节省时间 git clone --single-branch --depth 1 https://github.com/unbrowse-ai/unbrowse.git ~/unbrowse # 进入目录并运行安装脚本--host off 表示不自动配置特定宿主环境 cd ~/unbrowse ./setup --host off这个./setup脚本做了很多事情可以把它理解为一个“一体化部署工具”安装依赖检查并安装项目运行所需的 Node.js 包和其他系统依赖。构建 CLI预构建打包好的命令行工具运行时环境。安装稳定版 CLI 封装在你的系统路径中安装一个名为unbrowse的稳定命令行工具方便后续调用。首次启动引导这是最关键的一步。脚本会启动本地服务器并引导你完成服务条款ToS接受首次使用需要同意条款。智能体注册为你的本地实例在unbrowse市场注册一个唯一的智能体身份并生成 API Key。这个身份用于标记技能是由谁贡献的。钱包检测与配置如果你配置了加密货币钱包如 Crossmint 的lobster.cash该地址会被同步到你的智能体档案。它有两个用途一是作为你贡献技能后获得收益的收款地址二是作为你购买市场付费技能的支付钱包。安装脚本现在会鼓励新用户设置 Crossmint如果检测到相关工具甚至会尝试自动运行npx crossmint/lobster-cli setup。实操心得首次运行./setup时建议在图形化终端环境下进行因为它可能会有交互式提示如输入一个邮箱格式的智能体名称。对于无头Headless环境或自动化脚本你可以通过设置环境变量UNBROWSE_AGENT_EMAIL和UNBROWSE_TOS_ACCEPTEDtrue来非交互式地完成初始化。方案二通过 npm 全局安装如果你之前已经成功发布过包或者想使用更标准的包管理方式可以使用 npm。npm install -g unbrowse unbrowse setup方案三为通用 MCP 宿主安装MCPModel Context Protocol是一种让 AI 模型使用工具的标准协议。如果你的 AI 开发环境支持 MCP如某些 Claude 开发工具你可以这样安装git clone --single-branch --depth 1 https://github.com/unbrowse-ai/unbrowse.git ~/unbrowse cd ~/unbrowse ./setup --host mcp这个命令会在~/.config/unbrowse/mcp/目录下生成一个名为unbrowse.json的配置文件你的 MCP 宿主可以直接导入这个配置来集成unbrowse的功能。方案四通过 Skills 系统安装如果你的 AI 宿主环境使用独立的 “Skills” 管理系统例如某些特定的 AI 代码助手框架可以直接添加npx skills add unbrowse-ai/unbrowse3.2 关键目录结构与配置文件解析安装完成后unbrowse会在你的用户主目录下创建.unbrowse文件夹其结构如下。理解这些目录和文件的作用对于故障排查和高级配置至关重要。~/.unbrowse/ ├── config.json # 核心配置文件存储 API Key、智能体 ID、注册信息等。 ├── vault/ │ ├── credentials.enc # 加密的凭证存储文件Cookies, API Keys 等。 │ └── .key # 用于加密 vault 的密钥文件权限为 600仅所有者可读。 ├── skill-cache/ # 本地技能清单缓存加速重复查询。 ├── profiles/ # 按域名隔离的 Chrome 浏览器配置文件目录用于捕获时保持会话隔离。 │ └── domain/ └── logs/ └── unbrowse-YYYY-MM-DD.log # 按日期滚动的日志文件调试时第一手资料。config.json这是最重要的文件。通常你不需要手动编辑它。它由unbrowse setup自动生成包含了连接到共享市场所需的身份凭证。如果这个文件损坏或丢失可以删除它并重新运行unbrowse setup来重建。vault/目录安全重地。所有从你浏览器中“窃取”或在登录流程中捕获的认证信息都经过 AES-256-CBC 加密后存储在这里。unbrowse服务器进程在需要时会用.key文件解密这些信息。务必确保~/.unbrowse/目录的权限安全不要泄露.key文件。profiles/目录unbrowse为每个它需要“学习”的网站创建一个独立的 Chrome 用户配置文件。这保证了不同网站的登录会话、Cookies、缓存完全隔离避免串扰。例如学习github.com和google.com会使用两个不同的 profile。3.3 环境变量与常用命令你可以通过环境变量来定制unbrowse的行为变量名默认值作用描述PORT6969本地服务器监听的端口号。HOST127.0.0.1本地服务器绑定的 IP 地址。UNBROWSE_URLhttp://localhost:6969客户端如 CLI连接服务器时使用的基础 URL。UNBROWSE_API_KEY自动生成覆盖自动生成的 API Key通常不需要。UNBROWSE_AGENT_EMAIL—为无头安装设置一个邮箱格式的智能体名称。UNBROWSE_TOS_ACCEPTED—设置为true以非交互方式接受服务条款。UNBROWSE_NON_INTERACTIVE—设置为true跳过所有命令行交互提示。LOBSTER_WALLET_ADDRESS—如果你使用 Crossmintlobster.cash钱包在此设置地址。AGENT_WALLET_ADDRESS—其他钱包提供商的地址。AGENT_WALLET_PROVIDER—其他钱包提供商的名称。安装完成后你可以通过unbrowseCLI 工具来操作。以下是一些最常用的命令# 检查本地服务健康状态 unbrowse health # 显示 MCP 服务器配置如果以 MCP 模式安装 unbrowse mcp # 核心功能解析一个意图。例如让 unbrowse 去理解如何在谷歌上执行“获取热门搜索” unbrowse resolve --intent get trending searches --url https://google.com --pretty # 对需要登录的网站进行认证捕获。这会打开浏览器引导你登录。 unbrowse login --url https://calendar.google.com # 列出当前可用的所有技能包括本地和市场的 unbrowse skills # 在技能市场中搜索相关技能 unbrowse search --intent get stock prices4. 认证机制与安全实践深度解析让智能体操作需要登录的网站是自动化任务中最复杂的一环。unbrowse提供了几种灵活的认证策略核心思想是“复用你已经存在的登录状态”。4.1 自动 Cookie 解析默认且最推荐这是unbrowse的“魔法”所在。大多数情况下你不需要做任何额外操作。当unbrowse需要为一个网站例如https://github.com执行技能时它会去检查你电脑上正在运行的Chrome 或 Firefox浏览器。直接读取浏览器存储 Cookies 的 SQLite 数据库文件对于 Chrome通常是~/Library/Application Support/Google/Chrome/Default/Cookies或 Windows 下的对应路径。从中提取出目标网站的登录 Cookie。将这些 Cookie 加密存储到本地 vault 中。后续执行该网站的 API 调用时直接从 vault 中读取 Cookie 并注入到 HTTP 请求头中。这意味着只要你已经用浏览器手动登录了某个网站unbrowse就能直接“借用”你的会话无需二次登录。而且Cookie 是每次调用前动态解析的所以只要你的浏览器会话保持登录unbrowse就能一直使用最新的会话。注意事项这种机制依赖于浏览器 Cookie 数据库的本地访问。确保unbrowse进程有权限读取这些文件。在某些严格的沙盒环境或服务器上可能需要调整权限。4.2 Yolo 模式与交互式登录对于某些采用复杂认证流程的网站如带有 OAuth 弹窗、双因素认证 2FA自动读取 Cookie 可能失败。unbrowse提供了备选方案Yolo 模式通过unbrowse login --url website --yolo命令启动。它会直接打开一个带有你真实用户配置文件的 Chrome 浏览器窗口。你可以在里面手动完成任何复杂的登录流程包括扫码、2FA。unbrowse会录制这个过程中的网络流量和最终的 Cookie。完成后关闭浏览器即可。这种方式捕获的认证信息最完整。交互式登录这是 Yolo 模式的简化版也是unbrowse login的默认行为。它会打开一个干净的、无痕的浏览器窗口导航到目标网站让你手动登录。适用于你不想用现有浏览器 profile或者当前浏览器未登录的情况。4.3 认证信息的存储与使用捕获到的认证信息Cookies、Authorization Headers 等被统称为“凭证”它们被存储在本地加密 vault 中。unbrowse的智能之处在于跨域处理现代网站常使用多个子域名。例如luma的登录可能在lu.ma而 API 在api2.luma.com。unbrowse能透明地处理这种跨域 Cookie 的传递。凭证保鲜与淘汰当执行一个技能其 API 调用返回401未授权或403禁止访问状态码时unbrowse会自动将该次调用使用的凭证标记为“过期”并从 vault 中删除。这保证了失效的登录信息不会一直阻塞流程。安全执行技能执行时unbrowse服务器直接使用 vault 中的凭证发起 HTTP 请求无需再次启动浏览器。这既安全凭证不离开本地又高效无浏览器开销。4.4 变更操作Mutation的安全边界这是unbrowse设计中一个非常重要的安全特性。对于非只读操作即 POST, PUT, DELETE 等会改变服务器状态的请求unbrowse默认是禁止自动执行的。预览模式Dry Run你可以在请求中设置dry_run: true参数。unbrowse会解析出完整的请求包括 URL、Headers、Body但不会真正发送出去而是返回一个预览让你确认将要执行的操作。显式确认Confirm Unsafe只有当你明确在请求中设置confirm_unsafe: true时unbrowse才会实际执行这个变更操作。而对于 GET 请求通常是安全的读取操作unbrowse会默认自动执行。这个设计有效地防止了智能体意外地删除数据、提交表单或进行其他危险操作。5. 开发集成与高级应用场景5.1 与各类 AI 开发环境集成unbrowse的核心是一个运行在localhost:6969的 HTTP 服务器并提供了 CLI 和 MCP 接口。这使得它能轻松集成到几乎任何 AI 开发工作流中。Claude Code / Cursor / Windsurf 等 AI 编码助手这些工具通常可以直接调用本地 CLI 命令。你可以在 AI 的聊天窗口中直接输入unbrowse resolve --intent ... --url ...AI 助手会执行该命令并返回结果。更高级的集成可以通过配置让 AI 助手将unbrowse视为一个可用的工具来调用。支持 MCP 的宿主MCP 正在成为 AI 工具集成的标准协议。通过./setup --host mcp安装后生成的unbrowse.json配置文件可以直接被任何 MCP 客户端导入从而将unbrowse的技能解析和执行能力作为“工具”暴露给 AI 模型。自定义脚本和程序你可以直接向http://localhost:6969/v1/intent/resolve发送 HTTP POST 请求来使用unbrowse。请求体是一个 JSON包含intent和url字段。这使得你可以用 Python、Node.js、Go 等任何语言编写程序来驱动unbrowse。5.2 性能优化与成本考量官方宣称相比传统浏览器流有30倍速度提升和90%成本下降这主要源于架构差异速度浏览器流需要渲染、布局、执行 JS一个任务可能需要数十秒。而unbrowse执行一个已学习的技能是直接发起几个毫秒级的 HTTP API 调用。成本浏览器流需要持续运行一个内存占用巨大的浏览器进程。unbrowse的本地服务器和 API 调用消耗的资源微不足道。在云服务场景下这意味着更小的虚拟机规格和更低的计费。然而第一次“学习”一个网站即实时捕获阶段仍然较慢可能需要20到80秒。这是为后续无数次快速执行所做的必要投资。因此一个最佳实践是在开发或测试阶段主动让unbrowse去学习你需要的网站生成技能。在生产环境中智能体就能永远走“快速路径”了。5.3 处理复杂与反爬严格的网站虽然unbrowse很强大但并非万能。项目文档中也提到像 Reddit 这样具有强力反机器人保护的网站仍然是“困难目标”。对于这类网站优先寻找官方 API很多网站提供公开的、文档化的 API如 Reddit 的/.json接口。在让unbrowse去捕获之前先检查是否有这样的“后门”。unbrowse同样可以学习和使用这些官方 API。利用 Yolo 模式对于反爬策略基于浏览器指纹和复杂 JS 挑战的网站使用--yolo模式用你真实的、已登录的浏览器 profile 去捕获流量成功率最高。贡献与反馈如果你发现某个网站无法被unbrowse有效处理可以去项目的 GitHub Discussions如文档中提到的 #53 号讨论反馈。开发团队会收集这些案例用于改进下一轮的反向工程算法。5.4 技能市场的生态参与作为用户你不仅是技能的消费者也可以是贡献者。每次unbrowse因为市场中没有匹配技能而启动实时捕获时新生成的技能都会在匿名化处理后发布到共享市场。如果你的贡献被其他用户频繁使用并且你配置了钱包地址未来可能会有收益分享机制。你可以通过unbrowse skills命令查看自己本地贡献过或已缓存的技能。通过unbrowse search探索市场已有技能。如果你发现某个技能失效了可以使用unbrowseAPI 提交反馈或报告问题帮助维护市场质量。6. 故障排查与常见问题实录在实际使用中你可能会遇到一些问题。以下是我在深度使用过程中总结的一些常见情况及解决方法。6.1 安装与启动问题问题运行./setup或unbrowse命令时出现权限错误。排查检查~/.unbrowse/目录及其下文件特别是vault/.key的所有权和权限。确保当前用户有读写权限。vault/.key的权限应为600仅所有者可读可写。解决可以尝试删除~/.unbrowse目录注意这会清除所有配置和本地凭证然后重新运行安装命令。问题本地服务器localhost:6969无法启动或访问。排查运行unbrowse health检查服务状态。检查端口6969是否被其他程序占用lsof -i :6969(Mac/Linux) 或netstat -ano | findstr :6969(Windows)。查看日志文件~/.unbrowse/logs/unbrowse-*.log获取错误详情。解决如果端口占用可以通过环境变量PORT指定另一个端口如PORT6970 unbrowse health。重启unbrowse服务。通常停止再运行unbrowse相关命令会自动重启服务。6.2 认证与登录问题问题unbrowse无法自动获取我已登录网站的 Cookie。排查确认你使用的浏览器Chrome/Firefox正在运行并且已登录目标网站。检查unbrowse的日志看是否有读取 Cookie 数据库的权限错误。某些基于 Electron 的桌面应用如 Discord、Slack或特殊浏览器其 Cookie 存储路径可能不同。解决对于标准浏览器尝试关闭浏览器再重新打开登录一次然后重试。使用unbrowse login --url 目标网站命令启动交互式登录流程。对于非标准应用可以尝试使用unbrowse的/v1/auth/stealAPI手动指定 Cookie 数据库路径或用户数据目录。问题执行技能时返回 401/403 错误。排查这通常意味着之前捕获的凭证Cookie已过期。解决unbrowse会自动清理过期的凭证。你需要重新登录。运行unbrowse login --url 目标网站来更新凭证。完成后再次执行技能即可。6.3 技能解析与执行问题问题unbrowse resolve一个意图时一直卡在“捕获”阶段或者最终失败。排查目标网站可能加载缓慢或需要特殊交互才能触发 API 调用。查看日志了解捕获进程卡在哪一步。网站可能有很强的反爬机制阻止了无头浏览器。网络问题导致无法访问目标网站。解决增加超时目前 CLI 可能没有直接暴露超时参数但可以检查服务器日志。使用 Yolo 模式对于反爬网站在登录时使用--yolo标志unbrowse login --url 网站 --yolo。用真实的浏览器环境完成操作。检查网络确保你的本地网络可以正常访问目标网站。简化意图尝试更简单、更明确的意图描述。问题技能执行成功但返回的数据不是我想要的。排查这可能是意图解析偏差或者技能捕获的 API 端点并非你期望的那个。解决优化意图描述使用更精确、更具体的自然语言描述你的需求。例如“获取 Hacker News 首页前10条帖子标题”比“看看 Hacker News 新闻”更好。检查技能详情通过市场搜索或unbrowse skills找到相关技能看看它具体调用的是哪个 API 端点返回的数据结构是什么。提供反馈如果技能确实有问题可以通过 API (/v1/feedback) 或社区提交反馈帮助改进该技能。6.4 升级与维护问题升级unbrowse后原有功能出现异常。解决unbrowse已不再运行时自动更新。升级后务必按照官方指南重新运行安装脚本如果从仓库克隆安装cd ~/unbrowse git pull --ff-only ./setup --host off如果为 MCP 安装cd ~/unbrowse git pull --ff-only ./setup --host mcp如果通过 skills 安装重新运行npx skills add unbrowse-ai/unbrowse有时升级后可能需要清除旧的技能缓存可以尝试重启unbrowse服务或删除~/.unbrowse/skill-cache/目录不影响凭证。我个人在实际使用中的体会是unbrowse代表了智能体与 Web 交互的一个正确进化方向——从脆弱的、基于视觉/DOM 的模拟转向稳定的、基于协议/API 的调用。它巧妙地将一次性的、高成本的“学习”过程转化为可共享、可复用的数字资产。虽然它在处理极端动态或反爬网站时仍有挑战但其设计理念和已经实现的自动化程度已经能覆盖绝大多数常见场景并能显著提升智能体项目的开发效率和运行可靠性。对于任何需要构建 Web 自动化或 AI 智能体的开发者来说它都是一个值得深入研究和集成到工具箱中的利器。