auto-account-machine/browser-automation-ts/PLUGIN-SYSTEM-STATUS.md

# 插件系统实现状态

## ✅ 已完成

### 1. 核心基础设施

#### ITool.ts - Tool基础接口和抽象类
```typescript
interface ITool<TConfig> {
  readonly name: string;
  initialize(config: TConfig): Promise<void>;
  cleanup?(): Promise<void>;
  healthCheck?(): Promise<boolean>;
}

abstract class BaseTool<TConfig> implements ITool<TConfig> {
  // 强制子类实现配置验证
  protected abstract validateConfig(config: TConfig): void;
  // 强制子类实现初始化逻辑
  protected abstract doInitialize(): Promise<void>;
  // 提供状态检查
  protected ensureInitialized(): void;
}
```

**作用：**
- ✅ 强制所有Tool实现统一接口
- ✅ 提供模板方法模式保证初始化流程
- ✅ 自动状态检查防止未初始化调用

#### BaseAdapter.ts - Adapter基础类
```typescript
abstract class BaseAdapter implements ISiteAdapter {
  // 强制子类注册工具
  protected abstract registerTools(): void;
  // 强制子类声明依赖
  protected abstract getRequiredTools(): string[];
  // 提供工具管理
  protected registerTool(tool: ITool): void;
  protected getTool<T>(name: string): T;
}
```

**作用：**
- ✅ 强制Adapter注册工具
- ✅ 自动验证必需工具是否注册
- ✅ 类型安全的工具获取
- ✅ 统一的初始化流程

### 2. 第一个Tool实现

#### AccountGeneratorTool - 账号生成器
```typescript
class AccountGeneratorTool extends BaseTool<AccountGeneratorConfig> {
  async generate(): Promise<AccountData>
}
```

**功能：**
- ✅ 生成随机邮箱
- ✅ 生成强密码
- ✅ 生成随机姓名
- ✅ 生成手机号
- ✅ 支持配置（域名、密码长度等）

### 3. 示例Adapter实现

#### WindsurfAdapter
```typescript
class WindsurfAdapter extends BaseAdapter {
  protected registerTools() {
    // 注册工具并配置
    this.registerTool(new AccountGeneratorTool({
      emailDomain: 'tempmail.com',
      passwordLength: 12
    }));
  }
  
  getHandlers() {
    // 提供custom action处理
    return { generateCard, handleEmailVerification, ... };
  }
}
```

**演示了：**
- ✅ 如何注册工具
- ✅ 如何配置工具
- ✅ 如何使用工具
- ✅ 如何编排业务逻辑

---

## 📋 架构图

```
┌─────────────────────────────────────────┐
│        ISiteAdapter (接口)               │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│      BaseAdapter (抽象基类)              │
│  ┌──────────────────────────────────┐  │
│  │ 工具管理                          │  │
│  │ - registerTool()                 │  │
│  │ - getTool()                      │  │
│  │ - validateRequiredTools()        │  │
│  └──────────────────────────────────┘  │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    WindsurfAdapter (具体实现)            │
│  ┌──────────────────────────────────┐  │
│  │ 注册工具                          │  │
│  │ - AccountGeneratorTool           │  │
│  │ - DatabaseTool (TODO)            │  │
│  │ - EmailTool (TODO)               │  │
│  └──────────────────────────────────┘  │
│  ┌──────────────────────────────────┐  │
│  │ 业务逻辑                          │  │
│  │ - generateCard()                 │  │
│  │ - handleEmailVerification()      │  │
│  └──────────────────────────────────┘  │
└─────────────────────────────────────────┘
```

---

## 🚀 当前可运行

```bash
# 设置环境变量
export ADSPOWER_USER_ID="your-id"

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

**会发生什么：**
1. ✅ 加载 windsurf.yaml
2. ✅ 加载 windsurf-adapter.ts
3. ✅ 注册 AccountGeneratorTool
4. ✅ 验证必需工具
5. ✅ 初始化工具
6. ✅ 自动生成账号数据
7. ✅ 执行workflow
8. ✅ 调用custom handlers

---

## ⏳ 待实现的Tool

按优先级：

### 1. DatabaseTool (高优先级)
```typescript
class DatabaseTool extends BaseTool<DatabaseConfig> {
  async connect(): Promise<void>
  async query(sql: string, params?: any[]): Promise<any>
  async save(table: string, data: any): Promise<void>
  async close(): Promise<void>
}
```

**用途：**
- 保存账号数据
- 获取卡片数据
- 标记卡为已使用

### 2. CardGeneratorTool (高优先级)
```typescript
class CardGeneratorTool extends BaseTool<CardGeneratorConfig> {
  async generate(): Promise<CardData>
  async markAsUsed(cardNumber: string): Promise<void>
}
```

**配置：**
- source: 'database' | 'api' | 'mock'
- binFilter: string[]
- reuseDelay: number

### 3. EmailTool (中优先级)
```typescript
class EmailTool extends BaseTool<EmailConfig> {
  async connect(): Promise<void>
  async getVerificationCode(options: any): Promise<string>
  async close(): Promise<void>
}
```

**配置：**
- protocol: 'imap' | 'pop3' | 'api'
- server: string
- codePattern: RegExp

### 4. CaptchaTool (低优先级)
```typescript
class CaptchaTool extends BaseTool<CaptchaConfig> {
  async solve(type: string, params: any): Promise<any>
}
```

---

## 💡 设计优势总结

### 1. 强制规范
- ❌ 不能忘记实现 `validateConfig()`
- ❌ 不能忘记注册必需的Tool
- ❌ 不能在未初始化时调用Tool
- ✅ 编译时+运行时双重检查

### 2. 类型安全
```typescript
// ✅ TypeScript知道返回类型
const accountGen = this.getTool<AccountGeneratorTool>('account-generator');
const account = await accountGen.generate();  // 有代码提示
```

### 3. 配置驱动
```typescript
// 同一个Tool，不同配置 = 不同实例
// A网站
new AccountGeneratorTool({ emailDomain: 'mail.com' })
// B网站
new AccountGeneratorTool({ emailDomain: 'qq.com' })
```

### 4. 易扩展
```typescript
// 添加新Tool：
// 1. 继承BaseTool
// 2. 实现3个方法
// 3. 在Adapter中注册
// 完成！
```

---

## 🎯 下一步

1. 实现 `DatabaseTool`
2. 实现 `CardGeneratorTool`
3. 更新 `WindsurfAdapter` 使用所有Tool
4. 测试完整流程

**现在的架构：规范即代码，无法违反！** 🎉