2.1 分层模块与架构设计

2.1 分层模块与架构设计

本节摘要：Parlant 的模块化不是赶微服务时髦，而是让自然语言指南不绑死某一模型或某一工具。对照单体机器人「所有逻辑一个进程」、通用 Agent「模型调度一切」，它用规则引擎、上下文管理器、工具网关、审计模块四件套，把可编程行为拆成可替换零件。

核心问题

阅读完本节，你应当能够：

1. 用关注点分离解释业务逻辑与行为表现为何要拆开
2. 画出四模块在一轮对话里的数据流
3. 对照单体架构，说明模型升级为何不该掀翻对话流
4. 指出缓存、多模型接口、矛盾检测各自防哪类事故

单体为什么先死在合规上

早期对话系统常把策略、业务调用、界面文案揉在一处。模型一升级，话术全漂；一个接口权限变了，全链路挂；一条新规要改核心分支。通用 Agent 换了皮：进程里仍是「模型 + 工具循环」，合规规则要么写在提示里，要么事后过滤。规则引擎单体则把所有 if 写进一个服务，口语一变就全员加班。

Parlant 把维度劈成：业务逻辑由开发写成工具，行为表现由专家写成指南。医生不必懂手术刀冶金，但必须能下刀指令。模块化的动机是运行时组装执行单元，而不是编译期写死一张大图。

四模块原文写得很明确：

规则引擎：引导式生成，不是让模型「理解规则」

指南示例：「问余额且已验证则调余额工具，否则引导验证。」引擎抽出触发条件、动作、备选路径，编成逻辑图，带上优先级、互斥、回退等元信息，注入模型上下文。原文强调：不是依赖模型自行推理规则，而是精确注入，让输出落在边界内。这叫引导式生成。金融医疗里，这是幻觉的第一道闸。

上下文管理器分层：底层原始日志，中层结构化状态（是否已验证、上次问了什么），上层本轮情境摘要。避免把全文历史塞进提示。动态推断：「刚才那个贷款利率」能回溯产品，并结合是否处于申请流程判断真意。对照纯窗口：上下文一截断，指代全废。对照规则引擎：指代根本进不了条件表达式。

工具网关注册时要 schema、权限级别、副作用类型（只读还是改状态）。模型提议调用后：验权限、验参数、敏感操作可二次确认或人工，记日志。电商退款不会因误解自动打款；病历查询按最小权限。通用 Agent 的工具描述再详细，也常缺这一道独立守门人。

审计记下：哪些指南、哪些变量、哪些工具、为何此非彼。日志用于调试、合规，也可反哺：高频失败路径建议加指南或调优先级。原文甚至提到可作强化学习信号——那是方向，不是本节必配功能。

⚠️ 常见坑：以为微服务等于可靠。若指南质量差、边缘案例没写，四模块只会准确地走出错误路径。架构放大的是纪律，也会放大疏漏。
💡 关键直觉：乐团里指挥不代替小提琴，但决定何时进入。规则引擎是指挥，LLM 是乐器。

工程补丁：缓存、多模型、矛盾检测

高频确定规则（常见问答）可缓存推理与响应，相似上下文直接复用。淘汰策略原文写 LRU 加语义相似度。这是和「每次都走完整 Agent 循环」的成本对照。

多模型兼容层统一接口，配置切换后端，不改指南。规避厂商锁定。注意：原文列举多家云与开源模型作为支持方向，具体适配清单以当时文档为准，本教程不编造版本。

多条指南冲突时（一条要披露、一条要保密），矛盾检测按优先级、时效、业务权重仲裁，并记事件。法规环境里这比「模型自己平衡」可辩护。

银行合规客服、医院按就诊阶段控制信息披露、法务用自然语言条款校验合同——原文用这些说明：改规改指南，不重部署代码。局限同样要说：依赖指南质量；极模糊隐喻可能误判；复杂多跳延迟高于纯检索。社区在探索小样本归纳规则、形式化验证无矛盾——当作研究向，不当作已验收开关。

图 四模块协作

四模块看懂以后，下一节专门把 LLM 从「操作系统」里拎出来：它到底被谁调用、喂什么、输出如何被打回。那是和通用 Agent 差异最大的一刀。

把四模块写进事故复盘模板

复盘时按模块提问，比按「AI 犯错」提问有效。规则引擎：当时激活了哪些指南，有没有矛盾未仲裁。上下文：分层摘要有没有丢掉「已验证」这类关键槽位。网关：调用有没有过权限与副作用检查。审计：轨迹是否完整，能否五分钟内找到原因。四个问题对应四模块，缺记录就补模块，不要先换模型。

