275 lines
5.4 KiB
Markdown
275 lines
5.4 KiB
Markdown
# 如何使用自动化框架
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 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. 自动化执行✨
|