# Facebook AI 自动化工具

这是一个正在从 `Web 管理后台 + 主代码浏览器执行器` 原型升级为 `智能 Facebook 运营人` 的项目。目标是让 OpenClaw 根据你的自然语言要求创建每日运营计划、发布新鲜事/群组内容、处理客户消息、基于知识库回复、跨帖子/小组/Marketplace 等渠道挖掘客户，并把评论人与评论内容保存成可分析的结构化表格。

新产品蓝图见 [docs/facebook-operator-redesign.md](/Users/momo/Project/Facebook-auto/docs/facebook-operator-redesign.md)。当前代码仍有不少原型痕迹，后续实现应优先按这份蓝图重构数据模型、任务编排和线索表。

安装部署和客户交付步骤见 [docs/installation-deployment-guide.md](/Users/momo/Project/Facebook-auto/docs/installation-deployment-guide.md)。

商用客户端第一阶段远程更新方案见 [docs/remote-update.md](/Users/momo/Project/Facebook-auto/docs/remote-update.md)。

## 架构

- Web 后台：Next.js + TypeScript。
- 本地存储：`data/db.json`。
- 主代码浏览器执行器：当前默认实现位于 [lib/browser-executor.ts](/Users/momo/Project/Facebook-auto/lib/browser-executor.ts)，通过 Chrome DevTools Protocol 控制当前 Chrome。
- 执行器通信：OpenClaw 创建任务后，后台直接触发 browser 执行器。

## 已实现功能

- 浏览器登录态：执行器检测 Facebook 页面登录态并同步到后台。
- 执行器任务队列：后台创建任务，执行器在已登录浏览器中执行。
- 发布任务：执行器将发布内容复制到剪贴板，并尝试打开 Facebook 发布框，最后由人工确认发布。
- 搜索商机：通过关键词跨帖子、视频/Reels、小组、Marketplace 等渠道采集评论人和来源。
- 评论采集：执行器打开评论区、切换排序、展开评论/回复，并保存评论人与评论内容。
- AI + RAG 客服：生成待人工审核的客服回复，预留知识库检索入口。

## 运行 Web 后台

```bash
npm install
npm run dev
```

如果你希望启动项目时顺手打开你当前有登录态的 Chrome，并进入 Facebook：

```bash
npm run dev:facebook
```

如果你需要主代码直接接管 Chrome，则 Chrome 必须开启远程调试端口。可以用：

```bash
npm run dev:facebook:debug
```

如果你坚持使用你日常已经登录的 Chrome，则需要用相同用户数据目录重新以 `--remote-debugging-port=9222` 启动。普通已经打开、没有调试端口的 Chrome，主代码无法直接接管，这是 Chrome 的安全边界。部分新版 Chrome 还会禁止默认日常资料目录开启远程调试；这种情况下脚本会自动改用项目专用资料目录 `~/.facebook-auto-chrome`，需要在该窗口里登录 Facebook 一次。

更贴近日常 Chrome 登录态的方式：

```bash
npm run chrome:debug:current
npm run dev
```

如果脚本提示 Chrome 已经在普通模式运行，请先手动退出 Chrome（Cmd+Q），再运行 `npm run chrome:debug:current`。它不会使用单独自动化资料，目标是复用你日常 Chrome 的 Facebook 登录态。

打开：

```text
http://localhost:3000
```

## 使用流程

1. 在 Web 后台创建浏览器执行任务。
2. 默认 `browser` 模式会由主代码直接连接 CDP Chrome 执行任务。
3. 结果回传到后台任务队列表格。

## 重要说明

- 当前版本不会保存 Facebook 账号密码。
- 当前版本不绕过 Facebook 登录、验证码、风控或权限限制。
- 发布任务默认需要人工最终确认，避免误发内容。
- 后续可以扩展为更完整的页面自动化执行器，例如任务 DSL、步骤录制、选择器配置、失败截图和任务重试。

## 生产化建议

1. 后台改用 PostgreSQL/MySQL 保存任务、计划、评论和执行日志。
2. 执行器与后台之间加入 API Key 或设备绑定，避免任意本地请求创建任务。
3. 将任务队列迁移到 BullMQ、Temporal 或云队列。
4. RAG 接入 pgvector、Qdrant、Pinecone 等向量数据库。
5. 评论、客户消息和公开页面数据采集要遵守 Meta 平台政策；只处理当前账号有权限访问的数据。

