admin9webs/atomk-hermes-skills

Fork 0

Files

T

admin9webs ae94191795 Add cross-border-ecommerce/atomk-platform

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

17 KiB

Raw Blame History

name, description, version, author, license, metadata

name

description

version

author

license

metadata

atomk-platform

AtomK platform operations: product claiming, AI listing generation, API data export, WooCommerce import, Temu batch listing, desktop app dev, sidebar management, and three-layer architecture.

1.0.0

Hermes Agent

MIT

hermes

AtomK Platform

Complete guide to the AtomK cross-border e-commerce platform — from product claiming through AI listing generation to exporting and publishing.

Workflow Overview

Workflow	Purpose	See
Bulk Claim	Claim products from Product Pool	`references/atomk-bulk-claim.md` (Playwright) / `references/atomk-cdp-bulk-claim.md` (CDP)
AI Listing Generation	Generate listing data from claimed products	`references/atomk-auto-generate.md`
API Data Export	Extract product data via REST API (JWT auth)	`references/atomk-api-export.md`
Temu Batch Listing	Batch claim + generate + CSV export for Temu	`references/atomk-temu-batch-listing.md`
WooCommerce Import	Claim + generate + publish to WooCommerce	`references/atomk-to-woocommerce.md`
Desktop App Dev	Modify AtomK Desktop Electron app	`references/atomk-desktop-dev.md`
Desktop Sidebar	Manage sidebar menu items	`references/atomk-desktop-sidebar.md`
Architecture	Three-layer Server/Bridge/Desktop arch	`references/atomk-three-layer-arch.md`
SG Services v2	SG1-SG5 内网资源代理 + 健康检查 API + Gitea/FlairGS 集成	`references/sg-services-v2.md`
SG5 Gitea Setup	SG5 Gitea 组织/仓库/Token/Webhook 完整铺设 (10 repos)	`references/sg5-gitea-setup.md`
Desktop SG6 Tools	Desktop 面板重组 + 跨境电商工具卡片设计	`references/desktop-sg6-ecommerce-tools.md`
SG7 User Resources	每用户邮箱+WP+WC 自动开通 — Server-direct proxy + API + Desktop 集成	`references/sg7-user-resources.md`

Typical Flow

Claim products from AtomK Product Pool
Generate AI listing data (title, description, images)
Export or Publish to target platform:
- CSV export for Temu
- REST API import to WooCommerce
- Raw API data for Miaoshou ERP

Section 1: Bulk Product Claiming

Claim products from AtomK Product Pool using Node.js Playwright automation.

When to use: Finding and claiming products to list on e-commerce platforms.

Key patterns:

Login to AtomK (Playwright)
Navigate Product Pool
Select category (e.g., 家居百货)
Claim products → generate Temu/AliExpress data → download CSV with 800×800 images

See: references/atomk-bulk-claim.md

Section 2: AI Listing Generation

Automatically log into AtomK, select a claimed product, choose an e-commerce platform, and AI-generate listing data.

When to use: Generating product listing content (title, description, keywords) for claimed products.

See: references/atomk-auto-generate.md

Section 3: API Data Export

Extract product and listing data from AtomK via its undocumented REST API (JWT authentication).

When to use: Bulk data extraction, integration with other platforms (Miaoshou, custom systems).

Key features:

JWT auth via login endpoint
Product data, listing data, image URLs
Import into Miaoshou ERP collection box

See: references/atomk-api-export.md

Section 4: Temu Batch Listing

End-to-end: bulk claim products (家居百货 category), generate Temu listing data via AI, resize images to 800×800, export as CSV.

When to use: High-volume Temu listing creation.

See: references/atomk-temu-batch-listing.md

Section 5: WooCommerce Import

Claim products from AtomK, generate AI listing data, and publish them to WooCommerce via REST API.

When to use: Publishing AtomK products to a WooCommerce store.

See: references/atomk-to-woocommerce.md

Section 6: Desktop App Development

Modify AtomK Desktop Electron app — IPC handlers, i18n, components, build patterns, Chrome Bridge.

