1% Kanōsei Telegram 開店協作 Bot

這個 Cloudflare Worker 是兩人工作群的低摩擦入口：

09:00 天氣使用中央氣象署臺北市信義區鄉鎮預報。降雨機率達 30%，或天氣文字包含雨／雷時，bot 會提醒帶傘並附上「今日 00:00 至最新時間」的全臺累積雨量觀測圖；該圖是已觀測雨量，不是未來降雨預測。最高溫達 33°C 時會提醒防曬補水。手動 /today 與「今天」按鈕不載入天氣或圖片。

工作早報使用 Telegram Rich Message；Ryan、Phoebe、共同三個佇列都以原生 unordered list 呈現。若 Telegram 暫時拒絕 Rich Message，bot 會自動退回傳統 sendMessage，確保早報仍能送達。

指令

指令 用途
/today 顯示 Ryan、Phoebe、共同三個本週任務佇列與最大風險
/status 顯示 Ryan、Phoebe、共同三個佇列的目前狀態
/review 顯示 Inbox、critical path、本週結果與現有承諾
/done A-003 將行動設為完成
/defer A-003 延後可操作的本週任務，並由同一責任類型自動補位
/blocked A-003 等房東提供使用執照 設為等待並保存原因
/undo A-003 復原該行動最近一次 bot 狀態變更

按鈕與指令都會更新 private GitHub repo，並觸發 HQ 網站重建。

Canonical data

檔案 用途
tracking/milestones.md 開幕里程碑、Area、critical path 與目標日
tracking/actions.md 責任類型、Driver、Area、所服務里程碑、本週承諾、重啟點與成果證據
tracking/inbox.md Telegram 自然語言、照片與整理結果
tracking/check-ins.md 完成、延後、系統替補、原因與 undo 前狀態

每件行動的責任類型固定為 Ryan、Phoebe 或共同，並保留一位 Driver。個人佇列每週最多三件，共同佇列最多一件且不占個人額度。個人任務只有本人可更新；共同任務兩人皆可更新。系統依 Critical、最早里程碑、硬期限與行動順序在同一責任類型內補位，排除同週已延後、等待、需整理及 Post-launch 任務。若沒有合格 backlog，bot 會明說而不虛構任務。

一次性設定

  1. 在 Telegram 用 @BotFather 建立 bot，加入專用私人工作群。
  2. 用 /setprivacy 將這個 bot 設為 Disable。這是自然語言與照片能進 Inbox 的必要條件；群組不應用於私人閒聊。
  3. 取得群組 chat.id 與兩位成員的 from.id。
  4. 在 Cloudflare Worker 設定 secrets：
cd telegram-bot
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put TELEGRAM_CHAT_ID
npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
npx wrangler secret put ALLOWED_USER_IDS
npx wrangler secret put GITHUB_TOKEN
npx wrangler secret put CWA_AUTHORIZATION

ALLOWED_USER_IDS 格式：

123456789:Ryan,987654321:Phoebe

顯示名稱必須是 Ryan、Phoebe，才能符合 Driver 驗證。

  1. GitHub fine-grained token 只授權 private repo 的 Contents read/write；所有 secret 只存 Cloudflare，不得寫進 repo、文件或 git remote。
  2. 在中央氣象署開放資料平臺免費註冊一般會員，從「會員資訊 → API 授權碼」取得授權碼，並只透過上方 wrangler secret put CWA_AUTHORIZATION 寫入 Worker secret。缺少或失效時，bot 仍會送出工作早報，只會省略天氣。
  3. 部署 Worker：
npx wrangler deploy
  1. 設定 webhook。不要把 token 存入文件或 shell history：
https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook

送出的設定需包含 Worker /telegram URL 與 TELEGRAM_WEBHOOK_SECRET 對應的 secret_token。

驗收流程

  1. /today：確認 Ryan、Phoebe、共同三個佇列及延後按鈕，且不包含天氣或雨量圖。
  2. 等待或手動觸發 09:00 cron：確認顯示信義區天氣，且三個佇列呈現為原生 list；有雨風險時，先收到附天氣 caption 的雨量圖，再收到工作早報與按鈕。
  3. 圖片 caption 應清楚標示為全臺今日累積雨量觀測，而非降雨預測；天氣首行的「臺北市信義區」與「日累積雨量圖」應為可點擊文字連結。
  4. 延後個人任務：原任務退回待排，bot 只從同一人的佇列補位；兩人互相操作對方個人任務時應被拒絕。
  5. Ryan、Phoebe 分別操作共同任務，確認兩人都可完成或延後，且替補仍來自共同佇列。
  6. 標記完成時只完成該任務，不自動新增工作。
  7. 測試「外部等待」「太大／不清楚／改方向」及沒有合格替補任務時的明確回覆。
  8. 傳一段一般文字與一張有 caption 的照片；確認 Inbox、壓縮媒體與 📥 reaction。
  9. 傳一張無 caption 照片；回覆 bot 追問並確認說明補入原 Inbox 項目。
  10. 週日 21:00：確認未完成任務續留、空位補足為 3／3／1，重跑不重複分配；手動 /review 僅查看、不換週。
  11. 確認 GitHub commit、Cloudflare Pages 重建與 HQ 駕駛艙更新。

本機驗證

cd telegram-bot
npm test

測試涵蓋 schema、推薦排序、WIP／承諾上限、早晚與週檢視內容、天氣正規化、雨具／防曬門檻、條件式雨量圖、失敗回落、狀態事件、undo、Inbox 去重及照片選擇邏輯。