## OpenClaw 集成

项目内置了一层面向 OpenClaw 的桥接接口，路径在 `app/api/integrations/openclaw/*`。

推荐先注册 MCP 工具层，让 OpenClaw 能直接调用本项目：

```bash
npm run openclaw:register-mcp
```

注册后，OpenClaw 会看到 `facebook-auto` MCP server，常用工具包括：

- `facebook_auto_health`
- `facebook_auto_summary`
- `facebook_auto_pending`
- `facebook_auto_create_daily_plan`
- `facebook_auto_run_operator_plan`
- `facebook_auto_create_lead_search`
- `facebook_auto_create_lead_discovery_run`
- `facebook_auto_analyze_lead_table`
- `facebook_auto_export_lead_table`
- `facebook_auto_upsert_knowledge_document`
- `facebook_auto_create_customer_service_draft`
- `facebook_auto_queue_collect_comments`
- `facebook_auto_browser_snapshot`
- `facebook_auto_check_facebook_login`
- `facebook_auto_check_publish_readiness`
- `facebook_auto_queue_publish_dry_run`
- `facebook_auto_publish_feed_post_now`
- `facebook_auto_publish_group_post_now`
- `facebook_auto_create_publish_dry_run_for_task`
- `facebook_auto_create_publish_dry_run_for_latest_task`
- `facebook_auto_approve_publish_task`
- `facebook_auto_approve_latest_publish_task`
- `facebook_auto_run_lead_fixture_regression`
- `facebook_auto_queue_send_friend_request`

这样你可以在 OpenClaw 里直接说“用某个关键词搜索商机”、“把这个帖子加入评论采集”或“根据知识库给客户起草回复”，OpenClaw 会通过 MCP 工具调用本项目 API，再由主代码 browser 执行器同步执行任务。

项目只关心 OpenClaw 之后的执行链路。上游指令可以来自微信、OpenClaw Web UI、OpenClaw CLI 或其他入口，但这些入口不属于本项目职责，也不应该作为浏览器是否就绪的判断依据。

实际执行链路建议固定为：

```text
上游指令入口 -> OpenClaw -> facebook-auto MCP -> 本项目任务队列 -> 主代码 browser 执行器 -> 当前已登录 CDP Chrome -> Facebook 页面
```

## 商用化工作台

当前版本已经把产品口径调整为 `Facebook AI Operator`，首页新增“商用工作台”：

- 套餐授权：`starter / growth / pro / enterprise`，本地记录客户名、到期时间、席位和 Facebook 账号数。
- 今日风控预算：按套餐和本地风控设置展示商机发现、发布、加好友、客服回复的日用量。
- 人工确认策略：发布、加好友、私信默认显示为需确认，适合商业交付时降低误操作风险。
- 商用模块状态：集中查看商机发现、客服助手、内容发布和执行证据状态。
- 操作审计：从任务、商机搜索、CRM 和 Messenger 记录生成时间线，便于客户复盘“系统做了什么”。

商用状态 API：

- `GET /api/commercial`：返回套餐、授权、风控预算、使用量、模块状态和审计摘要。
- `GET /api/commercial/license`：读取本地授权和风控配置。
- `POST /api/commercial/license`：更新本地授权、到期时间、套餐和风控配置。

当前授权 gate 已接入关键写动作：商机发现、内容发布、加好友任务和 Messenger 回复任务会先检查授权状态、到期时间和今日额度；发布/加好友/私信默认按风控设置进入人工确认流程。

远程心跳授权由外部 Web 授权后台提供。本项目只保留客户端能力：在“商用工作台”保存云端 License Server URL 和 License Key，并刷新心跳。商业动作执行前会检查远程租约：

- `leaseExpiresAt` 未过期：正常执行。
- 租约过期但最近成功心跳仍在 `graceHours` 内：进入宽限期，默认 5 小时。
- 远程状态为 `expired / suspended` 或超过宽限期：阻止商机搜索、发布、加好友、客服发送等商业动作。

关键词商机搜索支持后续动作参数：

