# SakuraFrp 自动签到脚本

使用 Playwright 驱动浏览器，并通过 AI 视觉识别完成 SakuraFrp 九宫格验证码签到。

## 功能特性

- 自动登录 SakuraFrp 账户
- AI 视觉识别九宫格验证码
- 自动点击匹配的验证码格子
- 失败自动重试，默认最多 10 次
- 支持 GitHub Actions 定时执行
- 支持邮件通知和日志归档

## 本地运行

### 1. 环境准备

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

本项目默认优先使用本机已安装的 Chrome，不需要下载 ChromeDriver，也不强制执行 `playwright install chromium`。

如果本机没有 Chrome，或希望使用 Playwright 托管浏览器，可以执行：

```bash
python -m playwright install chromium
```

### 2. 配置环境变量

创建 `.env` 文件：

```env
SAKURAFRP_USER=your_username
SAKURAFRP_PASS=your_password

BASE_URL=https://api.example.com/v1
API_KEY=your_api_key
MODEL=your_model_name

MAX_RETRIES=10
HEADLESS=false
CHROME_BINARY_PATH=

# 是否将验证码图片转换为 base64（可选）
# 可接受：true/false, 1/0, yes/no, on/off
# 通过第三方适配器接入的服务可能不支持直接使用图片 URL，此时设为 true。
IMAGE_AS_BASE64=false
```

`CHROME_BINARY_PATH` 可选。留空时会自动查找系统 Chrome；如果你的 Chrome 不在默认位置，可以显式指定：

```env
CHROME_BINARY_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe
```

Playwright 只复用 Chrome 可执行文件，不会读取你日常 Chrome 的用户目录、Cookie、历史记录或扩展。

### 3. 运行脚本

```bash
python main.py
```

## GitHub Actions 部署

工作流文件位于 `.github/workflows/sakurafrp_sign.yml`，默认每天北京时间 9:00 执行，也支持手动触发。

需要配置以下 Secrets：

| 名称 | 说明 |
| --- | --- |
| `SAKURAFRP_USER` | SakuraFrp 用户名 |
| `SAKURAFRP_PASS` | SakuraFrp 密码 |
| `BASE_URL` | OpenAI 兼容 API 地址 |
| `API_KEY` | API 密钥 |
| `MODEL` | 多模态模型名称 |

邮件通知为可选配置：

| 名称 | 说明 |
| --- | --- |
| `EMAIL_USERNAME` | 发件邮箱 |
| `EMAIL_PASSWORD` | 邮箱授权码或应用密码 |
| `RECEIVER_EMAIL` | 收件邮箱，默认发给自己 |
| `SMTP_SERVER` | SMTP 服务器，默认 `smtp.gmail.com` |
| `SMTP_PORT` | SMTP 端口，默认 `587` |

Actions 使用 GitHub runner 自带 Chrome，并执行 `python -m playwright install-deps chromium` 安装 Linux 运行依赖，避免每次下载 Playwright Chromium 大包。

## 项目结构

```text
SakuraFrp-Qiandao/
├── .github/workflows/sakurafrp_sign.yml
├── automation.py          # Playwright 签到主流程
├── captcha_handler.py     # GeeTest 验证码识别和点击
├── config.py              # 环境变量和日志配置
├── human_simulator.py     # 简单人类操作模拟
├── main.py                # 程序入口
├── send_email.py          # 邮件通知
├── requirements.txt       # Python 依赖
└── README.md
```

## 配置说明

### 定时任务时间

修改 `.github/workflows/sakurafrp_sign.yml` 中的 cron 表达式：

```yaml
schedule:
  - cron: '0 1 * * *'  # UTC 1:00 = 北京时间 9:00
```

常用时间对照：
- `0 1 * * *` - 每天 9:00（北京时间）
- `0 13 * * *` - 每天 21:00（北京时间）
- `0 1,13 * * *` - 每天 9:00 和 21:00

### AI 模型推荐

支持任何兼容 OpenAI API 的多模态模型：

- OpenAI: `gpt-4o`
- 阿里通义: `qwen-vl-plus`, `qwen-vl-max`
- 智谱 AI: `glm-4v`
- GitHub Copilot: 可通过第三方 OpenAI 兼容适配层接入
- ModelScope: 各种开源视觉模型

## 故障排查

### 验证码识别失败

尝试更换更强的视觉模型，或增加 `MAX_RETRIES`。模型需要支持图片输入，并兼容 OpenAI Chat Completions API。

### 模型返回非标准响应

脚本会记录完整响应结构。如果响应中包含 `error` 或 `errors`，会直接终止，因为刷新验证码无法修复模型 API 错误。

### Playwright 下载 Chromium 失败

如果出现 `timed out`、`ECONNRESET` 或 `Failed to download Chrome for Testing`，通常是网络到 Playwright/CDN 下载源不稳定。推荐直接使用系统 Chrome，并在 `.env` 中按需设置 `CHROME_BINARY_PATH`。

### 登录失败

检查 `SAKURAFRP_USER` 和 `SAKURAFRP_PASS` 是否正确，必要时关闭无头模式查看页面行为：

```env
HEADLESS=false
```

### 未收到邮件

确认邮箱开启 SMTP，并使用授权码或应用专用密码，不要直接使用普通登录密码。

## 注意事项

请勿频繁触发签到，避免被限流。妥善保管账号密码、API Key 和邮箱授权码。

## 相关链接

- [SakuraFrp 官网](https://www.natfrp.com/)
- [Playwright 文档](https://playwright.dev/python/)
- [GitHub Actions 文档](https://docs.github.com/en/actions)
- [copilot-api](https://github.com/caozhiyuan/copilot-api)
- [LiteLLM](https://github.com/BerriAI/litellm)