nemo-relay-instrument-typed-wrappers

使用类型化封装和编解码器

当应用需要比原始 JSON 更强的领域类型来集成工具或大模型时，请使用此技能。 明确类型化边界，让中间件仍能看到可预测的 JSON。

默认指南

• 初次采用时，优先使用纯 JSON。
• 当应用已有稳定的领域模型时，再考虑使用类型化封装。
• 请记住，中间件仍处理 JSON，而不是类型化对象。

内嵌编解码器模型

• 类型化值编解码器是纯边界转换器。它会在 NeMo Relay 发出事件或运行中间件之前，将面向应用的值转换为 JSON；然后再将 JSON 转回框架回调或调用方所需的类型。
• Python 提供 JsonPassthrough、DataclassCodec、PydanticCodec 和 BestEffortAnyCodec。Node.js 提供 JsonPassthrough，以及自定义的 Codec<T> 实现。
• 仅在没有严格模式可用的边界处使用 BestEffortAnyCodec。如果框架拥有稳定的模式，优先使用 dataclass、Pydantic 或显式的 Node.js 编解码器。
• 提供方编解码器不同于类型化值编解码器：它们会规范化特定提供方的大模型请求和响应，以便中间件和订阅方检查消息、工具、模型名称、生成参数和响应注释。
• Python、Node.js 和 Rust 内置了 OpenAIChatCodec、OpenAIResponsesCodec 和 AnthropicMessagesCodec 等提供方编解码器。请选择与实际提供方负载结构匹配的编解码器。
• 响应编解码器会为大模型调用结束事件添加注释字段，例如 id、model、message、tool_calls、finish_reason、usage、特定提供方的数据以及额外的非建模字段。它们不会改写调用方可见的响应。
• 请求编解码器会在大模型请求拦截器之前运行。拦截器会同时接收原始 LLMRequest 和可选的带注释请求；在执行拦截器和提供方回调运行之前，encode 会将注释中的编辑合并回去。

关键规则

• 类型化封装目前是 Python 和 Node.js 的一等支持路径；Rust 则直接使用编解码器 trait
• 请求/响应转换应由编解码器负责
• 编码后，拦截器和护栏会看到 JSON 值
• 中间件所做的更改会保留到解码步骤

选择编解码器

• 对于原生 JSON 值，使用 JsonPassthrough
• 如果 Python 中已有模型，则使用 DataclassCodec 或 PydanticCodec
• 对于特定领域的线格式，使用自定义编解码器
• 仅当更宽松的契约值得更高灵活性时，才使用 BestEffortAnyCodec
• 提供方负载转换使用提供方编解码器，不要用于应用领域对象转换

验证清单

• 编解码器输出与 JSON 兼容
• 必需字段在 toJson/fromJson 或 decode/encode 转换后仍然保留
• 中间件看到预期的序列化结构
• 提供方编解码器会保留其不理解的字段
• 响应编解码器故障不会中断底层大模型调用
• 请求编解码器的 encode 会保留原始提供方字段，除非拦截器有意更改这些字段

相关技能

• nemo-relay-instrument-calls
• nemo-relay-plugin-observability
• nemo-relay-debug-runtime-integration