- `searchType: "posts"`：公共帖子评论人。
- `searchType: "videos"`：视频/Reels 评论人。
- `searchType: "groups"`：先找小组，再进入小组内关键词帖子采集评论人。
- `searchType: "marketplace"`：采集商品/卖家线索。
- `searchType: "all"`：按渠道分别执行帖子、视频/Reels、小组和 Marketplace 搜索，再合并评论人、卖家/商品线索和来源证据。
- `searchVariants: true`：默认开启，把关键词自动扩展为 `price / wholesale / where to buy / supplier / interested` 等商业意图搜索词，多轮搜索后合并排序。
- `autoRetryOnLowQuality: true`：默认开启；如果首轮评论人缺少询价、购买、私信、发货等商业信号，系统会自动追加 Marketplace、售卖帖、求购词重搜并去重合并。
- `autoSaveLeads: true`：AI 分析后把达到阈值的评论人保存到 CRM。
- `autoAddFriends: true`：AI 分析后给达到阈值的评论人排队加好友任务。
- `minAiScore`：默认 `70`。
- `friendRequestLimit`：默认 `10`，避免一次性加太多人。

保存到 CRM 的线索会保留 `sourceChannel / sourceType / sourceTitle / sourceUrl / sourceScore`，方便后续按帖子、群组、Reels 或 Marketplace 来源筛选和复盘。

规范化线索表和导出 CSV 还会保留 `sourceEvidence`，用于回查具体证据链接。CRM 保存会按归一化的 Facebook 身份做 upsert，并保留 `lastSeenAt`、`mergeCount` 和来源历史，避免同一人被重复堆成多条。

帖子评论采集现在会先尝试打开评论区、切换“全部评论/最新”、展开更多评论和回复，并按评论行抽取评论人；采集结果会排除检测到的帖主本人评论，并把来源类型、来源标题、来源评分、理由和新评论一起保存到本地评论线索。

不同渠道会使用不同的评论区准备策略：普通帖优先切“全部评论”，小组帖会更多轮展开评论/回复，视频/Reels 会优先处理评论面板和可滚动评论容器。采集轨迹里会记录 `strategy / opened / sort / expandClicks / articleCount`，用于判断是页面权限、评论面板还是展开按钮导致漏采。

主代码 browser 执行器内置了基础风控和失败证据：

- `FACEBOOK_AUTO_PROGRESS_NOTIFY`：关键进度主动通知 OpenClaw，默认 `true`。
- `FACEBOOK_AUTO_FRIEND_DAILY_LIMIT`：每日加好友上限，默认 `12`。
- `FACEBOOK_AUTO_PUBLISH_DAILY_LIMIT`：每日自动发帖上限，默认 `8`。
- `FACEBOOK_AUTO_FRIEND_DELAY_MIN_MS` / `FACEBOOK_AUTO_FRIEND_DELAY_MAX_MS`：加好友前随机延迟，默认 `8000-25000` 毫秒。
- 任务失败会保存截图和页面按钮列表到 `/executor-evidence/*`，任务结果里会记录证据路径。

发新鲜事/群组帖子支持 `mediaUrls` 或 `mediaBase64`。当你在 OpenClaw 里明确说“发布/发出/现在发”时，推荐直接使用 `facebook_auto_publish_feed_post_now` 或 `facebook_auto_publish_group_post_now`，它会自动完成“创建草稿 -> dry-run -> 自动批准 -> 真实发布”的整条链路。需要人工审核时，再使用 `queue_publish_*` 加 `create_publish_dry_run_for_task` / `approve_publish_task` 的分步流程。

HTTP API 仍然保留为兜底能力：

- `GET /api/integrations/openclaw/health`
- `GET /api/integrations/openclaw/summary`
- `GET /api/integrations/openclaw/pending`
- `POST /api/integrations/openclaw/action`

这些接口使用 `OPENCLAW_SHARED_TOKEN` 进行鉴权，适合让 OpenClaw skill 通过 `curl` 访问。

同时，项目也支持在配置后主动通知 OpenClaw：

- `OPENCLAW_GATEWAY_URL`
- `OPENCLAW_HOOK_TOKEN`
- `OPENCLAW_HOOK_MODE`
- `OPENCLAW_HOOK_PATH`

推荐配合 OpenClaw 的 webhook hooks 使用，文档见：

- `docs/openclaw-integration.md`
- `openclaw/facebook-auto-ops/SKILL.md`
