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），通过执行一系列模拟人类操作的指令（如“点击这个按钮”、“在那个输入框输入文字”）来完成任务。这个过程存在几个根本性问题：

1. 性能瓶颈：每个操作都需要等待页面渲染、JavaScript 执行、网络请求完成，耗时极长。
2. 稳定性差：前端 UI 的任何微小改动（一个 CSS 类名变化、一个按钮位置调整）都可能导致脚本失效。
3. 资源消耗大：运行一个完整的浏览器实例需要可观的内存和 CPU 资源。
4. 逻辑复杂：需要编写大量针对特定页面结构的定位和操作逻辑，代码冗长且难以维护。

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会启动一个智能的解析管道：

1. 缓存查询：首先检查本地是否有最近（5分钟内）解析过相同意图的结果，有则立即返回，实现瞬时响应。
2. 市场搜索：如果缓存未命中，则向共享市场发起语义搜索。搜索算法综合考虑了技能描述的语义相似度（40%）、历史执行的可靠性评分（30%）、技能的新鲜度（15%）和验证状态（15%），返回最匹配的现有技能。
3. 实时捕获：如果市场上没有找到足够可信的现有技能，unbrowse就会启动“学习模式”。它打开一个无头浏览器访问目标网站，引导智能体（或根据指令模拟）执行相关操作，全程录制网络流量，随后逆向工程并生成一个新的技能。
4. 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脚本做了很多事情，可以把它理解为一个“一体化部署工具”：

1. 安装依赖：检查并安装项目运行所需的 Node.js 包和其他系统依赖。
2. 构建 CLI：预构建打包好的命令行工具运行时环境。
3. 安装稳定版 CLI 封装：在你的系统路径中安装一个名为unbrowse的稳定命令行工具，方便后续调用。
4. 首次启动引导：这是最关键的一步。脚本会启动本地服务器，并引导你完成：
   • 服务条款（ToS）接受：首次使用需要同意条款。
   • 智能体注册：为你的本地实例在unbrowse市场注册一个唯一的智能体身份，并生成 API Key。这个身份用于标记技能是由谁贡献的。
   • 钱包检测与配置：如果你配置了加密货币钱包（如 Crossmint 的lobster.cash），该地址会被同步到你的智能体档案。它有两个用途：一是作为你贡献技能后获得收益的收款地址；二是作为你购买市场付费技能的支付钱包。安装脚本现在会鼓励新用户设置 Crossmint，如果检测到相关工具，甚至会尝试自动运行npx @crossmint/lobster-cli setup。

实操心得：首次运行./setup时，建议在图形化终端环境下进行，因为它可能会有交互式提示（如输入一个邮箱格式的智能体名称）。对于无头（Headless）环境或自动化脚本，你可以通过设置环境变量UNBROWSE_AGENT_EMAIL和UNBROWSE_TOS_ACCEPTED=true来非交互式地完成初始化。

方案二：通过 npm 全局安装如果你之前已经成功发布过包，或者想使用更标准的包管理方式，可以使用 npm。

npm install -g unbrowse unbrowse setup

方案三：为通用 MCP 宿主安装MCP（Model 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/unbrowse

3.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的行为：

安装完成后，你可以通过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 prices"

4. 认证机制与安全实践深度解析

让智能体操作需要登录的网站，是自动化任务中最复杂的一环。unbrowse提供了几种灵活的认证策略，核心思想是“复用你已经存在的登录状态”。

4.1 自动 Cookie 解析（默认且最推荐）

这是unbrowse的“魔法”所在。大多数情况下，你不需要做任何额外操作。当unbrowse需要为一个网站（例如https://github.com）执行技能时：

1. 它会去检查你电脑上正在运行的Chrome 或 Firefox浏览器。
2. 直接读取浏览器存储 Cookies 的 SQLite 数据库文件（对于 Chrome，通常是~/Library/Application Support/Google/Chrome/Default/Cookies或 Windows 下的对应路径）。
3. 从中提取出目标网站的登录 Cookie。
4. 将这些 Cookie 加密存储到本地 vault 中。
5. 后续执行该网站的 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 这样具有强力反机器人保护的网站仍然是“困难目标”。对于这类网站：

