用途 Catalyst SmartBrowz 是一套浏览器自动化与文档生成服务，面向需要在云端执行浏览器任务和批量生成文档的场景。它把六类能力集中在一个统一平台中，用户可按需选用其中一种或多种组件组合完成工作流。
主要能力 服务包含六个相互独立的组件：
Headless：连接 Catalyst 云中的远程 Chrome/Firefox，配合自动化库使用。端点由控制台自动生成，连接代码中不需要 api-key。 Browser Logic：以 Java/Node.js 编写的无服务器函数，用于承载浏览器自动化逻辑。 PDF & Screenshot：以编程方式生成可视化文档，输入格式支持 HTML、URL 和模板。 Templates：用于设计并存储模板，以便填充动态内容。 Browser Grid（早期访问）：提供并行无头浏览器，支持按需自动扩缩容。可配置节点与浏览器数量，通过 CDP 或 Webdriver 端点连接并并行处理请求。 Dataverse：提供数据抓取 API。
使用方式 使用前需在控制台为项目激活一次 SmartBrowz：进入 Console，选择你的项目，在左侧边栏选择 SmartBrowz，点击 "Start Exploring"。若跳过该步骤，将无法访问 Headless、Browser Logic、PDF & Screenshot、Templates、Browser Grid 和 Dataverse 组件。
对于 Browser Logic 函数，需要安装 Catalyst CLI，并通过 CLI 初始化与部署函数。此类函数无法直接在控制台创建，但可以上传。
不同组件对应不同工作流：Headless 模式使用控制台提供的端点与代码片段，配合 Puppeteer、Playwright 或 Selenium 连接；Browser Logic 通过 CLI 初始化、在 IDE 中编码，再部署到控制台，适合持续性浏览器自动化任务；PDF & Screenshot 可使用控制台 Playground、SDK（Java/Node.js/Python）或 API 生成文档；Browser Grid 配置节点与浏览器数量后，通过 CDP/Webdriver 端点连接并并行处理请求。
编写实现代码时应优先使用 SDK 方法而非原始 REST API： Node.js：app.smartbrowz()（小写，app.SmartBrowz() 不是函数）→ smartbrowz.convertToPdf()、smartbrowz.generateFromTemplate()、app.smartbrowz().browserGrid() → grid.getGrid()、grid.stopGrid() Python：app.smart_browz() → smart_browz.convert_to_pdf()、smart_browz.generate_from_template()、app.smart_browz().browser_grid() → grid.get_all_grid() Java：ZCSmartBrowz.getInstance() → smartBrowz.convertToPdf()、smartBrowz.generateFromTemplate() 仅当不存在对应 SDK 方法时才使用 REST API，例如查询 Browser Grid 实时统计中的 free_sessions。
关键概念 远程浏览器运行在 Catalyst 云中，而非本地；端点由控制台自动生成。 Puppeteer/Playwright/Selenium 连接代码中不含 api-key，仅使用端点 URL 连接；api-key 只用于 Browser Grid 的 REST API 调用（如实时统计）。 当前仅支持 Chrome 浏览器；Firefox 支持位于 Browser Grid（早期访问）。 Browser Logic 函数属于无服务器函数类型，通过 CLI 创建，而非控制台 UI。 Browser Grid 具备自动扩缩容能力，节点与浏览器按配置按需启动。 控制台提供 Code Recipes 可用于测试自动化库用例。
安全注意事项 任何浏览器自动化或网页抓取均由用户自行承担风险，仅应在允许此类行为的域名上或获得适当批准后使用。
安全检查清单： API Key 保护：Headless 与 Browser Grid 的端点由自动生成的 API Key 保护。若密钥泄露应重新生成（注意：这会重置网格统计）。 Browser Logic 日志：所有函数活动记录于 Console → DevOps → Logs，可查看日志用于调试与安全审计。 Browser Grid 队列限制：Selenium 请求排队 30 秒，Puppeteer/Playwright 排队 5 分钟，超时后请求被终止。 Browser Grid 告警：在 Dashboard 中监控告警，包括 Browser Creation Rejected、90% Disk Exhausted、80% Memory/CPU Exhausted、Nodes Crashed。 默认存储：Browser Grid 节点磁盘限制为 10GB，需监控磁盘使用以避免失败。 速率考虑：浏览器自动化可能产生较高网络流量，需注意目标网站的速率限制与服务条款。
适用场景 包括 SmartBrowz、无头浏览器、远程浏览器、Puppeteer、Playwright、Selenium、浏览器自动化、Browser Logic、PDF 生成、网页截图、HTML 转 PDF、URL 转 PDF、模板 PDF、模板生成、Browser Grid、并行浏览器、网页抓取、Dataverse、CDP 端点、Webdriver 端点、无头 Chrome、无头 Firefox、浏览器测试、自动化库等。
参考资料 references/smartbrowz-basics.md 适用于：Headless 设置（Puppeteer/Playwright/Selenium 代码片段）、Browser Logic（CLI 命令、函数结构、部署）、PDF & Screenshot（控制台 Playground、Java/Node.js/Python 的 SDK 用法、API 调用、HTML/URL/模板输入格式）、Templates（设计、存储、动态内容）、Browser Grid（Basic/Light/Moderate/Heavy 配置、节点与浏览器设置、CDP/Webdriver 端点、工作流、告警、Active/Inactive/Idle 状态、仪表盘、理想实践）、Dataverse（数据抓取 API）以及故障排查。
限制 远程浏览器运行于 Catalyst 云而非本地；当前仅支持 Chrome，Firefox 支持处于 Browser Grid 早期访问阶段；Browser Grid 请求存在排队超时限制；节点磁盘默认 10GB；Browser Logic 函数无法在控制台直接创建。