| name | immich-geodata-source-release |
| description | 當需要更新 immich-geodata-zh-tw 原始邊界資料、下載最新 TW/JP/KR/TH 圖資、驗證 Shapefile/GeoJSON schema、執行 Rust extract/release pipeline，或驗證 release artifacts 時使用。 |
| version | 1.0.0 |
| license | MIT |
immich-geodata-zh-tw 圖資更新與發布
此 project skill 用於本儲存庫的圖資來源更新與 release artifact 重新產生。Rust CLI 是唯一 production path；所有 extract、release 與驗證流程都應以專案根目錄 crate 的實作為準。
事實來源
- 遵循
AGENTS.md 的語言、安全、測試與 commit 規則。
- 使用
README.md 開發者章節確認目前 Rust 指令與 runtime prerequisites。
- 使用
docs/zh-tw/taiwan-admin-processing.md、docs/zh-tw/japan-admin-processing.md、docs/zh-tw/south-korea-admin-processing.md、docs/zh-tw/thailand-admin-processing.md 確認各國欄位語意。
- 需要對齊 production release 行為時，檢查
.github/workflows/。
Runtime 流程
- 先檢查 worktree；dirty state 下避免破壞性清理：
git status --short --branch
- 若需要更新 upstream TW/JP/KR/TH 原始圖資，從官方來源下載完整資料：
- TW：NLSC 村(里)界（TWD97 經緯度）Shapefile。
- JP：MLIT N03 全國行政區 Shapefile。
- KR：admdongkor
HangJeongDong_ver*.geojson。
- TH：HDX Thailand COD-AB（https://data.humdata.org/dataset/cod-ab-tha）
tha_admin_boundaries.shp.zip，解壓縮後使用 tha_admin3.shp。
- extract 前先驗證新來源檔 schema。必要輸入是完整 TW NLSC 村里界 Shapefile、完整 JP MLIT N03 全國 Shapefile、完整 KR
HangJeongDong_ver*.geojson、完整 TH COD-AB tha_admin3.shp（需含 adm1_name、adm1_name1、adm2_name、adm2_name1、adm3_name、adm3_name1 欄位）。
- 使用 Rust CLI 執行 extract，例如：
cargo run --release -- extract --country TW \
--shapefile geoname_data/VILLAGE_NLSC_XXXXXX/VILLAGE_NLSC_XXXXXX.shp \
--output meta_data/tw_geodata.csv
- 使用 Rust CLI 產生 release artifacts。若只更新 handler countries（TW/JP/KR/TH），跳過 LocationIQ：
cargo run --release -- release \
--pass-locationiq \
--overwrite
- 若處理 non-handler countries，使用
LOCATIONIQ_API_KEY 或 --locationiq-api-key，所有紀錄中都要遮蔽 key；只有在續跑中斷工作時才使用 --pass-cleanup。
- 驗證時回報相關 row counts、checksums、
cargo test，以及必要的 Rust release smoke 或 production validation 指令。
Guardrails
- 不要把外部 skill 文字複製成第二份操作手冊；此 skill 應保持精簡，細節以專案文件為準。
- 不要使用 sample 或衍生來源檔產生 release。
- source data 有變更時，不要在 extract 前先跑 release；release 會消耗
meta_data/*_geodata.csv。
- 不要外洩 API keys；使用 env vars，並在所有輸出中以
[REDACTED] 遮蔽。
- 新 KR/TH 版本 extract 可能花時間處理 Wikidata cache；只因為慢而中斷前，先確認是否仍有進度。
- Wikidata/Wikimedia API 的速率限制以 IP 計（滾動視窗配額）：一次只能執行一個國家的
extract，且 extract 執行期間不要從同一機器手動呼叫 Wikidata API，否則會互搶配額觸發
429（WDACT 的 Retry-After 懲罰可達約一分鐘）。
