1. 为什么我要从零手搓一个提示流编排器

去年年底我开始认真做一件事：把日常跟大模型打交道的那些零散操作，收敛成一个能复用、能调试、能回滚的编排器。起因很简单，我手上同时跑着七八个跟大模型相关的任务，有的负责把一段会议记录拆成结构化待办，有的负责把用户反馈归类打标，有的负责把一份长文档压缩成摘要再喂给下游。一开始我图省事，每个任务写一个脚本，脚本里把提示词硬编码进去，跑通了就扔在那。结果两个月后我回头改其中一个提示词，发现牵一发动全身，改完 A 任务的输出格式，B 任务解析就崩了，C 任务的中间结果又对不上。那种感觉就像你拿一堆散装积木搭了个东西，想抽掉中间一块，整个塔就塌了。

所以我决定从 0 到 1 做一个提示流编排器。它不是那种把大模型当机械拼图、把节点连起来就完事的玩具，而是一个真正考虑字段冻结、版本回滚、中间态可追溯的工程化工具。这篇文章是开源系列的第 15 篇，重点复盘 Case #7 里踩到的字段冻结陷阱，以及代码回滚的完整过程。如果你也在做多步骤的大模型调用链路，或者正在用类似 Dify 这类工具接入本地大模型，却总觉得中间环节不可控，那这篇应该能帮你少走点弯路。

先把这个编排器是什么说清楚。它本质上是一个有向无环图的任务执行引擎，每个节点是一次大模型调用或者一次数据处理，节点之间有明确的输入输出契约。所谓契约，就是每个节点声明自己需要哪些字段、会产出哪些字段，编排器负责在节点之间做字段的映射和校验。这跟单纯写个函数调 API 最大的区别在于：字段是有生命周期的，什么时候被创建、什么时候被消费、什么时候被冻结，全都有记录。字段冻结的意思就是，某个字段一旦被标记为冻结，后续任何节点都不能再修改它，只能读取。这个机制听起来很美好，但 Case #7 就是栽在它上面。

适合谁来读这篇？如果你只是偶尔调一次大模型 API，写个脚本跑完就完事，那这个编排器对你来说可能过重了。但如果你手上有超过三个步骤的链路，步骤之间有数据依赖，而且你需要反复调试提示词、对比不同版本的效果，那这套东西的价值就出来了。尤其是做企业大模型私有化部署的团队，链路一旦上线就不能随便改，回滚能力是刚需。我下面会从整体设计思路讲起，然后拆核心细节，再完整复盘 Case #7 的实操过程和排查记录，最后给一份常见问题速查表。

2. 编排器的整体设计与核心思路拆解

2.1 为什么不用现成方案而要自己搭

市面上做提示流编排的工具不少，Dify、Coze、LangFlow 这些我都试过。它们的好处是上手快，拖拖拽拽就能连出一个流程。但我遇到几个绕不过去的问题。第一是字段级别的控制粒度不够。这些工具大多以节点为最小单位做版本管理，你改了节点里的提示词，整个节点就变了，但我想控制的是某个具体字段的行为，比如这个字段在第三步之后就不允许再被覆盖。第二是回滚的语义不清晰。很多工具的回滚是整条链路回滚，但实际场景里我可能只想回滚某一次大模型调用的输出，前面的步骤不动。第三是中间态的可观测性。链路一长，某个字段的值到底是在哪一步被改的，排查起来非常痛苦。

自己搭的好处是，我可以把字段当成一等公民来设计。每个字段有独立的元数据：创建者、消费者、冻结状态、版本历史。节点只是字段的加工厂，真正流动的是字段。这个思路借鉴了数据流编程的思想，但加上了大模型特有的不确定性处理。因为大模型的输出不是确定性的，同一个提示词跑两次结果可能不一样，所以字段的版本历史特别重要，你得能追溯每一次输出的差异。

2.2 字段冻结机制的设计初衷

字段冻结这个概念，我是从数据库的不可变字段和函数式编程的不可变数据里借来的。核心想法是：在一条链路里，有些字段一旦确定就不应该再变。比如用户原始输入，这是事实来源，任何下游节点都不应该去改它。再比如某个节点产出的关键结论，如果下游节点能随便覆盖，那整个链路的可信度就没了。

冻结分两种：创建时冻结和消费后冻结。创建时冻结是指字段一产生就锁死，谁都不能改。消费后冻结是指字段被某个节点读取之后才锁死，在此之前还可以被修正。这两种模式对应不同的业务场景。用户输入适合创建时冻结，中间计算结果适合消费后冻结，因为计算过程中可能需要重试或者修正。

