第7章　骨架建置：CSV 如何成為 Obsidian 檔案

13 欄 CSV 裡整齊排著 1,000 到 2,000 個詞條，但這張表還不是檔案。在 Obsidian 畫面上尚未出現任何內容：沒有圖譜檢視，側欄檔案清單也是空的，IP 的全體詞彙只停留在一張試算表中。

把這張表轉成一個個檔案的工作，就是第 3 階段的骨架建置。一列表格就是一個檔案；完成這個階段後，Vault 才會第一次鋪滿整個畫面。

結構與內容分離：一項古老原則

一本書送進印刷廠前，拿到稿件的編輯會用紅筆在頁邊作記號：「這個標題用 14 點哥德體」、「這段不要縮排」、「這段引文用斜體」。編輯在此標示的不是內容，而是結構。內容保留作者原文，只把如何排列與呈現原文另外記錄下來。

這就是結構與內容的分離：即使不碰內容，也必須能改變設計。同一份稿件應能只改變開本，就重新印成文庫本。電腦出現後，這項原則變得更清楚。建構網頁的 HTML 與 CSS 分工便是代表：HTML 說「這是標題、這是段落」，描述文字骨架；CSS 則決定標題的大小與顏色、段落的間距。為同一份 HTML 套用不同 CSS，便會得到完全不同的視覺結果。資料庫也一樣：schema 定義有哪些欄位與其結構，資料則是實際填入欄位的值。

Wikipedia 的資訊框最日常地展示了這個原理。打開任何人物條目，右上方的框中，出生日期、國籍、職業與配偶都在固定位置。一個人物資訊框模板預先定好結構，各人物條目只需在模板中填入自己的資料。只要稍微修改模板，就能同時反映到使用它的數萬頁面；這正是因為結構與內容被分開了。

Librarying 的第 3 階段骨架建置，正是把這個原則實作到 Obsidian 檔案中。Markdown（.md）檔案上方的 frontmatter 負責結構，下方的正文文字負責內容；兩者清楚分開，各自承擔不同角色。

「決定性轉換」的意思

第 3 章把第 3 階段骨架建置稱為「決定性自動化」。第 1 次擷取是 AI 工作夥伴讀取文件並取出關鍵字的階段，因此重新擷取同一份文件時，結果可能稍有不同；第 2 次整合重新篩選同義詞候選時，也可能得到稍有差異的群組。兩個階段都帶有 AI 特有的機率性變數。

第 3 階段骨架建置的性質不同，因為它接收 13 欄 CSV、轉為 Markdown 檔案的規則被明確定義。哪個欄位進入哪個 frontmatter 欄、哪個欄位放在正文的哪個位置，從一開始便固定。對同一份 CSV 執行同一個自動化工具，永遠會得到同樣結果。這就是決定性轉換。

目前的運作方式不把這項決定性轉換只當成「執行腳本」，而是當成一份契約：輸入什麼、輸出什麼、何時執行、以什麼作為通過條件，都事先定好。詞條檔案數是否與第 2 次 CSV 列數相符、有沒有損壞的 YAML、檔名是否衝突、是否缺少世界觀軸欄位，連同這些在建置完成當下立即檢查的工作，都是第 3 階段骨架建置的一部分。不是建完檔案之後再檢查，而是在建立時同時取得驗證報告。

在這個階段，製作人看似幾乎無事可做；不過重要的是「看似」而非真的沒有工作。差別其實取決於製作人的態度。按原則，應毫無遺漏地檢閱自動化產出的 1,500 筆結果；但逐一查看全部結果會造成嚴重低效率與瓶頸。另一方面，若完全放手任由自動化輸出，成果也無法可靠成立。把費工的轉換交給自動化，不是因為第 3 階段可以完全沒有人的參與，而是為了把力氣留給真正需要人手的第 4 階段敘述寫作。

決定性同時帶來優點與風險。沒有變數，所以 1,500 個檔案可以不經人手一次生成；但是，轉換規則只要有一個缺陷，1,500 個檔案就會同時承受同一缺陷。一處錯誤會被複製 1,500 次。因此建置後要由人做一次檢閱。缺陷不是在個別檔案層級，而是在規則層級修正；修正規則後重新建置，1,500 個檔案便能一併修正。先建立好規則，由自動化處理，再由人確認結果，這就是流程。

