# Facebook Follow + Messenger 建联脚本

本目录是模块二的正式实现：从建联表生成英文社交建联预览，并通过 AdsPower + Playwright 执行 Facebook Page Follow + Messenger 私信。

## 脚本清单

| 脚本 | 作用 | 默认是否真实发送 | 默认是否写表 |
|---|---|---:|---:|
| `prepare_facebook_outreach.py` | 读取 Facebook Sheet，按客户类型生成中文判断 + 英文加好友/私信话术 JSON 预览 | 否 | 否 |
| `send_facebook_outreach.py` | 根据预览执行 Page Follow + Messenger DM；默认 dry-run，真实执行需 `--confirm` | 否 | 否 |
| `run_facebook_follow_dm.py` | 模块二总控入口：先生成预览，再调用执行脚本 dry-run 或确认发送 | 否 | 否 |
| `collect_facebook_conversations.py` | 通过 AdsPower + Playwright 只读采集已匹配客户的 Messenger 历史/增量消息 | 否 | 否 |
| `write_facebook_conversations.py` | 校验 Agent 中文翻译和五级意向分析，写入 Facebook对话记录并更新客户状态 | 否 | 需 `--write-workbook` |

## 推荐流程

1. 已在 AdsPower 指纹浏览器中登录 Facebook。
2. 运行总控脚本生成预览，确认客户和英文话术。
3. 运行 dry-run，检查脚本识别到的 Page 顶部 Follow / Message 和 Messenger 目标。
4. 用户明确确认后，加 `--confirm-send` 真实执行。
5. 只有需要回写建联表时，额外加 `--write-workbook`。

## 只生成预览

```powershell
python scripts/social/run_facebook_follow_dm.py `
  --excel "D:\WEFANBOT\摩洛哥客户建联表-按渠道分类 .xlsx" `
  --sheet Facebook `
  --profile-id k1eu4lc2 `
  --max-contacts 5 `
  --review-only
```

## Dry-run，不真实点击

```powershell
python scripts/social/run_facebook_follow_dm.py `
  --excel "D:\WEFANBOT\摩洛哥客户建联表-按渠道分类 .xlsx" `
  --sheet Facebook `
  --profile-id k1eu4lc2 `
  --max-contacts 5 `
  --use-open-page
```

## 真实执行，整批确认

```powershell
python scripts/social/run_facebook_follow_dm.py `
  --excel "D:\WEFANBOT\摩洛哥客户建联表-按渠道分类 .xlsx" `
  --sheet Facebook `
  --profile-id k1eu4lc2 `
  --max-contacts 5 `
  --use-open-page `
  --confirm-send
```

## 整批已确认后自动逐条执行

```powershell
python scripts/social/run_facebook_follow_dm.py `
  --excel "D:\WEFANBOT\摩洛哥客户建联表-按渠道分类 .xlsx" `
  --sheet Facebook `
  --profile-id k1eu4lc2 `
  --max-contacts 5 `
  --use-open-page `
  --confirm-send `
  --batch-confirmed
```

## 安全规则

- Facebook 对外发送语言固定为英文。
- 默认不写建联表；需要写表时显式加 `--write-workbook`。
- 默认且强制保持 AdsPower 浏览器打开；脚本结束时仅断开 Playwright 连接，不停止 AdsPower 配置或关闭浏览器。
- 私信只能发到 Messenger 小窗或 Messenger 私信页，且必须验证目标客户名称。
- 禁止向帖子评论框、回复框、页面底部通用输入框发送。
- 若主页 `發送訊息` 按钮不弹出 Messenger 小窗，脚本会兜底打开 `https://www.facebook.com/messages/t/<page_slug>`，验证客户名称后再发送。
- 遇到验证、限流、异常活动提示时立即停止。

## Facebook 回复同步

首次历史采集：

```powershell
python scripts/social/collect_facebook_conversations.py --excel "<建联表>" --profile-id "<profile_id>" --initial-full
```

后续增量采集将 `--initial-full` 改成 `--incremental`。Agent 必须按 `references/facebook-conversation-sync.md` 翻译和分析，并先在聊天框展示结果。写表时使用：

```powershell
python scripts/social/write_facebook_conversations.py --excel "<建联表>" --transcript "<raw.json>" --analysis "<analysis.json>" --write-workbook --refresh-summary --refresh-dashboard
```

回复同步只读取消息，不发送回复、不点击反应、不下载附件、不关闭 AdsPower。
