SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ziniao-webdriver-doc

ziniao-webdriver-doc

智能体与模型

查看项目

更新于 10-16 01:56

技能介绍

用途

ziniao-webdriver-doc（紫鸟 WebDriver 文档）用于帮助理解紫鸟浏览器 WebDriver 自动化接口的定位、能力、架构或对接流程，适用于设计讨论、集成规划或工具评估。若需要执行具体自动化脚本编写，应直接参考 reference/ 中的接口与示例，而非阅读本技能。

定位与边界

紫鸟浏览器 WebDriver 是紫鸟浏览器提供的本地自动化控制接口。通过命令行参数启动紫鸟浏览器进入 WebDriver 模式后，浏览器在本地开启 HTTP 服务，开发者可通过 JSON API 管理店铺窗口，并使用 Selenium / Puppeteer / Playwright / DrissionPage 等框架对接调试端口，实现对店铺浏览器的自动化控制。

能力概览：

  • 客户端启动控制：命令行参数启动/退出紫鸟浏览器进入 WebDriver 模式
  • 认证与登录：通过 API 完成设备授权、账号登录、获取店铺列表
  • 店铺窗口管理：启动/关闭指定店铺窗口，获取调试端口（debuggingPort）
  • 自动化框架对接：返回调试端口供 Selenium/Puppeteer/Playwright/DrissionPage 连接
  • 内核管理：检测/下载/更新浏览器内核
  • 缓存与会话：清理本地/在线缓存、管理 Cookie 策略
  • 插件管理：启动店铺时加载指定插件、查询插件安装状态

边界：不是通用浏览器自动化方案，仅适用于紫鸟浏览器客户端；不提供 WebDriver 驱动本身，需根据返回的 core_version 自行下载匹配版本的 ChromeDriver；不处理电商平台业务逻辑，仅提供浏览器窗口控制能力；不提供云端部署，仅支持本地运行（通过 --listen_ip 可开放远程控制）。

架构与流程

核心概念：

  • WebDriver 模式：通过 --run_type=web_driver 参数启动紫鸟浏览器，使其进入自动化控制模式。此模式下浏览器在本地指定端口开启 HTTP 服务，接受 JSON 格式的 API 调用。启动前必须关闭紫鸟主进程。
  • HTTP IPC 通信：所有 API 均为 POST 请求，JSON 格式，UTF-8 编码。通过 --port 参数指定通信端口，地址为 http://127.0.0.1:{port}。每个请求需携带 action 字段标识操作类型、requestId 做全局唯一标识。超时建议 120 秒以上。
  • 店铺窗口（browserOauth / browserId）：紫鸟以“店铺”为最小管理单位。调用 getBrowserList 获取店铺列表及加密 ID（browserOauth），然后通过 startBrowser 启动指定店铺窗口，返回 debuggingPort 用于自动化框架连接。若直接使用 getBrowserList 返回值打开店铺，只需传 browserOauth；仅当需要以明文店铺 ID 打开时才赋值 browserId。
  • 内核版本匹配：startBrowser 返回 core_type（如 Chromium）和 core_version（如 119.1.0.16），开发者必须使用对应大版本号的 ChromeDriver（如 119.x）连接，否则自动化将失败。

流程全景：

  1. 申请权限：在紫鸟开放平台开通 WebDriver 权限
  2. 启动客户端：先清理残留进程，再命令行启动紫鸟浏览器，必须参数：--run_type=web_driver --ipc_type=http --port={端口}
  3. updateCore：必须携带 company/username/password，轮询检测内核是否就绪（statusCode==0），缺失时自动下载
  4. getBrowserList：传入 company/username/password，获取店铺列表
  5. startBrowser：传入 company/username/password + browserOauth，返回 debuggingPort 和 core_version
  6. 下载 ChromeDriver：根据 core_version 大版本号下载匹配的 ChromeDriver（不是系统 Chrome 版本）
  7. 连接框架：用 127.0.0.1:{debuggingPort} + 匹配版本的 ChromeDriver 连接 Selenium 等
  8. 关闭：stopBrowser（需凭据）关闭店铺窗口，exit 退出客户端

