清大、陽明交大活動與講座｜竹梅活動觀測站

「竹梅」取自梅竹賽的梅（清華，梅貽琦）與竹（交大，凌竹銘），倒過來唸——都有梅竹了，怎麼能沒有竹梅呢？

功能

• 活動與貼文河道：首頁貼文河道，以及地圖、列表、日曆三種活動檢視；活動地點可對應校園建築座標。
• 470+ 單位名錄：/source/ 收錄校方、系所、社團與校外主辦，每個單位有自己的活動、貼文與例行時段頁面。
• 帳號系統：支援陽明交大 OAuth、清大 NTHUMods Auth 與 Google 登入，可互相綁定；提供預設不公開、可自行公開的個人頁、追蹤單位、「我會去」、回報紀錄與跨裝置同步。
• 自訂行事曆與 RSS：依學校、類型、校區、主辦自由組合。登入後可儲存最多 10 組具名訂閱，加入「只看我追蹤的單位」，並管理、換發私密網址。
• Web Push／PWA：網站可安裝成 App，依學校、類型、追蹤單位與關鍵字推送；「我會去」活動可在前一天提醒。
• Telegram 與查詢 Bot：Telegram 頻道 發布新活動；私訊 @chumei_events_bot 可用「這週末 清大」「熱舞社」等自然語句搜尋。
• AI／開發者介面：提供 JSON API 與 Streamable HTTP MCP server（https://chumei.observe.tw/mcp），讓支援 MCP 的 AI 助理搜尋活動、查名錄與建立訂閱網址。
• 限時動態牆：輪播兩校公開 Instagram 限時動態，保留足夠時間讓使用者補看校園消息。

資料來源與處理原則

竹梅只彙整公開資訊，主要來源包括：

• 陽明交大公告、清大各單位 RPage、WordPress 網站與 NYCU LIFE 官方活動 API。
• 學生社團與校方單位的 Instagram、Facebook、Threads、X 公開貼文；名冊位於 data/sources/，以兩校官方社團名冊為底。
• Instagram 公開限時動態。

活動時間、地點、報名方式與例行社課時段由 LLM 從貼文文字及海報擷取，再經程式後驗、來源歸戶與跨來源去重。資訊不足或信心偏低的結果會標示「待確認」；實際資訊仍以主辦單位原始公告為準。

系統流程

flowchart LR
    A[公開公告與社群來源] --> B[抓取與正規化]
    B --> C[(Inbox JSONL)]
    C --> D[LLM 文字與海報抽取]
    D --> E[後驗、去重、單位歸戶]
    E --> F[靜態網站與 PWA]
    E --> G[RSS、ICS、JSON API]
    E --> H[Telegram、Push、Bot、MCP]
    I[OAuth 帳號與使用者偏好] --> F
    I --> G
    I --> H

Repository 結構

