台灣史探索

今天，我們終於走到了 11 個流域探索計畫的最後一站：頭前溪。 作為這系列數位探索的「大終章」，頭前溪對我的意義非比尋常。這是我生活的主場，也是我每日通勤、呼吸的水源地。但也正因為這份熟悉，當我用之前產製的「AI 深度研究計畫 (Research 3)」去對合時，我感到了前所未有的 「違和感」。 這篇筆記，將記錄我們如何在這最後一站，完成 HGIS 方法論的 「權力對合革命」。 1. 質疑與修正：當 AI 遺漏了靈魂 之前的 AI 報告（Research 3）過於迷戀「科學園區供水」與「豆腐岩」的現代地景。但如果你翻開《新竹五書》，你會發現頭前溪的靈魂其實被隱藏在 「竹東、東興、隆恩、汀甫」 這四條名圳裡。 竹東圳 (21km)：它不是普通的溝渠，它是 1920 年代跨流域引水的工程奇蹟，更是後來科學園區水路技術的「史前雛形」。 東興圳：它在竹北高鐵區的斜向流動，是客家士紳對抗現代格子城市格線的最後痕跡。 筆記心得：如果探索不包含這些大圳，我們只是在看「河床」，而不是在讀「社會脈動」。 2. 從「地理圖釘」進化為「角色繫結 (Entity-Binding)」 這是我在這一站做的最大修正。以往我們只標記「這裡是隆恩堰」，但現在，我們強行執行了 POI Actor Attribution： 節點 = 問禮堂 -> 角色繫結 = 六家林家。 節點 = 指標性圳路 -> 角色繫結 = 王世傑 (新竹規劃師)。 這就是我們在 系列五：知識圖譜 中提到的邏輯。當地圖上的圖釘不再是死物，而是連結著《新竹五書》中鮮活的家族利益與水權博弈時，你的導航助理才會告訴你：「這不只是水，這是王世傑當年為了軍隊運糧所佈下的百年棋局。」 3. 數位資產的極致對合 (Triple-Sync) 在頭前溪計畫中，我們實踐了目前最複雜的數據對稱： KML 層級化：嚴格依照 RV_NO 分出主流、支流與次溪流，並注入 Associated_Entity 屬性。 SQLite 高階化：首次在 walkgis.db 中全面使用 WKT (Well-Known Text) 語法定錨空間標註。 ISMap 模組化：將計畫拆解為四大權力弧線（邊界、規劃、士紳、門戶），支援隨時「進場/離場」的模組化走查。 4. 11 流域工程的終局感悟 從第一站到第十一站，這場數位鍊金術讓我明白：「地圖是實體世界的代碼，而 HGIS 是對這段代碼的逆向工程。」 ...

在實現 QGIS 專案「一鍵生成」的路上，我們不僅要讓圖層「開得出來」，更要讓它「具備研究價值」。 這篇文章記錄了我們從 POC2 (樣式與標籤整合) 進化到 POC3 (空間分析與 SDM 紀律) 的完整心路歷程。這兩個階段分別解決了製圖中的「美學溝通」與「科學建模」兩大核心問題。 🎨 POC2：視覺精煉與動態標籤 (Visualization & Labeling) 目的：讓地圖「會說話」，透過自動化配置解決手動製圖中最繁瑣的排版工作。 在 POC1 成功掛載圖層後，我們發現原始的點位與線條在混亂的歷史底圖（如台灣堡圖）上極難辨識。POC2 的核心目標即是透過腳本，賦予地圖專業的視覺外觀。 1. 幾何感知的自動標註 (Geometry-aware placement) 我們實現了腳本對圖層類型的自動識別與對應配置： 點位圖層 (遺址)：自動採用 Centroid 配置，讓標籤精確落在遺址中心。 線段圖層 (河流)：自動切換為 Around Line (平行排列)，並預設帶有 0.5mm 的偏移量。這讓河名能順著水流蜿蜒，展現專業製圖感。 2. 跨平台字型與視覺消隱 (The macOS Fix) 我們在 POC2 中遭遇了字型相容性的重擊。原本預設的字型在 Mac 上會毀掉專案解析。最終，我們強制切換為 PingFang TC (萍方-繁)，並自動啟用了 0.7mm 白色光暈 (Text Buffer)。這小小的光暈，是讓地圖文字從花綠底圖中「浮現」出來的關鍵。 🛡️ POC3：空間分析中樞與 SDM 紀律 (Advanced Analysis & SDM) 目的：從「資料顯示」進化為「規律開發」，在不污染原始數據的前提下，自動生成分析模型。 當地圖變漂亮後，下一步就是「看見模式」。POC3 挑戰的是自動產出具有研究深度的分析圖層（如海拔區間與熱點圖）。 1. 恪守 SDM 紀律：絕對不改動原始資料 (Data Hub Snapshot) 開發者常為了分析方便，在原始 SQLite 裡建 View。但對歷史數據來說，原始碼應該是神聖的 (Holy Source)。 我們實作了「局部資料中樞 (Local Data Hub)」：腳本在產出專案的一瞬間，自動建立一個 poc_data_hub.db 快照。所有的 JSON 萃取、高程分區計算都只存在於這份快照中。原始 HGIS 資料庫保持 100% 乾淨，專案檔則是「可打包、可重製、可拋棄」的。 ...

