admin9webs/atomk-hermes-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c63ba2c36d9895b3590e8e24ca49ef775e8853a
atomk-hermes-skills/skills/cross-border-ecommerce/ziniao-bridge/SKILL.md
T

13 KiB
Raw Blame History

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

返回：

{
  "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"
}

返回：

{
  "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 直连：

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。

Reference in New Issue View Git Blame Copy Permalink