Skip to content

Latest commit

 

History

History
20 lines (15 loc) · 1.93 KB

response-contract.md

File metadata and controls

20 lines (15 loc) · 1.93 KB

回應慣例(response contract):各技能共通的分答規則

寫新技能或除錯時先對照這份清單。各 SKILL.md 是查詢流程的正本;這裡收錄「回報給使用者時」跨技能一致的規則。跨技能的資料處理慣例(民國年、Big5、curl、時區)見 conventions.md。

一定要做

  • 附資料時間:即時類 feed(YouBike、停車場、台電、AQI、NCDR 警報)回報時附上資料本身的更新/發布時間,不說「目前」而不給時間。
  • 缺值如實說:測站缺值、欄位空字串、-9(無此車種資料)就如實標示「無資料」。不用舊值、不用推測值充當現況。
  • 警報先看時效:NCDR CAP 的每則警報先確認發布時間與 cap:expires,過期警報不當現況。
  • 金鑰不落地:回覆、文件、commit、issue、日誌都不出現使用者的金鑰;範例一律用 $CWA_API_KEY / $MOENV_API_KEY 占位。

常見陷阱(實測踩過的)

  • HTTP 200 不等於成功:MOENV 金鑰錯誤回 200+純文字;政府站有時回 HTML 挑戰頁。先驗內容型態再解析。
  • 台 / 臺混用:站名、縣市名兩種寫法並存,比對前兩邊都正規化(gsub("臺";"台"))。
  • 民國年 ≠ 西元年,學年度 ≠ 民國年:115 年 = 2026;114 學年度 = 2025/08–2026/07。回報時換算。
  • 期別錯配:發票頁的「領獎期間」常是上一期的;分頁連結含獎項字樣,解析從「獎別」表格起點開始。
  • 地區性擋 IP:YouBike 統一 feed(Incapsula)、健保署、部分 etax 頁會擋機房/海外 IP。被擋時改用該技能的備援源,不要當成資料源失效。
  • 速率限制:NCDR feed 連續請求間隔至少 3 秒(429)。一次查多類型要加 sleep。
  • 官方公告為準:領獎期限、停班停課、颱風警報等重要判斷,一律請使用者回官方網站確認;推算值要註明是推算。