在進行 HGIS（歷史地理資訊系統）研究時，我發現最耗時的往往不是分析數據，而是「準備地圖」。每次要開啟一個新研究，總要重複掛載百年歷史底圖、設定 KML 座標、調整 SQLite 的 SQL 篩選器…。 為了打破這個瓶頸，我發起了一場實驗：能不能像寫程式一樣，用「寫」的出一份 QGIS 專案？ 這就是我最近在推動的 軟體定義地圖 (Software-Defined Maps, SDM) 概念。 🏗️ 為什麼要自動化？ 如果你手動配置過 QGIS，你一定遇過這些崩潰瞬間： URL 特殊字元破壞專案：WMTS 的 URL 裡一堆 &，手動貼上 XML 常報錯。 座標系統 (CRS) 位移：明明設定了 WGS84，圖層卻飄到非洲西岸海面（座標 0,0）。 重複定義的勞力：每個專案都要重新分組（底圖、水理、點位），這應該交給機器人。 透過 Python + Jinja2 模板，我們可以把地圖專案變成可程式化的零件。 🛠️ 基本作法：Jinja2 零件化 核心思路是將 .qgs 專案檔（實質是 XML）拆解為模板。 我們建立了一個 base_project.qgs.j2，裡面預留了動態注入的內容： 層級化圖層樹：自動生成的分組。 資料源設定：SQL 篩選指令與檔案路徑。 空間參考系統：自動注入對應的 AuthID、Proj4 與 SRID。 最關鍵的「零件庫」是 GIS_KNOWLEDGE.yaml。它充當了 GIS 資源的「DNS 伺服器」，記錄了所有中研院底圖、本機 KML 與資料庫的 Metadata。 🚀 第一階段 POC：曾文溪 HGIS 數位中樞 在這次的 POC 中，我們成功實現了 Zengwen_HGIS_Hub.qgs 的一鍵產出： ...

