makemd/docs/ARCH/plugin.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 消息类型

// 消息类型定义
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 连接器接口

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 连接器实现

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 错误重试

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

---

5. 代理管理

5.1 代理配置

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

5.2 代理轮换

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 指纹配置

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

6.2 指纹生成

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