Introduction

簡介

背景與動機

TeamPlus 是企業內部使用的即時通訊平台,但它:

• 沒有公開 API — 只能透過網頁版客戶端使用的私有端點存取
• 訊息歷史不在自己手上 — 查詢、備份、跨裝置存取都受限
• 通知體驗受限 — 離開電腦就容易漏訊息

本專案解決這三個問題:用你自己的帳號 cookies 驅動 TeamPlus 的 WebSocket + REST 端點,把訊息流鏡射到 Telegram(即時性)並封存到自己的 Turso 資料庫(所有權與可查詢性)。

設計理念

1. 兩半獨立 — Telegram 橋接(channel/)與雲端封存(worker/)互不依賴,可各自啟用。
2. 雲端優先 — 封存與發訊都走 Cloudflare Worker,筆電關機也不中斷;唯一的例行工作(cookie 更新)交給 GitHub Actions。
3. 不綁定組織 — TeamPlus 站台網址由 TEAMPLUS_BASE 環境變數注入,原始碼與版控中不含任何真實憑證或組織資訊。
4. 公私分離 — 程式碼放公開 repo(htlin222/team-plus-server),實際部署的 workflow 與 Secrets 放私有 repo(htlin222/team-plus-server-live)。
5. AI 助理原生 — 內建 MCP server 與 Claude Code skills(dms、fetch-hx),讓助理能讀訊息、擬回覆、代發送。

Repo 結構

路徑	說明
channel/	Bun daemon:TeamPlus WebSocket ↔ Telegram 橋接 + MCP server
worker/	Cloudflare Worker + Durable Object → Turso 封存
scripts/	Cookie 更新(Patchright + Tesseract OCR)、簽章上傳、logs.mjs / send.mjs / attachment_url.mjs / healthcheck.mjs 等工具
docs/	維運手冊(PLAYBOOK)
.claude/	dms、fetch-hx skills + 把助理回覆轉發到 Telegram 的 Stop-hook
Makefile	daemon 生命週期(make start / stop / logs,由 launchd 管理)

channel/ 主要模組

檔案	職責
server.ts	daemon 進入點:WS 監聽、事件分派
teamplus.ts / teamplus_rest.ts	TeamPlus WebSocket 與 REST 客戶端
telegram.ts	Telegram bot:訊息鏡射、回覆指令
bridge.ts	橋接邏輯與助理指令(如 remind → Todoist)
drafts.ts / cursor.ts	草稿管理與訊息游標
ipc.ts	與 MCP server / hooks 的行程間通訊

worker/ 主要模組

檔案	職責
src/index.ts	簽章 HTTP API:cookie 上傳、status、start/stop/nudge、send、backfill
src/session.ts	每個 TeamPlus 帳號一個 Durable Object;持有 cookie 與 WebSocket
src/turso.ts	把正規化後的訊息事件寫入 Turso
src/contacts.ts	透過 TeamPlus REST API 解析傳送者/聊天室名稱
src/attachments.ts	下載圖片/檔案訊息並封存至 R2
schema.sql	Turso 資料表:訊息歷史與 session 事件

技術棧

• Runtime:Bun(daemon)、Cloudflare Workers + Durable Objects(雲端)
• 儲存:Turso / libSQL(訊息)、Cloudflare R2(附件)
• 語言:TypeScript(主體)、Python 3.12(cookie 更新:Patchright 無頭瀏覽器 + Tesseract 驗證碼 OCR)
• 排程:Worker cron(keepalive)、GitHub Actions cron(cookie 更新、健康檢查)、launchd(本機 daemon)

快速開始

完整步驟見 README。摘要:

cp .env.example .env          # 設定 TEAMPLUS_BASE + TeamPlus 帳密
./scripts/setup_telegram.sh   # 產生 .telegram.json
./scripts/refresh.sh          # 首次 cookie 擷取(無頭登入 + OCR)
make start                    # 啟動 Telegram 橋接 daemon

雲端封存的部署見 worker/README。

安全性設計

• 所有密鑰都在 gitignored 檔案中,版控只有範本(.env.example、.dev.vars.example)
• 讀取 API 使用獨立的 TEAMPLUS_DB_KEY,與管理用的 COOKIE_UPLOAD_SECRET 分離 — 可分享唯讀權限而不交出控制權
• 管理端點以 HMAC 簽章保護
• 附件檢視連結帶簽章且強制一週內過期(即使持有 secret 也無法鑄造更長效的連結)
• GitHub Actions 只用 schedule / workflow_dispatch 觸發,fork PR 碰不到 Secrets