# 選舉小鎮 — 後端 遊戲規則、資料管線、人物資料庫與 AI 評分。前端在另一個程式庫(`../web`),只透過 `packages/protocol` 的協定和後端溝通。設計文件在 [`docs/`](docs/README.md)。 ## 目錄 ``` packages/protocol/ 前後端契約(Zod)→ 產生 JSON Schema(schema/);頭像部件目錄 packages/rogue/ 選戰卡牌的規則(主要玩法):純函式,狀態可序列化 packages/engine/ 選民模型,加上舊的十週選戰引擎(只給 apps/sim 校準用) packages/content/ 十週引擎的行動、事件、議題,與手工劇本(資料) packages/scenarios/ 劇本目錄:手工劇本+管線產生的全台劇本,套上校準值 packages/pack-loader/ 從磁碟讀取並驗證資料包(伺服器與模擬工具共用) apps/server/ 遊戲 API 伺服器(Fastify) apps/sim/ 校準、回測與平衡報告 data/pipeline/ Python 資料管線(election_data 套件) data/raw/ 下載的原始資料(不進版控,可重建) data/build/ 產出的資料包、劇本、參選人資料(不進版控,可重建) data/runs/ 選戰卡牌每一局的存檔 docs/ 文件;docs/README.md 是整體架構 ``` ## 需求 - Node.js 22 以上、pnpm 10 - Python 3.12 以上 ## 第一次設定 ```bash pnpm install pnpm schema # 由 Zod 產生 JSON Schema,Python 管線驗證輸出時會用到 cd data/pipeline python3 -m venv .venv .venv/bin/pip install -e ".[dev]" ``` ## 產生資料包 ```bash cd data/pipeline .venv/bin/election-data pack --county 68000 # 桃園市 .venv/bin/election-data pack --county 00000 # 全國 ``` 輸出在 `data/build/packs/<縣市代碼>/`:`manifest.json`、`villages.json`、`towns.json`、`cells.json`、`history.json`、`topology.json`、`sources.json`,以及給人看的 `report.md`(欄位完整度、補值旗標、與中選會總數的核對)。 第一次執行會下載約 150 MB 的原始資料到 `data/raw/`(有快取,之後不再下載)。 歷史回測用的資料包要排除當次與之後的選舉,避免「先看答案」: ```bash .venv/bin/election-data pack --county 68000 --before 2022-11-26 # → packs/68000-before-2022-11-26 ``` 一次做多個縣市用逗號分隔,`all` 是 22 個縣市。2018、2020 年劇本的資料包要加 `--older`,政黨傾向才有 2016、2018 年的選舉可用(不加時只用 2020 年以後的選舉,現有資料包不受影響): ```bash .venv/bin/election-data pack --county all,00000 --before 2020-01-11 --older # 2020 總統、立委 .venv/bin/election-data pack --county all --before 2018-11-24 --older # 2018 縣市長 ``` ## 劇本資料(全台的真實候選人與各里得票) ```bash .venv/bin/election-data local --year 2022 # 縣市長 → data/build/scenarios/2022-local/<縣市>.json(也可以 2018) .venv/bin/election-data races --year 2024 # 總統、區域立委 → data/build/scenarios/2024-president/、2024-legislator/(也可以 2020) ``` 候選人層級的得票都和中選會有效票核對(0 差);競選經費上限依法定公式計算,2018、2022 縣市長與 2020 總統已和中選會公告核對一致。 立委選區只含選區內的里;選舉後才分出來的新里依相鄰的里歸到選區。 劇本產生後要校準(AI 對打讓全區得票接近真實結果,各區、各里當驗證): ```bash node apps/sim/src/calibrate-local.ts --set 2024-legislator [--only 63000-01] # → data/build/scenarios//calibration.json ``` ## 玩遊戲 ```bash pnpm --filter @election2026/server start # API:http://127.0.0.1:8787 cd ../web && pnpm dev # 網頁:http://localhost:5173(/api 轉給上面的伺服器) ``` 伺服器啟動時不讀資料包,第一局開始時才讀(約 1 秒)。選戰卡牌每一局放在記憶體(最多 200 局),同時寫成 `data/runs/.json`(環境變數 `ROGUE_SAVE_DIR` 可改),伺服器重開也能繼續。 ## 政治獻金(劇本的錢) ```bash cd data/pipeline .venv/bin/election-data donations --election 111年直轄市市長選舉 --area 桃園市 # → data/build/finance/ ``` ## 回測與平衡報告 ```bash pnpm --filter @election2026/sim backtest -- --seeds 12 --rounds 12 ``` 用 AI 對打校準全國風向與投票率倍率,再拿各區、各里結果和真實開票比較,也比對 AI 陣營募到、花掉的錢和真實政治獻金。報告輸出到 `apps/sim/out/`。 ```bash pnpm --filter @election2026/sim balance -- --seeds 30 # 每位候選人 × 五種打法 node apps/sim/src/even.ts # 校準「勢均力敵」劇本的風向 pnpm --filter @election2026/sim rogue-balance # 選戰卡牌的平衡(模擬玩家) ``` `apps/sim/src/` 另外有 `career-balance.ts`、`party-balance.ts`、`ultimate-balance.ts`、`village-balance.ts`,直接用 `node` 執行。 ## 歷屆參選人、政黨、頭像部件 ```bash cd data/pipeline .venv/bin/election-data records # 歷屆參選人與資歷分數 → data/build/people/records.json、data/build/council/<年>.json .venv/bin/election-data parties # 歷屆政黨清單 → data/build/parties/parties.json、packages/protocol/src/parties.ts .venv/bin/python -m election_data.genders # 候選人性別(給頭像)→ data/build/people/genders.json cd ../.. pnpm avatar:build # 頭像部件 SVG → packages/protocol/src/avatar/*.generated.ts ``` ## 人物資料庫與 AI 評分 > 目前遊戲不讀 `people.json` 和評分結果;歷屆參選人頁用的是上面 `records` 產生的客觀資歷分數。 ```bash cd data/pipeline .venv/bin/python -m election_data.people # 產生 data/build/people/people.json .venv/bin/python -m election_data.scoring --dry-run # 不呼叫 API:預覽證據包、估計費用 .venv/bin/python -m election_data.scoring --limit 5 # 先評 5 人試跑 .venv/bin/python -m election_data.scoring # 全部 ``` - 人物資料第一次執行約 8 分鐘(Wikidata 查詢服務有流量限制),之後讀快取約 1 秒。可以設定環境變數 `ELECTION_DATA_CONTACT`(專案網址),放進給 Wikidata 的 User-Agent。人工維護的資料在 `data/pipeline/config/people/`。 - AI 評分使用 Claude API,憑證由 SDK 自行讀取:設定環境變數 `ANTHROPIC_API_KEY`,或安裝 `ant` 指令列工具後執行 `ant auth login`。 - 評分會產生費用。請先用 `--dry-run` 看估計,再決定範圍。 - 評分規則:[`docs/rubric-v1.md`](docs/rubric-v1.md)。輸出 `people_scored.json`、`scoring_report.md`(一致性、政黨偏差檢查)、`review_sample.csv`(人工抽查清單)。 ## 測試 ```bash pnpm test # 協定、引擎、內容、伺服器測試;用到資料包的測試在資料包不存在時略過 pnpm typecheck cd data/pipeline && .venv/bin/pytest && .venv/bin/ruff check src tests ``` ## 資料授權 政府開放資料多採「政府資料開放授權條款第 1 版」,每個資料包的 `sources.json` 列出所有來源、版本、擷取日期與授權。