makemd/docs/ARCH/plugin.md

# 插件架构

> **入口**: [_index.md](_index.md)

---

## 1. 插件结构

```
node-agent/src/
├── background/         # 后台脚本
│   └── index.ts        # 主入口
├── content/            # 内容脚本
│   └── index.ts        # 页面注入
├── popup/              # 弹窗页面
│   └── index.tsx       # 弹窗UI
├── connectors/         # 平台连接器
│   ├── ShopifyConnector.ts
│   └── AmazonConnector.ts
└── utils/              # 工具函数
```

---

## 2. 通信机制

### 2.1 消息类型

```typescript
// 消息类型定义
interface Message {
  type: string;
  payload: any;
  traceId: string;
}

// 消息类型枚举
enum MessageType {
  // 商品采集
  COLLECT_PRODUCT = 'COLLECT_PRODUCT',
  COLLECT_ORDER = 'COLLECT_ORDER',
  
  // 自动化操作
  AUTO_PUBLISH = 'AUTO_PUBLISH',
  AUTO_UPDATE_PRICE = 'AUTO_UPDATE_PRICE',
  
  // 数据同步
  SYNC_INVENTORY = 'SYNC_INVENTORY',
  SYNC_ORDER = 'SYNC_ORDER',
}
```

### 2.2 消息流程

```
前端控制台 → 后端服务 → 插件Background → Content Script → 平台页面
                ↑                                        │
                └──────────── 数据回传 ──────────────────┘
```

---

## 3. 连接器设计

### 3.1 连接器接口

```typescript
interface IPlatformConnector {
  platformCode: string;
  capabilities: {
    hasApi: boolean;
    supportsPriceSync: boolean;
    supportsInventorySync: boolean;
    supportsOrderPull: boolean;
  };
  
  pullProducts(shopId: string): Promise<PlatformProduct[]>;
  pullOrders(shopId: string): Promise<PlatformOrder[]>;
  pushListing(product: Product): Promise<ListingResult>;
  updatePrice(listingId: string, price: number): Promise<void>;
  syncInventory(listingId: string, stock: number): Promise<void>;
}
```

### 3.2 连接器实现

```typescript
export class ShopifyConnector implements IPlatformConnector {
  platformCode = 'SHOPIFY';
  capabilities = {
    hasApi: true,
    supportsPriceSync: true,
    supportsInventorySync: true,
    supportsOrderPull: true,
  };

  async pullProducts(shopId: string): Promise<PlatformProduct[]> {
    // Shopify API 调用
  }

  async pullOrders(shopId: string): Promise<PlatformOrder[]> {
    // Shopify API 调用
  }

  // ... 其他方法
}
```

---

## 4. 自动化流程

### 4.1 任务执行

```
1. 后端下发任务 → Redis Queue
2. Agent Worker 接收任务
3. 选择对应 Connector
4. 执行操作（API/页面操作）
5. 回传结果 → 后端服务
6. 更新任务状态
```

### 4.2 错误重试

```typescript
const retryOptions = {
  attempts: 3,
  backoff: {
    type: 'exponential',
    delay: 1000,
  },
};
```

---

## 5. 代理管理

### 5.1 代理配置

```typescript
interface ProxyConfig {
  host: string;
  port: number;
  username?: string;
  password?: string;
  protocol: 'http' | 'https' | 'socks5';
}
```

### 5.2 代理轮换

```typescript
class ProxyManager {
  private proxies: ProxyConfig[];
  private currentIndex = 0;

  getNext(): ProxyConfig {
    const proxy = this.proxies[this.currentIndex];
    this.currentIndex = (this.currentIndex + 1) % this.proxies.length;
    return proxy;
  }
}
```

---

## 6. 指纹管理

### 6.1 指纹配置

```typescript
interface FingerprintConfig {
  userAgent: string;
  viewport: { width: number; height: number };
  locale: string;
  timezone: string;
  webgl: { vendor: string; renderer: string };
  fonts: string[];
}
```

### 6.2 指纹生成

```typescript
class FingerprintGenerator {
  generate(): FingerprintConfig {
    return {
      userAgent: this.randomUserAgent(),
      viewport: this.randomViewport(),
      locale: 'en-US',
      timezone: 'America/New_York',
      webgl: this.randomWebGL(),
      fonts: this.randomFonts(),
    };
  }
}
```

---

*最后更新: 2026-03-22*