4.3 组件注册与使用

4.3 组件注册与使用

本节摘要：组件是有语义边界、可被自然语言规则触发、能参与运行时决策的功能实体，不是任意模块。对照「import 之后全局都能调」的脚本式 Agent，以及规则引擎里写死的服务定位器，Parlant 用元数据描述加运行时绑定：注册表、激活依赖图、上下文感知执行。四种关系在这里从概念变成调度规则。

核心问题

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

1. 写出工具注册时元数据应覆盖的 ID、类型、契约、触发、关系
2. 说明装饰器捕获签名、推断参数、生成默认触发的约定
3. 用蕴含、优先级、依赖、消歧处理「退货」和「查单」同时出现
4. 在调用前用上下文做前置条件，而不是调完再后悔

声明到绑定

组件在本文语境特指：工具、知识片段、意图模块等能进决策流的实体。开发者定义「什么条件下激活谁」，系统调度。元数据不是装饰：唯一标识、类型、输入输出契约、自然语言触发、与其他组件的优先级/依赖/互斥。用户说查某地天气，匹配到天气工具；两个相近意图靠优先级。

绑定：装饰器或显式注册 API 把函数挂到运行时，解析元数据，编译内部表示，写入全局注册表。表维护拓扑，供激活传播与冲突消解。

import parlant.sdk as p

@p.tool
async def get_weather(context: p.ToolContext, city: str) -> p.ToolResult:
    return p.ToolResult("晴，指定城市的温度摘要")
​

约定优于配置：捕获签名、推断 city 类型、默认触发模板。高级用户可覆盖触发规则。对照通用 Agent：常把函数名和一句话描述塞给模型，没有注册表级关系图。对照规则引擎：注册很完整，但触发不是自然语言。

三张表：注册表、激活图、执行器

1. 全局注册表：哈希式存储元数据与引用，组件有无歧义标识，跨模块引用才稳。
2. 激活依赖图：节点是组件，边是关系。初步匹配后沿图传播，消歧处理冲突。
3. 上下文感知执行器：调用前检查权限、会话状态、历史是否满足前置。

四种关系再次落地：蕴含（下单记录日志）、优先级（重叠意图）、依赖（改单先登录）、消歧（同时像退货又像查单则提问）。关系可在运行时调整。这比把关系写死在提示词里的「若冲突请询问」更可测。

⚠️ 常见坑：注册了工具却不写关系。两个工具同时匹配，系统要么双执行，要么隐式按注册顺序——抽检无法解释。宁可多一条消歧，少一次静默双写。
💡 关键直觉：火车站时刻表（注册表）加上信号联锁（关系图），列车才不会对向开进同一股道。只有时刻表没有联锁，就是通用 Agent。

调试时先看注册表里有没有这个组件，再看激活图这一跳走了哪条边，最后看执行器前置是否拒绝。三层对不上，不要先怪模型。很多「幻觉」是触发规则写太宽，或依赖边没画。

显式注册适合需要自定义 URI、批量挂载、非函数对象的情况。装饰器适合独立工具。混用时保持标识唯一。知识类组件同样要契约：检索结果不是事实许可，仍要指南决定能不能对用户说。

Journey 阶段声明的工具名，必须能在注册表解析到。改名而不改蓝图，是上线后静默失败的常见原因。把「注册名 / 蓝图名 / 指南引用名」当成同一套词汇表来治理，像术语 ID 那样当锚点。

注册表就是生产中的词汇表

把组件标识、Journey 引用、指南里的工具名当成同一词汇表来管。改名走评审。静默失败多来自三套名字各写各的。对照脚本式 Agent 靠函数名碰巧唯一，团队一大就会撞。URI 式标识的价值是跨模块不歧义，不要为了短再缩成拼音缩写。

关系边要有测试。构造同时像退货又像查单的句子，期望消歧提问而不是双执行。构造未登录改单，期望依赖拦截。构造 VIP 与普通退款冲突，期望优先级。这些测试不打模型也可以做，用模拟匹配结果喂激活图。图的测试比模型的测试便宜、稳。

前置执行器拒绝时，用户可见口径要是指南提供的，而不是堆栈信息。对内审计记原因码。原因码便于统计：哪条依赖总在挡人，是业务真要挡，还是身份系统太脆。没有原因码，运营只会说「机器人老让登录」。

知识类组件尤其容易被当成事实许可。检索到的段落仍要指南决定能否说、怎么说。把检索器注册成工具可以，把它的输出直接当罐头内容不行。注册机制解决的是「能被调度」，不解决「该被相信」。相信是合规与风格层的事。

批量挂载与装饰器混用时，做一次启动校验：重复标识、缺失关系、蓝图引用悬空。能在启动失败就不要运行时才 404。组件注册是声明式智能的底座，底座松了，上面 Journey 再漂亮也是空中楼阁。

悬空引用大扫除

启动校验列出：蓝图引用了但注册表没有的名字，注册了但从无指南引用的工具，关系边指向不存在的节点。前一类是上线炸弹，后一类是暗门，第三类是图损坏。每月扫一次。对照脚本式项目里从来不知道有哪些函数还活着。注册表让垃圾可见，可见才可删。智能体项目死于积攒看不见的工具，和死于模型幻觉一样常见，只是更少被写进事故标题。

对照作业：词汇表与悬空引用

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

蓝图有、注册无是炸弹；注册有、指南无是暗门。可见才可删。死于看不见的工具，和死于幻觉一样常见。

消歧测试可以不打模型，用模拟匹配喂图。图测试比模型测试便宜且稳。

钉列纪律：组件词汇表

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

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

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

要点速记

• 组件有语义边界：能被规则触发才算，不是任意代码
• 元数据是调度依据：契约、触发、关系缺一不可
• 绑定编译进注册表：约定可覆盖
• 三结构：表、图、前置执行器
• 四关系落地：冲突必须可解释
• 命名锚点：蓝图、指南、注册表用同一套名字

下一章离开开发机：可解释性、性能、安全、行业部署——对照「能跑」与「敢上线」。