Introduction

簡介

背景與動機

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

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

本專案解決這三個問題:用你自己的帳號 cookies 驅動 TeamPlus 的 WebSocket + REST 端點,把訊息流封存到自己的 Turso 資料庫(所有權與可查詢性),並提供一組 CLI / skills / 即時終端機客戶端,讓你隨處讀取歷史、擬回覆與發送。

設計理念

1. 兩半獨立 — 雲端封存(worker/)與 CLI/skills(.claude/、scripts/、tui/)互不依賴,可各自使用。
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 助理原生 — 提供 Claude Code skills(dms、fetch-hx),讓助理能讀訊息、擬回覆、代發送,發送直接走 REST(無審批中介)。

Repo 結構

路徑	說明
worker/	Cloudflare Worker + Durable Object → Turso 封存(見 Cloud-Archive-Worker)
scripts/	Cookie 更新(Patchright + Tesseract OCR)、簽章上傳、logs.mjs / send.mjs / attachment_url.mjs / cf_worker_request.mjs 等工具
tui/	curses 即時終端機客戶端(見 Live-TUI-Client)
docs/	維運手冊(PLAYBOOK)
.claude/	dms、fetch-hx skills(見 CLI-Skills)
Makefile	make refresh(cookie 擷取)、make setup-creds、make tui
archive/	telegram-bridge/ — 已退役的 Telegram 橋接 daemon,保留供參考

worker/ 主要模組

檔案	職責
src/index.ts	簽章 HTTP API:cookie 上傳、status、start/stop/nudge、send、backfill、/v1/logs、附件檢視 /a
src/session.ts	每個 TeamPlus 帳號一個 Durable Object;持有 cookie 與 WebSocket,自我修復
src/auth.ts	HMAC 簽章驗證(管理端點)與簽章工具
src/teamplus.ts	TeamPlus WebSocket + REST 客戶端(getToken、CORE:AUTH、訊息事件)
src/turso.ts	把正規化後的訊息事件寫入 Turso
src/contacts.ts	透過 TeamPlus REST API 解析傳送者/聊天室名稱
src/attachments.ts	下載圖片/檔案訊息並封存至 R2,簽發限時檢視連結
src/send.ts	以 session cookie 發送 outbound 訊息(DM/群組)
schema.sql	Turso 資料表:messages 訊息歷史與 session_events session 事件

CLI / skills / TUI

元件	職責
.claude/skills/dms/	收件匣分流:list_dms、fetch_history、find_user、send_now、ignore;共用 references/teamplus.py
.claude/skills/fetch-hx/	「名字 → 近期對話」快速讀取,hx.py,快取名字→key 對照
scripts/logs.mjs	讀取 API CLI(時間窗、過濾、附件連結)
scripts/send.mjs	透過 worker 發送 DM/群組訊息,支援引用回覆
tui/	curses 即時客戶端:WS 監聽 + REST backfill,兩欄焦點導覽

技術棧

• Runtime:Cloudflare Workers + Durable Objects(雲端封存與發訊)
• 儲存:Turso / libSQL(訊息)、Cloudflare R2(附件)
• 語言:TypeScript(worker)、Python 3.12(cookie 更新 + skills + tui)、Node(CLI 腳本)
• cookie 更新:Patchright 無頭瀏覽器 + Tesseract 驗證碼 OCR
• 排程:Worker cron(keepalive)、GitHub Actions cron(cookie 更新、健康檢查)

快速開始

完整步驟見 Getting-Started 或 README。摘要:

cp .env.example .env          # 設定 TEAMPLUS_BASE + TeamPlus 帳密
make refresh                  # 首次 cookie 擷取(無頭登入 + OCR)
cd worker && pnpm install     # 部署雲端封存
./scripts/setup_turso.sh teamplus-messages
./scripts/push_secrets.sh && wrangler deploy

之後用 make tui 開即時客戶端,或用 dms / fetch-hx skills 從 Claude Code 讀與回。

安全性設計

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

詳見 Security-and-Secrets。