Add cross-border-ecommerce/ziniao-bridge

2026-07-10 16:12:11 +08:00
parent 7f11e74d72
commit c7b971e724
1 changed files with 375 additions and 0 deletions
@@ -0,0 +1,375 @@
 ---
 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。