在完成平面位置 (X, Y) 的座標標註與河流距離分析後，我總覺得地圖還少了點什麼。直到我們引入了 Z 軸——也就是高程數據，整個曾文溪流域的歷史才真正「活」了起來。 這是我在 HGIS 建模中最精彩的一場實驗：運用 20m DTM (數位地形模型)，讓遺址開口說出三千年來海陸變遷的秘密。 🏔️ 海拔高度：決定「是海還是陸」的生死線 在台南平原，海拔 5 到 10 公尺是一個神奇的區間。 透過 scripts/enrich_sites_with_elevation.py，我們讓 133 處曾文溪流域遺址自動去匹配內政部的 DTM 資料。這是一個跨縣市的圖磚掃描工具，能精確取出每一筆數據的高度。 考古證詞：南科考古館的案例 以 南科考古館 為例，其海拔約 5-7 公尺。 三千年前：這裡的海拔正好處於古台江內海的沙丘邊緣。大坌坑遺址中發現的「貝塚」，證明了這裡曾是海景第一排。 一千年前：隨著曾文溪泥沙沖積，海拔 6 公尺處變成了濕地與三角洲。 今日：它縮到了離海岸 30 公里的平原中心。 海拔等高線，正是這場「海退人進」演義中的指揮線。 🤖 Layer 3：讓 AI 具備「大歷史語義」 當我們有了 XY 座標、河流距離與 Z 軸高度後，我問了 AI 助理一個問題：「能根據這些數據，幫我寫出一段吸引人的導覽文字嗎？」 這就是 Layer 3：大歷史語義層 (Semantic Context Layer)。 我開發了 scripts/batch_l3_enrichment.py 作業管線。它不只是跑跑程式，而是讓 Gemini 扮演一位考古學家，結合這三個維度的數據，自動生成「地理歷史脈絡」。 AI 生成範例： 「這處遺址位於海拔 540 公尺的穩定河階，離曾文溪主流恰好保持 2.2 公里的安全觀測距離。這顯示先民在金屬器時代已具備極強的避災智慧，選擇了這塊永遠免疫洪水改道的『定海神針』…」 🛠️ 釋出指南 (Release Guide) 這一系列針對考古與地貌的深度模型，我已全數彙整進 Taiwan History Atlas 儲存庫的 v260306.1 更新 中。 ...

當我們在地圖上標註了全台兩千五百多個考古遺址後，下一個問題是：「為什麼他們要住在這？」 在傳統的 HGIS 中，我們習慣去找「古地圖」。但面對三千年前的遺址，世界地圖還是一片空白。這時，我們必須切換思維，引入 Layer 4：空間拓樸分析 (Spatial Topology)。 📐 什麼是 Layer 4？跳脫物理地表的「相對關係」 如果說 L1 是點位，L2 是知識，那麼 Layer 4 就是「點與環境的交互作用」。 我不想只是知道遺址在哪裡，我想知道它與「生存資源」——特別是河流的幾何關係。在曾文溪流域，河道會擺盪、海岸線會進退，但人類對於「取水與避災」的空間邏輯往往是恆定的。 透過 scripts/poc_l4_tributary_clustering.py 這個對合引擎，我們讓 2,249 個遺址自動去尋找它們對應的主流與支流，計算出精確的「離水距離」。 📊 數據發現：離水 2.5 公里的生存密碼 透過分析，我們在曾文溪流域發現了一個驚人的統計規律： 濱海初始期：離水最近距離平均約 2,700 公尺。 長期定居點：離水最近距離平均約 2,200 公尺。 這是一個 「生存甜蜜點」。 在那個沒有堤防的年代，住得太近（如 1km 內）會面臨曾文溪猛烈氾濫的改道威脅；住得太遠又取水不便。 這 2.5 公里的緩衝帶，正是史前先民在沒有現代水利工程的情況下，利用地形與距離「換取安全」的生存智慧。 🛠️ 核心工具：空間特徵標記 (Feature Extractor) 為了實現這種規模的運算，我在儲存庫中提供了一個關鍵腳本： scripts/feature_extractor.py：它不只記錄座標，更會透過幾何運算為每個點位打上「空間標籤」。例如：是否位於「河流樞紐」、屬於哪個「次流域」、以及其「離水梯度」。 這樣的設計，讓 AI Agent 在解讀資料時，不再只是讀到一串數字，而是讀到一個 「人類與環境博弈的空間邏輯」。 🤖 AI Skill 的深度應用 這項分析成果已整合進我們的 HGIS Architect AI Skill。 目前的 AI 助理不再只是會翻翻方志摘要，當你開啟此 Skill 並指向一個座標時，它能調用 L4 的拓樸數據告訴你：「這個位置雖然現在離曾文溪很遠，但在三千年前，它正好位於主要支流的交會口，是一個戰略性的交通節點。」 ...

