361 lines
15 KiB
Markdown
361 lines
15 KiB
Markdown
# 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）
|
||
|
||
```typescript
|
||
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）
|
||
|
||
```yaml
|
||
---
|
||
name: product-listing
|
||
description: 电商平台商品上架自动化
|
||
metadata:
|
||
netaclaw:
|
||
platforms: [taobao, pdd, jd, douyin]
|
||
requires: { tools: [browser, file] }
|
||
---
|
||
|
||
# 商品上架 Skill
|
||
|
||
## 触发条件
|
||
用户要求上架商品、批量上架、商品发布
|
||
|
||
## 工作流程
|
||
1. 确认目标平台和商品信息
|
||
2. 打开平台卖家后台
|
||
3. 导航到商品发布页面
|
||
4. 填写商品信息（标题、价格、库存、描述）
|
||
5. 上传商品图片
|
||
6. 提交并确认发布状态
|
||
|
||
## 规则约束
|
||
- 操作前必须确认已登录目标平台
|
||
- 价格修改需要用户二次确认
|
||
- 批量操作间隔随机 3-8 秒，模拟人工节奏
|
||
```
|
||
|
||
#### 平台适配器基类
|
||
|
||
```typescript
|
||
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 多店铺并发
|
||
|
||
```typescript
|
||
// 浏览器实例池
|
||
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 打包
|
||
|
||
```bash
|
||
# 构建
|
||
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）
|
||
```
|