# 巡樓（Haixun Master）— Threads AI 經營與獲客工作台

用 AI 在 Threads（脆）上經營帳號，支援多帳號、混合資料來源（官方 API / 瀏覽器爬蟲）與自動化。

## 兩條核心流程

| 流程 | 說明 | 現階段建議 |
|------|------|------------|
| **流程 A — 風格複製發文** | 海巡爆文與留言 → AI 學風格 → 草稿 → 審核 → 發文 | Chrome 同步 + 爬蟲 |
| **流程 B — 產品獲客** | 找潛在客群貼文 → 生成獲客留言 → 回覆自己貼文 → 追成效 | 需 Meta 官方 API |

## 技術棧

- Next.js 15 + TypeScript + Tailwind CSS
- SQLite + Prisma
- Playwright（瀏覽器海巡、爬留言、發文）
- Meta Threads 官方 API（發文、獲客留言、成效；需 OAuth）
- Chrome 擴充（從本機 Chrome 同步 session 到遠端 server）
- Vercel AI SDK（OpenCode Go / Grok / OpenAI / Claude / Gemini）

## 快速開始

```bash
npm install
npm run playwright:setup   # Chromium + Linux 依賴

cp .env.example .env
# 填入 OPENCODE_GO_API_KEY 等

npm run db:push
npm run dev
```

開啟 http://localhost:3000

遠端 Linux server 部署時另需：

```bash
PLAYWRIGHT_HEADLESS=true npm run start
npm run worker   # 若要自動化排程
```

## 三層設定分離

| 層級 | 在哪裡設定 | 範圍 | 內容 |
|------|-----------|------|------|
| **巡樓使用者** | 設定 `/settings` | 登入者是誰就是誰 | AI API Key、預設模型、產文偏好 |
| **巡樓使用者** | 設定 `/settings` | 全 Threads 帳號共用 | Meta App ID/Secret |
| **Threads 經營帳號** | 連線設定 `/connections` | 每帳號各一份 | 連線預設、Chrome 同步、OAuth token |
| **Threads 經營帳號** | 帳號策略 `/accounts` | 每帳號各一份 | 人設、受眾、定位策略 |

> AI Key 跟你有幾個 Threads 帳號無關 — 切換經營帳號不會換 AI Key。

## 設定頁：連線與資料流程

每帳號的連線預設與 Chrome 同步在 **連線設定**（`/connections`）；AI Key 等在 **設定**（`/settings`）。

### 連線預設（三種常用模式）

| 預設 | 海巡 | 留言 | 發文 | 適用情境 |
|------|------|------|------|----------|
| **Chrome 同步** | 瀏覽器 | 瀏覽器爬取 | 瀏覽器 | 現階段全爬蟲、要留言學風格 |
| **API Key 優先** | Meta API | 不爬 | Meta API | 已申請官方 API、流程 B |
| **混合模式** | Meta API | 瀏覽器爬取 | 瀏覽器 | API 海巡 + 留言素材 |

設定頁會即時顯示「目前流程預覽」，說明海巡、留言、發文各走哪條路。

### 底層開關（進階自訂）

| 開關 | 作用 |
|------|------|
| `searchViaApi` | 海巡優先 Meta keyword search |
| `publishViaApi` | 發文優先 Meta API |
| `devMode` | 允許 Playwright 瀏覽器海巡與爬留言 |
| `scrapeReplies` | 是否抓他人貼文留言（需 devMode） |
| `repliesPerPost` | 每篇熱門文抓幾則留言 |
| `publishHeaded` | 發文時是否顯示瀏覽器視窗 |
| `playwrightDebug` | 保留 Playwright 除錯截圖 |

### Chrome Session 同步（遠端 server 必備）

服務跑在 Linux 無頭 server 時，**無法**在 server 上直接登入 Threads。

改用 Chrome 擴充（在**連線設定**頁操作）：

1. Chrome → `chrome://extensions` → 開發人員模式 → 載入 `extension/haixun-threads-sync`
2. 擴充選項填入 server 網址（例如 `https://your-server.com`）
3. 在 Chrome 登入 threads.com
4. 巡樓側欄切換到目標帳號
5. 連線設定頁按「從 Chrome 同步到目前帳號」

擴充會讀取 Chrome 的 Threads/Instagram cookies，轉成 Playwright `storageState` 寫入 server DB。

> 不要同時在本機 Chrome 與 server Playwright 登入同一 Threads 帳號，會互相踢出。

### Meta App 憑證（非 AI Key）

