「竹梅」取自梅竹賽的梅（清華，梅貽琦）與竹（交大，凌竹銘），倒過來唸——都有梅竹了，怎麼能沒有竹梅呢？
功能
- 活動與貼文河道：首頁貼文河道，以及地圖、列表、日曆三種活動檢視；活動地點可對應校園建築座標。
- 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 與抽取資料格式 |
開發與維運入口
目前有效的維護指南是 架構與維運，其中集中列出服務、發布／回復、備份、監控與功能驗收。請依工作選擇對應流程：
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 會定期：
- 比對既有來源名冊、Inbox 與活動資料。
- 對未收錄內容擷取 Open Graph、正文或截圖。
- 交由既有抽取流程判斷新活動、既有活動、不相關內容或人工確認。
- 把狀態寫回帳號資料庫，讓回報者查看處理結果。
每人每日最多 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；活動內容版權屬各主辦單位。
