一、项目定位与核心能力

Steel 是一个面向 AI Agent 与应用的开源浏览器 API，旨在让开发者无需从零搭建浏览器自动化基础设施即可驱动真实的 Chrome 实例。其内部使用 Puppeteer 与 Chrome DevTools Protocol (CDP)，因此客户端可以继续使用 Puppeteer、Playwright 或 Selenium 直接连接到 Steel 暴露的 WebSocket 端点。资料来源：README.md:1-30。

主要项目括：

上述能力与依赖可在 api/package.json:30-50 中直接看到，包括 [email protected]、[email protected]、[email protected]、proxy-chain@^2.5.6 等。

二、仓库结构

项目采用 monorepo 形式，主要由三个 npm 包组成：

graph LR
    A[steel-browser 仓库] --> B[api/]
    A --> C[ui/]
    A --> D[repl/]
    B --> E[Fastify HTTP API + CDP]
    B --> F[extensions/recorder/]
    C --> G[React + Vite 调试界面]
    D --> H[基于 puppeteer-core 的 REPL]

各包职责如下：

• api/：基于 Fastify 5 的 HTTP 服务，承载会话、页面、CDP 转发与抓取/截图/PDF 等动作端点；并使用 api/src/utils/schema.ts:1-30 的 buildJsonSchemas 将 Zod Schema 转写为 OpenAPI 3 文档，供 /documentation 展示。
• ui/：基于 React 18 + Radix UI + Tailwind 的调试与录制回放界面，依赖 ui/package.json:1-50 中的 rrweb-player 进行会话回放，使用 @hey-api/openapi-ts 自动生成 API 客户端。
• repl/：极简命令行 REPL，通过 repl/package.json:1-15 中的 puppeteer-core@^24.2.0 直接连接到 API 暴露的 WebSocket，便于快速试验。
• api/extensions/recorder/：基于 rrweb@^2.0.0-alpha.4 的 Chrome 扩展，用于录制用户操作；构建产物由 api/extensions/recorder/package.json:1-12 描述。

三、快速入门

3.1 通过 Docker 启动

最快的运行方式是从 GitHub Container Registry 拉取预构建镜像：

docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser

• 3000 端口对应 HTTP API（含 Swagger UI，路径 /documentation）。
• 9223 端口对应 CDP WebSocket，可由 Puppeteer/Playwright/Selenium 连接。

部署按钮与一键模板（Railway、Render）同样收录在 README 表格中。资料来源：README.md:55-80。

3.2 通过 REPL 连接已运行的实例

repl/ 包提供交互式脚本，约定 WebSocket 端点已对外暴露。启动方式：

cd repl
npm install
npm start

随后在 src/script.ts 中编写 Puppeteer 逻辑并重复执行即可，无需重启 API 服务。资料来源：repl/README.md:1-15。

3.3 常用动作示例

API 同时提供短路径动作端点（无需持有 CDP 会话），例如：

# 抓取页面 HTML
curl -X POST http://0.0.0.0:3000/v1/scrape \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "delay": 1000 }'

# 截屏
curl -X POST http://0.0.0.0:3000/v1/screenshot \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "fullPage": true }' --output screenshot.png

# 导出 PDF
curl -X POST http://0.0.0.0:3000/v1/pdf \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }' --output output.pdf

后端在 api/src/utils/scrape/index.ts 中聚合了 HTML 清洗、Readability 抽取（defuddle）、JSON 转 Markdown 与 base64 图片剥离等能力，并在 api/src/utils/scrape/jsonToMarkdown.ts:1-10 与 api/src/utils/scrape/pdfToHtml.ts 中实现。

四、常见陷阱与社区反馈

• 指纹注入失败：在自托管 steel-browser-api（v0.5.3 / [email protected]）下，部分 Chrome 146 + 固定 1920x1080 的组合会触发 Failed to generate a consistent fingerprint after 10 attempts，此时可用 SKIP_FINGERPRINT_INJECTION 环境变量临时绕过（参考 issue #295、#302）。
• 本地 npm run dev 报错 File is not defined：通常与 Node 版本低于 22 或 Web API polyfill 缺失有关，请使用仓库要求的 Node ≥ 22（参考 issue #230）。
• API 文档不完整：社区多次反馈希望补齐集群、代理链路、扩展加载等高级主题的文档（参考 issue #123、#144）。当前仓库通过 api/src/utils/requests.ts:1-15 的 compileUrlPatterns 与 isUrlMatchingPatterns 提供请求级黑白名单/匹配能力，可作为请求路由的参考实现。

