# Facebook Conversation Sync

Use this reference whenever the user asks to read Facebook replies, synchronize Messenger conversations, translate customer messages, assess cooperation intent, or update follow-up status from Facebook conversations.

## Mandatory Workflow

1. Read Facebook rows that contain a valid Facebook Page URL.
2. Run scripts/social/collect_facebook_conversations.py through AdsPower + Playwright.
3. Match each thread by Page URL identity/slug and visible Messenger title. Skip mismatches.
4. Preserve both directions of the conversation. Keep the original text unchanged and translate every non-Chinese message into Chinese.
5. Analyze cooperation intent only for effective customer replies.
6. Show the customer-reply summary, intent distribution, and high-intent customers in chat before workbook write-back.
7. Build an analysis JSON that follows the schema below.
8. Run scripts/social/write_facebook_conversations.py with --write-workbook --refresh-summary --refresh-dashboard.
9. After a successful local write, follow references/feishu-sync.md.

Never send a reply as part of this workflow. Only provide a Chinese next-step recommendation.

## Collection Modes

Initial full history:

    python scripts/social/collect_facebook_conversations.py --excel "<workbook>" --profile-id "<profile_id>" --initial-full

Incremental sync:

    python scripts/social/collect_facebook_conversations.py --excel "<workbook>" --profile-id "<profile_id>" --incremental

Rules:

- First use --initial-full; later runs use --incremental.
- The collector reads record IDs already stored in Facebook对话记录 and removes them from incremental output.
- Default safety limit is 2000 messages per thread. If the limit is reached, write history_truncated and report that older history may be incomplete.
- Do not collect unrelated inbox conversations. Only open threads derived from Facebook Page URLs already present in the workbook.
- Stop the batch on Facebook verification, rate limiting, suspicious activity, or temporary block prompts.
- Always leave AdsPower open. Detach Playwright only.

## Conversation Sheet

Use Sheet name Facebook对话记录 with exactly these columns:

记录ID、客户序号、客户姓名/公司、Facebook主页链接、Messenger线程ID、消息时间、消息方向、发件人、原文语言、对话原文、中文翻译、消息类型、是否有效客户回复、合作意向、意向判断依据、下一步建议、同步时间、来源账号/Profile ID、风险标记

- 消息方向: only 我方发送 or 客户回复.
- 记录ID: prefer Facebook message ID; otherwise use the collector stable hash.
- 对话原文: immutable evidence. Never overwrite it with a translation.
- 中文翻译: preserve company names, model names, prices, quantities, URLs, email addresses, and professional terms accurately.
- 消息类型: 文本, 图片, 文件, 视频, 语音, 系统消息, 自动回复, or 已读提示.
- Images/files/audio are recorded as types and descriptions; do not download attachments by default.
- System messages, automatic replies, reactions, likes, and read receipts are not effective customer replies.

## Agent Analysis JSON

The agent must create UTF-8 JSON. Each analyzed thread must match at least two of customer_index, thread_id, and facebook_link.

    {
      "schema_version": "4.26",
      "threads": [
        {
          "customer_index": "1",
          "facebook_link": "https://www.facebook.com/example",
          "thread_id": "example",
          "messages": [
            {
              "record_id": "fbh:...",
              "message_time": "2026-08-06T10:30:00+08:00",
              "original_language": "fr",
              "chinese_translation": "客户希望先查看车型和价格区间。",
              "is_effective_customer_reply": true,
              "intent": "明确有意向",
              "intent_reason": "客户主动询问车型和价格资料。",
              "next_action": "整理适合当地市场的车型和价格区间资料，优先回复客户。",
              "risk_flags": []
            }
          ],
          "latest_analysis": {
            "latest_reply_record_id": "fbh:...",
            "latest_reply_at": "2026-08-06T10:30:00+08:00",
            "chinese_summary": "客户愿意评估五菱车型，并要求先查看车型和价格区间。",
            "intent": "明确有意向",
            "intent_reason": "客户提出了具体资料需求。",
            "next_action": "在一个工作日内整理车型和价格区间资料。",
            "next_followup": ""
          }
        }
      ]
    }

Every message with non-Chinese text requires chinese_translation. Outgoing messages are translated for context but must use is_effective_customer_reply=false and no cooperation intent.

## Five-Level Cooperation Intent

| Intent | Evidence | Status | Default follow-up |
|---|---|---|---|
| 明确有意向 | asks for models, price, quotation, import terms, trial order, volume purchase, or supplies purchase details | 已回复,有合作意向 | 1 business day |
| 潜在意向 | agrees to review information or continue discussion without a concrete purchase step | 已回复,待跟进 | 3 business days |
| 需澄清 | ambiguous reply, asks who the sender is, or requires decision-maker/business-fit confirmation | 已回复,待澄清 | 2 business days |
| 暂不考虑 | no current plan but leaves a future opening or asks to reconnect later | 已回复,暂不考虑 | explicit customer date, otherwise 30 days |
| 明确拒绝 | explicitly not interested, requests no more contact, or confirms it is not a target business | 已回复,明确拒绝 | none |

Do not classify greetings, thanks, emojis, thumbs-up, read receipts, or automatic replies as positive intent. Base the decision on the full thread, customer type, business evidence, and the latest effective customer reply.

## Workbook Write-Back

Default is preview-only. Write only when the user explicitly asks to update the workbook.

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

The writer must:

- deduplicate by 记录ID;
- update existing records only to complete translation/analysis fields;
- preserve original text and customer identity fields;
- update the matched Facebook row by both customer index and normalized Facebook URL;
- preserve email, WhatsApp, and previous outreach evidence in 建联状态;
- replace, not append repeatedly, the structured note block between 【Facebook回复分析】 and 【/Facebook回复分析】;
- calculate the default follow-up date when the analysis does not provide one;
- create one backup per run;
- rebuild 客户信息汇总表 without adding conversation columns;
- regenerate the dashboard when requested;
- reopen and scan the workbook after save.

A completed write must report question_mark_cells=0 and question_mark_note_rows=0.

## Dashboard Metrics

Dashboard reply metrics are unique-customer metrics:

- Facebook DM customers: unique customers with at least one 我方发送 record.
- Effective reply customers: unique customers with at least one effective 客户回复.
- Facebook reply rate: effective reply customers / Facebook DM customers.
- Intent distribution: each customer latest effective reply only.
- High-intent customers: 明确有意向 plus 潜在意向.
- Reply trend: effective replies in the latest 30 days.

Never use message count as customer count.

## Safety And Privacy

- Use only business conversations matched to workbook customers.
- Do not save passwords, cookies, access tokens, or AdsPower credentials.
- Keep raw/analysis JSON under runs/YYYYMMDD/<run_id>/, never inside the skill package.
- Major browser steps use 90-200 seconds, page-level steps use 30-90 seconds, and technical waits use 0.5-8 seconds.
- Do not reply, react, send attachments, or change the browser account state.