atomk-hermes-skills/skills/cross-border-ecommerce/ziniao-bridge/SKILL.md

---
name: ziniao-bridge
description: "紫鸟浏览器 AI 自动化 — 通过 Desktop 桥接紫鸟 WebDriver，自然语言驱动店铺运营：打开店铺、导航后台、拉取订单、下载报表、巡检评论、截图存档。"
version: 1.2.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [ziniao, 紫鸟, webdriver, browser-automation, cross-border, store-operations, bridge-cdp]
    related_skills:
      - bridge-cdp-agent
      - drissionpage-toolkit
      - competitor-price-monitor
      - 1688-cross-border-sourcing
      - ozon-operations
    target_platforms: [amazon, ebay, shopee, shopify, lazada, ozon, temu-seller]
    cron_compatible: true
---

# 紫鸟桥接 (Ziniao Bridge)

通过 AtomK Desktop + Bridge CDP 连接紫鸟浏览器 WebDriver，用自然语言操控店铺后台。

**触发词：** "紫鸟" / "ziniao" / "店铺" / "后台" / "订单截图" / "下载报表" / "巡检评论"

---

## 架构总览

```
钉钉自然语言指令
    ↓
Hermes Agent (解析意图)
    ↓
AtomK Bridge (CDP relay, 9228/9229)
    ↓
AtomK Desktop (Electron, 与紫鸟同机)
    ↓
Playwright → 紫鸟 WebDriver 端口 (127.0.0.1:{port})
    ↓
紫鸟浏览器内核 (Chromium) → 店铺后台页面
```

**前提条件：**
- 紫鸟浏览器与 AtomK Desktop 在同一台 Windows/Mac 机器
- 紫鸟开放平台已为自动化账号开通 WebDriver 权限
- 紫鸟以 WebDriver 模式启动（`--run_type=web_driver --ipc_type=http`）
- **API 凭证输入**：Desktop Chrome Bridge 页面 → 「紫鸟 & Hubstudio API」→ 输入 API Key + Base URL → 保存（safeStorage 加密存储到 `~/.atomk/ziniao.json`）

---

## 紫鸟 WebDriver API（核心）

紫鸟提供本地 HTTP API 管理店铺浏览器生命周期。Desktop 直接调这些接口。

### 基础 URL

```
http://127.0.0.1:{紫鸟服务端口}
```

默认端口由紫鸟启动参数 `--port` 指定（通常 19481 或自定义）。

### 核心接口

#### 1. 获取店铺列表

```
GET /api/store/list
```

返回：
```json
{
  "code": 0,
  "data": [
    {
      "storeId": "xxx",
      "storeName": "店铺A-亚马逊美国站",
      "platform": "amazon",
      "status": "idle"
    }
  ]
}
```

#### 2. 启动店铺浏览器

```
POST /api/browser/start
Content-Type: application/json

{
  "storeId": "xxx",
  "runType": "web_driver"
}
```

返回：
```json
{
  "code": 0,
  "data": {
    "debuggingPort": 9222,
    "coreVersion": "120.0.6099.109",
    "wsEndpoint": "ws://127.0.0.1:9222/devtools/browser/xxx"
  }
}
```

> **关键：** `debuggingPort` 就是 Playwright/Selenium 的连接端口。

#### 3. 关闭店铺浏览器

```
POST /api/browser/stop
Content-Type: application/json

{
  "storeId": "xxx"
}
```

#### 4. 获取店铺浏览器状态

```
GET /api/browser/status?storeId=xxx
```

---

## Playwright 连接紫鸟浏览器

拿到 `debuggingPort` 后，Desktop 内用 Playwright 直连：

```javascript
const { chromium } = require('playwright');

// 连接紫鸟 WebDriver 端口
const browser = await chromium.connectOverCDP(
  `http://127.0.0.1:${debuggingPort}`
);