See Also

• API 路由与会话管理（Session 生命周期、CDP 转发）
• 抓取与内容抽取管线（scrape utilities、PDF/JSON 转换）
• 指纹与反检测配置（fingerprint-generator / fingerprint-injector）
• 录制扩展与回放（rrweb、rrweb-player）

总体架构概述

Steel Browser 是一个面向 AI Agent 与自动化应用的开源浏览器 API 项目，其设计目标是将浏览器会话管理、CDP（Chrome DevTools Protocol）控制、页面抓取与反检测能力以 HTTP / WebSocket 接口的形式对外暴露，调用方可以使用 Puppeteer、Playwright 或 Selenium 直接连接 (README.md:55-65)。

整个系统由多个相互协作的包组成，源代码按职责划分为 api（核心服务）、ui（调试控制台）、repl（本地脚本入口）以及 api/extensions/recorder（会话录制扩展）四个主要模块 (README.md:1-15, api/package.json:1-15, ui/package.json:1-15, repl/package.json:1-10, api/extensions/recorder/package.json:1-10)。这种「API + UI + REPL + 扩展」的组合方式让开发者既能以服务方式部署，也可以通过脚本直接驱动浏览器实例。

核心包与组件结构

仓库采用 monorepo 风格的多包布局，每个子目录都是一个独立的 Node 包，依赖通过 package.json 分别管理。

repl/README.md 中明确说明，REPL 仅依赖一个本地脚本 src/script.ts，运行前需要确保 Steel Browser 已经启动，且 WebSocket 端点可达 (repl/README.md:5-15)。这种轻量的连接器让本地调试可以复用服务实例，避免重复启动 Chrome。

API 服务关键模块

api 包基于 Fastify 5 构建，并集成 @fastify/swagger 与 @scalar/fastify-api-reference 自动生成 OpenAPI 文档 (api/package.json:30-50)。其内部工具模块按职责进一步切分：

• Schema 工具：api/src/utils/schema.ts 封装了 buildJsonSchemas，基于 zod 与 zod-to-json-schema 将 Zod 模型转换为 OpenAPI 3 JSON Schema，并以 $ref 形式复用 (api/src/utils/schema.ts:1-40)。
• 会话投射（casting）工具：api/src/utils/casting.ts 实现了 navigatePage、getPageTitle、getPageFavicon 等对 puppeteer-core Page 对象的封装，处理前进 / 后退 / 刷新等导航事件 (api/src/utils/casting.ts:1-20)。

值得注意的是，api/package.json 同时依赖 [email protected] 与 [email protected]，这是项目反检测能力的核心实现 (api/package.json:50-60)。社区中已经出现与指纹生成相关的故障报告（如 Chrome 146 + 1920x1080 解析失败），说明该模块在升级时需要重点回归测试（参见 Issue #302）。

数据采集与转换工具

api/src/utils/scrape/ 目录提供了页面抓取后处理流水线，由 index.ts 统一导出 (api/src/utils/scrape/index.ts:1-5)：

flowchart LR
  A[原始 HTTP 响应] --> B{Content-Type}
  B -- HTML --> C[cleanHtml / readability]
  B -- application/json --> D["jsonToMarkdown<br/>(jsonToMarkdown.ts)"]
  B -- application/pdf --> E["pdfToHtml<br/>(mupdf 解析)"]
  C --> F[Markdown / 纯文本输出]
  D --> F
  E --> F