在之前的 HGIS 系列中，我們主要處理的是「紙上的歷史」——透過方志與古籍還原清代的社會空間。然而，要真正觸摸到「台灣主體性」最深層的脈絡，我們必須將目光投向更長的時間尺度：考古遺址。 如果說《臺灣通史》記載的是數百年的族群演進，那麼埋藏在台南平原地底下的「文化層」，則是長達數千年的地景變遷證詞。 今天，我正式在 Taiwan History Atlas 專案中發布了 v260306.1 更新，核心重點就在於建構一套具備「血緣追蹤」能力的 考古遺址 Master Registry (主註冊表)。 🏛️ 為什麼我們需要 Master Registry？ 在處理全台遺址資料時，最頭痛的不是「沒資料」，而是「資料太多且碎片化」。文資局有「法定遺址」、中研院有「普查遺址」、地方政府還有「疑似遺址」。 要在 AI 輔助下進行科學分析，我們不能只是貼貼補補，必須建立一個 Master Registry： 資料對齊：解決同一個遺址在不同單位有不同名字 or 座標微差的問題。 層級化建模：將原始資料 (L0) 轉化為帶有語義標籤的實體 (L1)，再整合進知識中樞 (L2)。 血緣追蹤 (Source Origin)：每一筆數據都能回溯到是哪個單位的原始點位，確保「證據力」。 目前這套系統已成功整合了 2,563 處 遺址，成為我們 HGIS 引擎中最堅實的核心數據庫。 🛠️ 核心腳本與工作流 (Scripts Toolkit) 在 taiwan-history-atlas 儲存庫中，我們透過以下工具實現了這一流程： 1. Layer 1：實體萃取與特徵標記 利用 scripts/extract_entities.py，AI 會自動掃描原始 Open Data 文本，提取出： 文化年代：從大坌坑、蔦松到金屬器時代。 遺址等級：Rank 1（國定）到 Rank 4（疑似）。 特徵標籤：貝塚、石器、多層疊壓等。 2. Layer 2：跨庫遷移與合成 使用 scripts/atlas_migrator.py，將分散在各區域的實體統一遷移至 data/history_atlas.db。這個過程不只是搬家，更是在進行「去重 (De-duplication)」與「血緣標註」。 ...

當我們開始嘗試將 AI 與歷史地理資訊系統 (HGIS) 結合時，最初是在探勘總體性的《臺灣通史》。但歷史的魔鬼往往藏在地方的細節裡。 為了驗證我們的架構是否具備「橫向擴展」到區域史料的能力，我將目光轉向了北台灣早期的政經中心——竹塹 (新竹)。這次，我決定一次挑戰五本重量級的地方方志：《新竹縣採訪冊》、《淡水廳志》、《樹杞林志》、《新竹縣志初稿》、《新竹縣制度考》。 這五本書，總計 34 卷、9,000 多條史料片段。如果單靠純文本搜尋，那就像是在汪洋中撈針。 今天，我正式在 Taiwan History Atlas 專案中，釋出了這套針對新竹史料開發的「多書跨卷整合與空間對合框架」，並同步上線了 竹塹五書歷史知識地圖。 🏗️ L0-L1-L2：史料的階梯式煉金術 要讓 AI 不會在這 9,000 多條文獻中「幻覺」，我們採用了嚴謹的「分散式溯源，集中式建模」三層架構： 1. L0 文獻底座 (Text ETL) 有別於單一文本，地方方志的卷次編排極度不一致。透過 hsinchu_multi_loader.py，我們實作了多種 Regex 解析器，一次性將五本史書的目錄、卷次、條目全部打散又重組，完美塞入 hsinchu_history.db 的標準 Documents -> Volumes -> Contents 結構中。 2. L1 實體萃取與降維對合 (Entities & Linkage) 光有文字不夠，我們需要提取「有意義」的節點。 透過 AI 輔助腳本，我們一口氣從五書中抓出了三類實體： Infrastructure (基礎建設)：1,410 筆（橋樑、隘口、古道、城門等）。 Location (聚落空間)：4,343 筆（堡、里、庄、社、窠、坑等）。 Irrigation (水利開發)：834 筆（陂圳、埤塘、水門等）。 但困難來了：古地名在地圖上是找不到座標的！ 例如史書寫「隆恩圳」或「林先坤陂」，現代 Google Map 根本不知道在哪。 這時我們啟動了 「地理特徵降維打擊」 的演算法。我們寫了清洗函數（如 clean_infra_name, clean_water_name），把地名的尾巴（像是 xxx庄、xxx圳、xxx城門）全部剁掉，只保留核心字根。 ...