When to use: Developing or debugging the AtomK Desktop application.

Key topics: IPC channels, window management, i18n syncing, Chrome Bridge (relay + CDP), bundled Chromium.

See: references/atomk-desktop-dev.md for full architecture and development guide.

Section 7: Desktop Sidebar Management

Manage AtomK Desktop sidebar menu — add/remove/rename/group items, i18n syncing, QuickPromptBar, Prompts CRUD.

When to use: Customizing the AtomK Desktop sidebar navigation.

See: references/atomk-desktop-sidebar.md

7.1 Panel Restructuring (2026-06-20)

SG6 跨境电商工作流引入后，Desktop 面板做了两处调整：

A2A Inbox → Mail: A2A 收件箱从 Tools.tsx 迁移到 Mail.tsx，作为第三个标签页 ("webmail" | "accounts" | "inbox")。语义上 Agent 消息属于通信类。
Tools 扁平化: 去掉跨境电商工具的分组层级，与 Hermes 工具开关、MCP 服务器统一平铺在 Tools 面板。

新 Tools 面板结构: 智能刊登 / 定价引擎 / 选品采集 / IP筛查 → Hermes 开关 → MCP

See: references/desktop-sg6-ecommerce-tools.md

Section 8: Desktop Build Upload

Upload AtomK Desktop builds to the us1.atomk.cn WooCommerce store for download.

When to use: Publishing new AtomK Desktop builds for users to download. Also covers publishing the Hermes Page Bridge Chrome extension zip to the same download page (package resources/extension/ → COS → insert section before 历史版本).

See: references/atomk-desktop-upload.md

Section 9: Three-Layer Architecture

AtomK's Server/Bridge/Desktop architecture — authentication, registration, heartbeat, and disconnect/failover handling.

When to use: Understanding the full system architecture, debugging connectivity issues, extending the platform.

See: references/atomk-three-layer-arch.md

Section 10: Credential Management

Centralized credential loading for scripts that interact with AtomK's API. Hardcoded credentials in shell/Python scripts are a security risk — all credentials live in a single env file with a Python loader.

Credential file: ~/.hermes/credentials.env (chmod 600, never committed to Git) Python loader: ~/.hermes/scripts/atomk_credentials.py

Available helpers

Function	Returns
`get_atomk_auth()`	`(username, password)` for atomlisting.com
`get_miaoshou_auth()`	`(username, password)` for miaoshou ERP
`get_ozon_auth(store)`	`(email, password)` for Ozon store 1 or 2
`get_gitea_auth()`	`(username, password)` for Gitea SG5
`get_credential(key)`	Any single credential by env var name

Refactoring a script

import sys, os
sys.path.insert(0, os.path.expanduser("~/.hermes/scripts"))
from atomk_credentials import get_atomk_auth

ATOMK_USERNAME, ATOMK_PASSWORD = get_atomk_auth()

Migrated scripts (all 23 — complete)

Batch	Count	Examples
Initial (manual)	2	`auto_miaoshou_import.py`, `miaoshou_atomk_bridge.py`
Batch refactor (automated)	21	`add_dianxiaomi.py`, `batch_gen_ozon.py`, `create_accounts.py`, `tongtool_run_specific.py`, etc.

