207 lines
7.7 KiB
Markdown
207 lines
7.7 KiB
Markdown
# 巡樓（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 — 使用風險自負。 |