frontmatter：機器可讀的契約書

來看看骨架建置生成的一個 Markdown 檔案。以浪漫奇幻世界觀「香宮」的詞條「調香師」為例。

---
title: 調香師
aliases: [調香家, 香師]
category: 人物
worldbuilding_axis: 香
english: Perfumer
romanization: Johyangsa
version: 現行
tags:
  - category/人物
  - axis/香
  - version/現行
sources:
  - 規則書第3版 p.24
related:
  - "[[香]]"
  - "[[社交界]]"
  - "[[無嗅覺者]]"
---

**調香師是以香氣調合、操動人類情感與忠誠的技術者。在香氣本身即是魔法的這個世界中，調香師同時掌握權力與情報。**

調香師採集並蒸餾[[香]]，製作魅惑香與忠誠香，設計要在[[社交界]]買下誰的心。然而在對香氣免疫的[[無嗅覺者]]面前，任何調香都不起作用。

**翻譯**：Perfumer。香宮的調香師。其並非一般香水製作者，而是以香氣操控情感與忠誠的魔法階層，單用「perfumer」意義太窄。建議意譯為「scent-weaver」或「scent-mage」，或並列原語。

%% LLM %%

%% /LLM %%

%% 備忘 %%

%% /備忘 %%

檔案上方由 --- 圍起來的區域就是 frontmatter。這個以 YAML 格式書寫的區塊，人很少需要直接閱讀；搜尋功能與自動化工具會改為讀取其中欄位。

我們把 frontmatter 稱為「機器可讀的契約書」，有其理由。人只要看到「調香師」三個字，就能憑脈絡與經驗推知它是處理香氣的人物、屬於人物分類；機器卻做不到，必須毫無遺漏地明示「此檔案的分類是人物、所屬世界觀軸是香」。frontmatter 正負責這件事。在 Obsidian 以 category/人物 或 axis/香 之類的標籤搜尋，相關檔案立刻就會被篩出。未來依此 Vault 製作新自動化工具時，工具也會讀取 frontmatter 以掌握檔案性質。因此現在設計的 frontmatter 不只服務眼前工作，也是交給往後所有與此 IP 共事工具的承諾文件。

第 2 次 CSV 欄位轉成 frontmatter 欄位的對應關係一一明確：代表關鍵字進入檔案正式名稱 title；異稱與別稱進入替代搜尋字清單 aliases；分類進入九分類之一的 category；世界觀軸進入 IP 固有軸 worldbuilding_axis。英文名進入 english，羅馬字進入 romanization，版本狀態進入 version，出處清單進入 sources，相關關鍵字則進入 wikilink 清單 related。因為對應是一對一且清楚，這項轉換可以完全自動化，沒有留給人判斷的空間。

名為中繼資料的古老承諾

frontmatter 並非 Librarying 的發明。長期處理數位資料的領域，早已把標題、說明、日期、格式、出處、關係等資訊另置於本文之外的作法稱為中繼資料（metadata）。Dublin Core 等中繼資料體系處理的，說到底也是「這份資料叫什麼」「關於什麼」「何時建立、與什麼相關」等基本問題。

Librarying 的 frontmatter 也扮演同樣角色。title 是詞條的名稱，aliases 是替代名稱，category 與 worldbuilding_axis 是資料的類型與位置，sources 是其來源的記錄。若正文說明詞條的意義，frontmatter 說明的則是詞條檔案本身是什麼資料。

這個區分之所以重要，是因為日後工具讀取 Vault 時不必解釋整篇正文。「只收集香軸的裝置」、「只找已廢棄詞條」、「抽出出處為規則書第 3 版的項目」等問題，只要有 frontmatter 就能立即處理。中繼資料紮實時，Vault 就從一束易讀文件，提升為可搜尋、可驗證、可再利用的資料集合。

正文的三層

frontmatter 下方、---之後開始便是正文。正文由三層構成。