路徑	用途
data/sources/*.csv	人工維護的社團、單位、社群帳號、公告站與場地座標名冊
data/feeds/inbox/	各來源 adapter 正規化後的 JSONL
scripts/fetch_*.py	公告、Instagram、Facebook、Threads、X、WordPress 與限動抓取器
scripts/extract_events.py	LLM 活動判別、文字／海報欄位抽取與快取
scripts/build_site.py	合併、去重、單位歸戶、場地定位，產生網站、feeds 與 API
scripts/auth_server.py	OAuth、Session、個人頁、「我會去」、回報與帳號型自訂訂閱
scripts/apify_contributions.py	社群 Apify 帳號驗證、加密保存、排行榜與動態抓取加速
scripts/push_server.py	Web Push 訂閱 API 與帳號綁定
scripts/publish_push.py	依偏好滴灌新活動與「我會去」提醒
scripts/publish_telegram.py	以原始貼文為單位發布 Telegram 訊息
scripts/bot_core.py	Telegram／LINE 共用的自然語句活動查詢核心
scripts/mcp_server.py	唯讀 MCP server，資料源為目前已發布版本
scripts/run_pipeline.py	定期抓取、抽取、建站與發布的 orchestrator
site/	網站範本、品牌資產及本機建站／抓取快取
published/current	Caddy 提供的已驗證正式版本（原子 symlink 切換）
deploy/	macOS launchd 服務與 Caddy 路由範本
docs/SCHEMA.md	Inbox 與抽取資料格式

開發與維運入口

目前有效的維護指南是 架構與維運，其中集中列出服務、發布／回復、備份、監控與功能驗收。請依工作選擇對應流程：

• 本機環境、鎖定依賴與 CI 檢查：乾淨 checkout 使用合成資料驗證，不需要正式金鑰。
• 正式發布與回復：離線重建、原子切換與首次啟用。
• 備份、還原與新主機部署：含可搬移的 launchd／Caddy 設定產生器。

PLAN.md 是 2026-08-21 的歷史紀錄；不再用作待辦清單。進行中的工作以 Issues 為準。

登入、訂閱簽章與 Apify 貢獻加密設定由被 Git 忽略的 .env／.env.apify（權限 0600）或程序環境變數提供；網站不再讀取 macOS Keychain。Web Push VAPID 私鑰仍保存在受保護的 state/push/，隨推播狀態備份。請勿把 OAuth secret、Telegram token、社群 cookie 或 state/ 內的使用者資料提交到 repository。完整 pipeline 會存取外部供應商並可能消耗額度；日常程式驗證使用上述隔離 CI 流程。

帳號與自訂訂閱

OAuth

NYCU OAuth Authorization Code 應用程式的 callback：

https://chumei.observe.tw/auth/nycu/callback

Google OAuth 2.0 Web application 的 callback：

https://chumei.observe.tw/auth/google/callback

清大登入走 NTHUMods Auth（OpenID Connect，public client chumei-observe，PKCE S256，沒有 client secret）。NTHUMods 登記的 redirect URI 不帶 provider 段：

https://chumei.observe.tw/auth/callback

服務會用 JWKS 驗 id_token 的簽章、iss、aud、exp 與 nonce，帳號以 sub（學號）為鍵，顯示名稱取 name。若之後 NTHUMods 另外登記 /auth/nthu/callback，設定 CHUMEI_NTHU_OAUTH_REDIRECT_PATH 即可切換；CHUMEI_NTHU_OAUTH_CLIENT_ID 留空可關閉清大登入。

開發及正式環境均可在 .env 設定（純 KEY=value，不要加引號或 export）：

CHUMEI_NYCU_OAUTH_CLIENT_ID=
CHUMEI_NYCU_OAUTH_CLIENT_SECRET=
CHUMEI_GOOGLE_OAUTH_CLIENT_ID=
CHUMEI_GOOGLE_OAUTH_CLIENT_SECRET=
CHUMEI_NTHU_OAUTH_CLIENT_ID=chumei-observe
CHUMEI_NTHU_OAUTH_REDIRECT_PATH=/auth/callback
CHUMEI_AUTH_PUBLIC_BASE_URL=https://chumei.observe.tw
CHUMEI_FEED_SIGNING_KEY=
CHUMEI_APIFY_CONTRIBUTION_KEY=

上述登入、訂閱簽章與 Apify 貢獻加密設定只由環境檔與程序環境變數提供。.env.apify 會覆蓋 .env 同名項目，程序中的 CHUMEI_* 設定再覆蓋檔案；環境檔與備份均須限制權限。舊機的 Keychain 值需要在部署前一次性移入 .env，並保留實際生效的訂閱簽章與 Apify 加密金鑰，詳見 停用 Keychain 與金鑰遷移。舊 Keychain 項目可保留但程式不會再使用。

三種登入可在帳號頁互相綁定。若該身分已有帳號，系統會把追蹤、參加標記、回報、已儲存訂閱與 Session 合併到目前帳號；解除綁定時至少保留一種登入方式。

頁面與 Feed

• /account/：帳號設定、登入方式、行事曆、回報、自訂訂閱與刪除帳號；/account/privacy 說明資料保留。
• /contribute/：社群 Apify 額度貢獻、每日優先點數、排行榜與已註冊帳號池。
• /@handle：新帳號預設不公開，可由使用者在設定中主動公開。
• /auth/calendar/{token}.ics：「我會去」活動的私密行事曆，可由帳號頁換發。
• /feeds/custom.ics、/feeds/custom.xml：不需登入的多維條件組合。
• /feeds/s/{signed-token}.ics、.xml：帳號儲存的私密訂閱；修改條件不更換網址，除非使用者主動換發。

CHUMEI_FEED_SIGNING_KEY 未另外設定時，服務會從 NYCU OAuth client secret 做用途隔離後衍生簽章金鑰；資料庫只保存 public ID，不保存可直接使用的完整 signed token。

CHUMEI_APIFY_CONTRIBUTION_KEY 未另外設定時，同樣會從 NYCU OAuth client secret 做用途隔離後衍生 Fernet 金鑰。貢獻者的 Apify token 在寫入 SQLite 前即加密；公開 API、排行榜與 log 只使用遮罩代號和額度資訊。

帳號服務由 deploy/tw.observe.chumei.auth.plist 常駐在 127.0.0.1:8324。Caddy 需將 /auth/*、/account*、/contribute*、/@*、/feeds/custom.* 與 /feeds/s/* 反代到該服務。

推播、Telegram 與抓取排程

• Telegram publisher 以 CHUMEI_TELEGRAM_ENABLED=true 啟用；正式發送前可執行 scripts/publish_telegram.py --check 與 --dry-run。
• Instagram 貼文先走免登入公開端點，必要時以 Apify 備援；限時動態走 Apify Story actor，兩者都不使用本站的 Instagram 帳號。
• Instagram 帳號採持久化分批排程與 jitter，依近期發文頻率調整為 12 小時至 14 天；狀態保存在被 Git 忽略的 state/。
• 每個有效的社群 Apify 貢獻帳號，會讓貢獻者每日多 3 點優先 quota，並讓每輪 Instagram 貼文與限動各多 3 個處理槽位（全站上限 30）。每日 quota 可重複投入同一來源；來源權重持久累加，背景服務以加權公平排程提高高權重來源的抓取頻率，同時保留冷卻與額度保護。token 只以 Fernet 加密形式保存。
• 首次正常執行會把現有近期活動設為 baseline，避免洗版；後續每輪 pipeline 最多推送 10 則，22:00–07:59 靜音。
• Web Push 偏好與帳號追蹤跨裝置同步；發布器每 30 分鐘檢查新活動與隔日「我會去」提醒。

登入回報活動

登入者可從 /submit/ 或帳號頁提交活動／帳號連結。scripts/process_submissions.py 會定期：

1. 比對既有來源名冊、Inbox 與活動資料。
2. 對未收錄內容擷取 Open Graph、正文或截圖。
3. 交由既有抽取流程判斷新活動、既有活動、不相關內容或人工確認。
4. 把狀態寫回帳號資料庫，讓回報者查看處理結果。

每人每日最多 10 筆，相同連結會去重。可公開驗證的學校單位或社團帳號會進入來源審核流程。

品牌資產

• 完整 Open Graph 預覽圖：site/assets/og-default.png（1200 × 630）
• PWA／Apple Touch Icon：site/assets/brand/logo-square-*.png
• Favicon：site/assets/favicon.svg 與 site/assets/brand/logo-mark-*.png
• 品牌字型：site/assets/fonts/chumei-brand*.woff2

資料回報、下架與 License

活動資訊有誤、主辦單位希望調整或下架，可從網站登入後回報，或寄信至 [email protected]。GitHub Issues 僅處理程式問題；轉載的海報與貼文均附原始來源，主辦單位要求即下架。

程式碼採用 MIT License；活動內容版權屬各主辦單位。