ziniao-webdriver-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ziniao-webdriver-doc（紫鸟 WebDriver 文档）

ziniao-webdriver-doc (Ziniao WebDriver Documentation)

何时使用 / 不使用

When to Use / Not to Use

场景	做法
需要理解紫鸟 WebDriver 是什么、能做什么	读本 Skill
需要做自动化集成/框架选型的设计决策	读本 Skill
需要查阅某个接口的请求/响应格式	读本 Skill 的 §按需深入获取路径，再读对应 reference/ 文件
需要查看各语言/框架示例代码	不读本 Skill → 直接读 `reference/framework-examples.md`

Scenario	Action
Need to understand what Ziniao WebDriver is and what it can do	Read this Skill
Need to make design decisions for automation integration/framework selection	Read this Skill
Need to check the request/response format of a specific interface	Follow the access path in §Deep Dive on Demand of this Skill, then read the corresponding reference/ file
Need to view sample code for various languages/frameworks	Do not read this Skill → Directly read `reference/framework-examples.md`

Level 0：定位与边界

Level 0: Positioning and Boundaries

是什么

What It Is

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

Ziniao Browser WebDriver is a local automation control interface provided by Ziniao Browser. After launching Ziniao Browser in WebDriver mode via command-line parameters, the browser starts an HTTP service locally. Developers can manage store windows through JSON APIs, and use frameworks like Selenium / Puppeteer / Playwright / DrissionPage to connect to the debugging port, achieving automated control of the store browser.

能力概览

Capability Overview

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

Capability Domain	Description
Client Launch Control	Launch/exit Ziniao Browser into WebDriver mode via command-line parameters
Authentication and Login	Complete device authorization, account login, and obtain store list via API
Store Window Management	Launch/close specified store windows, obtain debugging port (debuggingPort)
Automation Framework Integration	Return debugging port for connection with Selenium/Puppeteer/Playwright/DrissionPage
Kernel Management	Detect/download/update browser kernel
Cache and Session	Clear local/online cache, manage Cookie policies
Plugin Management	Load specified plugins when launching stores, query plugin installation status

不做什么（边界）

What It Doesn't Do (Boundaries)

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

It is not a general-purpose browser automation solution—only applicable to Ziniao Browser client
It does not provide the WebDriver driver itself—you need to download the matching version of ChromeDriver according to the returned
```
core_version
```
It does not handle e-commerce platform business logic—only provides browser window control capabilities
It does not provide cloud deployment—only supports local operation (remote control can be enabled via
```
--listen_ip
```
)

Level 1：架构与流程

Level 1: Architecture and Process

核心概念

Core Concepts

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）连接，否则自动化将失败。

WebDriver Mode: Launch Ziniao Browser with the

--run_type=web_driver

parameter to enter automation control mode. In this mode, the browser starts an HTTP service on a specified local port and accepts JSON-formatted API calls. The Ziniao main process must be closed before launching.

HTTP IPC Communication: All APIs are POST requests in JSON format with UTF-8 encoding. The communication port is specified via the

--port

parameter, and the address is

http://127.0.0.1:{port}

. Each request must carry an

action

field to identify the operation type and a

requestId

as a globally unique identifier. It is recommended to set the timeout to over 120 seconds.

Store Window (browserOauth / browserId): Ziniao uses "store" as the smallest management unit. Call

getBrowserList

to obtain the store list and encrypted ID (

browserOauth

), then launch the specified store window via

startBrowser

, which returns

debuggingPort

for automation framework connection. If opening a store directly using the return value of

getBrowserList

, only pass

browserOauth

; assign

browserId

only when you need to open it with a plaintext store ID.

Kernel Version Matching:

startBrowser

returns

core_type

(e.g., Chromium) and

core_version

(e.g., 119.1.0.16). Developers must use a ChromeDriver with the corresponding major version number (e.g., 119.x) for connection, otherwise automation will fail.

流程全景

Overall Process

mermaid

