iT邦幫忙

2026 iThome 鐵人賽

DAY 20
0
自我挑戰組

30 天養大一個開源專案:baodao-skill 從零開始系列 第 20 篇

【Day 20】0.8.2:發票會讀錯號碼、停車場每天長大,然後我們把地雷寫成了制度

  • 分享至 

  • xImage
  •  

先講結論:昨天(2026-09-26)倉庫進了 0.8.2。沒有新 skill,但這可能是目前為止最重要的一版——它把前面 19 天踩過的地雷,一顆一顆寫成了 CI 規則和文件制度。地雷圖鑑不再只是這個系列的連載專欄,它變成了 repo 的一部分。

發票解析真的修了一個會讀錯號碼的 bug

Day 9 寫過統一發票頁面「排版是給人看的」。9/26 在 115 年 07-08 月期實測重現了更陰的問題:頁首頁尾的分頁連結裡含有「特別獎、特獎中獎清冊」字樣,從期別標籤直接往後掃,會把特獎對到清冊連結、讀出特別獎的號碼。對獎這種錢的事,讀錯一碼都不能忍。修法:解析改從期別標籤後第一個「獎別」表格起點開始;補了 07-08 月期版面的回歸 fixture,還新增 check-invoice.py 煙霧測試(特別獎/特獎必須是 8 碼且不重複)。當期實測記錄:特別獎 38548029、特獎 10138845;領獎期間仍殘留上一期——陷阱還在,但現在有測試盯著。

停車場數字每天動,CI 學會容忍

Day 15 和 Day 17 講過「數字會動」不是 bug 是事實。這次輪到 CI 長知識:check-counts 原本對停車場場數做 exact-match,結果 9/20-25 health-check 連續誤報。0.8.2 改成 ±5% 的 WARN 級檢查,YouBike 統一 feed 總站數同級處理。新的實測基準(2026-09-26):

指標 舊基準 新基準
停車場即時場數 1,174 1,188
停車場靜態場數 1,773 1,775
停車場 -9 場數 88 88(沒動)
YouBike 統一 feed 站數 9,521 9,629
站名含「臺」站數 385 385(沒動)

順帶,check-urls 也修了:404 不再被地區限制 WARN 掩蓋,NCDR 同網域請求串行隔 3 秒不再自踩速率限制,stats.moe.gov.tw 的機房封鎖列入已知 geo 限制。

文件會老:實測日標頭,90 天沒重測就 CI 失敗

「實測過才收錄」從 Day 1 喊到現在,0.8.2 把它變成強制規則:新的 check-measured-date.py 要求每個 SKILL.md 帶「實測日」標頭,超過 90 天沒重測,CI 直接失敗並自動開 issue 提醒。文件會說謊不只是因為寫錯,也會因為放太久——這條把「過期」也變成可偵測的故障。

金鑰的唯一例外

Day 14 寫過第三把金鑰。AGENTS.md 這次補了一條精準的例外:政府開放平臺針對特定資料集公布的公用存取金鑰(例如 taiwan-toilet 用的 data.gov.tw resource key)不是個人秘密,可以寫進 SKILL.md,但必須註明來源頁與失效時的重取方式。個人金鑰照樣金鑰不落地——回覆、文件、commit 一律用 $CWA_API_KEY 占位。界線畫清楚了:「不能提交的是你的秘密,不是政府的公告」。

response-contract.md:地雷圖鑑有了正本

新文件 docs/response-contract.md 把跨技能的回報規則收成一份:附資料時間(不說「目前」)、缺值如實說(-9 就是無資料,不拿舊值充數)、HTTP 200 不等於成功、台臺混用先正規化、民國年與學年度換算、地區擋 IP 用備援源、官方公告為準。外加 docs/getting-started.md 把 25 個 skill 依六種用途分組,開宗明義寫清楚只有 3 個要金鑰。來源都在倉庫:CHANGELOG.md、docs/response-contract.md、docs/getting-started.md(github.com/tahodev/baodao-skill,0.8.2)。

第 20 天。前十九天踩的每一顆雷,今天變成 CI 裡的一條規則或文件裡的一行字。養一個專案到這個階段,長大的不是功能數量,是它記住教訓的方式。


上一篇
【Day 19】免 key 的官方「預測」:中油 open data 週日中午就把下週油價寫死,95 無鉛 32.7 元
下一篇
【Day 21】寫這篇的今天剛好放假:6,499 bytes 的人事總處日曆,和一年一變的編碼
系列文
30 天養大一個開源專案:baodao-skill 從零開始 共 24 篇
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言