auto-account-machine/browser-automation-ts/TOOLS-MIGRATION-PLAN.md

Tools迁移计划

🎯 目标

将 src/shared/libs/ 中的JS工具迁移到 browser-automation-ts/src/tools/，统一使用TypeScript和ITool规范。

---

📊 迁移清单

1. AccountGenerator ✅ (已创建)

• 源文件: src/shared/libs/account-generator.js
• 目标: browser-automation-ts/src/tools/AccountGenerator.ts
• 状态: ✅ 完成（新实现符合ITool规范）
• 接口: IAccountGenerator

2. CardGenerator

• 源文件: src/shared/libs/card-generator.js
• 目标: browser-automation-ts/src/tools/CardGenerator.ts
• 状态: ⏳ 待迁移
• 接口: ICardGenerator
• 依赖: Database
• 功能:
  • 从数据库获取未使用的卡
  • 标记卡为已使用
  • BIN去重逻辑

3. EmailHandler

• 源文件: src/shared/libs/email-handler.js (如果存在)
• 目标: browser-automation-ts/src/tools/EmailHandler.ts
• 状态: ⏳ 待创建
• 接口: IEmailHandler
• 功能:
  • 连接邮箱服务
  • 获取验证码
  • 解析邮件内容

4. CaptchaSolver

• 源文件: src/shared/libs/captcha-solver.js
• 目标: browser-automation-ts/src/tools/CaptchaSolver.ts
• 状态: ⏳ 待迁移
• 接口: ICaptchaHandler
• 功能:
  • Turnstile处理
  • hCaptcha处理
  • reCAPTCHA处理

5. DatabaseClient

• 源文件: src/shared/libs/database.js
• 目标: browser-automation-ts/src/tools/DatabaseClient.ts
• 状态: ⏳ 待迁移
• 接口: IDatabaseClient
• 功能:
  • MySQL连接
  • 保存账号数据
  • 保存卡片数据
  • 查询操作

---

🏗️ 最终架构

browser-automation-ts/
├── src/
│   ├── core/                     # 核心（Provider、Action、WorkflowEngine）
│   ├── adapters/                 # 适配器接口
│   └── tools/                    # 业务工具（符合ITool规范）
│       ├── ITool.ts             # ✅ 工具接口规范
│       ├── AccountGenerator.ts   # ✅ 账号生成器
│       ├── CardGenerator.ts      # ⏳ 卡生成器
│       ├── EmailHandler.ts       # ⏳ 邮箱处理器
│       ├── CaptchaSolver.ts      # ⏳ 验证码处理器
│       └── DatabaseClient.ts     # ⏳ 数据库客户端
├── configs/
│   └── sites/
│       ├── windsurf.yaml         # 流程定义
│       └── windsurf-adapter.ts   # 业务逻辑（使用tools）
└── cli/
    └── run.ts                    # 通用执行器

---

💡 使用示例

Windsurf Adapter示例

import { WindsurfAdapter } from './windsurf-adapter';
import { AccountGenerator } from '../../src/tools/AccountGenerator';
import { CardGenerator } from '../../src/tools/CardGenerator';
import { DatabaseClient } from '../../src/tools/DatabaseClient';

class WindsurfAdapter implements ISiteAdapter {
  private accountGen: AccountGenerator;
  private cardGen: CardGenerator;
  private db: DatabaseClient;

  async initialize(context: any) {
    // 初始化工具
    this.accountGen = new AccountGenerator({
      emailDomain: 'tempmail.com'
    });
    await this.accountGen.initialize();

    this.db = new DatabaseClient({
      host: 'localhost',
      database: 'accounts'
    });
    await this.db.initialize();

    this.cardGen = new CardGenerator({
      database: this.db
    });
    await this.cardGen.initialize();

    // 生成账号（如果需要）
    if (!context.data.account.email) {
      context.data.account = await this.accountGen.generate();
    }
  }

  getHandlers() {
    return {
      generateCard: async () => {
        const card = await this.cardGen.generate();
        this.context.data.card = card;
        return { success: true, data: card };
      },
      
      saveToDatabase: async () => {
        await this.db.saveAccount(this.context.data.account);
        await this.db.saveCard(this.context.data.card);
        return { success: true };
      }
    };
  }
}

---

✅ 迁移优势

1. 类型安全 - 全TypeScript，编译时检查
2. 统一规范 - 所有工具实现ITool接口
3. 易测试 - 接口明确，方便mock
4. 可扩展 - 新工具遵循同样规范
5. 解耦 - 工具独立，adapter组合使用

---

📅 迁移计划

第一阶段：核心工具（当前）

• ITool接口规范
• AccountGenerator
• DatabaseClient（优先）
• CardGenerator

第二阶段：扩展工具

• EmailHandler
• CaptchaSolver

第三阶段：测试和优化

• 单元测试
• 集成测试
• 性能优化

---

🚀 开始使用

当前可以直接使用：

# 只需设置AdsPower ID
export ADSPOWER_USER_ID="your-id"

# 运行（会自动生成账号）
pnpm run run -- windsurf

账号数据完全由 AccountGenerator 自动生成！