第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 阶段骨架构建称作“确定性自动化”。第一次提取是 AI 工作伙伴阅读文档并抽出关键词的阶段，所以重新提取同一份文档时，结果可能略有不同；第二次整合重新筛选同义词候选时，也可能得到稍有差异的分组。两个阶段都带有 AI 特有的概率性变量。

第 3 阶段骨架构建的性质不同，因为接收 13 列 CSV、转换为 Markdown 文件的规则已经明确规定。哪个列进入哪个 frontmatter 字段、哪个列放在正文的哪个位置，从一开始就固定。对同一 CSV 运行同一个自动化工具，始终会得到相同结果。这就是确定性转换。

在当前的运行方式中，这种确定性转换并不被当作单纯的“执行脚本”，而是被当作一份契约：接收什么输入、输出什么、何时执行、以什么为通过条件，都预先确定。词条文件数是否与第二次 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 共事工具的承诺文档。

第二次 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 下方、---之后就是正文。正文由三层构成。

定义是第一个粗体段落，把第二次 CSV 的定义列以一两句完整句子的原貌移入。其他词条文件参照这个词条时，或 AI 工作伙伴把该文件读作上下文时，最先看到的就是这句话。把一个词条核心压缩为一两句并细致打磨得越好，整个 Vault 的引用质量越高。

详细说明位于定义之后，放入第二次 CSV 的详细说明列，并用 [[链接]]连接相关词条。每个链接都是编织 Vault 连接网的一根线；详细说明里的一个 [[香]]链接，会成为“调香师”文件和“香”文件之间的连线，在图谱视图中显示为两点间的线。

翻译笔记放入第二次 CSV 的翻译笔记列，可以说是写给未来译者的一封信。它记录将该词条译成某种语言时应注意什么、哪些译词已经获准、若无法直译原因是什么。

这三层之下，还有两个在骨架构建时以空白建立的区块：LLM 区块与备忘区块。

为什么要把 LLM 区块留空

从 %% LLM %%到 %% /LLM %%的区块为什么为空？因为它是第 4 阶段叙述写作时才会填入文字的地方。这里容纳的是将一个词条展开为完整流动文字的 200 到 1,000 字叙述。

还有更重要的理由。第 3 阶段骨架构建是自动化；自动化可以搭起结构，却无法创作。定义和详细说明都直接从第二次 CSV 移入，所以可以由自动化处理；但写进 LLM 区块的叙述不同。那是把词条描绘成在 IP 世界中呼吸存在的文字。“调香师是以香气操动情感与忠诚的技术者”这个定义，与“用香气买下社交界所有人心的调香师，在香气对其无效的无嗅觉者面前，第一次遇到未经粉饰反应的瞬间”这种叙述，性质完全不同。后者是创作，在第 4 阶段完成。

完成第 3 阶段骨架构建的 Vault 是一本词典；完成第 4 阶段叙述写作的 Vault，则是活着的 IP 世界的记忆库。造成这种差异的正是 LLM 区块。在 Obsidian 中，%%符号表示“这里是输出时不显示的注释”；LLM 区块与备忘区块都以此注释符号包围，将工作空间与完成输出分开。

幂等性：执行两次也安全

幂等性（idempotency）指同一运算执行多次，结果仍与只执行一次时完全相同的性质。例如“按电灯开关”不是幂等操作，因为第一次按会亮、第二次按会灭；“把电灯设为亮”则是幂等的，因为灯已亮时再设一次，结果不变。以数据库来说，原样添加相同数据的 INSERT 会产生两行，因而不幂等；若已存在就更新、不存在才添加的 UPSERT，对相同数据处理两次仍只有一个结果，所以是幂等的。

幂等性为何在 Librarying 中重要？IP 在运营期间会不断变化：新书推出、既有设定修订、新词条加入；每次第二次 CSV 更新，都必须重新运行第 3 阶段骨架构建。然而此时第 4 阶段可能已经在 %% LLM %%区块写下 1,500 篇叙述；重新构建绝不能抹去它们。若花数百小时写下的叙述在一次重建中消失，将是一场灾难。

Librarying 的幂等更新规则解决了这个问题。frontmatter、定义、详细说明与翻译在每次重跑时都以第二次 CSV 为准进行覆盖更新；相反地，%% LLM %%区块和%% 备忘 %%区块作为保留对象，不会触动第 4 阶段写入的叙述和工作者修改过的编辑。

假设运营中“调香师”的正式英文名从“Perfumer”改为“Scent-Weaver”，只需修改第二次 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 的实用价值在于检阅。第二次 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 检阅是核对数字：第二次 CSV 行数是否与 Markdown 文件数完全一致，任何分类或世界观轴的词条数是否明显偏离预期，Stub 文件数是否在合理范围内。三到五分钟即可完成。

Vault 文件随机样本检阅是从侧栏随机选十到二十个文件打开，确认 frontmatter 字段是否正确填写、定义是否符合词条、详细说明中的 wikilink 是否正确连接。五分钟便足够。若样本发现异常，代表转换规则或第二次 CSV 的数据质量有问题，应在规则层寻找原因、修正后重新构建；逐一手改文件是错误做法。

确认构建后立即执行的自动验证。 详细说明中有 [[链接]]却不存在目标文件，就是断裂链接（dangling link）；在 Obsidian 图谱视图中，它会指向没有任何点的空处。除了链接完整性外，.md 文件数、frontmatter 解析、文件名冲突、worldbuilding_axis缺失，都可由自动检查找出。这些是发现后应立即修正的问题。断裂链接通常来自两种情况：在第二次 CSV 输入相关关键词时，使用了与词条代表关键词不同的拼写，例如该写“无嗅觉”却写成“无嗅者”；或已将某关键词连接为相关词，却未将其登记为词条。前者统一写法，后者则检讨是否要把该词加入词条。

骨架立起来之后

第 3 阶段骨架构建是 Librarying 管线中最少需要人手的一步。它几乎不需要创意判断，自动化安静地完成工作。这个阶段结束后，Vault 第一次获得肉眼可见的形态。

第 8 章将讨论 hub 与 leaf：以什么标准区分图上处于中心的 hub 和末端的 leaf，以及为何应先把写作集中于 hub。

第7章 骨架构建：CSV 如何成为 Obsidian 文件