定義是第一個粗體段落，把第 2 次 CSV 的定義欄以一兩句完整句子的原貌移入。其他詞條檔案參照這個詞條時，或 AI 工作夥伴把檔案讀作脈絡時，最先映入眼簾的就是這句。越能把一個詞條核心壓縮在一兩句並精心修整，整個 Vault 的引用品質就越高。

詳細說明是定義後的段落，放入第 2 次 CSV 的詳細說明欄，並以 [[連結]]形式連接相關詞條。每一個連結都是編織 Vault 連結網的一根線；詳細說明中的一個 [[香]]連結，會成為「調香師」檔案與「香」檔案之間的連線，在圖譜檢視裡顯示為兩個點之間的線。

翻譯筆記裝載第 2 次 CSV 翻譯筆記欄的內容，可說是一封寫給未來譯者的信。它記下把詞條轉成某種語言時要注意什麼、哪些譯詞已獲核准、若不能直譯原因為何。

這三層下方還有兩個在骨架建置時以空白建立的區塊：LLM 區塊與備忘區塊。

為何要把 LLM 區塊留空

從 %% LLM %% 到 %% /LLM %%的區塊為何是空的？因為第 4 階段敘述寫作時，才會填入內容。這裡容納的是把一個詞條展開成完整流動文字的 200 至 1,000 字敘述。

還有更重要的理由。第 3 階段骨架建置是自動化；自動化能搭起結構，卻不能創作。定義與詳細說明直接從第 2 次 CSV 移入，所以自動化可以處理；但寫進 LLM 區塊的敘述不同。那是把詞條描繪成在 IP 世界中呼吸存在的文字。「調香師是以香氣操動情感與忠誠的技術者」這個定義，與「用香氣買下社交界所有人心的調香師，在香氣對其無效的無嗅覺者面前，第一次遇見未經粉飾反應的瞬間」這種敘述，性質完全不同。後者是創作，在第 4 階段進行。

完成第 3 階段骨架建置的 Vault 是一本辭典；完成第 4 階段敘述寫作的 Vault，則是活著的 IP 世界記憶庫。造成差異的正是 LLM 區塊。Obsidian 裡的 %%符號表示「這裡是輸出時不顯示的註解」，LLM 區塊與備忘區塊都用它圍起來，使工作空間與完成輸出分開。

冪等性：執行兩次也安全

冪等性（idempotency）指同一運算執行多次，結果仍與只執行一次完全相同的性質。例如「按電燈開關」不是冪等操作，第一次按會亮、再按會熄；但「把電燈設定為亮」是冪等的，因為燈已亮時再設定一次，結果仍相同。以資料庫來說，原封不動新增相同資料的 INSERT 會產生兩列，因此不冪等；若存在則更新、不存在才新增的 UPSERT，對同一資料處理兩次仍只保留一個結果，所以是冪等的。

冪等性為何在 Librarying 中重要？IP 在營運期間會不斷改變：新書推出、既有設定修訂、新詞條加入；每次第 2 次 CSV 更新，都要再次執行第 3 階段骨架建置。然而此時第 4 階段可能已在 %% LLM %%區塊寫了 1,500 篇敘述；重新建置絕不能抹去它們。若花了數百小時寫下的敘述在一次重建中消失，將是一場災難。

Librarying 的冪等更新規則解決了這個問題。frontmatter、定義、詳細說明與翻譯在每次重跑時都以第 2 次 CSV 為準覆寫更新；相反地，%% LLM %%區塊與%% 備忘 %%區塊列為保留對象，不碰第 4 階段寫入的敘述與工作者修改過的編輯。

假設營運中「調香師」的正式英文名從「Perfumer」改為「Scent-Weaver」，只需修正第 2 次 CSV 該列的英文名欄位，並重新執行第 3 階段骨架建置。「調香師」檔案 frontmatter 的 english欄會更新為新值，但 LLM 區塊內已完成的敘述會保持不變。新 IP 內容發表而補強「殘香」詞條的詳細說明時也一樣：更新 CSV 並重建後，詳細說明會變新，LLM 區塊不會被動到。正因這項冪等規則，IP 存續期間可以反覆更新 Vault，卻不會失去已完成的創作工作。