但这里有个陷阱，也是 Case #7 的核心。冻结的判定时机如果跟节点的执行顺序耦合得太紧，就会出现一种情况：某个字段本该在 A 节点之后冻结，但因为 B 节点先执行了，导致冻结提前触发，后续节点拿到的就是被锁死的旧值。这个陷阱我在设计时没考虑到，直到实际跑链路才暴露出来。

2.3 版本回滚的粒度选择

回滚这件事，粒度太粗没用，粒度太细又难管理。我最后选的是字段级快照加节点级回滚的组合。每次节点执行前，编排器会对该节点涉及的所有输入字段做一次快照，执行后对输出字段做一次快照。这样回滚的时候，你可以选择回滚到某个节点的某次执行之前的状态，也可以只回滚某个字段到它的某个历史版本。

为什么不做全链路快照？因为链路一长，全量快照的存储成本很高，而且大部分时候你只需要回滚局部。字段级快照的好处是精准，坏处是回滚之后字段之间的依赖关系可能不一致。比如字段 A 回滚了，但依赖 A 的字段 B 没回滚，那 B 就是脏数据。所以回滚之后必须做一次依赖校验，把受影响的字段标记出来，让用户决定是级联回滚还是手动修复。

这个设计在 Case #7 里也出了问题。回滚的时候我只考虑了字段本身的历史版本，没考虑冻结状态的历史版本。结果回滚之后字段的值回去了，但冻结状态没回去，导致字段处于一个“值很旧但状态是冻结”的矛盾状态，后续节点读到的就是错的。

3. 核心细节解析与实操要点

3.1 字段元数据的结构设计

字段的元数据我用一个 JSON 结构来存，核心字段包括：field_id、name、type、value、version、frozen、frozen_at、created_by、consumed_by、history。其中frozen是个布尔值，frozen_at记录冻结发生的节点 ID 和时间戳，history是一个数组，存每次值变更的快照。

这里有个细节值得说：consumed_by我设计成列表而不是单个值，因为一个字段可能被多个节点消费。每次消费都会往列表里追加一条记录，包含节点 ID、消费时间、消费时的字段版本。这个记录在排查问题时特别有用，你可以清楚地看到某个字段在哪个节点被读走的时候是什么值。

{ "field_id": "f_001", "name": "user_input", "type": "string", "value": "帮我总结这份会议记录", "version": 3, "frozen": true, "frozen_at": "node_002", "created_by": "node_001", "consumed_by": [ {"node": "node_002", "version": 2, "time": "2024-01-15T10:23:01Z"}, {"node": "node_003", "version": 3, "time": "2024-01-15T10:23:05Z"} ], "history": [ {"version": 1, "value": "帮我总结", "time": "..."}, {"version": 2, "value": "帮我总结这份会议记录", "time": "..."}, {"version": 3, "value": "帮我总结这份会议记录", "time": "..."} ] }

注意version是递增的，即使值没变，只要经过一次写操作版本号也会加一。这样做的好处是版本号可以当作逻辑时钟用，判断先后顺序很直观。坏处是版本号会膨胀得比较快，但实际用下来问题不大，因为字段数量是可控的。

3.2 节点执行时的字段校验流程

每个节点执行前，编排器会做一轮字段校验。校验分三步：存在性校验、类型校验、冻结校验。存在性校验检查节点声明的输入字段是否都存在，类型校验检查字段类型是否匹配，冻结校验检查节点是否试图修改一个已冻结的字段。

冻结校验是最容易出问题的一步。我的实现是：节点执行前先扫描它的输出字段声明，如果某个输出字段在全局字段表里已经存在且frozen为 true，就直接拒绝执行并报错。这个逻辑本身没问题，但问题出在冻结的触发时机上。我原本的设计是，字段被消费后立即冻结。但“消费”这个动作是在节点执行过程中发生的，而节点的输出字段声明是在执行前就确定的。这就导致一个节点可能既消费了某个字段，又试图输出同名字段，而冻结校验在执行前跑，此时字段还没被冻结，校验通过；等节点执行到一半，字段被消费触发了冻结，节点再想写这个字段就被拒绝了，但此时节点已经执行了一半，状态不一致。

这个就是 Case #7 的根因。我后面会详细讲怎么修的，这里先记住一点：冻结的判定和执行必须在一个原子操作里完成，不能拆成两个阶段。

3.3 提示词模板与字段的绑定方式

提示词模板我用的是类似 Jinja2 的语法，但做了简化。模板里用{{field_name}}引用字段，编排器在节点执行前会把字段值渲染进去。这里有个坑：如果字段值是复杂结构（比如列表或字典），直接渲染会变成 Python 的 repr 字符串，大模型读起来很别扭。所以我对复杂类型做了序列化处理，列表转成换行分隔的文本，字典转成 key: value 的文本。

