ziniao-webdriver-doc

ziniao-webdriver-doc（紫鳥 WebDriver ドキュメント）

使用する場合／しない場合

状況	対応
紫鳥 WebDriver とは何か、何ができるかを知りたい	この Skill を読む
自動化統合／フレームワーク選定に関する設計判断を行いたい	この Skill を読む
特定のインターフェースのリクエスト／レスポンス形式を調べたい	この Skill の §必要に応じて詳しく調べる から参照先を確認し、対応する reference/ ファイルを読む
各言語／フレームワークのサンプルコードを確認したい	この Skill は読まず → reference/framework-examples.md を直接読む

---

レベル 0：位置づけと境界

概要

紫鳥ブラウザー WebDriver は、紫鳥ブラウザーが提供するローカル自動化制御インターフェースです。コマンドライン引数で紫鳥ブラウザーを起動して WebDriver モードにすると、ブラウザーがローカルで HTTP サービスを開始します。開発者は JSON API を介して店舗ウィンドウを管理し、Selenium／Puppeteer／Playwright／DrissionPage などのフレームワークをデバッグポートに接続して、店舗ブラウザーを自動制御できます。

機能の概要

機能領域	説明
クライアントの起動制御	コマンドライン引数で紫鳥ブラウザーを起動／終了し、WebDriver モードにする
認証とログイン	API でデバイスの認証、アカウントへのログイン、店舗リストの取得を行う
店舗ウィンドウ管理	指定した店舗ウィンドウを起動／終了し、デバッグポート（debuggingPort）を取得する
自動化フレームワークとの接続	デバッグポートを返し、Selenium／Puppeteer／Playwright／DrissionPage の接続に使用する
カーネル管理	ブラウザカーネルの検出／ダウンロード／更新
キャッシュとセッション	ローカル／オンラインキャッシュの削除、Cookie ポリシーの管理
プラグイン管理	店舗の起動時に指定したプラグインを読み込み、プラグインのインストール状態を確認する

対応しないこと（境界）

• 汎用ブラウザー自動化ソリューションではありません。紫鳥ブラウザーのクライアントでのみ使用できます
• WebDriver ドライバー自体は提供しません。返された core_version に一致するバージョンの ChromeDriver を自分でダウンロードする必要があります
• EC プラットフォームのビジネスロジックは処理しません。ブラウザーウィンドウの制御機能のみを提供します
• クラウドへのデプロイには対応しません。ローカルでのみ実行できます（--listen_ip でリモート制御を許可できます）

---

レベル 1：アーキテクチャとフロー

主な概念

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）を使用する必要があります。一致しない場合、自動化に失敗します。

フロー全体

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>退出客户端]

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 でクライアントを終了します

機能の要約表

インターフェース 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[]	いいえ

重要な落とし穴

以下は実運用で頻繁に発生する落とし穴です。自動化スクリプトを作成する際は、必ず厳守してください。

落とし穴 1：認証情報の一貫性

「認証情報が必要」とされるすべてのインターフェース（updateCore、getBrowserList、startBrowser、stopBrowser、ClearOnline）には、呼び出すたびに company/username/password をすべて渡す必要があります。「ログイン系」のインターフェースだけではありません。特に updateCore は抜けやすいので注意してください。カーネルの検出だけに見えますが、紫鳥のサーバー側では、認証情報で本人確認をしてからカーネルの状態を返します。

落とし穴 2：エラー情報の処理

API がエラーを返した場合は、statusCode の数字だけに頼らず、まず err フィールドの内容を確認して問題を特定してください。err フィールドには具体的な中国語のエラー説明が含まれており、トラブルシューティングに最も役立つ情報です。

エンコードに関する注意：レスポンス本文が UTF-8 として正しくデコードされていないと、err 内の中国語が文字化けし、根本原因を特定できないことがあります。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 をダウンロードする必要があります。

推奨する手順：

1. 初回に core_version を取得した後、ローカルのキャッシュディレクトリに該当するメジャーバージョンの ChromeDriver があるか確認します
2. なければ、https://googlechromelabs.github.io/chrome-for-testing/ から対応するバージョンをダウンロードします
3. ローカルディレクトリ（例：./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