# 如何使用自动化框架

## 🚀 快速开始

### 1. 安装依赖

```bash
cd browser-automation-ts
npm install
```

### 2. 配置环境变量

创建 `.env` 文件或设置环境变量：

```bash
# AdsPower配置（必需）
ADSPOWER_USER_ID=your-profile-id
ADSPOWER_API=http://local.adspower.net:50325

# 账号信息（按网站命名）
# Windsurf
WINDSURF_EMAIL=your-email@example.com
WINDSURF_PASSWORD=your-password

# Stripe
STRIPE_EMAIL=your-email@example.com
STRIPE_PASSWORD=your-password

# 通用测试账号（可选，作为默认值）
TEST_EMAIL=test@example.com
TEST_PASSWORD=test123
```

### 3. 添加网站配置

将网站的YAML配置文件放到 `configs/sites/` 目录：

```
browser-automation-ts/
├── configs/
│   └── sites/
│       ├── windsurf.yaml    ← 你的配置文件
│       ├── stripe.yaml
│       └── github.yaml
```

### 4. 运行自动化

```bash
# 运行Windsurf自动化
npm run run -- windsurf

# 运行Stripe自动化
npm run run -- stripe

# 运行任意网站
npm run run -- <网站名称>
```

---

## 📝 创建新网站配置

### YAML配置格式

```yaml
# configs/sites/my-site.yaml
site: my-site

workflow:
  # 1. 导航到网站
  - action: navigate
    name: "打开首页"
    url: https://example.com
    
  # 2. 等待页面加载
  - action: wait
    type: delay
    duration: 2000
  
  # 3. 点击按钮
  - action: click
    name: "点击登录按钮"
    selector: "#login-button"
  
  # 4. 填写表单
  - action: fillForm
    name: "填写登录表单"
    fields:
      email: "{{account.email}}"
      password: "{{account.password}}"
  
  # 5. 提交
  - action: click
    selector: "button[type='submit']"
  
  # 6. 验证成功
  - action: verify
    name: "验证登录成功"
    conditions:
      success:
        - urlContains: "/dashboard"
        - elementExists: ".user-profile"
```

### 支持的Action类型

| Action | 说明 | 示例 |
|--------|------|------|
| **navigate** | 导航到URL | `url: "https://example.com"` |
| **click** | 点击元素 | `selector: "#button"` |
| **wait** | 等待 | `type: delay, duration: 2000` |
| **fillForm** | 填写表单 | `fields: { email: "{{account.email}}" }` |
| **verify** | 验证条件 | `conditions: { success: [...] }` |
| **custom** | 自定义逻辑 | `handler: "myFunction"` |
| **scroll** | 滚动页面 | `type: bottom` |
| **extract** | 提取数据 | `selector: ".data", saveTo: "result"` |
| **retryBlock** | 重试块 | `steps: [...], maxRetries: 3` |

### 变量替换

在YAML中可以使用变量：

```yaml
# 账号数据（从环境变量加载）
email: "{{account.email}}"
password: "{{account.password}}"

# 网站配置
url: "{{site.url}}"

# 环境变量
apiKey: "{{env.API_KEY}}"

# 默认值
timeout: "{{config.timeout|30000}}"
```

---

## 🔧 环境变量命名规则

### 格式：`网站名_字段名`

```bash
# 网站名转大写，连字符改下划线
# windsurf → WINDSURF
WINDSURF_EMAIL=xxx
WINDSURF_PASSWORD=xxx

# my-site → MY_SITE
MY_SITE_EMAIL=xxx
MY_SITE_PASSWORD=xxx
```

### 支持的字段

- `EMAIL` - 邮箱
- `PASSWORD` - 密码
- `USERNAME` - 用户名
- `PHONE` - 手机号
- `APIKEY` - API密钥
- `TOKEN` - 令牌

---

## 📂 项目结构

```
browser-automation-ts/
├── cli/                    # CLI工具
│   └── run.ts             # 主执行文件
├── configs/               # 配置文件
│   └── sites/            # 网站YAML配置
│       ├── windsurf.yaml
│       └── ...
├── src/                   # 源代码
│   ├── core/             # 核心类
│   ├── providers/        # Provider实现
│   │   └── adspower/    # AdsPower Provider
│   │       ├── actions/ # 9个Action类
│   │       └── core/    # ActionFactory等
│   └── workflow/         # WorkflowEngine
└── package.json
```

---

## 🎯 使用示例

### 示例1：运行Windsurf自动化

```bash
# 1. 复制windsurf.yaml到configs/sites/
cp ../src/tools/automation-framework/configs/sites/windsurf.yaml configs/sites/

# 2. 设置环境变量
export ADSPOWER_USER_ID=your-profile-id
export WINDSURF_EMAIL=your-email@example.com
export WINDSURF_PASSWORD=your-password

# 3. 运行
npm run run -- windsurf
```

### 示例2：添加新网站

```bash
# 1. 创建配置文件
cat > configs/sites/github.yaml << EOF
site: github
workflow:
  - action: navigate
    url: https://github.com/login
  - action: fillForm
    fields:
      login: "{{account.email}}"
      password: "{{account.password}}"
  - action: click
    selector: "input[type='submit']"
EOF

# 2. 设置环境变量
export GITHUB_EMAIL=your-email@example.com
export GITHUB_PASSWORD=your-password

# 3. 运行
npm run run -- github
```

---

## 🐛 调试

### 查看可用配置

运行不带参数的命令会列出所有可用配置：

```bash
npm run run
```

### 输出说明

执行时会显示：
- ✅ 成功的步骤
- ❌ 失败的步骤
- ⏸️ 等待状态
- 📊 最终统计

### 常见问题

**Q: "Config file not found"**
- 确认YAML文件在 `configs/sites/` 目录下
- 文件名与运行命令匹配（不含.yaml扩展名）

**Q: "AdsPower Profile ID is required"**
- 设置 `ADSPOWER_USER_ID` 环境变量

**Q: "Element not found"**
- 检查selector是否正确
- 增加wait时间
- 使用SmartSelector的多策略

---

## 🎉 完成！

现在你可以：
1. 编写YAML配置
2. 设置环境变量
3. 运行 `npm run run -- 网站名`
4. 自动化执行✨