// 获取已有页面或创建新页面
const pages = browser.contexts()[0].pages();
const page = pages[0] || await browser.contexts()[0].newPage();

// 导航到店铺后台
await page.goto('https://sellercentral.amazon.com/orders-v3');
```

> **注意：** `coreVersion` 必须与 Playwright 的 Chromium 大版本匹配，否则 `connectOverCDP` 会失败。

---

## 典型操作场景

### 场景 1：打开店铺 + 截图订单

**自然语言：** 「打开店铺A，去亚马逊后台看最近订单，截图发我」

**执行链：**
1. `GET /api/store/list` → 找到「店铺A」
2. `POST /api/browser/start` → 启动浏览器 → 拿到 `debuggingPort`
3. Playwright `connectOverCDP(port)` → 连接
4. `page.goto('https://sellercentral.amazon.com/orders-v3')`
5. `page.screenshot()` → 截图
6. Bridge → Hermes → 钉钉 → 图片回传

### 场景 2：下载业务报表

**自然语言：** 「下载店铺B最近7天的销售报表和广告报表」

**执行链：**
1. 获取店铺 → 启动浏览器 → 连接
2. 导航到 Reports 页面
3. 设置日期范围（最近7天）
4. 点击「下载 CSV」
5. 监听下载事件 → 获取文件
6. 回传文件到钉钉

### 场景 3：巡检评论

**自然语言：** 「巡检所有店铺今天的差评，有新的标红提醒我」

**执行链：**
1. 遍历店铺列表
2. 逐个打开 → 导航到评论页
3. 筛选 1-2 星评论
4. 提取评论文本 + 日期
5. AI 分析差评内容
6. 汇总报告 → 标红新差评 → 钉钉推送

### 场景 4：多店铺批量截图

**自然语言：** 「把所有店铺的首页截个图存档」

**执行链：**
1. 获取所有店铺列表
2. 串行处理（避免资源冲突）：
   - 启动 → 截图 → 关闭 → 下一个
3. 所有截图打包 → 回传

### 场景 5：定时自动巡检（Cron）

**自然语言：** 「每天早上9点自动巡检所有店铺订单和差评」

**执行链：**
```
cronjob create --name "每日店铺巡检" \
  --schedule "0 9 * * *" \
  --prompt "加载 ziniao-bridge skill，巡检所有紫鸟店铺：拉取昨日订单数、检查新增差评、截图汇总" \
  --deliver "dingtalk"
```

---

## 店铺后台 URL 速查表

| 平台 | 订单页 | 报表页 | 评论页 |
|------|--------|--------|--------|
| Amazon Seller Central | `/orders-v3` | `/reporting` | `/customer-reviews/ref=xxx` |
| Amazon 日本站 | `/orders-v3` | `/reporting` | 同上 |
| eBay | `https://www.ebay.com/sh/ord` | `https://www.ebay.com/sh/prf` | — |
| Shopee | `https://seller.shopee.sg/portal/sale/order` | — | `https://seller.shopee.sg/portal/sale/comment` |
| Lazada | `https://sellercenter.lazada.sg/order/` | — | — |
| Shopify | `/admin/orders` | `/admin/analytics` | — |
| Ozon Seller | `/app/orders` | — | — |
| Temu Seller | `https://seller.kuajingbao.com/order` | — | — |

---

## 架构：relay vs 本地 Playwright 速度对比

紫鸟的 Playwright 封装在本机，不走网络 relay，速度差异显著：

| 操作 | Bridge CDP relay（跨网） | 本地 Playwright（同机） | 倍差 |
|------|------------------------|------------------------|------|
| 单次 CDP 往返 | 10-100ms | <1ms | **10-100x** |
| 页面导航+截图 | 2-5 秒 | 0.5-1.5 秒 | **2-5x** |
| 大图截图回传 | 0.5-2 秒（Base64跨网） | ~100ms（内存直读） | **5-20x** |
| 多步复合操作 | 5-15 秒 | 1-3 秒 | **3-5x** |