在《台灣歷史知識地圖》Layer 2 架構釋出後，我們隨即投入了第一個實戰場域：曾文溪流域。 這次的目標非常明確：我們不再滿足於地圖上冷冰冰的座標點，而是要透過「時空對合」技術，讓曾文溪流域的 696 個 POI 全部具備歷史靈魂與文獻厚度。 任務目標：構建曾文溪「厚數據」圖層 傳統的地圖標註往往只有名稱與座標，但我們希望構建的是具備歷史深度 (Depth)、水利脈絡 (Context) 與 因果邏輯 (Logic) 的「厚數據 POI」。 這意味著，當你走到曾文溪畔的一個小村落時，AI 不僅能告訴你這裡是哪裡，還能告訴你： 這個地名在 1920 年代的行政歸屬。 它在《臺灣通史》或其他地方志中被如何記載。 它與曾文溪水系（如埤圳、改道）的深層互動關係。 製作歷程：數位考古的三部曲 這次的產製過程是一次典型的「AI 協作數位鍊金術」，分為三個階段： 1. 空間鎖定層 (Spatial Anchor) 利用中研院提供的 1920 年代行政邊界 SHP 檔，與曾文溪流域範圍進行空間交集。我們篩選出了 100 個「大字 (Oaza)」點位，並計算其精確的 WGS84 座標。這是將歷史文本對齊到現代地圖的「時空錨點」。 2. 文獻厚化層 (Textual Enrichment) 這是最精彩的部分。我們開發了專門的萃取腳本，針對這 100 個古名點位，自動檢索 taiwan_history.db。 跨庫鉤稽：除了 1920 年代的官方資料，我們更進一步引入了內政部古地名庫的 37,758 筆資料，篩選出流域內的 813 筆關鍵紀錄。 故事萃取：不僅抓取名稱，更重點提取「地名由來（Place Mean）」，例如某個村落是因為躲避曾文溪改道水患而搬遷的。 3. 邏輯建模與匯入 最後，我們將這些分散的片段，透過 Python 腳本整合為 WalkGIS 特徵檔案。總計 696 個厚數據 POI 被正式匯入系統。 成果展示：三個有靈魂的 POI 讓我們看看這套流程產出的成果： ...

在先前的系列中，我們完成了從原始文本（Layer 0）到結構實體（Layer 1）的跨越。透過 Python 腳本，我們讓幾十萬字的《臺灣通史》變成了資料庫中清晰的人名、地名與座標。 但在數位考古的最後一哩路，我們面臨了一個更終極的挑戰：AI 該如何「理解」歷史的動態邏輯，而不僅僅是搜尋關鍵字？ 這就是今天我們要分享的壓軸戰役——Layer 2：知識中樞 (Knowledge Atlas) 的建構，以及本專案正式對外開源的里程碑。 從「搜尋」進化到「理解」：何謂 Layer 2？ 如果 Layer 1 是史料中的「單點實體」，那麼 Layer 2 就是將這些點連成線、織成網的「邏輯圖譜」。 當我問 AI：「為什麼清代的新竹會發展出如此發達的水利系統？」傳統的 RAG 頂多能幫我找到幾段描述。但擁有 Layer 2 知識中樞的 AI，能直接調用我們今日建立的五大專題模型： 水利開發模型 (Eco_System)：結構化全台 226 處埤圳，整合開鑿者與水源脈絡。 產業貿易模型 (Economy)：分析「南糖北茶」的經濟地理骨架。 官職權力模型 (Gov_Structure)：釐清三代政權演變與行政邊界。 衝突因果模型 (Conflict_Logic)：建模民變、械鬥與海防轉向的底層邏輯。 地名演進矩陣 (Toponym_Ref)：建立「古社名 -> 舊地名 -> 現代區劃」的跨時空映射。 這意味著，現在的 AI 助理（如 Antigravity）已經不只是在陪我翻古書，它更像是一位**「數位歷史策展人」**。 數位鏈金術的成果：taiwan-history-atlas 正式釋出 為了讓這份努力產出的數位資產不只是鎖在我的硬碟裡，今天我們做了一個重要的決定：將今日建構的所有腳本、資料庫 Schema 與核心 Layer 2 知識資產，正式獨立封裝並在 GitHub 上開源。 🔗 Repo 連結： https://github.com/wuulong/taiwan-history-atlas 這個版本不僅僅是一個資料集。它包含了： taiwan_history.db：具備三層架構的核心資料庫。 全套 AI 建模腳本：讓你可以複製這套方法論去處理其他的歷史志書。 AI 導航指引：教導如何引導 GPT/Claude 等 Agentic AI 使用這座歷史大腦的方法論。 授權：公眾領域貢獻 (CC0) 我們決定採用 CC0 1.0 通用公眾領域貢獻宣告 釋出這個專案。 ...

