巡樓（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）

快速開始

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 部署時另需：

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。

使用流程

流程 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 — 使用風險自負。