期末專題：真實資料 × AI agent

先想問題，再找資料

期末專題鼓勵大家用開放政府資料或其他真實資料，避免選用已被大量分析過的公開資料集。 現在的 AI coding agent（例如 Claude Code、Codex CLI、OpenCode）可以幫你搜尋資料目錄、讀欄位說明、寫下載與清理程式， 找資料這一步比以前省力很多。分析的想法與判斷仍須由你自己負責。MCP 能做與不能做的事見 P03； 請 AI 協助分析之前，先看 P05 的核對清單，更完整的原則在 課前準備 C：用 AI 做統計分析。

推薦的資料來源

下表的來源都不強制使用，任何可靠的來源都可以。前五個是台灣政府機關的官方資料，都免費，授權條款請到各站確認； Twinkle Hub 適合用中文描述需求、讓 agent 幫你找資料；做國際題目可以看 FRED 與 Our World in Data。

把資料來源接進 AI agent

MCP（Model Context Protocol）是讓 AI agent 呼叫外部工具的標準介面。 資料平台有 MCP 端點，agent 就能自己搜尋資料目錄、查資料，不必手動逐頁瀏覽網站。 下面用 Twinkle Hub 示範。

1. 先了解 MCP 能做什麼

可以把 MCP 想成會查目錄、也會替你算摘要的圖書館員；整份資料還是要自己到原機關下載。下表依專題階段整理：

Twinkle Hub 免費方案的限制（2026-11-04 實測）：每次資料查詢扣 1 點，最多回 10 列，沒有翻頁。 聚合（count、sum、avg、min、max）會對符合條件的全部資料計算，但結果同樣最多回 10 組； 例如查高雄市各行政區的交易件數，只會拿到 38 區中的 10 區，要用條件分批查。 這個列數上限和點數無關，點數還有剩也一樣只回 10 列。

2. 取得金鑰，放進環境變數

到 Twinkle Hub 註冊，在 Dashboard 取得以 sk- 開頭的金鑰。 金鑰不要寫進程式碼、筆記本、投影片或要 commit 的設定檔，一律放在環境變數：

# macOS／Linux：寫進 ~/.zshrc 或 ~/.bashrc，重開終端機
export TWINKLE_HUB_API_KEY=sk-你的金鑰

# Windows PowerShell：設定後重開終端機
setx TWINKLE_HUB_API_KEY "sk-你的金鑰"

3. 依你用的 agent 加入 MCP 伺服器

Claude Code（Twinkle Hub 官方文件提供的指令，金鑰改從環境變數帶入）：

claude mcp add --transport http twinkle-hub https://api.twinkleai.tw/mcp/ \
  --header "Authorization: Bearer $TWINKLE_HUB_API_KEY"
claude mcp list        # 確認狀態

這個設定預設存在你自己的使用者設定裡，不會進入專案。請不要加 --scope project，否則金鑰會寫進專案的 .mcp.json，commit 後就會外流。

Codex CLI（Twinkle Hub 官方文件）：

codex mcp add twinkle-hub --url https://api.twinkleai.tw/mcp/ \
  --bearer-token-env-var TWINKLE_HUB_API_KEY
codex mcp list

如果啟動時出現 30 秒逾時，在 ~/.codex/config.toml 的 [mcp_servers.twinkle-hub] 底下加一行 startup_timeout_sec = 60。

OpenCode（Twinkle Hub 文件沒寫，下面照 OpenCode 官方 MCP 說明 寫成， 已在 OpenCode 1.18 用真實金鑰實測可以查詢）。在專案根目錄建立 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twinkle-hub": {
      "type": "remote",
      "url": "https://api.twinkleai.tw/mcp/",
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:TWINKLE_HUB_API_KEY}" }
    }
  }
}

{env:...} 會在執行時讀環境變數，所以這個檔案裡沒有金鑰，可以放進 Git。用 opencode mcp list 確認狀態。

沒有付費的 AI 訂閱也能先試：OpenCode 內建幾個免費模型（名稱以 -free 結尾，用 opencode models 查看），例如 opencode run -m opencode/deepseek-v4.1-flash-free "你的問題"。免費模型的清單會變動，以 opencode models 的結果為準。

4. 額度與學術方案

Twinkle Hub 免費方案每 5 小時 50 點、每週最多 200 點（2026-11-04 查證，方案可能調整，以 官方定價頁為準）。每次資料查詢扣 1 點，回應的 meta.usage.credit_price 會寫明；查詢工具清單與參數說明不是資料查詢。剩餘點數請到 Dashboard 查看。 需要更多額度可以用學校信箱申請 Edu 學術方案（申請方式見定價頁）；使用 Edu 方案的成果須註記「本研究由 Twinkle Hub 贊助資料服務」。

可以這樣問 agent

提問時把問題、限制和你要的輸出講清楚，agent 給的東西會好用很多。三個例子：

找資料：
我想研究高雄市近十年住宅交易價格和屋齡、捷運距離的關係。
請用 twinkle-hub 找出相關的政府資料集，列出資料集名稱、提供機關、
時間範圍、主要欄位、更新頻率、授權，以及原始檔的下載網址。先不要下載。

下載並記錄出處：
請寫 src/fetch_data.py，從上面選定的原始網址下載 2016–2025 年的檔案到 data/raw/，
不要修改原始檔。同時在 data/SOURCES.md 記下每個檔案的網址、提供機關、
授權、下載日期與篩選條件。需要金鑰的話從環境變數讀取。

