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

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

栏
法 用什么方法
写于
篇幅
2,133 字
卦
井
011010
这是校验和,不是占卜
原文
Markdown
少则得,多则惑。是以圣人抱一为天下式。《道德经》第二十二章

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

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

当时让图跟着代码走

在 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 写图逻辑」的案例,就重新讨论可执行语言方案。这是具体的需求门槛,不是预定的完成时间。当前把声明桩做薄,是一个有条件的选择。

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

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