# 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）
```