将流程建模为故事线——正确的方法

将复杂流程转化为故事线（Storyline）是一项建模工作，而非简单的转录。相关机制见 将流程编译为故事线；本文旨在阐述 如何思考，以确保结果可靠，而非构建一个仅在理想情况下勉强运行的图。

从画像（profile）开始，然后是决策点

在绘制节点之前，确定 你要跟踪的内容 —— 即 profile_schema（例如 docs_ready、risk_flag、attempts）。然后映射 真实的决策点，而不仅仅是理想路径。对话中任何可能分支或失败的地方都是一个带有出口（exits）的节点；仅对理想路径进行建模的流程，在用户做出意外行为时第一次运行就会失效。

一个节点 = 一个连贯的步骤

一个节点应只做一个人会命名的一件事（“收集文档”、“确认身份”）。不要试图将整个子流程塞入单个节点的 task 中并指望模型能按顺序执行——否则你将失去分支、恢复和度量的能力。如果一个节点的任务描述中包含“然后，然后”，那它应该是多个节点。

在结果必须可靠的地方使分支确定性化

• 当分支必须可预测时，基于 rule（针对画像维度）或 user_choice 进行路由。将 ai 出口保留给真正的判断场景（“他们是否真的描述了他们的问题？”）。
• 出口是 按优先级排序的 —— 将确定性的出口放在前面，ai 回退放在最后。
• 使用带后向边（back-edge）和 writes 计数器（op: "inc"）以及 rule 上限的模型来构建重试循环。永远不要依赖模型来决定它已经循环了足够的次数。

将身份和安全机制保留在智能体（agent）上，而非节点上

智能体的 soul 和安全边界在整个故事线中保持不变——这正是其意义所在。不要试图在每个节点中重新陈述人格或重新施加安全限制；节点仅添加任务/技能/知识库/工具并写入画像维度。

保持 node_key 稳定；发布前进行验证

node_key 是出口的身份标识和漏斗引用。当你使用 update_storyline 进行编辑时，请保持它们稳定——静默地重命名节点会导致其出口孤立。在 publish_storyline 之前始终执行 validate_storyline；它能捕获不可达的节点、死胡同和悬空的出口。

不要过度建模

如果任务只是一个问答，那它 不是 故事线——它是一个带有知识库的智能体。当存在需要携带的真实多步骤状态时（如信息收集、辅导、引导式申请），才使用故事线。将一次性问答建模为图只会增加成本并引入不必要的故障模式。

常见的错误方式（避免这些）

• 仅理想路径 —— 没有处理“用户困惑”或“未提供信息”的出口，导致流程停滞。
• 所有出口都是 ai —— 路由变成了一场赌博；相同的输入会走不同的路径。
• 巨型节点 —— 一个节点的 task 描述了整个过程；无法分支或恢复。
• 无界循环 —— 没有计数器也没有上限的后向边。
• 在每个节点中重申安全规则 —— 这会干扰智能体实际的安全边界。

通过命名真实的状态并将每个决策移至确定性出口来修复这些问题。