autoUpload/utils/README_human_typing.md

# 人类化输入包装器 (HumanTypingWrapper)

## 概述

`HumanTypingWrapper` 是一个基于 Playwright 的人类化输入包装器，旨在模拟真实人类的打字行为。它提供了随机时间间隔输入、可变输入速度、偶尔的错误修正以及其他人类特征的模拟。

## 主要特性

### 🎯 核心功能
- **随机输入速度**：模拟人类不同的打字速度
- **思考停顿**：随机的停顿，模拟思考过程
- **错误修正**：偶尔输入错误字符并及时修正
- **疲劳效应**：长时间输入后速度逐渐减慢
- **分段输入**：长文本自动分段输入，更自然

### 🛡️ 反检测特性
- **键盘邻键错误**：基于真实键盘布局的错误模拟
- **退格重输**：偶尔删除并重新输入字符
- **自然停顿**：在标点符号后适当停顿
- **点击延迟**：点击前后的随机延迟

### 🔧 高度可配置
- 所有参数都可以自定义
- 支持不同场景的预设配置
- 运行时动态调整配置

## 快速开始

### 基础使用

```python
from playwright.async_api import async_playwright
from utils.human_typing_wrapper import create_human_typer

async def basic_example():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=False)
        page = await browser.new_page()
        
        # 创建人类化输入器
        typer = create_human_typer(page)
        
        # 访问目标页面
        await page.goto("https://example.com")
        
        # 人类化输入文本
        await typer.type_text_human("#username", "我的用户名")
        await typer.type_text_human("#password", "我的密码")
        
        # 人类化点击
        await typer.human_click("#login-button")
        
        await browser.close()
```

### 自定义配置

```python
from utils.human_typing_wrapper import HumanTypingWrapper

# 自定义配置
custom_config = {
    'min_typing_speed': 2,      # 最小输入速度 (字符/秒)
    'max_typing_speed': 6,      # 最大输入速度 (字符/秒)
    'pause_probability': 0.20,  # 停顿概率 (20%)
    'correction_probability': 0.15,  # 错误修正概率 (15%)
    'fatigue_effect': True,     # 启用疲劳效应
}

# 使用自定义配置
typer = HumanTypingWrapper(page, custom_config)
```

## 配置选项

### 输入速度设置
```python
{
    'min_typing_speed': 2,      # 最小打字速度 (字符/秒)
    'max_typing_speed': 10,     # 最大打字速度 (字符/秒)
}
```

### 思考停顿设置
```python
{
    'pause_probability': 0.15,     # 停顿概率 (15%)
    'min_pause_duration': 0.3,     # 最小停顿时长 (秒)
    'max_pause_duration': 2.5,     # 最大停顿时长 (秒)
}
```

### 错误修正设置
```python
{
    'correction_probability': 0.10,    # 错误修正概率 (10%)
    'backspace_probability': 0.05,     # 退格重输概率 (5%)
}
```

### 点击延迟设置
```python
{
    'click_delay_before': (0.1, 0.4),  # 点击前延迟范围
    'click_delay_after': (0.2, 0.6),   # 点击后延迟范围
}
```

### 分段输入设置
```python
{
    'chunk_input': True,           # 启用分段输入
    'max_chunk_length': 50,        # 每段最大长度
    'chunk_pause_duration': (0.5, 1.5),  # 段落间停顿时长
}
```

### 疲劳效应设置
```python
{
    'fatigue_effect': True,        # 启用疲劳效应
    'fatigue_threshold': 100,      # 疲劳阈值 (字符数)
    'fatigue_slowdown': 0.3,       # 疲劳减慢比例 (30%)
}
```

## API 参考

### 主要方法

#### `type_text_human(selector, text, clear_first=True)`
在指定元素中人类化输入文本
- `selector`: CSS选择器
- `text`: 要输入的文本
- `clear_first`: 是否先清空现有内容

#### `human_click(selector, wait_after=True)`
人类化点击元素
- `selector`: CSS选择器  
- `wait_after`: 点击后是否等待

#### `human_scroll(direction="down", amount=3)`
人类化滚动页面
- `direction`: 滚动方向 ("up" 或 "down")
- `amount`: 滚动次数

#### `click_and_type(selector, text, **kwargs)`
点击元素并输入文本的便捷方法

#### `update_config(new_config)`
更新配置参数

## 使用场景

### 1. 微信公众号自动发布
```python
# 微信公众号专用配置
wechat_config = {
    'min_typing_speed': 3,
    'max_typing_speed': 7,
    'pause_probability': 0.20,
    'correction_probability': 0.08,
    'chunk_input': True,
    'max_chunk_length': 30,
}

typer = create_human_typer(page, wechat_config)
await typer.type_text_human("#title", "文章标题")
await typer.type_text_human(".ProseMirror", "文章内容...")
```

### 2. 表单填写
```python
# 表单填写配置
form_config = {
    'min_typing_speed': 4,
    'max_typing_speed': 8,
    'pause_probability': 0.10,
    'correction_probability': 0.05,
}

typer = create_human_typer(page, form_config)
await typer.type_text_human("#name", "张三")
await typer.type_text_human("#email", "zhangsan@example.com")
await typer.type_text_human("#phone", "13800138000")
```

### 3. 搜索查询
```python
# 搜索查询配置
search_config = {
    'min_typing_speed': 5,
    'max_typing_speed': 12,
    'pause_probability': 0.05,
    'correction_probability': 0.12,
}

typer = create_human_typer(page, search_config)
await typer.type_text_human("#search-box", "人工智能发展趋势")
await typer.human_click("#search-button")
```

## 最佳实践

### 1. 配置选择
- **谨慎场景**（银行、支付）：低错误率，慢速输入
- **一般场景**（社交媒体）：中等错误率，正常速度
- **测试场景**：高错误率，观察效果

### 2. 性能优化
- 对于长文本，启用分段输入
- 根据网站响应速度调整延迟
- 在无头模式下适当提高速度

### 3. 反检测策略
- 避免过于规律的操作模式
- 在关键操作前增加适当停顿
- 模拟真实的浏览行为

## 注意事项

1. **兼容性**：支持同步和异步 Playwright 页面
2. **性能影响**：人类化操作会显著增加执行时间
3. **检测规避**：合理配置参数以避免被反爬虫系统识别
4. **错误处理**：所有方法都包含异常处理，返回成功/失败状态

## 示例文件

- `examples/human_typing_example.py` - 基础使用示例
- `examples/wechat_human_typing_integration.py` - 微信公众号集成示例

## 许可证

此项目遵循与主项目相同的许可证。