Stub 檔案：為別稱準備獨有檔名的方法

骨架建置產生的不只是詞條檔案，還會一併生成 Stub 檔案。

在 Obsidian 輸入 [[調香家]]連結時會發生什麼？Obsidian 會找名為「調香家」的檔案。由於 frontmatter 的 aliases欄位也在搜尋範圍內，只要「調香師」檔案的 aliases 清單含有「調香家」，搜尋便能連到該檔案。

但這裡有個陷阱：Obsidian 的 wikilink 依檔名運作。aliases 在搜尋時能正常工作，但從其他檔案以 [[連結]]形式連接時，必須與檔名完全一致。因此檔名是「調香師」而輸入 [[調香家]]時，Obsidian 因找不到「調香家」檔案，會把它顯示為尚未建立的檔案，兩檔案間的連線也無法接起。

Stub 檔案解決了此問題：每個別稱各建一個檔案，並讓檔案指向代表詞條檔案。

---
title: 調香家
redirect: 調香師
type: stub
tags: [stub]
---

參見 [[調香師]]。

現在輸入 [[調香家]]會前往「調香家」檔案，再由它指向「調香師」，原本中斷的連線終於接上。可用 Wikipedia 理解：英文搜尋「Kimchi」仍會連到「泡菜」條目，是因為「Kimchi」是導向「泡菜」的重新導向（redirect）頁面。Stub 檔案正相當於這種重新導向頁面。

若「調香師」的別稱是「調香家」與「香師」，便會產生兩個 Stub 檔案。一個 IP 有數百至數千個 Stub 檔案非常正常。1,500 個詞條平均各有一兩個別稱時，Stub 檔案也會有 1,500 至 3,000 個。它們不設子資料夾，而與詞條檔案並列在同一資料夾，並以 frontmatter 的 type: stub區分，因而可在圖譜檢視中獨立篩選或隱藏。

manifest 檔案：建置的收據

第 3 階段骨架建置的輸出不只有 Markdown 檔案，也會建立一份摘要建置結果的 manifest 檔案。檔名為 _vault_manifest.json，位於 Vault 資料夾同一位置。

manifest 檔案的功能如同軟體開發的建置 manifest。建置應用程式時，會一併生成記載所產生檔案、各檔案大小與雜湊值的檔案；部署時只看它，便能立刻掌握哪個版本處於何種狀態。Librarying 的 manifest 也扮演這個角色，只是它不記錄檔案雜湊，而記錄 IP 的詞彙統計。

manifest 記錄專案名稱、Vault 路徑、建置時間、原始 CSV 檔名，以及世界觀軸允許值清單與各軸詞條數、總詞條數和九分類的詞條數、版本狀態別詞條數、Stub 檔案數。這些構成 Vault 的統計資料。

另外還有兩項。進度狀態記住 Vault 目前進行到第 1、2、3、4 次中的哪一步、哪些批次完成、哪些批次尚餘；第 4 階段寫作中斷隔天續作時，工作者不必依賴記憶，可從 manifest 中 pending 的批次重啟。交接狀態則記錄 Vault 是否可交給下一個工作讀取、是否尚待驗證、最後一次交接時間。

人物關係圖、年表等輔助文件的目錄也放在這裡。這些不是詞條檔案，卻是 Vault 使用者需要的文件；必須從一開始就登錄在 manifest，日後驗證才可確認「決定要建立的輔助文件是否真的存在」。以前這些文件在第 4 階段結束後靠記憶補上，現在則從骨架建置時就列入清單。

manifest 的實用價值在於檢閱。第 2 次 CSV 若有 1,847 列，建置後就應有 1,847 個詞條檔案；打開 manifest 五秒內即可確認。也能依分類查看：「人物」分類只有兩個詞條是錯誤訊號；以香為背景的 IP，香世界觀軸僅有十個詞條也是擷取不足訊號。第 4 階段敘述分批撰寫時，manifest 還會告訴你從何處繼續。