另一个坑是字段缺失时的行为。我一开始设计成字段缺失就报错，但实际用下来发现太严格了。有些字段是可选的，缺失时应该用默认值或者空字符串。所以后来加了required标记，只有标记为 required 的字段缺失才报错，其他的用默认值填充。这个改动看起来小，但让链路的容错性好了很多。

提示：提示词模板里的字段引用一定要跟字段表里的 name 严格一致，大小写敏感。我踩过一次坑，模板里写的是{{UserName}}，字段表里是user_name，结果渲染出来是空字符串，大模型收到一个残缺的提示词，输出完全跑偏。排查了半天才发现是大小写问题。

4. Case #7 字段冻结陷阱的完整复盘

4.1 问题现象与初步定位

Case #7 的场景是这样的：一条三步链路，第一步从用户输入里抽取关键实体，第二步根据实体检索相关知识，第三步把知识和原始输入一起喂给大模型生成最终回答。字段方面，user_input是创建时冻结，entities是第一步产出，knowledge是第二步产出，final_answer是第三步产出。

问题出现在第二步。第二步的节点声明里，输入字段是entities，输出字段也是entities，因为它要对实体做一次归一化处理。按照我的设计，entities被第二步消费后应该冻结，但第二步又要写它，这就矛盾了。实际跑的时候，第二步执行到一半报错，说entities已冻结无法写入。但此时第二步已经调用了检索接口，产生了一些副作用。

更麻烦的是，报错之后我尝试回滚，发现entities的值回滚到了第一步的版本，但frozen状态还是 true，导致第三步读取entities的时候读到的是旧值，而且这个旧值还被锁死了，怎么改都改不了。整个链路卡死。

初步定位下来，问题有三个层次：第一层是冻结时机跟节点执行顺序的耦合，第二层是回滚时冻结状态没有一起回滚，第三层是节点执行到一半失败后的状态清理不完整。

4.2 冻结时机的重新设计

修复的第一步是把冻结判定从“消费后立即冻结”改成“节点执行完成后统一冻结”。具体做法是：节点执行期间，所有字段的写操作都记录在一个事务日志里，不立即生效。等节点执行成功，再把事务日志里的写操作批量提交，同时根据节点的消费记录更新冻结状态。如果节点执行失败，事务日志直接丢弃，字段状态不变。

这个改动的核心是把执行和状态变更解耦。执行期间字段状态是冻结的，但冻结的判定基于执行前的快照，而不是执行中的实时状态。这样就不会出现“执行到一半状态变了”的问题。

class NodeExecutor: def execute(self, node, fields): # 执行前快照 snapshot = {f.name: f.snapshot() for f in fields} transaction = [] try: # 执行节点逻辑，写操作记录到 transaction result = node.run(fields, transaction) # 执行成功，批量提交 for op in transaction: op.apply() # 更新冻结状态 self.update_frozen_status(node, fields) return result except Exception as e: # 执行失败，回滚到快照 for name, snap in snapshot.items(): fields[name].restore(snap) raise e

这段代码的关键是snapshot和transaction。快照保证失败时能恢复，事务保证成功时批量生效。实测下来，这个改动把 Case #7 那类问题彻底解决了。

4.3 回滚时冻结状态的同步处理

第二步修复是让冻结状态也纳入版本管理。原来frozen和frozen_at是字段的当前状态，没有历史。我改成把冻结状态也存进history里，每次冻结状态变更都追加一条记录。回滚的时候，不仅回滚value，也回滚frozen和frozen_at。

{ "history": [ {"version": 1, "value": "v1", "frozen": false, "time": "..."}, {"version": 2, "value": "v2", "frozen": false, "time": "..."}, {"version": 3, "value": "v2", "frozen": true, "time": "..."} ] }

这样回滚到 version 2 的时候，frozen自动变成 false，字段就解锁了。这个改动看起来简单，但当时我没想到，因为脑子里一直把frozen当成元数据而不是状态数据。实际上它就是一种状态，跟value一样需要版本管理。

4.4 节点失败后的状态清理

第三步修复是节点失败后的清理逻辑。原来的实现是节点抛异常就直接往上抛，不做任何清理。但节点执行过程中可能已经产生了一些副作用，比如调用了外部接口、写了临时文件、修改了内存里的字段对象。这些副作用如果不清理，下次重试的时候就会出问题。

我的做法是给节点加一个cleanup方法，节点自己声明需要清理哪些资源。编排器在捕获异常后调用cleanup，然后再恢复字段快照。这样节点作者可以精确控制清理逻辑，编排器不用关心具体细节。

def execute_with_cleanup(self, node, fields): snapshot = {f.name: f.snapshot() for f in fields} try: return node.run(fields) except Exception as e: node.cleanup() for name, snap in snapshot.items(): fields[name].restore(snap) raise e

