unbrowse-ai/unbrowse

# Unbrowse 本包用于安装 `unbrowse` CLI。 将任意网站转换为可供 Agent 使用的可复用 API 接口。Unbrowse 捕获网络流量，逆向工程隐藏在 UI 之下的真实端点，并将所学内容存储在共享市场中，以便下一个 Agent 立即复用。 一个 Agent 学习一次。后续所有 Agent 即可走快速通道。 ## 快速开始 ``` # 最快完整设置 npx unbrowse setup ``` `npx unbrowse setup` 会按需下载 CLI，安装浏览器资源，在检测到 Open Code 时注册 Open Code `/unbrowse` 命令，并启动本地服务器。 日常使用： ``` npm install -g unbrowse unbrowse setup ``` 如果你的 Agent 主机使用 skills： ``` npx skills add unbrowse-ai/unbrowse ``` 默认情况下，每个 CLI 命令都会在 `http://localhost:6969` 上自动启动本地服务器。可以通过 `UNBROWSE_URL`、`PORT` 或 `HOST` 进行覆盖。首次启动时，它会自动作为 Agent 注册到市场，并将凭证缓存在 `~/.unbrowse/config.json` 中。 兼容 Claude Code、Open Code、Cursor、Codex、Windsurf 以及任何可以调用本地 CLI 或 skill 的 Agent 主机。 ## setup 做了什么 - 检查 npm/npx 流程的本地前置条件。 - 安装实时捕获所需的浏览器资源。 - 当存在 Open Code 时，注册 Open Code `/unbrowse` 命令。 - 除非传递了 `--no-start`，否则启动本地 Unbrowse 服务器。 ## 常用命令 ``` unbrowse health 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" ``` ## 演示说明 - 在网站上首次捕获/索引可能需要 20-80 秒。这是慢速路径；重复操作应该会快得多。 - 对于网站任务，让 Agent 保持在 Unbrowse 上，而不是让它 drifting 到通用网页搜索或临时的 `curl`。 - 由于反机器人保护，Reddit 仍然比大多数网站更难处理。如果可用，优先使用规范的 `.json` 路由。 ## 工作原理 当 Agent 请求某项内容时，Unbrowse 首先在市场中搜索现有的 skill。如果存在置信度足够高的 skill，则立即执行。如果不存在，Unbrowse 会捕获该网站，学习其背后的 API，发布可复用的 skill，然后执行该 skill。 每个学习到的 skill 都可以被未来的每个 Agent 发现。可靠性评分、反馈、schema 漂移和验证机制让好的路径保持热度，并将损坏的路径排除在外。 ### 意图解析管道 当你调用 `POST /v1/intent/resolve` 时，编排器遵循此优先级链： 1. **路由缓存**（5 分钟 TTL）——如果最近解析过相同的意图，则立即命中 2. **市场搜索**——语义向量搜索，按综合得分排名：40% embedding 相似度 + 30% 可靠性 + 15% 新鲜度 + 15% 验证状态 3. **实时捕获**——headless 浏览器记录网络流量，逆向工程 API 端点，发布新的 skill 4. **DOM 回退**——如果未找到 API 端点（静态/SSR 站点），则从渲染的 HTML 中提取结构化数据 通过实时捕获发布的 skill 可供网络上的所有 Agent 使用。 ## 市场飞轮 每个新用户都会让平台对下一个用户更有价值——就像 Waze 一样，只不过是为网络的 API 服务。 ``` More Users → More Skills → More Domains → More Value ↑ | └──────────────────────────────────────────┘ ``` Skills 存储在 `beta-api.unbrowse.ai` 的共享市场中。首次启动时，服务器会自动注册为 Agent 并将凭证缓存在 `~/.unbrowse/config.json` 中。任何 Agent 发布的 skill 都可以通过语义搜索被所有 Agent 发现。 ### Skill 生命周期 - **active** —— 已发布、可查询、可执行 - **deprecated** —— 可靠性低（连续失败后自动触发） - **disabled** —— 端点关闭（验证失败） 后台验证循环每 6 小时运行一次，执行安全（GET）端点以检测故障和 schema 漂移。连续失败 3 次以上的 skill 会自动弃用。 ## 门控站点的身份验证 对于大多数站点，身份验证是自动的。如果你在 Chrome 或 Firefox 中登录了某个站点，Unbrowse 会直接从浏览器的 SQLite 数据库中读取你的 cookie——无需额外步骤。Cookie 在每次调用时都会重新解析，因此会话保持最新。 | 策略 | 工作原理 | 使用场景 | | ------------------- | -------------------------------------------------- | ---------------------------------------------------- | | Auto cookie resolve | 自动从 Chrome/Firefox 读取 cookie DB | 默认——如果你通过浏览器登录，则有效 | | Yolo mode | 使用你的真实配置文件打开 Chrome | 具有复杂身份验证的站点（OAuth 弹窗、2FA） | | Interactive login | 打开有头浏览器进行手动登录 | 自动解析没有 cookie 时的回退方案 | 身份验证头（CSRF token、API key、authorization header）在浏览过程中被捕获并存储在加密的 vault（`~/.unbrowse/vault/`）中。服务器端 fetch 会自动重放这些 header——无需启动浏览器。跨域身份验证（例如 lu.ma 的 cookie 在 api2.luma.com 上有效）被透明处理。过期的凭证（401/403 响应）会被自动删除。 ## 变更安全性 非 GET 端点（POST、PUT、DELETE）需要明确确认： - `dry_run: true` —— 预览将要执行的内容，无副作用 - `confirm_unsafe: true` —— 明确用户同意继续 GET 端点自动执行。变更操作在未选择加入的情况下绝不会触发。 ## API 参考 查看 [SKILL.md](./SKILL.md) 获取完整的 API 参考，包括所有端点、搜索、反馈、身份验证和问题报告。 | Method | Endpoint | 描述 | | ------ | ------------------------ | ---------------------------------------------- | | POST | `/v1/intent/resolve` | 搜索市场，如需要则捕获，执行 | | POST | `/v1/skills/:id/execute` | 执行特定 skill | | POST | `/v1/auth/login` | 交互式浏览器登录 | | POST | `/v1/search` | 跨所有域的语义搜索 | | POST | `/v1/search/domain` | 限定于某个域的语义搜索 | | POST | `/v1/feedback` | 提交反馈（影响可靠性分数） | | POST | `/v1/skills/:id/verify` | 健康检查 skill 端点 | | POST | `/v1/skills/:id/issues` | 报告损坏的 skill | | GET | `/v1/skills` | 列出所有市场 skill | | GET | `/v1/stats/summary` | 平台统计 | | GET | `/health` | 健康检查 | ## 配置 ### 运行时目录 ``` ~/.unbrowse/config.json # API key, agent ID, registration ~/.unbrowse/vault/credentials.enc # Encrypted credential store ~/.unbrowse/vault/.key # Encryption key (mode 0o600) ~/.unbrowse/skill-cache/ # Local skill manifest cache ~/.unbrowse/profiles// # Per-domain Chrome profiles ~/.unbrowse/logs/unbrowse-YYYY-MM-DD.log # Daily logs ``` ### 环境变量 | Variable | Default | 描述 | | -------------------------- | ----------------------- | ---------------------------- | | `PORT` | `6969` | 服务器端口 | | `HOST` | `127.0.0.1` | 服务器绑定地址 | | `UNBROWSE_URL` | `http://localhost:6969` | API 调用的 Base URL | | `UNBROWSE_API_KEY` | auto-generated | API key 覆盖 | | `UNBROWSE_TOS_ACCEPTED` | — | 非交互式接受服务条款 | | `UNBROWSE_NON_INTERACTIVE` | — | 跳过 readline 提示 | ## 系统布局 ``` src/ ├── index.ts # Fastify server entrypoint (port 6969) ├── api/routes.ts # HTTP route definitions ├── orchestrator/ # Intent resolution pipeline ├── execution/ # Skill/endpoint execution + retry logic ├── capture/ # Headless browser traffic recording ├── reverse-engineer/ # HAR parsing → endpoint extraction ├── extraction/ # DOM structured data extraction ├── marketplace/ # Backend API client (beta-api.unbrowse.ai) ├── client/ # Agent registration & config management ├── auth/ # Interactive login + cookie extraction ├── vault/ # Encrypted credential storage (AES-256-CBC) ├── transform/ # Field projection + schema drift detection ├── verification/ # Periodic endpoint health checks ├── ratelimit/ # Request throttling ├── types/ # TypeScript type definitions ├── domain.ts # Domain utilities └── logger.ts # Logging ``` ## 许可证 AGPL-3.0 —— 详见 [LICENSE](LICENSE)。

标签：AI 编程, API 逆向工程, CLI 工具, Headless Browser, IP 地址批量处理, MITM代理, PE 加载器, RPA, 威胁情报, 开发者工具, 技能市场, 接口生成, 效率工具, 数据提取, 暗色界面, 本地部署, 流量抓包, 浏览器自动化, 系统分析, 网络分析, 网络协议分析, 网络请求拦截, 自动化攻击