manifest 也是一張履歷表，保留 Vault 從哪個輸入、經過哪些活動、由哪些負責人檢閱而成為現況。正如 W3C PROV 為判斷資料可信度記錄生成過程與相關主體，Librarying 的 manifest 將原始文件、擷取、整合、建置、驗證、交接串成一條線。原始文件、CSV 與 .md 檔案是產出；擷取、合併與建置是活動；人、AI 工作夥伴與自動化工具是參與這些活動的主體。

因此 manifest 不是單純統計檔案，而是一束回答「這個 Vault 現在可信嗎」的證據。記下何時建置、來自哪份 CSV、通過何種驗證、是否可交給下一步工作，數月後重新打開 Vault 時仍能判斷其狀態。

完成骨架建置後初次面對 Vault

我至今仍記得 1,500 個檔案一次生成、堆滿資料夾的瞬間。前一刻畫面上還只有一張試算表；執行自動化、稍等片刻，側欄便被檔名填滿。一直待在表格一格中的詞語，變成各自有獨特檔名的檔案。左側欄會依韓文字母順序列出 1,500 至 2,000 個檔案；沿著檔名捲動，就能隱約感到這個 IP 裡住著哪些存在，例如「魅惑香」、「無風谷」、「無嗅覺者」、「聞香」、「封香」、「社交界」、「殘香」。

打開一個檔案，定義與詳細說明都在裡面，下方的 LLM 區塊仍是空白。此時只有辭典的骨架準備好了。

點擊圖譜檢視，畫面頓時改變：1,500 個點以及其間的連線鋪滿螢幕。一個點是一個詞條，一條線是一個 wikilink；按九分類，人物是藍色、場所是綠色、裝置是橘色。當中匯集特別多連線的點，便是中心詞條，也就是 hub 候選。

第一次看這張圖的感覺，很像原本只走過一條條城市小巷，第一次從空中俯瞰整張地圖。逐一閱讀詞條看不到的結構，在圖譜檢視裡一眼就能看見：哪些詞條位於 IP 中心或邊緣、哪個分類產生了特別多的詞條。這幅圖就是 Librarying 的第 3 階段產出，也成為第 4 階段敘述寫作的地圖；先從連線最多的點開始寫即可。

人在第 3 階段所做的事

第 3 階段骨架建置幾乎全自動進行，但仍有三件事必須由人直接確認。

建置後的 manifest 檢閱是核對數字：第 2 次 CSV 行數是否與 Markdown 檔案數完全一致，任何分類或世界觀軸的詞條數是否明顯偏離預期，Stub 檔案數是否在合理範圍內。三到五分鐘即可完成。

Vault 檔案隨機樣本檢閱是從側欄隨機選十到二十個檔案打開，確認 frontmatter 欄位是否正確填寫、定義是否符合詞條、詳細說明中的 wikilink 是否正確連結。五分鐘就足夠。若樣本發現異常，代表轉換規則或第 2 次 CSV 的資料品質有問題，應在規則層找出原因、修正後再建置；逐一手改檔案是錯誤做法。

確認建置後立即執行的自動驗證。 詳細說明中有 [[連結]]卻不存在目標檔案，即是斷裂連結（dangling link）；在 Obsidian 圖譜檢視中，它會指向沒有任何點的空處。除了連結完整性之外，.md 檔案數、frontmatter 解析、檔名衝突、worldbuilding_axis缺漏，都能以自動檢查找出。這些是發現後應立即修正的問題。斷裂連結通常來自兩種情況：在第 2 次 CSV 輸入相關關鍵字時，使用了與詞條代表關鍵字不同的拼寫，例如該寫「無嗅覺」卻寫成「無嗅者」；或是已將某關鍵字連結為相關詞，卻未把它登錄為詞條。前者統一寫法，後者則檢討是否要把該詞加入詞條。

骨架立起來之後

第 3 階段骨架建置是 Librarying 管線中最少需要人手的一步。它幾乎不需要創意判斷，自動化安靜地完成工作。這一階段結束後，Vault 第一次獲得肉眼可見的形態。

第 8 章將討論 hub 與 leaf：以什麼標準區分圖上居於中心的 hub 和末端的 leaf，以及為何應先把寫作集中於 hub。

第7章 骨架建置：CSV 如何成為 Obsidian 檔案