NetaClaw 电商浏览器自动化平台设计文档
日期: 2026-04-11
状态: 设计阶段
范围: Neta-monorepo 架构转型 — 从保险审核 AI 平台转为电商浏览器自动化运营平台
1. 项目定位
Neta 电商浏览器自动化运营平台，基于 OpenClaw Agent 架构（命名为 NetaClaw），结合 Playwright 浏览器自动化，实现电商平台的智能化运营操作（商品管理、订单处理、竞品监控、营销投流、文生图等）。
2. 核心决策
| 决策项 |
结论 |
理由 |
| Agent 引擎 |
NetaClaw（迁移自 OpenClaw） |
微内核+插件化，Skill 懒加载，比 LangChain 更适合工具驱动场景 |
| LangChain |
完全移除 |
不符合最终需求，OpenClaw 的 ReAct 循环更直接 |
| 浏览器自动化 |
Playwright |
模拟真人操作，Node.js 生态最成熟，反检测插件丰富 |
| 架构模式 |
纯 B/S（去掉 Tauri） |
后端本地运行可直接操作文件系统，无需 Tauri IPC |
| 业务框架 |
Midway.js（保留） |
CRUD、TypeORM、权限系统继续使用 |
| 前端 |
Vue 3 + Element Plus（保留） |
改造 UI 适配电商运营场景 |
| 桌面体验 |
pkg 打包 .exe + NSIS 安装包 |
非技术用户双击启动，系统托盘图标 |
| 现有 Skill |
全部清理重建 |
旧 Skill 面向保险审核，与电商无关 |
| 目标平台 |
淘宝/天猫、拼多多、京东、抖音/快手 |
四大电商平台全覆盖 |
| 数据存储 |
本地文件 + MySQL + SQLite |
对话/图片存本地，业务数据存 MySQL，会话检查点存 SQLite |
3. 系统架构
┌─ 云端服务器 ─────────────────────────────────┐
│ 用户认证 / License 验证 / 共享配置 / 模型API代理 │
└──────────────────────┬───────────────────────┘
│ HTTPS
┌──────────────────────┴───────────────────────┐
│ 用户本地 (Neta.exe) │
│ │
│ ┌─── Vue 3 前端 (localhost:9001) ─────────┐ │
│ │ 操作面板 │ 任务监控 │ Agent对话 │ 数据看板 │ │
│ └────────────────┬────────────────────────┘ │
│ │ HTTP / WebSocket │
│ ┌────────────────┴────────────────────────┐ │
│ │ Midway.js 后端 (localhost:8003) │ │
│ │ │ │
│ │ ┌── NetaClaw Agent Engine ───────────┐ │ │
│ │ │ Gateway (WS) → Runtime (ReAct) │ │ │
│ │ │ → Tools → Plugins → Subagents │ │ │
│ │ └──────────────┬─────────────────────┘ │ │
│ │ │ │ │
│ │ ┌──────────────┴─────────────────────┐ │ │
│ │ │ Playwright Engine │ │ │
│ │ │ 反检测 │ 多店铺并发 │ 平台适配 │ │ │
│ │ └────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─ Skills (SKILL.md) ────────────────┐ │ │
│ │ │ 商品管理│订单处理│竞品监控│营销投流 │ │ │
│ │ └────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─ 存储 ─────────────────────────────┐ │ │
│ │ │ 本地文件 │ MySQL │ SQLite │ │ │
│ │ └────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────┘ │
│ │
│ ┌─ 系统托盘 ─────────────────────────────┐ │
│ │ 状态指示 │ 打开面板 │ 设置 │ 退出 │ │
│ └─────────────────────────────────────────┘ │
└───────────────────────────────────────────────┘
4. Monorepo 结构重组
移除
packages/desktop/ — 整个 Tauri 桌面端packages/skills/ — 旧的 Python/Node skill 目录packages/backend/src/modules/agent/ — 旧的 LangChain Agent 模块- 所有
@langchain/* 依赖
保留
packages/backend/ — Midway.js 后端（base/dict/task/user/notification 等模块）packages/frontend/ — Vue 3 前端（改造 UI）packages/shared/ — 共享类型
新增
packages/
├── backend/
│ └── src/modules/
│ ├── netaclaw/ # ★ NetaClaw Agent 引擎（从 OpenClaw 迁移）
│ └── ... (保留的业务模块)
├── frontend/ # 改造 UI
├── shared/ # 共享类型
├── skills/ # ★ 电商 Skill 文档（SKILL.md 格式）
└── scripts/
├── build.ts # ★ pkg 打包脚本
└── installer/ # ★ NSIS 安装包配置
5. NetaClaw 模块设计
5.1 OpenClaw → NetaClaw 迁移映射
| OpenClaw 源码路径 |
NetaClaw 目标路径 |
迁移策略 |
src/gateway/server.impl.ts |
netaclaw/gateway/server.ts |
精简迁移，去掉 Channel 路由，保留 WS + 会话管理 |
src/gateway/session-utils.ts |
netaclaw/gateway/session.ts |
迁移会话 CRUD 和历史管理 |
src/gateway/net.ts |
netaclaw/gateway/ws.ts |
迁移 WebSocket 服务器 |
src/agents/pi-embedded-runner/ |
netaclaw/runtime/ |
核心迁移，保留 ReAct 循环、工具执行、模型调用 |
src/agents/pi-tools.ts |
netaclaw/tools/common.ts |
迁移 AgentTool 接口 + TypeBox Schema |
src/agents/bash-tools.ts |
netaclaw/tools/builtin/bash.ts |
迁移命令执行工具 |
src/agents/acp-spawn.ts |
netaclaw/runtime/subagent.ts |
迁移子代理生成（多店铺并行） |
src/agents/model-selection.ts |
netaclaw/runtime/model_selection.ts |
迁移模型选择与故障转移 |
src/agents/tool-policy.ts |
netaclaw/tools/policy.ts |
迁移工具访问控制 |
extensions/browser/ |
netaclaw/browser/ |
核心迁移，新增反检测和电商适配 |
src/plugin-sdk/ |
netaclaw/plugins/ |
精简迁移，保留工具工厂和钩子 |
src/config/ |
不迁移 |
使用 Midway.js 配置体系 |
src/channels/ |
不迁移 |
电商场景不需要 IM 渠道 |
skills/ |
不迁移内容 |
保留 SKILL.md 格式，内容全部替换 |
5.2 NetaClaw 目录结构
packages/backend/src/modules/netaclaw/
├── gateway/ # WebSocket Gateway
│ ├── server.ts # WS 服务器（精简版）
│ ├── session.ts # 会话管理
│ └── protocol.ts # 消息协议定义
│
├── runtime/ # Agent 运行时
│ ├── agent.ts # Agent 核心循环（ReAct loop）
│ ├── attempt.ts # 单次执行尝试
│ ├── model_selection.ts # 模型选择与故障转移
│ ├── subagent.ts # 子代理生成
│ └── thinking.ts # 思考级别控制
│
├── tools/ # 工具系统
│ ├── common.ts # AgentTool 接口 + TypeBox Schema
│ ├── policy.ts # 工具访问控制
│ ├── builtin/ # 内置工具
│ │ ├── bash.ts # 命令执行
│ │ ├── file.ts # 文件读写
│ │ └── web_search.ts # 网页搜索
│ ├── browser/ # 浏览器工具（迁移自 extensions/browser/）
│ │ ├── pw_tools_core.ts # Playwright 核心
│ │ ├── interactions.ts # 点击/输入/滚动
│ │ ├── snapshot.ts # 页面快照
│ │ └── stealth.ts # 反检测配置
│ └── ecommerce/ # 电商专用工具
│ ├── product.ts # 商品操作（上架/下架/改价）
│ ├── order.ts # 订单操作
│ └── data_collect.ts # 数据采集
│
├── plugins/ # 插件系统
│ ├── plugin_entry.ts # 插件定义接口
│ ├── plugin_api.ts # 插件 API
│ └── llm_providers/ # LLM 提供商
│ ├── openai.ts
│ ├── anthropic.ts
│ └── deepseek.ts
│
├── platforms/ # 电商平台适配层
│ ├── base_platform.ts # 平台基类（登录/反检测/选择器）
│ ├── taobao/ # 淘宝/天猫
│ │ ├── login.ts
│ │ ├── selectors.ts
│ │ └── actions.ts
│ ├── pdd/ # 拼多多
│ ├── jd/ # 京东
│ └── douyin/ # 抖音
│
├── config.ts # NetaClaw 配置（接入 Midway config）
└── module.ts # Midway.js 模块注册
5.3 核心接口设计
AgentTool 接口（迁移自 OpenClaw）
import { Type, TSchema } from '@sinclair/typebox';
export type AgentTool<TParams extends TSchema, TResult> = {
name: string;
label: string;
description: string;
parameters: TParams;
execute(id: string, params: Static<TParams>): Promise<TResult>;
};
export type AgentToolWithMeta<TParams extends TSchema, TResult> =
AgentTool<TParams, TResult> & {
ownerOnly?: boolean;
displaySummary?: string;
};
Skill 格式（SKILL.md）
---
name: product-listing
description: 电商平台商品上架自动化
metadata:
netaclaw:
platforms: [taobao, pdd, jd, douyin]
requires: { tools: [browser, file] }
---
# 商品上架 Skill
## 触发条件
用户要求上架商品、批量上架、商品发布
## 工作流程
1. 确认目标平台和商品信息
2. 打开平台卖家后台
3. 导航到商品发布页面
4. 填写商品信息（标题、价格、库存、描述）
5. 上传商品图片
6. 提交并确认发布状态
## 规则约束
- 操作前必须确认已登录目标平台
- 价格修改需要用户二次确认
- 批量操作间隔随机 3-8 秒，模拟人工节奏
平台适配器基类
export abstract class BasePlatform {
abstract name: string;
abstract loginUrl: string;
abstract login(page: Page, credentials: Credentials): Promise<void>;
abstract isLoggedIn(page: Page): Promise<boolean>;
abstract getSelectors(): PlatformSelectors;
// 反检测配置
getStealthConfig(): StealthConfig {
return { humanDelay: [100, 300], randomMouseMove: true };
}
}
6. Playwright 浏览器引擎
6.1 反检测策略
| 策略 |
实现方式 |
| 指纹伪装 |
playwright-extra + stealth plugin |
| 人工延迟 |
随机间隔 100-500ms，高斯分布 |
| 鼠标轨迹 |
贝塞尔曲线模拟真人移动 |
| 键盘输入 |
逐字输入，随机打字速度 |
| 浏览器指纹 |
使用用户已安装的 Chrome（channel: 'chrome'） |
| WebDriver 标志 |
移除 navigator.webdriver 等自动化特征 |
| 行为模式 |
随机滚动、页面停留、Tab 切换 |
6.2 多店铺并发
// 浏览器实例池
export class BrowserPool {
private contexts: Map<string, BrowserContext> = new Map();
// 每个店铺一个独立的 BrowserContext（隔离 Cookie/Storage）
async getContext(shopId: string): Promise<BrowserContext>;
// 并发控制（信号量，默认 max=3）
async executeWithLimit<T>(shopId: string, fn: (page: Page) => Promise<T>): Promise<T>;
}
7. 数据存储
| 数据类型 |
存储位置 |
说明 |
| Agent 对话记录 |
本地文件 (~/.neta/sessions/) |
默认本地，用户可选同步到 MySQL |
| 生成的图片 |
本地文件 (~/.neta/workspace/) |
文生图等产出物 |
| 业务数据 |
MySQL (neta_ecommerce) |
店铺配置、任务记录、操作日志 |
| 会话检查点 |
SQLite (~/.neta/checkpoints.sqlite) |
Agent 会话持久化 |
| 浏览器状态 |
本地文件 (~/.neta/browser/) |
Cookie、Storage、登录态 |
8. 打包与分发
8.1 pkg 打包
# 构建
pnpm build
# 打包为 .exe
pkg dist/bootstrap.js \
--targets node20-win-x64 \
--output Neta.exe \
--assets "skills/**/*"
8.2 启动流程
Neta.exe 双击启动
→ 启动 Midway.js 后端 (localhost:8003)
→ 启动系统托盘图标
→ 自动打开默认浏览器到 localhost:9001
→ 前端加载，连接后端 WebSocket
→ 用户开始使用
8.3 NSIS 安装包
- 安装 Neta.exe 到 Program Files
- 创建桌面快捷方式和开始菜单项
- 捆绑 Playwright Chromium（可选，或首次启动时下载）
- 注册开机自启（可选）
9. 电商 Skill 清单（首批）
| Skill |
描述 |
目标平台 |
product-listing |
商品上架（单个/批量） |
全平台 |
product-delist |
商品下架 |
全平台 |
price-update |
价格修改 |
全平台 |
inventory-sync |
库存同步 |
全平台 |
order-process |
订单处理（发货/备注） |
全平台 |
customer-reply |
客服自动回复 |
全平台 |
competitor-monitor |
竞品价格/销量监控 |
全平台 |
ad-campaign |
直通车/推广投流 |
淘宝/拼多多 |
image-gen |
产品详情页文生图 |
不限平台 |
data-export |
运营数据导出 |
全平台 |
10. 需要移除的依赖
@langchain/classic
@langchain/cohere
@langchain/community
@langchain/core
@langchain/deepseek
@langchain/langgraph
@langchain/langgraph-checkpoint
@langchain/mcp-adapters
@langchain/ollama
@langchain/openai
@langchain/textsplitters
langchain
11. 需要新增的依赖
playwright-core # 浏览器自动化
playwright-extra # 反检测插件框架
puppeteer-extra-plugin-stealth # 反检测插件（兼容 playwright-extra）
@sinclair/typebox # JSON Schema（AgentTool 参数定义）
@anthropic-ai/sdk # Anthropic Claude API
node-systray # 系统托盘图标
open # 自动打开浏览器
pkg # 打包为 .exe（devDependency）