能力摘要表：

  • updateCore：检测/下载内核，输入 company, username, password，输出 statusCode, msg(进度)，需凭据
  • applyAuth：设备授权，输入 company, username, password，输出 statusCode，需凭据
  • getBrowserList：获取店铺列表，输入 company, username, password，输出 browserList[{browserOauth, browserName, siteId...}]，需凭据
  • startBrowser：启动店铺窗口，输入 company, username, password, browserOauth/browserId，输出 debuggingPort, core_version, core_type，需凭据
  • stopBrowser：关闭店铺窗口，输入 company, username, password, browserOauth/browserId，输出 statusCode，需凭据
  • logout：退出登录，无输入，输出 statusCode，不需凭据
  • exit：退出客户端进程，无输入，输出 statusCode，不需凭据
  • ClearCache：清理本地缓存，输入 browserOauths[]，输出 statusCode，不需凭据
  • ClearOnline：清理在线缓存，输入 company, username, password, browserOauth, type(1/2/3)，输出 statusCode，需凭据
  • getPluginInstalled：查询插件安装状态，输入 browserId, pluginIds，输出 install_status，不需凭据
  • getRunningInfo：获取已开启的店铺，无输入，输出 browsers[]，不需凭据

关键陷阱

陷阱 1：凭据一致性。所有标记“需凭据”的接口（updateCore、getBrowserList、startBrowser、stopBrowser、ClearOnline）每次调用都必须携带完整的 company/username/password，不只是“登录类”接口。updateCore 尤其容易遗漏——它看似只是内核检测，但紫鸟服务端需要凭据验证身份后才返回内核状态。

陷阱 2：错误信息处理。API 返回错误时，优先读取 err 字段的内容来定位问题，而非仅依赖 statusCode 数字。err 字段包含具体的中文错误描述，是最有价值的排障信息。编码注意：err 中的中文可能因响应体未正确按 UTF-8 解码而出现乱码，导致无法定位根因。务必确保 HTTP 客户端以 UTF-8 解码响应体（Python requests 库需设置 response.encoding = 'utf-8'，或使用 response.content.decode('utf-8')）。

陷阱 3：进程残留清理。紫鸟启动失败或异常退出后，可能残留多个子进程（主进程 + 内核进程），如果不清理就重启会导致端口占用、反复失败。每次启动前和失败后重试前，必须确保所有紫鸟相关进程已终止。

清理命令：

Windows (PowerShell)

Get-Process | Where-Object { $_.ProcessName -match 'ziniao|ZiNiao' } | Stop-Process -Force

macOS / Linux

pkill -f ziniao || true

陷阱 4：ChromeDriver 版本必须匹配紫鸟内核。紫鸟浏览器的内核版本（core_version）与系统安装的 Chrome 浏览器版本无关。必须根据 startBrowser 返回的 core_version 提取大版本号（如 119.1.0.16 → 119），下载对应版本的 ChromeDriver。

建议策略：

  • 首次获取 core_version 后，检查本地缓存目录是否已有该大版本的 ChromeDriver
  • 若无，从 https://googlechromelabs.github.io/chrome-for-testing/ 下载对应版本
  • 缓存到本地目录（如 ./chromedriver_cache/{major_version}/chromedriver），后续复用

环境约定

  • Windows：紫鸟 V5 (5.X.X.X) 或 V6 (6.16.0.126+)
  • macOS：紫鸟 V6 (6.15.0.44+)
  • Linux：紫鸟 V6 (6.25.3.3+)
  • 通信协议：HTTP POST, JSON, UTF-8
  • 超时设置：≥ 120 秒
  • 启动前提：紫鸟主进程必须已完全关闭
  • 推荐框架：Selenium（Playwright/Puppeteer 会被检测为自动化）

按需深入（Level 2 路由表）

以下内容不要主动加载。仅在明确需要了解某个细节时，按路由表读取对应的 reference/ 文件。

  • 核心工作流接口（applyAuth/getBrowserList/startBrowser）：reference/api-core.md
  • 辅助管理接口（stopBrowser/logout/exit/缓存/插件/updateCore）：reference/api-auxiliary.md
  • 启动客户端的命令行参数详细说明：reference/startup-params.md
  • 各语言/框架的示例代码与下载链接：reference/framework-examples.md
  • 权限开通、账号配置、常见问题排查：reference/prerequisites.md