1. 优先寻找官方 API：很多网站提供公开的、文档化的 API（如 Reddit 的/.json接口）。在让unbrowse去捕获之前，先检查是否有这样的“后门”。unbrowse同样可以学习和使用这些官方 API。
2. 利用 Yolo 模式：对于反爬策略基于浏览器指纹和复杂 JS 挑战的网站，使用--yolo模式，用你真实的、已登录的浏览器 profile 去捕获流量，成功率最高。
3. 贡献与反馈：如果你发现某个网站无法被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）无法启动或访问。

• 排查：
  1. 运行unbrowse health检查服务状态。
  2. 检查端口6969是否被其他程序占用：lsof -i :6969(Mac/Linux) 或netstat -ano | findstr :6969(Windows)。
  3. 查看日志文件~/.unbrowse/logs/unbrowse-*.log获取错误详情。
• 解决：
  • 如果端口占用，可以通过环境变量PORT指定另一个端口，如PORT=6970 unbrowse health。
  • 重启unbrowse服务。通常停止再运行unbrowse相关命令会自动重启服务。

6.2 认证与登录问题

问题：unbrowse无法自动获取我已登录网站的 Cookie。

• 排查：
  1. 确认你使用的浏览器（Chrome/Firefox）正在运行，并且已登录目标网站。
  2. 检查unbrowse的日志，看是否有读取 Cookie 数据库的权限错误。
  3. 某些基于 Electron 的桌面应用（如 Discord、Slack）或特殊浏览器，其 Cookie 存储路径可能不同。
• 解决：
  1. 对于标准浏览器，尝试关闭浏览器再重新打开登录一次，然后重试。
  2. 使用unbrowse login --url <目标网站>命令启动交互式登录流程。
  3. 对于非标准应用，可以尝试使用unbrowse的/v1/auth/stealAPI，手动指定 Cookie 数据库路径或用户数据目录。

问题：执行技能时返回 401/403 错误。

• 排查：这通常意味着之前捕获的凭证（Cookie）已过期。
• 解决：unbrowse会自动清理过期的凭证。你需要重新登录。运行unbrowse login --url <目标网站>来更新凭证。完成后，再次执行技能即可。

6.3 技能解析与执行问题

问题：unbrowse resolve一个意图时，一直卡在“捕获”阶段，或者最终失败。

• 排查：
  1. 目标网站可能加载缓慢或需要特殊交互才能触发 API 调用。查看日志了解捕获进程卡在哪一步。
  2. 网站可能有很强的反爬机制，阻止了无头浏览器。
  3. 网络问题导致无法访问目标网站。
• 解决：
  1. 增加超时：目前 CLI 可能没有直接暴露超时参数，但可以检查服务器日志。
  2. 使用 Yolo 模式：对于反爬网站，在登录时使用--yolo标志：unbrowse login --url <网站> --yolo。用真实的浏览器环境完成操作。
  3. 检查网络：确保你的本地网络可以正常访问目标网站。
  4. 简化意图：尝试更简单、更明确的意图描述。

问题：技能执行成功，但返回的数据不是我想要的。

• 排查：这可能是意图解析偏差，或者技能捕获的 API 端点并非你期望的那个。
• 解决：
  1. 优化意图描述：使用更精确、更具体的自然语言描述你的需求。例如，“获取 Hacker News 首页前10条帖子标题”比“看看 Hacker News 新闻”更好。
  2. 检查技能详情：通过市场搜索或unbrowse skills找到相关技能，看看它具体调用的是哪个 API 端点，返回的数据结构是什么。
  3. 提供反馈：如果技能确实有问题，可以通过 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 智能体的开发者来说，它都是一个值得深入研究和集成到工具箱中的利器。