先檢查資料：
讀 data/raw/ 的檔案，回報每個欄位的型態、缺值比例、單位與可疑的值
（例如負的面積、民國年未轉換）。只回報，不要自動刪資料。

agent 回報的欄位意義、單位與資料筆數，都要自己對照原始資料說明再確認一次。

免費額度內做得到的查詢

下面每個提問大約只需要一次資料查詢（1 點），實際次數以 agent 的呼叫紀錄為準。

• 確認樣本數：「用 twinkle-hub 的 lvr-trades，統計高雄市三民區、苓雅區、左營區 2024 年的交易件數與平均單價，只回傳聚合結果。」 三個區在 10 組以內，一次就能完整回傳。
• 確認期間涵蓋：「篩選苓雅區，回傳交易日期的最小值、最大值與筆數。」可以確認起訖年份，但不能據此認定中間沒有缺期。
• 先看真實值長相：「回傳苓雅區 2025 年起 10 筆交易，依交易日期由新到舊排序，附欄位說明與單位。」 看過日期格式、單位與欄位內容，再請 agent 寫下載與清理程式。
• 找可以合併的資料：「找出可以和實價登錄依行政區合併的人口或所得資料集，列出欄位、年份、授權與原始下載網址，先不要下載。」

用 AI 分析時要核對的事

AI 很會寫 scikit-learn 程式，也很會把結果講得頭頭是道，但統計學習專題最常出錯的地方，AI 預設不會替你檢查。 每次請 agent 分析的前後，都逐項核對下列事項：

1. 資料洩漏：標準化、補值、特徵選擇與調參只能用訓練資料估計（例如放進 Pipeline 再做交叉驗證）； 有時間順序的資料按時間切分，同一地區或個體重複出現時要分組切分；測試集只在最後用一次。AI 產生的程式若只有一行 train_test_split，就要特別檢查這幾點。
2. 資料本身：確認每一列代表什麼，以及欄位定義與單位（民國年或西元年、總價或單價、坪或平方公尺）； 合併、篩選、刪除缺值前後都印出列數，看樣本有沒有悄悄變少或變偏。
3. 評估方式：先建立基準模型（例如線性或邏輯斯迴歸），依任務選擇驗證方式與指標，回報交叉驗證的平均與變異，不要只挑表現最好的一次。
4. 解讀結果：不只看 p 值或 accuracy，也要說明效果大小、不確定性與限制；類別不平衡時改看 precision、recall 或 AUC；相關不等於因果。
5. 查證 AI 的說法：AI 會自信地解釋欄位，甚至編出不存在的欄位或論文。欄位意義回原機關的說明核對，文獻要自己找到原文，報告裡的數字都要由你的程式重算。
6. 保護資料：個資、未公開資料與金鑰不要貼進雲端 AI 服務。

怎麼把分析拆成小任務、要留哪些協作紀錄、哪些資料不能上傳，見 課前準備 C：用 AI 做統計分析。

讓別人跑得出同樣的結果

期末專題要求繳交的程式能從頭跑完，重現報告裡的數字與圖。專案可以照這個結構整理：

my-project/
├── README.md          # 怎麼跑：環境、執行指令、會產生哪些圖表
├── requirements.txt   # 套件與版本（pip freeze > requirements.txt）
├── data/
│   ├── raw/           # 原始檔，下載後不手改
│   └── SOURCES.md     # 來源網址、授權、取得日期、查詢條件
├── src/
│   ├── fetch_data.py  # 下載資料（金鑰從環境變數讀）
│   └── analysis.py    # 從 data/raw 一路跑到報告裡的數字與圖
├── .env               # 金鑰只放本機
└── .gitignore         # 列入 .env；太大的資料檔也排除

• 切分資料、交叉驗證、隨機森林這類有隨機性的步驟，都要設 random_state。
• 小檔案直接附上；大檔案附下載連結或 fetch_data.py，寫明取得日期。 經 API 或 MCP 查到的資料，要存成檔案一起附上，助教重現時不應該需要任何金鑰。
• 交件前找個乾淨的環境（新的 Colab 或新的虛擬環境），照 README 從頭跑一次，確認數字和圖跟報告一樣。

AI 協作的過程要記哪些東西，可以參考 課前準備 C 的紀錄表； 同一節也講了哪些資料（例如個資、未公開的研究資料）不該貼進雲端 AI 服務。

AI 使用聲明與資料出處

歡迎使用 AI 工具，但書面報告與簡報都要簡短說明用了哪些工具、用在哪裡， 不需要附對話紀錄。報告放在 Acknowledgements 裡，簡報放一張投影片或某頁的角落即可。例如：

AI use: We used Claude Code to search Taiwan open-data catalogs and to draft
the data-cleaning code, and ChatGPT to polish the English in Sections 1–2.
All code was run and checked by the team, and every number in this report
comes from our own code.

資料出處也要寫清楚。政府資料開放授權條款要求標示來源，例如：

資料來源：內政部不動產實價登錄開放資料（政府資料開放授權條款第 1 版），
2026-11-04 下載。

連結與查證日期

本頁的額度、方案與指令於 2026-11-04 查證，服務可能調整，請以各官方頁面為準。 學期日期、繳交方式與評分重點以當學期的期末專題規範為準。