文档 / Documentation

安装 / Installation

AutoWave 是绿色版 ZIP，无需管理员权限。完整步骤：
AutoWave is a portable ZIP — no admin needed. Steps:

1. 从 下载页 获取最新 ZIP。/ Get the latest ZIP from the download page.
2. 解压到非 OneDrive 路径（路径不要含中文/空格）。/ Extract to a non-OneDrive path (no Chinese/spaces).
3. 双击 AutoWave.exe。/ Double-click AutoWave.exe.
4. 首次启动会创建 config/、output/、logs/ 三个目录。/ First launch creates three folders.

BitBrowser 配置 / BitBrowser Setup

AutoWave 不自带浏览器内核，全部委托给 BitBrowser。3 步完成：
AutoWave delegates browser kernel to BitBrowser entirely. Three steps:

1. 启用 Local API / Enable Local API

BitBrowser → 设置 → "启用 API 接口"，确认端口为默认的 54345。

2. 准备 profile / Prepare profiles

每个 profile 必须配置好代理和指纹。AutoWave 不修改这些——它只调用 BitBrowser 已配置好的 profile。

3. 健康检查 / Health check

启动 AutoWave → 点 Health Check 按钮 → 应该看到所有 profile 列表。

# 命令行验证 / CLI verification
curl http://127.0.0.1:54345/browser/list \
  -H "Content-Type: application/json" \
  -d '{"page": 0, "pageSize": 10}'

首次运行 / First Run

建议第一次跑 detect-login 任务，确认浏览器能正常打开 + FB 已登录。1 个 seq 即可：
For your first run, do a detect-login task on 1 seq:

# GUI: 打开 AutoWave → 选 1 个 seq → 任务类型选 detect-login → 跑
# CLI:
autowave detect --profiles "25190"

预期输出：LOGGED_IN（已登录）、NOT_LOGGED_IN（未登录，会自动关闭浏览器）、CHECKPOINT（FB 检查站，需要人工处理）。
Expected output: LOGGED_IN / NOT_LOGGED_IN (auto-closes browser) / CHECKPOINT (needs manual handling).

22 种任务类型 / 22 Task Types

每种任务都有独立的参数 schema 和结果 schema。模板自带下拉验证。
Each task type has its own params/result schema. Template ships with dropdown validation.

Excel 工作流 / Excel Workflow

AutoWave 设计的初衷是给运营用，所以核心交互是 Excel：
AutoWave is designed for ops people, so Excel is the core interaction:

1. 生成模板 / Generate template — CLI: autowave template --output ./templates
2. 填写任务 / Fill tasks — Sheet1 每行一个任务：seq、task_type、params_json
3. 执行 / Execute — CLI: autowave excel-run --file tasks.xlsx
4. 结果 / Results — 同名 Excel 文件 autowave-YYYYMMDD-N.xlsx（永不覆盖，N 自动递增）

报告 4 表 / Report 4 sheets

• Tasks — 每个任务的完整结果
• Summary — 按 task_type 汇总
• Errors — 失败任务的详细错误
• Profiles — 按 seq 汇总（成功率、平均耗时）

CLI 命令 / CLI Commands

# 帮助 / Help
autowave --help

# 检测登录状态 / Detect login
autowave detect --profiles "25190,25491"

# 跑指定 workflow / Run workflow
autowave run --profiles "25190" --workflow basic-nurture

# Excel 任务执行 / Excel task run
autowave excel-run --file ./tasks.xlsx

# 生成 Excel 模板 / Generate template
autowave template --output ./templates

# 列出所有任务类型 / List task types
autowave task-types

# 只看已实现的 / Implemented only
autowave task-types --implemented-only

反检测原理 / Anti-Detection

AutoWave 把反检测拆成 15 条强制规则。挑核心几条说明：
AutoWave codifies anti-detection into 15 mandatory rules. The core ones:

规则 1 — 点击式导航 / Click-nav

FB 站内跳转必须通过点击（logo / 侧边栏 / 按钮）完成。page.goto() 仅用于首次进入或无法点击到达的页面。
FB in-site navigation must use click (logo / sidebar / buttons). page.goto() only for initial entry or unreachable pages.

规则 11 — 按账号派生指纹 / Per-profile personality

所有时长类参数通过 personalizedDelay(profileId, range, field) 按 SHA-256 派生。同一 profileId 永远得到相同性格。
All durations derived per profileId via SHA-256. Same profileId always yields same personality.

规则 12 — 永不空 referrer / Never-empty referrer

任何 page.goto(url) 必须设置 referer。FB 域 → facebook.com；首次进入 → google.com。
Every page.goto(url) must set referer. FB domain → facebook.com; first entry → google.com.

规则 13 — 视频按上下文判断静音 / Context-aware muting

Autoplay 背景视频静音；用户主动观看的视频不静音（直播限速场景例外）。
Mute autoplay/background; never mute user-clicked videos (live-throttle context excepted).

规则 15 — 只拦 analytics + fonts / Resource block: analytics + fonts only

禁止拦截图片/媒体/CSS/XHR——真人浏览器不会在网络层把图全拦掉。
Forbidden to block images/media/CSS/XHR — real browsers never block them at network level.

疑难解答 / Troubleshooting

白屏 / White screen

AutoWave 自动检测 about:blank 并触发 forceClose → reconnect（最多 2 次）。如果连续白屏，通常是代理问题，检查 BitBrowser profile 的代理配置。
AutoWave auto-detects about:blank and triggers forceClose → reconnect (max 2x). If persistent, usually a proxy issue.

代理错误 / Proxy errors

7 种已知代理错误模式（SOCKS / ERR_PROXY / ERR_CONNECTION_REFUSED 等）会标记为"代理异常"且不触发重启（重启解决不了代理问题）。
7 known proxy patterns marked as "proxy error" and won't trigger restart (restart can't fix proxy).

CHECKPOINT

FB checkpoint 3 种类型：1501092823525282（人脸验证）/ 828281030927956（需要认证）/ 601051028565049（自动化提示，FB hint 非死刑）。AutoWave 检测到立即停止业务步骤 + 释放 profile，不重试。
3 official FB checkpoint types — AutoWave short-circuits, releases profile, no retry.

账号"已被打开" / "Already opened"

BitBrowser 报"已打开/不允许多个账号同时打开"——AutoWave 标记为 NOT_RETRYABLE 直接跳过，备注谁正在使用。
BitBrowser "already opened" → marked NOT_RETRYABLE, skipped with note about who's using it.

FAQ

没找到你要的？写信给 support@autowave.dev 或加 Telegram @autowave。
Didn't find what you need? Email support@autowave.dev or join Telegram.