在建立完這套由「時光羅盤 + 歷史文本 + 自動空間配對」組成的 歷史空間感知引擎 (HGIS) 後，一定有人會問：費這麼大功夫寫程式，究竟能帶來什麼改變？ 答案是：它將徹底顛覆我們閱讀歷史與感知旅行的方式。 讓我們用新竹開源始祖——王世傑 來做個火力展示。 傳統閱讀法的侷限 如果你翻開《臺灣通史．列傳三》，你會讀到王世傑是因為幫鄭克塽的軍隊「運餉有功」，所以獲准前去開拓「竹塹埔」。這是一個很典型的拓王傳記，但也僅止於此。 HGIS 的跨域聯動 (Knowledge Graph) 但現在，我們擁有的是一個具備空間關聯性的資料庫。我透過 SQL 引擎對全庫下達指令，去搜尋「王世傑」這三個字在整本地圖與史書中的關節點。 奇蹟發生了，資料庫以空間座標為支點，將原本散落在不同章節的片段，拼湊成了一張無比立體的「城鎮規劃藍圖」： 取得合法性與資本： 來源：《列傳三》 內容：靠著支援軍事後勤（運糧）獲得竹塹的獨家開墾特許權。這是一切政治資本的起點。 切開經濟命脈 (紅藍圖釘連線)： 來源：《農業志》 內容：當上大開發商（業戶）後，出資主導開鑿了我們前幾天才在地圖上完成配對的**「隆恩圳（四百甲圳）」**。這條水路一口氣灌溉了兩千甲良田，也是我們最初在地形圖上看到「黃金洞」的原因！ 穩定社會的定海神針 (紅色圖釘)： 來源：《宗教志》 內容：人在吃飽之後，需要心靈依託。王世傑在南門的「巡司埔」捐地，興建了新竹最古老的觀音亭——「竹蓮寺」。 透過這樣跨越篇章的串聯，王世傑的形象立體化了。他不是一個帶著鋤頭亂挖的農夫，他是用**「水利工程（養活肉體）」與「信仰中心（凝聚精神）」，聯手畫下了大新竹百年格局的城鎮綜合規劃師**。 下一步：會說古書的語音助理 現在，這些關聯的經緯度與史料脈絡，都已經封裝成 KML 與 JSON 格式。 未來，當我們開車經過新竹市區的「竹蓮寺」，或是馳騁在「隆恩圳」遺址旁時。我的 Smart Traveling Assistant (智慧行車助理) 的雷達一旦感測到這些 WGS84 座標，就會瞬間在背景調用這套 HGIS 引擎。 它會用語音告訴我： 「哈爸，你現在位在竹蓮寺。這不只是一間大廟，它跟我們剛剛經過的那條隆恩圳，都是三百年前那個為了軍隊運糧的男人——王世傑，一手擘劃百年帝國的拼圖…」 從地圖上的一個疑惑，到實體化一整套能運作的歷史感知大腦。這就是我們這場數位鏈金術的最終意義：讓歷史不再只存在紙上，而是真正走進了我們每一次漫遊的風景裡。 (全系列完) 本文為哈爸與 AI 助理協作產出，紀錄實體探勘與數位工程之歷程。