• jsonToMarkdown.ts 通过 isJsonContentType 正则匹配 +json 或 /json，并将原始 JSON 字符串包裹在 `` `json `` 代码块中返回 (api/src/utils/scrape/jsonToMarkdown.ts:1-10)。
• pdfToHtml.ts 使用 mupdf（mupdf@^1.27.0）打开 PDF 缓冲，按页遍历 toStructuredText 输出 HTML，并提取外部链接以及元数据（标题、创建日期、修改日期） (api/src/utils/scrape/pdfToHtml.ts:1-30, api/package.json:60-65)。
• 其他模块如 cleanHtml、readability（defuddle）、stripBase64Images 也都通过 index.ts 暴露，用于实现 README 中提到的「页面转 Markdown、Readability、截图、PDF」等 Browser Tools (README.md:60-65, api/src/utils/scrape/index.ts:1-5)。

部署与组件协作

README 在「Quick Deploy」一节中推荐使用 GitHub Container Registry 上的预构建 Docker 镜像同时部署 API 与 UI，并暴露 3000（API）与 9223（CDP）两个端口 (README.md:85-105)。REPL 在此基础上作为可选客户端，连接到 API 暴露的 WebSocket 端点即可复用同一个 Chrome 实例 (repl/README.md:5-15)。这种「单实例多入口」的部署方式减少了浏览器进程数量，但同时也意味着水平扩展时需要自行实现会话亲和性（社区 Issue #144 正是关于集群路由的讨论）。

See Also

• 入门与部署：参见 README.md
• 本地 REPL 使用：参见 repl/README.md
• 相关社区话题：Issue #302 指纹生成故障、Issue #295 指纹一致性失败、Issue #144 集群会话路由

1. 会话（Session）：浏览器生命周期的根对象

会话是 Steel 与 Chrome 实例交互的根抽象。每个 Session 对应一个隔离的 Puppeteer/Chromium 进程，并通过 CDP（Chrome DevTools Protocol）暴露 WebSocket 端点，供 Puppeteer、Playwright 或 Selenium 直接接入。

会话控制器由 api/src/modules/sessions/sessions.controller.ts 负责，路由定义在 sessions.routes.ts，数据契约由 Zod Schema 强制校验（见 sessions.schema.ts）。v0.5.3-beta 起新增 onSessionStart、onBeforeSessionEnd、onAfterSessionEnd 三个插件钩子，允许在生命周期的精确节点插入自定义逻辑（Release v0.5.3-beta）。

flowchart LR
    A[Client] -->|POST /v1/sessions| B(Sessions Controller)
    B --> C[CDP Service]
    C --> D[Browser Launcher]
    D --> E[Chrome Process]
    C --> F[Plugin Manager]
    F --> G[Fingerprint Plugin]
    F --> H[User Plugin]
    E -->|CDP WS :9223| I[Puppeteer/Playwright]

会话上下文（包括 Cookies、localStorage、sessionStorage、IndexedDB）通过 api/src/utils/context.ts 中的 extractStorageForPage 提取。该函数利用 CDP 的 Page.getFrameTree 与 DOMStorage 域，按 origin 与 hostname 聚合存储数据，形成 context/types.ts 中定义的 SessionData 结构，从而支持跨请求的状态保持（README 中所强调的「Session Management」特性）。

2. 操作（Actions）：高层页面交互 API

Actions 模块位于 api/src/modules/actions/，是对底层 CDP/Puppeteer 调用的高层封装，目标是让 Agent 用最少的请求完成抓取、截图、PDF 生成、搜索等任务。actions.controller.ts 与 actions.routes.ts 共同定义了以下常用端点（端点路径以 README 示例为准）：

后端使用 [email protected]（api/package.json），并通过 api/src/utils/scrape/readability.ts 调用 defuddle 库提取主要内容，使用 pdfToHtml.ts 解析 PDF 文本流（v0.5.1-beta 引入），使用 jsonToMarkdown.ts 处理 JSON 响应。导航逻辑则在 api/src/utils/casting.ts 的 navigatePage 中实现，支持 back、forward、refresh 与 URL 跳转四种语义。

3. 反检测（Anti-Detection）：指纹与隐身插件

反检测能力由 api/src/services/cdp/plugins/builtin/fingerprint.ts 提供，依赖 [email protected] 与 [email protected] 两个核心包（见 api/package.json）。插件由 plugin-manager.ts 在浏览器启动前统一调度，覆盖 User-Agent、Canvas、AudioContext、WebGL 等数十个指纹维度，并支持用户覆写（v0.4.3-beta 改进插件启动时机与指纹覆写支持）。

⚠️ 已知限制：社区已报告在 Chrome 146 + 固定 1920×1080 分辨率下，[email protected] 会抛出 Failed to generate a consistent fingerprint after 10 attempts（#295、#302），必须临时设置 SKIP_FINGERPRINT_INJECTION 才能启动容器。部署到生产前应关注此问题的修复进展。

4. 协作与扩展：插件钩子与 CDP

会话、操作、反检测三层并非孤立，而是通过 插件系统 与 CDP 服务 串联。onBrowserReady 自 v0.5.0-beta 起支持 Promise 返回（#226），v0.5.2-beta 引入 disconnect handler override（#233），使自定义反检测逻辑可在浏览器就绪但尚未连接时介入。对于需要连接 Selenium 的场景，api/src/modules/selenium/selenium.routes.ts 通过代理转发复用同一份 Session，从而避免重复实现反检测栈。

社区中关于集群与 session affinity 的讨论（#144）提示：在水平扩展时需保证路由层能将同一 Session 的请求始终转发至持有该 Chrome 进程的工作节点，否则 CDP 端点会失效。

See Also

• API 模块总览：会话、Actions、Selenium
• CDP 服务与插件机制
• 上下文持久化与反指纹策略

部署路径与产物形态

Steel 将运行时拆分为两个并列的 npm 工作区：API 服务（@steel-browser/api）与 调试 UI（@steel-browser/ui）。api/package.json 列出了运行 API 所需的全部依赖，包括 [email protected]、[email protected]、[email protected]、proxy-chain、mupdf 与 duckdb-async 等，外部必须显式提供 Fastify 5.x 作为 peer 依赖；ui/package.json 则声明 Vite + SWC 的前端构建链以及 @scalar/fastify-api-reference、rrweb-player 等客户端资源。

官方 README 推荐三种部署方式：

本地 Docker 启动命令示例（资料来源：README.md）：

docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser

启动后可通过 http://0.0.0.0:3000/documentation 查看由 @scalar/fastify-api-reference 渲染的 OpenAPI 文档。

插件与扩展开发

Steel 的可扩展面主要由三类入口组成：会话生命周期钩子、REPL 工作区以及内置 recorder 扩展。

会话生命周期钩子：根据 v0.5.3-beta 的发布说明（Release v0.5.3-beta），新增了 onSessionStart、onBeforeSessionEnd、onAfterSessionEnd 三个插件钩子，用于在会话建立前后插入自定义逻辑。api/src/utils/schema.ts 暴露了基于 Zod 的 JSON Schema 构建工具，开发者可以借此为自定义配置项生成 OpenAPI 描述，从而让外部 API 客户端获得类型提示。

REPL 工作区：repl/package.json 声明仅依赖 puppeteer-core@^24.2.0 与 tsx，并要求 Node ≥ 22，便于直接连接远端 CDP 调试现有会话。repl/README.md 给出的标准流程是：先确保 Steel Browser 已在本地或远端运行，再执行 npm start 让 src/script.ts 通过 WebSocket 连接到 CDP 端点（默认 ws://localhost:9223），随后即可像普通 Puppeteer 脚本一样驱动浏览器。

内置扩展目录：api/extensions/recorder/package.json 是一个独立的 webpack 构建单元，依赖 rrweb@^2.0.0-alpha.4 与 @rrweb/packer@^2.0.0-alpha.4，用于将会话录制为 rrweb 事件流。开发者可以仿照该目录结构创建新扩展，并在主 API 中按需装载。

flowchart LR
  Client[客户端脚本] -->|REST| API[Steel API]
  API -->|CDP| Chrome[Chromium 实例]
  API -->|加载| Recorder[recorder 扩展]
  API -->|触发| Hooks[onSessionStart 等钩子]
  Hooks --> Plugin[自定义插件]
  Plugin --> API

抓取与请求工具集

API 在 api/src/utils/scrape/index.ts 中统一对外暴露四类工具：cleanHtml、getDefuddleContent、isJsonContentType/jsonToMarkdown 与 stripBase64Images。其中 getDefuddleContent（api/src/utils/scrape/readability.ts）使用 Defuddle 提取正文，并在字数低于阈值（MIN_EXTRACTED_WORDS = 50）时切换到宽松选择器回退；jsonToMarkdown（api/src/utils/scrape/jsonToMarkdown.ts）则把 application/json 响应包入三反引号代码块，方便 LLM 直接消费。

请求侧，api/src/utils/requests.ts 提供 isHostBlocked、compileUrlPatterns 与 isUrlMatchingPatterns 三个纯函数，用于在会话配置中实现 host 白/黑名单与 URL 通配符过滤——这通常与代理链结合使用，避免对外暴露的内网地址被访问。

常见故障与排查

社区中反馈最频繁的三类问题及其应对方式如下：

1. 指纹生成失败。issue #295 与 #302 都报告了 [email protected] 在 Chrome 146、固定分辨率 1920x1080 组合下抛出 Failed to generate a consistent fingerprint after 10 attempts，导致浏览器启动失败、容器变为 unhealthy。临时缓解是设置环境变量 SKIP_FINGERPRINT_INJECTION=true，等待上游 fingerprint-generator 修复后再恢复（资料来源：Issue #295、Issue #302）。

1. npm run dev 报 File is not defined。issue #230 显示 undici 在某些 Node 版本下会因缺少全局 File 而报错。仓库对 cross-spawn 与 tar-fs 已写入 overrides（见 api/package.json），遇到类似兼容性错误时，建议显式安装 Node ≥ 22 并清理 node_modules 后重新安装。

1. 集群与请求路由。issue #144 询问如何实现会话亲和（session affinity），即把同一会话的请求始终路由到持有该 Chrome 实例的节点。仓库目前未提供开箱即用的集群实现，需要在外部负载均衡层基于 sessionId 做一致性哈希，或将单实例横向扩展为独立租户。

1. 文档缺口。issue #123 指出部分高级特性（自定义插件钩子、代理链配置、optimizeBandwidth 标志等）缺乏细节说明；建议结合本仓库 docs/ 目录（若存在）、官方 docs.steel.dev 以及源码注释交叉验证。

1. 安全披露。issue #311 记录了与 VulnCheck 协同披露的 CVE 流程。若在自托管实例中发现异常行为，建议通过 GitHub Security Advisories 渠道提交，而非公开讨论。

排错时的最小检查清单：确认镜像版本与 fingerprint-generator 版本组合、确认 CDP 端口 9223 在防火墙中开放、确认 optimizeBandwidth 与 SKIP_FINGERPRINT_INJECTION 等开关符合预期，并通过 /documentation 页面验证 API 协议是否一致。

See Also

• 官方 API 文档：https://docs.steel.dev/api-reference
• 协调披露流程：https://github.com/steel-dev/steel-browser/issues/311
• 集群与会话亲和讨论：https://github.com/steel-dev/steel-browser/issues/144
• v0.5.3-beta 发布说明：https://github.com/steel-dev/steel-browser/releases/tag/v0.5.3-beta

Pitfall Log / 踩坑日志

项目：steel-dev/steel-browser

摘要：发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] Fingerprint generation fails for Chrome 146 at fixed 1920x1080, forcing SKIP_FINGERPRINT_INJECTION。

1. 安装坑 · 来源证据：[BUG] Fingerprint generation fails for Chrome 146 at fixed 1920x1080, forcing SKIP_FINGERPRINT_INJECTION

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Fingerprint generation fails for Chrome 146 at fixed 1920x1080, forcing SKIP_FINGERPRINT_INJECTION
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/302 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：[BUG] Self-hosted steel-browser-api fails with "Failed to generate a consistent fingerprint after 10 attempts"

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Self-hosted steel-browser-api fails with "Failed to generate a consistent fingerprint after 10 attempts"
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/295 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：[QUESTION] how to fix this bug ,npm run dev

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[QUESTION] how to fix this bug ,npm run dev
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/230 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser
• 证据：identity.distribution | https://github.com/steel-dev/steel-browser | docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser

5. 能力坑 · 能力判断依赖假设

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

6. 维护坑 · 维护活跃度未知

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

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

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

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

9. 安全/权限坑 · 来源证据：Coordinated Vulnerability Disclosure - steel-browser

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Coordinated Vulnerability Disclosure - steel-browser
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/311 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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