admin9webs/atomk-hermes-skills

Fork 0

Files

T

admin9webs c7b971e724 Add cross-border-ecommerce/ziniao-bridge

2026-07-10 16:12:11 +08:00

13 KiB

Raw Permalink 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

紫鸟桥接 (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，去亚马逊后台看最近订单，截图发我」

执行链：

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

场景 2：下载业务报表

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

执行链：

获取店铺 → 启动浏览器 → 连接
导航到 Reports 页面
设置日期范围（最近7天）
点击「下载 CSV」
监听下载事件 → 获取文件
回传文件到钉钉

场景 3：巡检评论

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

执行链：

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

场景 4：多店铺批量截图

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

执行链：

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

场景 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" 是纯展示文本，不影响功能。

操作纪律

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

调紫鸟 API 获取 debuggingPort
Playwright 连接 → 导航 → 操作 → 截图
结果通过 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。

13 KiB Raw Permalink Blame History Unescape Escape

紫鸟桥接 (Ziniao Bridge)

架构总览

紫鸟 WebDriver API（核心）

基础 URL

核心接口

1. 获取店铺列表

2. 启动店铺浏览器

3. 关闭店铺浏览器

4. 获取店铺浏览器状态

Playwright 连接紫鸟浏览器

典型操作场景

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

场景 2：下载业务报表

场景 3：巡检评论

场景 4：多店铺批量截图

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

店铺后台 URL 速查表

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

错误处理规范

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

操作纪律

与 AtomK Bridge 的集成点

Desktop 实施 Spec 与实现

依赖

API 凭证配置

紫鸟 (Ziniao)

Hubstudio

13 KiB

Raw Permalink Blame History