在設定頁填 **Threads App ID** + **App Secret**（全帳號共用），再到連線設定頁或側欄為**每個帳號**各做一次 OAuth 綁定。

完整申請步驟見 [docs/threads-api-setup.md](docs/threads-api-setup.md)。

## 使用流程

### 流程 A（現階段：Chrome 同步）

1. **連線設定** `/connections` → 安裝擴充並同步 Chrome session
2. **設定** `/settings` → 填 AI Key
3. **海巡** `/matrix` → 開始海巡 → 生成草稿 → 審核 → 發布
4. **成效紀錄** `/published` → 查看發布結果

### 流程 B（API 獲客）

1. **連線設定** `/connections` → 綁定 Threads API OAuth
2. **設定** `/settings` → 填 AI Key
3. **找 TA** `/outreach` → 挖掘受眾 → 生成留言 → 發布
4. **互動經營** `/engagement` → 同步留言 → 生成回覆 → 發布
5. **成效紀錄** `/published` → 追蹤成效

## 多帳號模型

每個「經營帳號」各自有策略、主題、草稿、session 與 API token：

- **瀏覽器 session**：Chrome 擴充同步到 `Account.storageState`（每帳號各一次）
- **官方 API token**：側欄 OAuth 授權（每帳號各一把，共用一組 App ID/Secret）

側欄可「新增經營帳號」→ 切換帳號 → 對該帳號同步 Chrome session。

## 資料抓取邏輯（程式行為）

```
海巡
  ├─ searchViaApi + 帳號有 OAuth → Meta keyword search
  ├─ 失敗或未開 → devMode 開 → Playwright 搜尋
  └─ 記錄 Scan.searchSource = "api" | "browser"

留言（top 12 篇）
  ├─ scrapeReplies + devMode + 有 session → Playwright 爬留言
  └─ 否則略過（API 模式無法讀他人留言）

發文
  ├─ publishViaApi + OAuth → Meta API
  └─ 否則 / 失敗 → Playwright + storageState
```

## 自動化

到 **自動化** 頁設定定時任務（需 `npm run worker`）：

| 任務 | 流程 |
|------|------|
| 自動海巡 | A + B |
| 自動生成草稿 | A |
| 自動發文 | A |
| 自動獲客留言 | B（需 Meta API） |
| 自動回覆留言 | B（需 Meta API） |

## 環境變數

| 變數 | 說明 |
|------|------|
| `OPENCODE_GO_API_KEY` | OpenCode Go（預設 AI） |
| `XAI_API_KEY` / `OPENAI_API_KEY` 等 | 其他 AI provider（可選） |
| `PLAYWRIGHT_HEADLESS` | `true`（server 預設）或 `false`（本機除錯） |
| `DATABASE_URL` | SQLite 路徑，預設 `file:./dev.db` |
| `THREADS_APP_ID` / `THREADS_APP_SECRET` | 也可在設定頁填，不必寫 .env |
| `APP_URL` | 對外網址，OAuth 與含圖 API 發文用 |

## 專案結構

```
app/                            # Next.js 頁面與 API
  (dashboard)/matrix/           # 海巡 — 內容矩陣與草稿審核
  (dashboard)/outreach/         # 找 TA — 獲客留言
  (dashboard)/engagement/       # 互動經營 — 留言回覆
  (dashboard)/connections/      # 連線設定 — Chrome 同步、OAuth、搜尋來源
  (dashboard)/automation/       # 自動化排程
  (dashboard)/published/        # 成效紀錄
  (dashboard)/settings/         # 設定 — AI Key、模型、產文偏好
extension/haixun-threads-sync/  # Chrome 擴充：同步 session
lib/
  threads-api/                  # Meta 官方 API
  threads-browser/              # Playwright 爬蟲
  services/scan.ts              # 海巡編排（API / 瀏覽器）
  automation/                   # 自動化引擎
worker/                         # cron 排程器
docs/threads-api-setup.md       # Meta API 申請指南
```

## 路線圖

| 階段 | 讀資料 | 寫資料 |
|------|--------|--------|
| **現在** | Playwright 爬蟲 + Chrome 同步 | Playwright 發文 |
| **之後** | Apify（留言）+ Meta API（海巡） | Meta API（獲客/回覆/成效） |

爬蟲模組會保留作 fallback。

## 風險與注意事項

- **瀏覽器爬蟲違反 Meta ToS**，有封號風險；建議用測試帳號
- **官方 API 較合規**，但讀不了他人貼文留言
- `storageState` 與 token 等同密碼，勿 commit `.env` 或 `*.db`
- Threads 貼文 ≤ 500 字

## License

MIT — 使用風險自負。