graph LR
  A[申请权限] --> B["启动客户端<br>(先清理残留进程)"]
  B --> C["updateCore<br>检测内核<br>⚠ 需凭据"]
  C --> D["getBrowserList<br>获取店铺列表<br>⚠ 需凭据"]
  D --> E["startBrowser<br>启动店铺窗口<br>⚠ 需凭据"]
  E --> F["下载匹配的<br>ChromeDriver"]
  F --> G["连接自动化框架<br>Selenium等"]
  G --> H[执行自动化操作]
  H --> I["stopBrowser<br>关闭店铺<br>⚠ 需凭据"]
  I --> J[exit<br>退出客户端]

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

mermaid

graph LR
  A[Apply for Permissions] --> B["Launch Client<br>(Clean residual processes first)"]
  B --> C["updateCore<br>Check Kernel<br>⚠ Credentials Required"]
  C --> D["getBrowserList<br>Obtain Store List<br>⚠ Credentials Required"]
  D --> E["startBrowser<br>Launch Store Window<br>⚠ Credentials Required"]
  E --> F["Download Matching<br>ChromeDriver"]
  F --> G["Connect to Automation Framework<br>Selenium, etc."]
  G --> H[Execute Automation Operations]
  H --> I["stopBrowser<br>Close Store<br>⚠ Credentials Required"]
  I --> J[exit<br>Exit Client]

Apply for Permissions: Enable WebDriver permissions on the Ziniao Open Platform
Launch Client: Clean residual processes first (see §Key Pitfalls), then launch Ziniao Browser via command line with required parameters:
```
--run_type=web_driver --ipc_type=http --port={port}
```
updateCore: Must carry company/username/password, poll to check if the kernel is ready (statusCode==0), automatically download if missing
getBrowserList: Pass company/username/password to obtain the store list
startBrowser: Pass company/username/password + browserOauth, return debuggingPort and core_version
Download ChromeDriver: Download the matching ChromeDriver according to the major version number of
```
core_version
```
(not the system Chrome version)
Connect to Framework: Use
```
127.0.0.1:{debuggingPort}
```
+ matching version of ChromeDriver to connect to Selenium, etc.
Shutdown: Use
```
stopBrowser
```
(credentials required) to close the store window, use
```
exit
```
to exit the client

能力摘要表

Capability Summary Table

接口 Action	职责	关键输入	关键输出	需凭据
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[]	否

API Action	Responsibility	Key Input	Key Output	Credentials Required
updateCore	Detect/download kernel	company, username, password	statusCode, msg(progress)	Yes
applyAuth	Device authorization	company, username, password	statusCode	Yes
getBrowserList	Obtain store list	company, username, password	browserList[{browserOauth, browserName, siteId...}]	Yes
startBrowser	Launch store window	company, username, password, browserOauth/browserId	debuggingPort, core_version, core_type	Yes
stopBrowser	Close store window	company, username, password, browserOauth/browserId	statusCode	Yes
logout	Log out	None	statusCode	No
exit	Exit client process	None	statusCode	No
ClearCache	Clear local cache	browserOauths[]	statusCode	No
ClearOnline	Clear online cache	company, username, password, browserOauth, type(1/2/3)	statusCode	Yes
getPluginInstalled	Query plugin installation status	browserId, pluginIds	install_status	No
getRunningInfo	Obtain running stores	None	browsers[]	No

关键陷阱

Key Pitfalls

以下均为实战中高频踩坑点，务必在编写自动化脚本时严格遵守。

The following are high-frequency pitfalls in actual practice, please strictly abide by them when writing automation scripts.

陷阱 1：凭据一致性

Pitfall 1: Credential Consistency

所有标记"需凭据"的接口（

updateCore

、

getBrowserList

、

startBrowser

、

stopBrowser

、

ClearOnline

）每次调用都必须携带完整的 company/username/password，不只是"登录类"接口。

updateCore

尤其容易遗漏——它看似只是内核检测，但紫鸟服务端需要凭据验证身份后才返回内核状态。

All interfaces marked "Credentials Required" (

updateCore

getBrowserList

startBrowser

stopBrowser

ClearOnline

) must carry the complete company/username/password every time they are called, not just "login-type" interfaces.

updateCore

is particularly easy to miss—although it seems to only detect the kernel, the Ziniao server requires credential verification to return the kernel status.

陷阱 2：错误信息处理

Pitfall 2: Error Message Handling

API 返回错误时，优先读取
err
字段的内容来定位问题，而非仅依赖