Zero hardcoded Tt123456! remaining in /home/ubuntu/*.py. Verified with grep -rl.

Section 11: SG8 A2A Agent Gateway (SG3 Integrated)

SG3 (atomlisting.com) now serves as the A2A Agent Gateway, replacing the standalone a2a-gateway service. Agents register, authenticate, and communicate through the same backend that manages users, bridges, and stores.

API surface: POST/GET/DELETE /api/v1/a2a/agents/*, POST /api/v1/a2a/route, POST /api/v1/a2a/broadcast, GET/DELETE /api/v1/a2a/inbox/*, WS /api/v1/a2a/ws/{agent_id}

Key design decisions:

Agents are owned by users (tenant isolation — messages scoped per-user)
API keys hashed with SHA-256 (never stored plaintext)
WebSocket delivery preferred, inbox fallback + HTTP push to agent endpoint
Reuses SG3's existing JWT auth infrastructure (hardened with refresh token families)

Migration from standalone gateway:

Register agents at POST /api/v1/a2a/agents/register instead of the old gateway
Agent clients connect to wss://www.atomlisting.com/api/v1/a2a/ws/{agent_id} with X-Agent-Key header
The standalone a2a-gateway service can be decommissioned

Files: models/a2a_agent.py, schemas/a2a.py, api/v1/a2a.py, alembic/versions/add_a2a_agents.py

See: references/sg8-a2a-gateway.md

Section 12: Security Audit Remediation (2026-06)

The 2026-06-22 code audit identified 5 Critical, 8 High, and 12 Medium findings across the Server monorepo. Key fixed items:

Fix	File(s)	What changed
Bridge approval bypass	`bridges.py`	Server-owned state machine; pending bridges can't self-approve via heartbeat
API response secret leakage	`store.py`, `settings.py`	`api_key` masked to `abcd...wxyz`; password stored in `api_secret` (not `extra_data`)
Plaintext cookie vault	`cookies.py`	5MB limit, 1,000 cookies, 10 backups/user, 90-day retention, rate limiting
MySQL pgcrypto incompatibility	`utils/crypto.py`, `users.py`, `wp_proxy.py`	AES-256-GCM app-level encryption replaces PostgreSQL `pgp_sym_encrypt`
Refresh token revocation	`security.py`, `auth.py`, `models/refresh_token.py`	Token families with jti tracking, replay detection, family-level revocation
Hardcoded root SSH	`email_service.py`, `config.py`	BillionMail API preferred; SSH opt-in only with `EMAIL_SSH_PROVISIONING_ENABLED`
Bridge key blast radius	`bridges.py`, `auth.py`	Keys always masked in responses; dedicated `GET /{id}/key` reveal endpoint

See: references/server-security-fixes.md for full remediation details.

Common Pitfalls

Login CAPTCHA — AtomK may show CAPTCHA on login; handle retry logic
800×800 image requirement — Temu requires exact 800×800 product images
JWT token expiry — re-authenticate if API returns 401
Desktop app reload — after sidebar changes, reload the app to see updates
Bridge reconnection — Desktop must handle Bridge disconnect/reconnect gracefully
Server security — See references/server-security-fixes.md for bridge register auth, startup validation, and remaining security items from the 2026-06 review.
Server env vars — See references/atomlisting-server-env-setup.md for BRIDGE_JWT_SECRET, WEBHOOK_SECRET, HERMES_WEBHOOK_HMAC_KEY, and ATOMK_BRIDGE_KEY configuration.
Repo naming: 首字母大写、- 分词。正确 AtomK-Cloud-Bridge 错误 atomk-page-bridge。
Credential scanner: shell/Python 中的密码会被 Hermes 扫描器替换为 ***。用 base64.b64decode() 运行时解码绕过。见 references/base64-auth-pattern.md。
A2A Inbox: 已从 Tools 迁移到 Mail 面板的第三个标签页。
Centralized credentials: 所有 AtomK/9Webs 凭证统一管理。见 references/credential-management.md。
Production deployment: 生产 Git 只读，用 SSH piping 部署。后端在 /root/AtomK_Operation_Tools/backend/（非 /var/www/atomlisting/）。见 references/production-deployment-workflow.md。
FastAPI imports: 加 middleware 需 from fastapi import Request；加 DI 端点需 from fastapi import Depends。这两个 import 容易遗漏，会导致 NameError。见 references/production-deployment-workflow.md 的调试部分。
FastAPI route ordering: 当 /resource/{param} 类型的参数化路由注册在 /resource/specific 类型的字面路由之前时，FastAPI 按注册顺序匹配 — /resource/specific 会被 /resource/{param} 吞掉（param="specific"）。导致 404 而非 401/405。修复：始终把字面路由（如 /remote/submit）放在参数化路由（如 /remote/{product_code}）之前注册。这个 bug 在 products.py 中发生过 — Submit 功能返回 404 而非正常鉴权错误。
Desktop userBridges type — Settings.tsx 中 userBridges 的类型定义漏了 ws_port 和 api_port 字段，导致 Desktop 用 HTTP 端口(9228)建 WS 连接而非 WS 端口(9229)。Server API 已返回这些字段但 Desktop 没读。修复需同步更新：(a) useState 类型定义、(b) typedBridges cast、(c) bridgeList map、(d) WS URL 构造 (用 ws_port || port)、(e) 显示文本。
Submit title vs Products name mismatch — remote_submit_product 把自定义标题存入 MongoDB 的 title 字段，但 _format_remote_product 只读 name 字段。Submit 提交的商品在 Products 列表显示空白名字。修复：product.get("name") or product.get("title", "") — name 优先（爬虫数据），为空时 fallback 到 title（手动提交）。同样注意 category 字段：爬虫数据用 categories[0].name，手动提交用纯字符串 category — line 93 已有 product.get("category", "") fallback。
Gitea 502 — 旧地址 gitea9webs.sh3.ikuai7.com 已下线，所有仓库已迁移到 frp.9webs.online:3000 (org=9webs)。遇到 502 先检查 URL 地址。
Chrome Extension publishing — 下载页也托管 Hermes Page Bridge Chrome 扩展 zip。从 resources/extension/ 打包（zip CONTENTS 而非父目录），上传到 COS atomk-desktop/releases/atomk-chrome-extension.zip，在下载页 历史版本 前插入扩展段。
WP 下载页历史表清除 (re.split 方法) — 正则匹配单个历史段容易遗漏重复段（如 append 造成的双 历史版本 表）。可靠方法：用 re.split() 将 content 按历史段模式切分，取 parts[0]（第一个历史段之前的内容），然后重建整个历史表追加回去。公式：parts = re.split(r'()', content, flags=re.DOTALL); new_content = parts[0] + rebuilt_history。
WP 下载页全局 replace 会破坏历史链接 — content.replace(f"atomk-desktop-{OLD}-setup.exe", f"atomk-desktop-{NEW}-setup.exe") 会把历史表中旧版本的 href 也改成新版本。解决方法：先替换最新版块中的链接（限定匹配范围），或全局替换后对历史表行做定向恢复：content.replace(bad_history_link, good_history_link)。
MongoDB premium-products 缺失 status 字段 — 旧文档缺少 status 字段，但 _format_doc 用 doc.get("status", "active") 返回默认值。API 无过滤时返回 total=11，但 ?status=active 返回 total=0（因为 MongoDB {"status":"active"} 不匹配缺字段的文档）。直接连 MongoDB 执行 db.products.update_many({'status': {'$exists': False}}, {'$set': {'status': 'active'}}) 修复。Server 地址 43.134.190.229:27018，DB premiumproducts。
WP Proxy P0-2 IP 白名单拦截 Desktop 客户端 — wp_proxy.py:162-166 的 _is_trusted_source() 校验只允许 127.0.0.0/8、10.3.0.0/24、172.17.0.0/16 来源访问内网上游 WordPress。Desktop 客户端从公网 IP 连接被 403 拦截 ("Internal routing not allowed from this source")。已移除 IP 校验（JWT 认证已足够），无需再手动加白名单。部署需在 43.134.190.229 上 git pull + 重启。
WP Application Password 401 fallback — wp_sites 表中存储的 Application Password 过期导致 WordPress 401 (rest_cannot_create)。三层根因：① wp_admin_user 不是 admincao（DB 里是 admin）② WP URL 指向错误的域名 ③ SSRF 白名单缺少 .atomk.cn。修复：wp_proxy.py 加 401 自动重试（用 admincao 而非 wp['wp_admin_user']），config.py 加 .atomk.cn 白名单，wp_endpoints.py 加 PATCH /api/v2/user/wp/config 端点 + debug 字段。详见 references/wp-401-fallback.md。

17 KiB Raw Blame History Unescape Escape