# https://github.com/browserable/browserable 项目说明书

生成时间：2026-06-20 22:12:19 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [核心功能与浏览器代理系统](#page-2)
- [REST API、JS SDK 与 CLI 使用指南](#page-3)
- [部署、自托管、扩展与故障排查](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[核心功能与浏览器代理系统](#page-2), [部署、自托管、扩展与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/browserable/browserable/blob/main/README.md)
- [tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)
- [tasks/agents/base.js](https://github.com/browserable/browserable/blob/main/tasks/agents/base.js)
- [tasks/agents/jarvis.js](https://github.com/browserable/browserable/blob/main/tasks/agents/jarvis.js)
- [tasks/prompts/agents/browserable/extractPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/extractPrompts.js)
- [ui/src/containers/FlowContainer.jsx](https://github.com/browserable/browserable/blob/main/ui/src/containers/FlowContainer.jsx)
- [sdk/browserable-js/src/types.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)
</details>

# 项目概览与系统架构

Browserable 是一个面向 AI Agent 的开源浏览器自动化库，旨在帮助开发者构建能够在真实网站中导航、填写表单、点击按钮并提取结构化信息的浏览器代理。官方数据表明，该项目在 Web Voyager 基准测试上已达到 90.4% 的通过率 资料来源：[README.md:9-11]()。本仓库同时提供管理后台、任务调度服务、远程浏览器服务与 JavaScript SDK，构成一套端到端的"代理化浏览器"解决方案 资料来源：[README.md:1-30]()。

## 定位与核心能力

项目的核心定位是"为 AI 代理提供可编程的浏览器" 资料来源：[README.md:7-13]()。在实现层面，Browserable 暴露了四种原子能力：打开新标签页（`open_new_tab`）、读取标签页（`read_tab`）、在标签页上执行操作（`act_on_tab`）以及从标签页中提取内容（`extract_from_tab`）。复杂任务都可以通过这四种能力的组合来表达 资料来源：[tasks/agents/browserable.js:1-50]()。

为了让代理能够"看见"网页，Browserable 同时使用文本/DOM 渲染与截图两种通道。LLM 在收到图像后会优先基于图像理解页面，再与 DOM 元素进行对照决策 资料来源：[tasks/prompts/agents/browserable/actionPrompts.js:1-30]()。当网页较长时，系统会按块（chunk）滚动页面，循环调用提取流程并合并多次结果，最终输出符合用户自定义 schema 的结构化数据 资料来源：[tasks/agents/browserable.js:100-200]()。

## 系统架构

项目主要由三个独立的服务组成：管理后台 UI、任务调度与代理执行服务（`tasks`）、远程浏览器服务（`browser`）。三者通过 Docker Compose 在本地编排启动，统一监听在 `http://localhost:2001` 资料来源：[README.md:15-30]()。

```mermaid
flowchart LR
    User[用户] --> AdminUI[Admin UI<br/>ui/*]
    AdminUI -->|REST / SDK| TasksService[Tasks Service<br/>tasks/*]
    TasksService -->|CDP| BrowserService[Browser Service<br/>browser/*]
    TasksService -->|OpenAI 兼容协议| LLM[LLM Provider]
    SDK[JS SDK<br/>sdk/browserable-js] -->|HTTP| TasksService
```

`tasks` 服务内部由"代理"（Agent）构成，代理以节点（Node）形式在流程（Flow）中执行。每个代理都继承自 `BaseAgent`，并通过 `jarvis.endNode` 与 `jarvis.errorAtNode` 等方法向编排层汇报生命周期状态 资料来源：[tasks/agents/base.js:1-60]()。其中 `Jarvis` 是顶层编排代理，负责子任务拆分、消息日志聚合与结果表处理；代理在决策时会通过 `work_on_subtask_before_deciding` 等动作码控制执行节奏 资料来源：[tasks/agents/jarvis.js:1-50]()。管理端 UI 通过 `FlowContainer` 把代理运行过程中产生的文本、Markdown、图片与代码片段渲染成可折叠的对话流 资料来源：[ui/src/containers/FlowContainer.jsx:1-40]()。对外，JS SDK 暴露 `BrowserableConfig`、`Task`、`TaskRun`、`TaskRunStatus` 等类型，并支持 `pollInterval`、`timeout` 与 `onStatusChange` 回调，简化客户端轮询 资料来源：[sdk/browserable-js/src/types.ts:1-60]()。

## LLM 兼容性与社区关注点

默认支持 OpenAI 兼容协议，Tasks 服务在多模型之间按顺序回退，候选列表包括 `gemini-2.0-flash`、`deepseek-chat`、`gpt-4o-mini`、`claude-3-5-haiku` 与 `qwen-plus` 资料来源：[tasks/agents/browserable.js:50-80]()。社区中关于 Groq 与 OpenRouter 的支持已被列入路线图（issue #5），Ollama 等本地 LLM 的支持也在持续讨论中（issue #9）；目前若希望切换到非 OpenAI 提供方，需手动将 `https://api.openai.com/v1/chat/completions` 替换为对应提供方的兼容 URL（issue #3 维护者回复）。

启动方式上，`npx browserable` 是一键入口，但部分使用 fnm 的用户在 Ubuntu/WSL 环境下会遇到 `/usr/bin/env: 'node --no-warnings': No such file or directory` 错误（issue #20），此时可改用 `git clone` + `docker-compose -f docker-compose.dev.yml up` 的手动方式 资料来源：[README.md:23-30]()。若管理后台一直停留在 "Initial setup is in progress" 提示（issue #6），通常意味着 `tasks` 容器未健康启动，可通过 `docker ps` 检查容器状态并查看对应日志进行排查。

## See Also

- [官方文档：https://docs.browserable.ai](https://docs.browserable.ai) — REST API、JS SDK、Custom Functions 与 Troubleshooting 详细说明
- [Web Voyager 基准（issue #17）](https://github.com/browserable/browserable/issues/17) — 与项目宣传中 90.4% 通过率对应的发布博客进度跟踪
- [Public Roadmap（issue #7）](https://github.com/browserable/browserable/issues/7) — 通过 GitHub Issues 维护的 1:1 公开路线图

---

<a id='page-2'></a>

## 核心功能与浏览器代理系统

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [REST API、JS SDK 与 CLI 使用指南](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)
- [tasks/agents/base.js](https://github.com/browserable/browserable/blob/main/tasks/agents/base.js)
- [tasks/agents/jarvis.js](https://github.com/browserable/browserable/blob/main/tasks/agents/jarvis.js)
- [tasks/prompts/agents/browserable/extractPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/extractPrompts.js)
- [tasks/prompts/agents/browserable/actionPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/actionPrompts.js)
- [tasks/prompts/agents/jarvis/richOutputPrompt.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/jarvis/richOutputPrompt.js)
- [sdk/browserable-js/src/types.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)
- [tasks/package.json](https://github.com/browserable/browserable/blob/main/tasks/package.json)
</details>

# 核心功能与浏览器代理系统

## 一、目标与定位

Browserable 的核心是一个**浏览器代理系统**，由 `Browserable Agent`、`Base Agent` 与 `Jarvis` 三大模块协作完成"代替用户在浏览器内完成任务"的使命。`Browserable Agent` 的 `CODE` 与 `DETAILS` 明确描述其作用：提供可在浏览器中代替用户执行点击、输入、抽取等操作的智能体，并通过远程浏览器会话与 Playwright 完成实际交互 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)。

当用户明确要求"在浏览器里完成某事"时，系统会优先选用浏览器代理；当存在更专用的 Agent（如 Google Sheets Agent）时，应使用专用 Agent 代替 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)。

## 二、代理分层架构

### 2.1 BaseAgent 基类

`BaseAgent` 定义了 Agent 的生命周期：`_action_end` 负责汇总 reasoning 与 output 并调用 `jarvis.endNode()` 结束节点；`_action_irrecoverable_error` 则把错误日志写入 user/debug log 并调用 `jarvis.errorAtNode()` 终结节点 资料来源：[tasks/agents/base.js](https://github.com/browserable/browserable/blob/main/tasks/agents/base.js)。

### 2.2 Browserable Agent

继承自 `BaseAgent`，其 `this.CODE = "BROWSER_AGENT"`。它使用四种基础动作：`open_new_tab`、`read_tab`、`act_on_tab`、`extract_from_tab`，理论上能完成任何网站交互 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)。

### 2.3 Jarvis 协调器

`Jarvis` 是任务调度与上下文管理中枢。它通过 `convertMessageLogsToLLMFormat` 从 `browserable.message_logs` 表按 `run_id`、`node_id`、`thread_id` 维度回捞历史消息，向 LLM 提供统一上下文 资料来源：[tasks/agents/jarvis.js](https://github.com/browserable/browserable/blob/main/tasks/agents/jarvis.js)。

```mermaid
flowchart LR
    User[用户任务] --> Jarvis
    Jarvis -->|调度| BrowserAgent[Browserable Agent]
    BrowserAgent -->|open_new_tab| Playwright[Playwright/Steel SDK]
    BrowserAgent -->|act_on_tab| Playwright
    BrowserAgent -->|extract_from_tab| LLM
    LLM -->|多模型回退| BrowserAgent
    BrowserAgent --> Jarvis
    Jarvis --> RichOutput[richOutputPrompt 汇总]
    RichOutput --> User
```

## 三、关键工作流

### 3.1 打开标签页与截图

执行 `open_new_tab` 时，Agent 调用 `browserService.getPlaywrightBrowser()` 获取 Playwright 会话，并通过 `screenshotHelper` 抓取截图存入运行私有数据；随后立即调用 `waitForSettledDom(page)` 与 `debugDom(page)` 等待 DOM 稳定 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)。截图通过 `imageUrl` 与 `privateImageUrl` 暴露给下游 LLM，便于多模态决策。

### 3.2 内容抽取与分块合并

`extractPrompts.js` 中的 `buildExtractLLMPrompt` 提供两种模式：`useTextExtract=true` 时基于文本化网页，`false` 时基于 DOM 元素列表。系统提示词强制要求"不要假设、不要幻觉"，并要求输出 `justification` 与 `extractedContent` 字段 资料来源：[tasks/prompts/agents/browserable/extractPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/extractPrompts.js)。

抽取按"分块滚动"方式循环：每次滚动到新 chunk 后截图并请求 LLM，再调用 `buildRefineExtractedContentPrompt` 合并 `previouslyExtractedContent` 与新内容，去重数组、扩展文本、更新数值字段 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js) 与 [tasks/prompts/agents/browserable/extractPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/extractPrompts.js)。

### 3.3 行为决策

`actionPrompts.js` 定义三类动作：`doAction`（执行点击、输入等）、`skipSection`（跳过无法在此完成的部分）、`actionCompleted`（标记完成）。当附图时，提示词明确要求"以图像为主、DOM 为辅"进行判断 资料来源：[tasks/prompts/agents/browserable/actionPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/actionPrompts.js)。`actionExtractLLMHelper` 内置的"下拉框需先键入再选择"等 SPECIAL ELEMENTS 规则体现了对真实网站交互细节的考虑 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)。

## 四、LLM 多模型与失败兜底

`callOpenAICompatibleLLMWithRetry` 内置一组回退模型：`gemini-2.0-flash`、`deepseek-chat`、`gpt-4o-mini`、`claude-3-5-haiku`、`qwen-plus`，`max_attempts=3`，按列表顺序尝试以保证可用性 资料来源：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)。

需要替换 OpenAI 时，可在社区指引下将 OpenAI 兼容 URL 切换为 Groq 等第三方端点；本地 LLM（如 Ollama）支持尚未内置进 Admin UI 资料来源：[issues/9](https://github.com/browserable/browserable/issues/9)、[issues/3](https://github.com/browserable/browserable/issues/3)、[issues/5](https://github.com/browserable/browserable/issues/5)。

## 五、SDK 与对外契约

`browserable-js` 通过 `CreateTaskOptions`、`Task`、`TaskRunStatus` 等 TypeScript 类型对外暴露运行生命周期；`TaskRunStatus` 状态枚举为 `scheduled | running | completed | error`，`TaskRunResult` 增加 `output` 与 `dataTable` 字段 资料来源：[sdk/browserable-js/src/types.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)。`WaitForRunOptions` 默认 1 秒轮询、5 分钟超时，便于在 JS 端稳定等待 run 完成。

## 六、汇总输出与社区已知问题

任务收尾时，`richOutputPrompt` 按 `outputData` 模板逐字段累计 `outputGenerated`，并以 4000 词为上限强制截断 资料来源：[tasks/prompts/agents/jarvis/richOutputPrompt.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/jarvis/richOutputPrompt.js)。后端依赖 Playwright、`steel-sdk`、`sharp` 等图形与浏览器栈 资料来源：[tasks/package.json](https://github.com/browserable/browserable/blob/main/tasks/package.json)。

常见故障包括：首次安装 `Initial Setup` 卡住，多为 tasks 服务未启动（`docker ps` 检查）；`npx browserable` 在 fnm 多 shell 场景下出现 `node --no-warnings` shebang 错误 资料来源：[issues/6](https://github.com/browserable/browserable/issues/6)、[issues/20](https://github.com/browserable/browserable/issues/20)。截图、任务 GIF、日志 API 已在路线图中陆续上线 资料来源：[issues/13](https://github.com/browserable/browserable/issues/13)、[issues/14](https://github.com/browserable/browserable/issues/14)、[issues/12](https://github.com/browserable/browserable/issues/12)。

## See Also

- 浏览器自动化与 Playwright 集成
- Jarvis 任务调度与消息日志
- LLM 多模型回退与本地化
- browserable-js SDK 使用指南

---

<a id='page-3'></a>

## REST API、JS SDK 与 CLI 使用指南

### 相关页面

相关主题：[核心功能与浏览器代理系统](#page-2), [部署、自托管、扩展与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [sdk/browserable-js/src/index.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/index.ts)
- [sdk/browserable-js/README.md](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/README.md)
- [sdk/browserable-js/src/types.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)
- [sdk/browserable-js/package.json](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/package.json)
- [sdk/examples/js-sdk-test/README.md](https://github.com/browserable/browserable/blob/main/sdk/examples/js-sdk-test/README.md)
- [sdk/examples/js-sdk-test/package.json](https://github.com/browserable/browserable/blob/main/sdk/examples/js-sdk-test/package.json)
- [README.md](https://github.com/browserable/browserable/blob/main/README.md)
- [tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)
- [tasks/agents/base.js](https://github.com/browserable/browserable/blob/main/tasks/agents/base.js)
- [ui/src/containers/SettingsContainer.jsx](https://github.com/browserable/browserable/blob/main/ui/src/containers/SettingsContainer.jsx)
- [tasks/package.json](https://github.com/browserable/browserable/blob/main/tasks/package.json)
</details>

# REST API、JS SDK 与 CLI 使用指南

## 一、概述与定位

Browserable 是一个开源、可自托管的浏览器自动化平台，提供三层对外接口：REST API、JavaScript/TypeScript SDK（`browserable-js`）以及 `npx browserable` CLI。三个接口最终都对接同一个后端任务服务（`tasks`），用户可以根据使用场景选择最合适的入口。

- **REST API**：HTTP 接口，适合任意语言或无语言偏好的服务端集成；官方文档为 `https://docs.browserable.ai/rest-api/introduction`。
- **JS SDK**：基于 `axios` 封装的 TypeScript 包，包名为 `browserable-js`（[sdk/browserable-js/package.json](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/package.json)）。
- **CLI**：`npx browserable` 命令行入口，用于一键拉起本地 Docker 部署。

资料来源：[README.md](https://github.com/browserable/browserable/blob/main/README.md)、[sdk/browserable-js/package.json:1-30](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/package.json)

## 二、JS SDK 使用详解

`browserable-js` 通过 `Browserable` 类暴露所有方法，初始化时需要 `apiKey`，可选 `baseURL`（默认 `https://api.browserable.ai/api/v1`）。

```typescript
import { Browserable } from 'browserable-js';

const browserable = new Browserable({
  apiKey: 'your-api-key',
  // baseURL: 'http://localhost:2003/api/v1' // 本地自托管示例
});
```

### 核心方法

| 方法 | 用途 | 关键参数 |
| --- | --- | --- |
| `createTask` | 创建任务 | `task: string`，可选 `agent` |
| `listTasks` | 分页列出任务 | `page`, `limit` |
| `getTaskRunStatus` | 查询运行状态 | `taskId`, `runId?` |
| `getTaskRunResult` | 获取运行结果 | `taskId`, `runId?` |
| `stopRun` | 停止运行 | `taskId`, `runId?` |

资料来源：[sdk/browserable-js/README.md:1-60](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/README.md)、[sdk/browserable-js/src/types.ts:1-90](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)

### 类型与状态机

任务状态在 `Task.status` 中定义为 `'active' | 'inactive'`；任务运行状态在 `TaskRunStatus.status` 中定义为 `'scheduled' | 'running' | 'completed' | 'error'`。运行结果可能附带 `output` 与结构化的 `dataTable`，用于二次处理。轮询工具 `waitForRun` 接受 `pollInterval`（默认 1000ms）、`timeout`（默认 300000ms）和 `onStatusChange` 回调。

资料来源：[sdk/browserable-js/src/types.ts:18-80](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)

### 端到端示例

`sdk/examples/js-sdk-test` 演示了调用流程：先获取用户档案，再列出可用浏览器，最后创建浏览器会话。该示例默认指向本地 `http://localhost:2003/api/v1`，便于在自托管环境下联调。

```bash
cd sdk/examples/js-sdk-test
npm install
npm test
```

资料来源：[sdk/examples/js-sdk-test/README.md:1-30](https://github.com/browserable/browserable/blob/main/sdk/examples/js-sdk-test/README.md)、[sdk/examples/js-sdk-test/package.json:1-18](https://github.com/browserable/browserable/blob/main/sdk/examples/js-sdk-test/package.json)

## 三、REST API 与后端任务流

REST API 端点的请求/响应模型与 SDK 保持一致，均遵循 `ApiResponse<T>` 统一结构（`success` + `data` + `error` + 分页字段）。从后端代码看，任务执行由 `tasks/agents/browserable.js` 中的 `BrowserAgent` 驱动，浏览器操作以工具调用（`open_new_tab`、`read_tab`、`act_on_tab`、`extract_from_tab`）的形式编排，每次操作都会向 `jarvis` 写入节点日志（`updateNodeUserLog` / `updateNodeAgentLog` / `updateNodeDebugLog`）。

```mermaid
sequenceDiagram
    participant Client as 客户端(SDK/CLI/cURL)
    participant API as REST API
    participant Tasks as tasks 服务
    participant Browser as 远程浏览器
    Client->>API: createTask / 触发器
    API->>Tasks: 调度 run
    Tasks->>Browser: 工具调用(open/read/act/extract)
    Browser-->>Tasks: 页面/截图
    Tasks-->>API: 更新 status / output
    Client->>API: getTaskRunStatus / getTaskRunResult
    API-->>Client: ApiResponse<T>
```

社区已规划但尚未完全交付的端点包括 `task-run-gif`（GIF 回放）、`screenshots`、`logs` 等（见 Issue #13、#14、#12），使用前请先确认官方 REST 文档是否已上线对应接口。

资料来源：[tasks/agents/browserable.js:1-120](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)、[tasks/agents/base.js:1-90](https://github.com/browserable/browserable/blob/main/tasks/agents/base.js)、[sdk/browserable-js/src/types.ts:60-80](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)

## 四、CLI 安装与常见问题

CLI 入口为 `npx browserable`，由 Issue #8 跟踪的命令行能力（`--help`、`down` 等）已合入 1.0.13。常见使用步骤：

1. `npx browserable` 启动本地 Docker Compose 栈；
2. 等待 `Initial setup is in progress` 提示消失；
3. 通过 `http://localhost:2003` 访问管理 UI，复制 API Key 用于 SDK/REST 集成。

### 常见故障

- **`/usr/bin/env: 'node --no-warnings': No such file or directory`**：出现在 Ubuntu/WSL 等使用 `fnm` 多 shell 的环境，原因是 shebang 中 `node` 解析失败（Issue #20）。临时方案：在普通终端（非 `fnm_multishells`）下运行 `npx browserable`，或将 Node 路径加入 `/usr/bin/env` 查找列表。
- **初始化卡在 “reload this page in a minute”**：通常是后端 `tasks` 容器未健康启动。先执行 `docker ps` 检查 `browserable_tasks` 状态，再 `docker exec -it browserable_tasks sh` 查看日志（Issue #6）。
- **想使用非 OpenAI 提供方（Groq / OpenRouter / Ollama）**：当前 Admin UI 与 Docker Compose 未直接支持，需要在代码中替换 `https://api.openai.com/v1/chat/completions` 为兼容端点（Issue #3、#5、#9）。`ui/src/containers/SettingsContainer.jsx` 中的 `userApiKeys` 仅识别 `openai` / `claude` / `gemini`，新增提供方需要扩展该表单。

资料来源：[ui/src/containers/SettingsContainer.jsx:1-60](https://github.com/browserable/browserable/blob/main/ui/src/containers/SettingsContainer.jsx)、[README.md](https://github.com/browserable/browserable/blob/main/README.md)、[tasks/package.json:1-30](https://github.com/browserable/browserable/blob/main/tasks/package.json)

## 参见

- [Browserable 主仓库](https://github.com/browserable/browserable)
- [REST API 官方文档](https://docs.browserable.ai/rest-api/introduction)
- [JS SDK 官方文档](https://docs.browserable.ai/js-sdk/introduction)
- [Troubleshooting 文档](https://docs.browserable.ai/development/troubleshooting)
- [自定义工具/函数指南](https://docs.browserable.ai/guides/custom-functions)

---

<a id='page-4'></a>

## 部署、自托管、扩展与故障排查

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [REST API、JS SDK 与 CLI 使用指南](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [tasks/agents/jarvis.js](https://github.com/browserable/browserable/blob/main/tasks/agents/jarvis.js)
- [tasks/agents/base.js](https://github.com/browserable/browserable/blob/main/tasks/agents/base.js)
- [tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)
- [tasks/prompts/agents/browserable/extractPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/extractPrompts.js)
- [tasks/prompts/agents/browserable/actionPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/actionPrompts.js)
- [tasks/prompts/agents/jarvis/richOutputPrompt.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/jarvis/richOutputPrompt.js)
- [tasks/prompts/agents/deepresearch/processSerpsPrompt.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/deepresearch/processSerpsPrompt.js)
- [tasks/package.json](https://github.com/browserable/browserable/blob/main/tasks/package.json)
- [sdk/browserable-js/src/types.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)
- [ui/package.json](https://github.com/browserable/browserable/blob/main/ui/package.json)
</details>

# 部署、自托管、扩展与故障排查

本文面向希望自行部署、扩展或排查浏览器自动化平台 Browserable 的工程师与运维人员。Browserable 是一个由多个协同 Agent 组成的浏览器任务执行系统，包含任务调度 (`tasks`)、管理员界面 (`ui`) 与官方 JavaScript SDK (`sdk/browserable-js`)。本页围绕部署架构、安装流程、扩展点与常见故障展开，所有结论均基于仓库源码与社区讨论记录。

## 一、部署架构概览

Browserable 通过 Docker Compose 启动一组协同服务，核心组件包括后端任务服务、数据库与本地浏览器运行时。任务服务通过 `pg`、`redis`、`playwright`、`steel-sdk` 等依赖与外部世界交互，分别承担持久化、队列调度、浏览器自动化与远程浏览器连接等职责 资料来源：[tasks/package.json:1-30]()。

后端任务服务通过 `browserable` PostgreSQL schema 存储运行日志，典型的查询会写入 `browserable.message_logs` 表，字段涵盖 `run_id`、`node_id`、`thread_id`、`segment`、`messages` 与 `created_at`，分别用于标识运行、节点、线程、消息段、消息内容与时间戳 资料来源：[tasks/agents/jarvis.js:1-50]()。运行时还会调用 `isRunActive`、`updateNodeLiveStatus`、`scheduleQueueJob` 等函数来判断运行是否仍然有效，并在 Agent 节点结束时通过 `endNode`、`errorAtNode` 更新状态 资料来源：[tasks/agents/base.js:1-80]()。

```mermaid
flowchart LR
    A[npx browserable / Docker] --> B[tasks 服务]
    B --> C[PostgreSQL<br/>browserable schema]
    B --> D[Redis 队列]
    B --> E[Playwright 浏览器]
    B --> F[Steel SDK 远程浏览器]
    B --> G[OpenAI 兼容 LLM]
    B --> H[ui 管理后台]
    H --> I[JS SDK / REST API]
```

部署时各组件以容器方式运行，管理员通过 Web UI 提交任务，JS SDK 或 REST API 触发任务运行；任务节点在完成后将状态写回数据库并通过 WebSocket/轮询向前端反馈 资料来源：[sdk/browserable-js/src/types.ts:1-60]()。

## 二、自托管安装流程

社区文档推荐的安装方式为 `npx browserable`，该命令会拉取并启动所需的 Docker 容器。1.0.13 版本起，`npx browserable` 增加了 `--help` 与 `down` 等子命令，用于查看帮助与停止所有服务 资料来源：[issue #8](https://github.com/browserable/browserable/issues/8)。

安装步骤大致为：

1. 在主机上安装 Node.js（建议使用 LTS 版本）与 Docker Engine；
2. 执行 `npx browserable` 拉起 `tasks`、`ui` 等容器；
3. 通过浏览器访问 `ui` 容器暴露的端口，使用 OpenAI 兼容 LLM 的 API Key 完成初始配置；
4. 等待"Initial setup is in progress. Please reload this page in a minute." 提示消失即代表后端任务服务就绪 资料来源：[issue #6](https://github.com/browserable/browserable/issues/6)。

值得注意的是，部分用户在 WSL/Ubuntu 环境下执行 `npx browserable` 会遇到 `/usr/bin/env: ‘node --no-warnings’: No such file or directory` 错误，根因是 fnm/nvm 等工具的临时 shell 目录未进入 PATH，需要在普通 shell 中执行，或将 Node 装入系统级路径 资料来源：[issue #20](https://github.com/browserable/browserable/issues/20)。

## 三、扩展能力

### 3.1 LLM 提供商

Browserable 默认通过 OpenAI 兼容接口调用大模型，源码中可见 `callOpenAICompatibleLLMWithRetry` 这一通用入口，其 `models` 数组按顺序回退尝试 `gemini-2.0-flash`、`deepseek-chat`、`gpt-4o-mini`、`claude-3-5-haiku`、`qwen-plus` 等多种模型 资料来源：[tasks/agents/browserable.js:1-60]()。该设计天然支持任意 OpenAI 兼容服务，社区已验证通过替换 `https://api.openai.com/v1/chat/completions` 为 Groq 端点即可临时启用 Groq 资料来源：[issue #3](https://github.com/browserable/browserable/issues/3)。

| 能力 | 状态 | 备注 |
| --- | --- | --- |
| OpenAI 兼容多模型回退 | 已上线 | 见 `callOpenAICompatibleLLMWithRetry` |
| Groq 直连 | 实验性 | 需手动替换请求端点 |
| OpenRouter | 计划中 | 见 issue #5 |
| 本地 LLM（Ollama） | 计划中 | 见 issue #9 |

### 3.2 自定义工具与本地浏览器

用户可通过自定义函数（custom functions）扩展 Agent 能力，V1 版本已上线相关接口 资料来源：[issue #10](https://github.com/browserable/browserable/issues/10)。同时，`BROWSER_AGENT` 类提供 `open_new_tab`、`read_tab`、`act_on_tab`、`extract_from_tab` 四类核心动作，并在执行过程中调用 `browserService.getPlaywrightBrowser` 申请浏览器会话，支持本地浏览器会话与远程会话两种模式 资料来源：[tasks/agents/browserable.js:60-140]()。

### 3.3 SDK 与 REST API

官方 JavaScript SDK 暴露 `CreateTaskOptions`、`TaskRunStatus`、`TaskRunResult` 等类型，运行状态枚举为 `scheduled | running | completed | error`，并提供 `WaitForRunOptions` 用于轮询与超时控制 资料来源：[sdk/browserable-js/src/types.ts:1-60]()。后台还可生成任务运行 GIF（`TaskRunGifResult`，枚举为 `pending | error | completed`），用于可视化浏览器交互过程 资料来源：[issue #13](https://github.com/browserable/browserable/issues/13)。

## 四、故障排查

### 4.1 后端服务未启动

若管理界面长时间停留在 "Initial setup is in progress"，通常意味着 `tasks` 服务未就绪。建议执行：

```bash
docker ps                     # 检查 tasks 容器是否 unhealthy
docker exec -it browserable ... # 进入容器查看日志
```

若容器处于重启循环，可结合 `updateNodeDebugLog` 中的错误信息进一步定位 资料来源：[issue #6](https://github.com/browserable/browserable/issues/6) 与 [tasks/agents/base.js:40-80]()。

### 4.2 npx 启动失败

如遇 shebang 解析错误 `/usr/bin/env: ‘node --no-warnings’: No such file or directory`，说明 Node 可执行文件未在当前 PATH 中。可在常规 shell（非 fnm 多 shell 临时环境）重新执行 资料来源：[issue #20](https://github.com/browserable/browserable/issues/20)。

### 4.3 Agent 节点错误

Agent 在执行过程中若发生不可恢复异常，会通过 `errorAtNode` 将错误上报，并将状态写入 `browserable.message_logs` 表，便于后续审计。`BaseAgent` 的 `_action_end` 与错误处理分支展示了完整的成功/失败生命周期 资料来源：[tasks/agents/base.js:1-80]()。

### 4.4 LLM 调用失败

由于多模型回退机制的存在，单一模型失败通常不会中断任务；建议在自托管环境中预先在管理面板配置至少两个 OpenAI 兼容提供方（如 OpenAI + 自托管网关），以提高稳定性 资料来源：[tasks/agents/browserable.js:1-60]()。

更多排障手册可参考官方 troubleshooting 文档 资料来源：[issue #15](https://github.com/browserable/browserable/issues/15)。

## See Also

- 浏览器 Agent 内部动作与抽取流程：[tasks/agents/browserable.js](https://github.com/browserable/browserable/blob/main/tasks/agents/browserable.js)
- 抽取内容合并与去重策略：[tasks/prompts/agents/browserable/extractPrompts.js](https://github.com/browserable/browserable/blob/main/tasks/prompts/agents/browserable/extractPrompts.js)
- 任务调度与日志持久化：[tasks/agents/jarvis.js](https://github.com/browserable/browserable/blob/main/tasks/agents/jarvis.js)
- JS SDK 类型定义：[sdk/browserable-js/src/types.ts](https://github.com/browserable/browserable/blob/main/sdk/browserable-js/src/types.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：browserable/browserable

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：npx browserable returns error `/usr/bin/env: ‘node --no-warnings’: No such file or directory`。

## 1. 安装坑 · 来源证据：npx browserable returns error `/usr/bin/env: ‘node --no-warnings’: No such file or directory`

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：npx browserable returns error `/usr/bin/env: ‘node --no-warnings’: No such file or directory`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/browserable/browserable/issues/20 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/browserable/browserable | host_targets=claude

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/browserable/browserable | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/browserable/browserable | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/browserable/browserable | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/browserable/browserable | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/browserable/browserable | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/browserable/browserable | release_recency=unknown

<!-- canonical_name: browserable/browserable; human_manual_source: deepwiki_human_wiki -->