单体事故典型是改一处坏三处。模块化之后会出现另一种事故：接口契约变了，指南还在用旧字段名。所以四模块之外要有词汇表治理，和第 3 章术语 ID、第 4 章注册名是同一件事。架构再干净，名字漂移仍会让网关放过错误参数或让规则匹配落空。

缓存是性能补丁，也会是正确性漏洞。常见问答缓存了「可退」，政策改为「不可退」后仍命中旧响应。缓存键必须含指南版本或政策版本。矛盾检测同样：只仲裁不记账，合规无法证明当时为何选保密而非披露。架构图上的审计模块若只记最终回复，等于没装。

多模型接口让你能换发动机，不让你省略回归。换模型后引导式生成的遵守度会变，关键路径要重跑。把「兼容多家模型」写成销售语言可以，写成测试计划必须列出回归清单：退货、余额、转人工、超限审批。四模块的价值是清单有地方挂，而不是清单消失。

复盘四问
引擎：激活/抑制/矛盾如何仲裁？
上下文：本轮摘要丢掉了哪只槽位？
网关：这次调用的权限与副作用声明是什么？
审计：轨迹能否在五分钟内打开？
​

模块边界的反例周记

连续一周记录线上对话事故，强行归类到四模块。归不进去的，往往是名字漂移或指南质量，不是需要第五个模块。团队一出事故就加模块，架构会肿。肿了之后调度权再次糊掉，回到单体，只是单体分散在更多进程里。反例周记的目标是克制：能用指南解决的不要加模块，能用网关拒绝的不要加模型护栏。分层的敌人不是简单，而是不断新发明的层。四件套够用很久，先用到真痛再扩展。

对照作业：四模块复盘模板是否真用

围绕「四模块复盘模板是否真用」，把四条路径再过一遍。表里每格都是可执行判断，不是形容词。读完请把你的项目钉进一格，不要钉在两格之间假装都占了。

反例周记的目标是克制加模块的冲动。能用指南解决的不要新层。层越多，调度权越糊，单体只是换了分散的皮。

缓存命中了过期政策，可解释性会指着旧指南说话。那是正确性事故，不是性能胜利。

钉列纪律：四模块复盘

在「四模块复盘」上，纯 prompt 把判断写进一段话，改的人必须会改提示，复盘只能翻聊天，口语进得来但口径会漂。通用 Agent 把判断交给循环，灵活的代价是越权与路径不可复现。规则引擎把判断写进分支，确定的代价是口语进不来、改口径要排期。Parlant 把判断写成指南与契约：业务改口径，未授权则无行动，复盘指轨迹。把这四句贴到工位上，比再记一组术语有用。

针对四模块复盘，本周只做一件可验收的事：找出一条真实对话或工单，标注它今天落在哪一列；若要迁到第四列，缺的是指南、工具还是关系边。缺指南就写草稿，缺工具就列契约，缺关系就补消歧或依赖。不要同时开十条战线。最常见的伪装是文件名叫指南、真源仍是提示词，或者架构图上有网关、运行时模型仍直接调函数。用「改文本能否改行为」和「低权限点名是否被拒」两张试纸识破。识破了再谈优化与案例。优化在伪装上加速，只会让错误承诺更多；案例在伪装上复制，只会把新闻变成事故。

四模块复盘的纪律是先钉列，再谈快。钉列需要抽检，抽检需要轨迹，轨迹需要审计真的在记抑制原因，而不只记最终回复。若没有抑制原因，排错会以为没写规则，其实是优先级压了。看得见「为什么没走另一条路」，才叫对照，才叫可控。把这句话写进值班手册，四模块复盘才从概念变成岗位。对照驱动不是文风，是岗位制：模型是引擎和笔杆子，方向盘在指南与工具契约上。谁把方向盘又塞回提示词，谁就在四模块复盘上退回第一列。

本章回顾

• 拆开的是意图与机制：指南不绑模型、不绑工具
• 四件套：规则引擎、上下文、网关、审计，各挡一类失控
• 引导式生成：规则注入上下文，而不是请模型自学 SOP
• 上下文分层：摘要进提示，全文不当作唯一记忆
• 网关独立：权限与副作用不交给模型自觉
• 补丁三件：缓存、多模型接口、矛盾检测；指南质量仍是上限

下一节对照「一次提示赌对」：Parlant 如何把模型嵌进控制环。