statusCode

数字。

err

字段包含具体的中文错误描述，是最有价值的排障信息。

编码注意：

err

中的中文可能因响应体未正确按 UTF-8 解码而出现乱码，导致无法定位根因。务必确保 HTTP 客户端以 UTF-8 解码响应体（Python

requests

库需设置

response.encoding = 'utf-8'

，或使用

response.content.decode('utf-8')

）。

When the API returns an error, prioritize reading the content of the
err
field to locate the problem, rather than relying solely on the

statusCode

number. The

err

field contains specific Chinese error descriptions, which are the most valuable troubleshooting information.

Encoding Note: The Chinese in

err

may appear garbled if the response body is not decoded in UTF-8 correctly, making it impossible to locate the root cause. Ensure that the HTTP client decodes the response body in UTF-8 (for Python

requests

library, set

response.encoding = 'utf-8'

, or use

response.content.decode('utf-8')

陷阱 3：进程残留清理

Pitfall 3: Residual Process Cleanup

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

清理命令：

bash

undefined

After Ziniao fails to launch or exits abnormally, multiple child processes (main process + kernel process) may remain. Restarting without cleaning them up will cause port occupation and repeated failures. Before each launch and before retrying after a failure, ensure all Ziniao-related processes have been terminated.

Cleanup Commands:

bash

undefined

Windows (PowerShell)

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

macOS / Linux

pkill -f ziniao || true

undefined

pkill -f ziniao || true

undefined

陷阱 4：ChromeDriver 版本必须匹配紫鸟内核

Pitfall 4: ChromeDriver Version Must Match Ziniao Kernel

紫鸟浏览器的内核版本（

core_version

）与系统安装的 Chrome 浏览器版本无关。必须根据

startBrowser

返回的

core_version

提取大版本号（如

119.1.0.16

→

），下载对应版本的 ChromeDriver。

建议策略：

首次获取
```
core_version
```
后，检查本地缓存目录是否已有该大版本的 ChromeDriver
若无，从 https://googlechromelabs.github.io/chrome-for-testing/ 下载对应版本

缓存到本地目录（如

./chromedriver_cache/{major_version}/chromedriver

），后续复用

The kernel version of Ziniao Browser (

core_version

) has nothing to do with the Chrome browser version installed on the system. You must extract the major version number from

core_version

returned by

startBrowser

(e.g.,

119.1.0.16

→

) and download the corresponding ChromeDriver version.

Recommended Strategy:

After obtaining
```
core_version
```
for the first time, check if the ChromeDriver of this major version already exists in the local cache directory
If not, download the corresponding version from https://googlechromelabs.github.io/chrome-for-testing/
Cache it to a local directory (e.g.,
```
./chromedriver_cache/{major_version}/chromedriver
```
) for reuse in subsequent operations

环境约定

Environment Requirements

项目	要求
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 会被检测为自动化）

Item	Requirement
Windows	Ziniao V5 (5.X.X.X) or V6 (6.16.0.126+)
macOS	Ziniao V6 (6.15.0.44+)
Linux	Ziniao V6 (6.25.3.3+)
Communication Protocol	HTTP POST, JSON, UTF-8
Timeout Setting	≥ 120 seconds
Prerequisite for Launch	Ziniao main process must be completely closed
Recommended Framework	Selenium (Playwright/Puppeteer will be detected as automation)

按需深入（Level 2 路由表）

Deep Dive on Demand (Level 2 Routing Table)

规则：以下内容不要主动加载。 仅在你明确需要了解某个细节时，按路由表读取对应的 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`

Rule: Do not actively load the following content. Only read the corresponding reference/ file according to the routing table when you clearly need to understand a certain detail.

What You Need to Understand	File to Read
Core workflow interfaces (applyAuth/getBrowserList/startBrowser)	`reference/api-core.md`
Auxiliary management interfaces (stopBrowser/logout/exit/cache/plugin/updateCore)	`reference/api-auxiliary.md`
Detailed description of command-line parameters for launching the client	`reference/startup-params.md`
Sample code and download links for various languages/frameworks	`reference/framework-examples.md`
Permission activation, account configuration, and common troubleshooting	`reference/prerequisites.md`