# 从「代码是真相」到「YAML 是真相」，没变的是什么

> 真相源可以换地方，同一份状态只能有一个裁决方向

- 作者：王乙锟 (William Wang)
- 日期：2026-11-16
- 栏目：法（用什么方法）
- 网址：https://blog.openet.ai/posts/one-source-of-truth/

> 少则得，多则惑。是以圣人抱一为天下式。 —— 《道德经》第二十二章

---

我的判断是：真相源可以换地方，但同一份状态只能有一个最终说了算的地方。图、代码和配置发生分歧时，裁决的箭头只能朝一个方向。

我不把某种文件格式当成信仰。更值得坚持的是，修改落在哪里，其他表示从哪里生成，发生冲突时听谁的。如果这些问题没有答案，所谓同步，只是把下一次争执推迟。

## 当时让图跟着代码走

在 Acti 的一个工作流版本里，我把 TypeScript 代码定成唯一真相源。TypeScript 是给代码加类型约束的语言，工作流写成普通函数。可视化的图是只读投影：解析代码的语法结构，再把关系画出来。

只读不代表用户不能从图上发起编辑。项目说明文件 README 对这个边界说得很清楚：图上的编辑是一个编辑器命令，它先把修改写回源文件，再重新解析。用户可以从不同入口操作，但最后落笔的地方相同。

我当时要保住的，是代码和图发生分歧时不需要谈判。如果图能独立保留一份修改，代码也能独立保留另一份，接下来就要定义合并规则。遇到双方都改过的部分，还得判断谁覆盖谁，或者让人再作一次决定。

图和代码适合表达的东西也未必相同。把图当成观察代码的窗口，可以承认它只是一个视角；要求两边都能独立表达全部意图，就背上了更重的承诺。我宁愿让修改回到源头，再重画窗口里的内容。

这个决定没有把实现问题一起解决。Acti 的状态文件记录了编辑代码、看图和运行的路径，也记录了生成代码往返时的细节退化。它还指出，模型在较长的修改过程中会重新编辑此前正确的代码。唯一真相源确定了在哪里改，不能保证每次都改对。

## Forge 改了源头，也缩小了承诺

Forge 是把自然语言需求编译成可执行工作流的项目。它的 ADR，也就是记录架构决定和理由的文档，选了另一种安排：把 `graph.yaml` 定为磁盘工件的权威。YAML 是写结构化配置的文本格式，这里保存的是工作流图。

这份决定有具体背景。ADR 记录，当时命令行路径用 `artifact.json`，服务端用进程内存，写出的 YAML 还是没人读取的副本。因此，把 YAML 叫作真相源还不够，加载和执行实际依赖什么，必须跟着改变。

更关键的是，Forge 里的 TypeScript 文件承担了不同职责。它是声明桩和调用点，也就是描述输入、输出与需求的接口壳。引擎执行的是 IR，即工作流的中间表示，并不执行这段声明代码。照搬 Acti 的安排，会把不同的东西当成同一种代码。

ADR 选择的反向生成，只恢复声明里的输入、输出和需求，不恢复图的内部结构。被否决的另一条路，是再造一套能执行的 TypeScript 专用语言，连同解析器和控制流代码生成器。那会重新把手写控制流引进来，和 Forge 希望下沉这份复杂度的方向冲突。

它还否决了两种权威安排。让 TypeScript 始终说了算、YAML 只读，会堵住手工修改 YAML 后继续使用的路径；让两边双向合并，又会重新背上维持两份权威的负担。选择 YAML，是为了让实际要支持的编辑方式有一个明确落点。

所以，这次决定里，编译是一次确定产物的事件。产出 `graph.yaml`，它就成为这份磁盘工件的依据；再改 TypeScript，要重新编译。不是某一端随时悄悄覆盖另一端，也没有承诺把双方独立的修改自动揉在一起。

## 能来回转换，不代表能各说各话

Forge 的 README 画了 IR、TypeScript 和 YAML 之间的双向转换。我理解这张图时，要把转换能力和裁决权拆开。文件可以被读入、导出、再生成，仍然只能有一份权威状态。否则工具图上的双向箭头，很容易被读成产品承诺的双向同步。

ADR 对往返校验的要求也很具体：YAML 读进来再写出去，结果应当稳定。它没有把保证扩大成任意内部对象逐项完全相等，也没有承诺从声明代码中找回整张图。输入输出的描述和图的结构，本来就是不同层面的信息。

范围也必须说清。这项裁决只针对磁盘工件库，服务端内存路径的持久化留给后续决定。ADR 按阶段安排落地；设计哲学已经把磁盘 YAML 写成原则，但这些文字还不足以证明所有路径都已经迁完。我不能把选定方向写成全系统完成。

这也是我说箭头只能朝一个方向的意思。编辑入口可以有多个，转换工具也可以有多个；争执发生时，谁负责保存最终状态，要有唯一答案。源头换成 YAML，没有改变这条纪律。

## Lorica 把同一个问题放进数据模型

Lorica 遇到的是另一种重复。它的 ADR 列出，同一份 schema，也就是数据字段和约束的定义，要出现在后端、前端、给模型的提示、工具输入输出以及数据库里。各处独立维护，一处改了另一处忘记跟进，就会出现接口校验失败、字段名对不上或前端类型不对。

这里的决定是让 Pydantic 模型成为唯一真相源。Pydantic 是 Python 里的数据建模和校验工具，其他地方从模型定义生成所需的格式。前端拿类型，给模型的 prompt 指令通过模板注入 schema，而不是各自再手写一份字段说明。

Lorica 没选以接口描述为中心的 YAML 方案，ADR 给出的理由包括：接口描述不能替代领域里的数据类型，YAML 本身也不承载可执行的验证逻辑。我觉得这恰好说明，Forge 选 YAML，并不推出所有项目都该选 YAML。要看真正需要集中维护的是什么。

在工作流里，我要统一的是执行图的权威；在 Lorica 里，要统一的是数据定义和约束。具体格式可以不同，其他表示都从它派生。判断有没有做到，不能只数文件多少，还要看有没有几处需要人为重复修改的定义。

## 一个源头也有自己的代价

集中权威会让生成流程变得更重要。源头改错，派生出来的东西可能一起错；生成没有及时执行，其他地方仍会拿着旧版本。删掉第二份手写定义，只解决了重复维护，还要让人知道什么时候该重新生成，以及怎样检查结果。

Lorica 的 ADR 明列了代价：前端没有运行时验证，团队还要学习代码生成流程。前者意味着生成类型这件事，不能顺带证明运行中的数据已经检查过。我不想因为源头统一，就把它没覆盖的事情也算成收益。

Forge 也为反悔留了条件：真出现 3 个「开发者要直接用 TypeScript 写图逻辑」的案例，就重新讨论可执行语言方案。这是具体的需求门槛，不是预定的完成时间。当前把声明桩做薄，是一个有条件的选择。

我认为以后可以再换源头。前提是实际的创作方式变了，现有源头已经装不下需要表达的东西，迁移又能说清哪些派生物要重建。更换时仍要重新指定权威，不能为了过渡方便，长期留着两份都可以各自修改的真相。

我可能错在低估了人对不同编辑方式的需要。唯一源头不该成为拒绝好用入口的理由；它要求的是每个入口最终改到同一个地方。下一次再换格式，我仍然会先问：这份状态发生分歧时，到底听谁的。