Desktop 同时担任两个角色：
- **被控端**：Bridge relay → CDP → 内置 Chromium（爬虫/反爬场景）
- **控制端**：本地 Playwright → 紫鸟 WebDriver（店铺运营场景）

同进程内切换通道，零额外开销。

---

## 错误处理规范

| 错误 | 原因 | 处理 |
|------|------|------|
| `debuggingPort` 连不上 | 紫鸟进程残留 / 端口被占 | 调 `POST /api/browser/stop` 强制关闭 → 重试 |
| **端口 9222 冲突** | **Desktop 内置 Chromium 也用 9222（chrome-bridge.ts:373 `CDP_PORT=9222`），与紫鸟 WebDriver 默认端口撞车** | **改 Desktop `CDP_PORT` 为 9322，同时修复 line 2256 硬编码的 `ws://127.0.0.1:9222/...` 改为 `${CDP_PORT}`** |
| `connectOverCDP` 版本不匹配 | `coreVersion` 与 Playwright Chromium 版本不一致 | 检查版本号 → 必要时 `npx playwright install chromium` |
| 页面元素找不到 | 后台改版 / 国际站差异 | 用 `page.content()` 查看实际 DOM → 调整选择器 |
| 登录态过期 | 店铺 Cookie 失效 | 需手动在紫鸟重新登录一次 |
| 下载文件无响应 | 浏览器下载弹窗未处理 | 用 Playwright `page.on('download')` 监听 |

---

## Desktop 端口冲突修复清单（✅ 已在 v4.0.0 实现）

`AtomK-Desktop/src/main/chrome-bridge.ts` 修改（commit ac4f645，main 分支）：

| 行号 | 原代码 | 改为 | 说明 |
|------|--------|------|------|
| 373 | `const CDP_PORT = 9222;` | `const CDP_PORT = 9322;` | 端口常量，所有引用自动跟随 |
| 2256 | `` `ws://127.0.0.1:9222/devtools/${kind}/${target_id}` `` | `` `ws://127.0.0.1:${CDP_PORT}/devtools/${kind}/${target_id}` `` | 消除硬编码 |

UI 文件（ChromeBridge.tsx / BridgeConnection.tsx）中的 "9222" 是纯展示文本，不影响功能。

---

## 操作纪律

1. **串行优先**：多店铺操作默认串行，避免紫鸟资源冲突和 IP 风控
2. **操作间隔**：页面间导航至少间隔 2-3 秒，模拟人类节奏
3. **失败隔离**：单店铺失败不影响后续店铺
4. **截图留痕**：关键操作（下单、改价、删评）必须截图存档
5. **频率控制**：同一店铺 1 小时内自动化操作不超过 10 次
6. **进程清理**：每次操作完成后调 `POST /api/browser/stop` 释放资源
7. **版本锁定**：紫鸟 `coreVersion` 和 Playwright Chromium 版本必须对齐

---

## 与 AtomK Bridge 的集成点

Desktop 端需新增 `ziniao` 指令处理器：

```
Bridge CDP 指令格式:
{
  "method": "ziniao.operate",
  "params": {
    "action": "screenshot_orders",   // 操作类型
    "storeId": "xxx",                // 店铺ID（或 storeName 模糊匹配）
    "targetUrl": "/orders-v3",       // 目标页面路径
    "options": {
      "screenshot": true,
      "fullPage": false
    }
  }
}
```

Desktop 收到后执行：
1. 调紫鸟 API 获取 `debuggingPort`
2. Playwright 连接 → 导航 → 操作 → 截图
3. 结果通过 Bridge 回传 Hermes

---

## Desktop 实施 Spec 与实现

**Spec 文件：** `/home/ubuntu/docs/desktop-playwright-ziniao-spec.md`（**v2.1**，2025-06-14 GLM-5.1 Review 后修订）  
**实现版本：** **4.0.0**（已提交 Gitea main 分支，PR #25-#31 全部合入，**已 build** → `dist/atomk-desktop-4.0.0-setup.exe`，已上传 COS `desktop/`）