这三个修复做完之后，我重新跑了一遍 Case #7 的场景，链路顺利跑通，回滚也正常了。但这个过程让我意识到，编排器的复杂度不在于节点怎么连，而在于状态怎么管。字段冻结、版本回滚、失败清理，这些都是状态管理的问题，任何一个没处理好，链路就会出诡异的问题。

5. 常见问题与排查技巧实录

5.1 字段冻结相关的典型问题

这个表是我踩坑之后整理的，基本上覆盖了字段冻结相关的常见问题。其中“回滚后字段值对了但状态不对”是最隐蔽的，因为值看起来是对的，但状态错了，导致后续行为异常。排查的时候不能只看值，一定要看状态。

5.2 回滚失败的排查思路

回滚失败通常有三种表现：回滚后值没变、回滚后值变了但依赖字段没变、回滚后链路跑不通。第一种一般是快照没存对，检查快照的时机和内容。第二种是依赖校验没做，回滚一个字段后要检查所有依赖它的字段，标记为脏数据。第三种是回滚后的状态不一致，比如字段值回去了但冻结状态没回去，或者字段的版本号跟历史对不上。

我的排查顺序是：先看快照内容，再看依赖关系，最后看状态一致性。快照内容可以直接打印出来对比，依赖关系可以画个简单的图，状态一致性需要写个校验函数，检查每个字段的 value、version、frozen 是否自洽。

注意：回滚操作本身也要记录日志，包括回滚了哪些字段、回滚到哪个版本、回滚后的状态是什么。不然回滚出问题的时候，你连回滚前是什么状态都不知道。

5.3 大模型输出不确定性的应对

大模型的输出不是确定性的，同一个提示词跑两次可能得到不同的结果。这对编排器的影响是，字段的值可能每次执行都不一样，版本历史会膨胀得很快。我的应对策略是：对关键字段做输出校验，校验不通过就不写入，直接重试。校验规则可以是格式校验（比如必须是 JSON）、长度校验、关键词校验等。

另一个策略是缓存。如果某个节点的输入字段完全没变，提示词也没变，那可以直接复用上次的输出，不用重新调用大模型。这个缓存对调试特别有用，因为调试的时候大部分节点是不变的，只有少数节点在改，缓存能省很多时间和成本。

5.4 实操心得与避坑清单

• 字段命名要统一规范，建议用 snake_case，避免大小写混用。我踩过UserName和user_name不一致的坑，排查了很久。
• 冻结状态要跟值一起版本管理，不要分开存。分开存迟早会出现状态不一致。
• 节点执行要幂等，因为失败重试是常态。如果节点有副作用，要确保重试不会重复产生副作用。
• 回滚要支持级联，回滚一个字段时自动标记依赖它的字段为脏数据，让用户决定是否级联回滚。
• 日志要详细，每个字段的每次变更都要记录，包括变更前后的值、变更的节点、变更的时间。排查问题时日志是唯一的线索。
• 测试要覆盖边界，特别是字段缺失、类型不匹配、冻结冲突这些边界情况。我写了一套边界测试用例，每次改编排器都跑一遍，省了很多事。

6. 从这次复盘里我真正学到的东西

做完 Case #7 的修复之后，我回头看了看整个编排器的代码，发现状态管理相关的代码占了将近一半。这让我意识到，编排器的核心难点从来不是“怎么把节点连起来”，而是“怎么管好节点之间的状态”。字段冻结、版本回滚、失败清理，这些都是状态管理的具体问题。任何一个没处理好，链路就会出诡异的问题，而且这些问题往往很难排查，因为现象和原因之间隔了好几层。

我现在设计新链路的时候，会先画一张字段流转图，标清楚每个字段在哪里创建、在哪里消费、在哪里冻结、在哪里可能被回滚。这张图比节点连接图重要得多，因为它决定了链路的健壮性。节点连接图只告诉你数据怎么流，字段流转图告诉你数据的状态怎么变。

另外一点体会是，回滚不是万能的。回滚能恢复状态，但不能恢复副作用。如果节点调用了外部接口，回滚字段值并不能撤销那次调用。所以对于有副作用的节点，要么设计成幂等的，要么在回滚时手动补偿。这个在链路设计阶段就要考虑，不能等到出问题才想。

最后分享一个小技巧：我在编排器里加了一个“干跑”模式，节点只做校验和渲染，不实际调用大模型。这个模式在调试链路结构的时候特别有用，能快速发现字段缺失、类型不匹配、冻结冲突这些问题，不用每次都真的调大模型。干跑通过之后再实际跑，效率高很多。这个模式后来成了我调试链路的标准第一步，每次改完链路先干跑一遍，没问题再实际跑。