haixunMaster/extension/haixun-threads-sync/README.md

巡樓 Threads Session 同步（Chrome 擴充）

從你已登入的 Chrome Threads 帳號，一鍵把 session 傳到巡樓 Go 後端（:8890）。

安裝

方式 A（推薦）：巡樓「設定」頁 → 下載擴充套件（ZIP） → 解壓後載入。

方式 B：直接選擇 repo 資料夾 extension/haixun-threads-sync。

1. Chrome 打開 chrome://extensions
2. 開啟「開發人員模式」
3. 點「載入未封裝項目」
4. 選擇解壓後的 haixun-threads-sync 資料夾

必要條件

• 後端 API 在跑：make run（預設 http://127.0.0.1:8890）
• 前端在跑：make web-dev（預設 http://localhost:5173）
• 已在 Chrome 登入 threads.com 或 threads.net
• 已在巡樓網頁登入（JWT 存在 localStorage）

使用方式 A：連線設定頁（推薦）

1. 開啟 http://localhost:5173 並登入
2. 頂部切換目標經營帳號
3. 到「帳號 → 連線設定」
4. 切換到 開發模式（爬蟲）
5. 確認顯示「擴充已偵測」
6. 按 「從 Chrome 同步到目前帳號」

關閉開發模式 = 全部走 Threads API，不需要同步 Chrome session。

使用方式 B：擴充圖示

1. 先開著巡樓分頁並登入
2. 點擴充圖示 →「同步到巡樓」
3. 擴充會自動讀取巡樓分頁的 JWT 與目前帳號

設定 server 網址

擴充選項填入前端網址（不是 8890），例如：

• 本機：http://localhost:5173 或 http://127.0.0.1:5173
• 遠端：https://haixun.example.com

儲存後會自動注入網頁橋接腳本。API 在本機 dev 時會自動改打 :8890。

常見問題

現象	原因與處理
尚未偵測擴充	擴充安裝/更新後頁面不會自動注入腳本 → chrome://extensions 重新載入擴充，再 F5 刷新巡樓頁
等待擴充逾時	巡樓網址與擴充選項不一致（localhost vs 127.0.0.1）→ 統一用同一個，或在擴充選項重新儲存
找不到登入狀態 / JWT	開錯網站：要用 新版 http://localhost:5173（Go 後台），不是舊版 Next :3000
無法連線後端 :8890	只開了 make web-dev 沒開 API → 另開終端執行 cd haixun-backend && make run
invalid access token	JWT 過期（15 分鐘）→ 在巡樓頁重新整理或重新登入後再同步
找不到 cookies	先在 Chrome 開 threads.com / threads.net 完成登入，再同步
缺少帳號 ID	在巡樓頂部切換經營帳號，或打開 /threads/:id/connections
開發模式未開啟	連線頁底部「開發工具」要先 開啟開發模式，同步按鈕才會出現

技術說明

• 網頁透過 postMessage 與 content-haixun.js 溝通
• 擴充 background 收集 Threads/Instagram cookies，組成 Playwright storageState
• 呼叫 POST /api/v1/threads-accounts/:id/session/import（Bearer JWT）