**v2.1 关键变更**（GLM-5.1 审查 7 个问题全部修复）：
- 🔴 端口 9222→9322（避免紫鸟 WebDriver 默认 9222 冲突）
- 🔴 BrowserContext 多 slot 隔离（`Map<slotId, BrowserContext>`）
- 🔴 版本映射表修正（Electron 39→Chromium 142→playwright-core ~1.56）
- 🟡 通道互斥锁、僵尸浏览器 TTL、下载超时、请求队列、safeStorage 加密

**Desktop 4.0.0 新增文件：**
- `src/main/playwright-controller.ts` — Playwright 控制器（BrowserContext 隔离 + 通道锁 + 操作队列）
- `src/main/ziniao-client.ts` — 紫鸟 HTTP API 客户端（safeStorage 加密存储）
- `src/main/bridge-message-router.ts` — 路由注册（`playwright.*` / `ziniao.*`）

**Bridge 指令协议（实现后）：**
```
playwright.navigate / .screenshot / .click / .type / .extract / .download / .execute / .status
ziniao.status / .list_stores / .screenshot / .get_reviews / .download_report
```

关键变更：使用 `playwright-core ~1.56.0`（锁定匹配 Electron 39 Chromium 142）。

## 依赖

- **Desktop 侧：** Node.js + `playwright-core ~1.56.0`（锁定匹配 Electron 39 Chromium 142，已在 Desktop v4.0.0 的 package.json 中）
- **紫鸟侧：** WebDriver 权限已开通 + API Key
- **Hermes 侧：** `bridge-cdp-agent` skill（已就绪）
- **网络：** Desktop 与紫鸟同机 → `127.0.0.1` 本地通信
- **技术规格：** 详见 `/home/ubuntu/docs/desktop-playwright-ziniao-spec.md`（v2.1）
- **实现细节与开发流程：** 详见 `atomk-desktop-development` skill（Gitea PR 工作流、review pipeline、构建规则）
- **Review 记录：** 详见 `references/review-pipeline-4.0.0.md`（六轮 review 总计 ~50 个问题及修复）
- **已知 Bug：** 详见 `references/review-pipeline-4.0.0.md`（六轮 review 全部修复，仅剩 Server 侧 4 个端点问题待修）

## API 凭证配置

### 紫鸟 (Ziniao)

| 项目 | 说明 |
|------|------|
| **凭证来源** | Bridge/atomlisting 服务端配置下发 |
| **本地存储** | `~/.atomk/ziniao.json`（Electron `safeStorage` 加密） |
| **Desktop UI** | 暂无手动输入入口 |
| **代码** | `src/main/ziniao-client.ts`（Desktop v4.0.0） |

API Key 由 `ziniao-client.ts` 首次启动时从 Bridge 配置同步。Desktop 的 Accounts 页面（账号管理 → 添加店铺）支持 `apiKey` + `apiSecret` 字段，但目前没有"紫鸟" platform 选项。

### Hubstudio

| 项目 | 说明 |
|------|------|
| **集成状态** | ✅ 已有 `hubstudio-bridge` skill（Hermes v1.0.0） |
| **API 方式** | Local API `127.0.0.1:6873`，认证 `app_id` + `app_secret` |
| **Skill 位置** | `~/.hermes/skills/cross-border-ecommerce/hubstudio-bridge/` |
| **Gitea 注册表** | `admin9webs/atomk-hermes-skills/skills/cross-border-ecommerce/hubstudio-bridge/` |
| **Desktop client** | `src/main/hubstudio-client.ts`（v4.0.1+），UI 在 Chrome Bridge 页面底部 |

Hubstudio 是紫鸟同公司产品，提供浏览器环境 + 云手机管理。调用路径：Hermes → Bridge → Desktop → HubStudio Local API。