
名称	nemo-relay-plugin-build 描述: 使用此技能来构建或打包可复用的NeMo Relay运行时行为，作为嵌入式配置组件或支持清单的`rust_dynamic`原生或`worker` gRPC插件，并具备确定性验证和回滚安全注册。
开源协议	Apache-2.0 metadata:
作者	NVIDIA Corporation and Affiliates

构建插件

当用户想要将可复用的NeMo Relay运行时行为打包到插件配置后时，使用此技能。将可复用插件行为与一次性应用启动代码分开。

此技能用于

当行为应由共享配置激活，并跨应用、团队或进程启动路径重用时，使用此技能。

常见案例：

注册订阅者、护栏、拦截，或一组相关的运行时行为。
在更改运行时行为之前验证操作员提供的配置。
为可重用行为提供稳定的插件kind和激活生命周期。
打包应通过插件配置启用、禁用或发布的行为，而不是重复应用启动代码。

不要使用此技能的场景

当更窄的NeMo Relay表面足够时，不要构建插件：

一个请求或租户需要临时行为 -> 使用作用域局部中间件。
用户只需要一次性作用域、工具调用或LLM调用 -> nemo-relay-instrument-calls。
用户只需要选择导出器路径 -> nemo-relay-plugin-observability。
行为依赖配置文件中的实时可调用对象、提供方客户端、文件句柄、凭据或框架对象。

选择交付模型

在配置或注册之前选择交付模型：

嵌入式组件： 当行为随Relay宿主应用一起发布时，使用共享插件文档。遵循下面的嵌入式组件模型。
可发现动态包： 当插件独立于宿主发布时，使用relay-plugin.toml清单。对可信的进程中原生Rust库使用rust_dynamic；对本地grpc-v1工作器使用worker。在设计包边界之前阅读公开的原生动态插件或gRPC工作器指南。不要凭记忆复制原生ABI或工作器协议细节。

原生插件是可信的C-ABI扩展，在Relay进程内运行，不受沙箱保护。工作器插件提供进程隔离，而非安全沙箱。

嵌入式组件模型

插件封装可复用的进程级行为。
插件暴露稳定的kind字符串，并从共享插件文档中接收组件局部配置。
插件配置必须在Rust、Python、Node.js、文件、测试和部署系统中保持JSON兼容。
验证是确定性的、无副作用的。它在改变运行时行为之前检查配置并返回结构化诊断。
验证后执行注册，并通过PluginContext安装真实行为，如订阅者、护栏、请求拦截、执行拦截或流执行拦截。
PluginContext为插件系统提供足够的拥有权，以限定运行时名称并在激活失败时回滚部分设置。
禁用组件仍应尽可能验证，以便操作员在发布前发现配置问题。

默认路径

决定是否确实需要插件。当用例不是可复用的进程级行为时，优先直接插桩或作用域局部行为。
选择嵌入式组件或可发现动态包。对于动态包，在实现行为前先确定清单支持的原生或工作器边界。
对于原生动态插件，在回调API之前，根据包约束、锁文件或部署目标确定目标Relay版本。
选择一个初始运行时面：订阅者导向导出、清理护栏、条件护栏、请求拦截、执行拦截或流执行拦截。
选择稳定的插件kind和最小的JSON兼容配置形状。
为缺失字段、不支持值、未知字段、不安全配置和无效字段组合定义诊断。
初始化前验证配置。验证不得打开网络连接、创建客户端、注册中间件或更改进程状态。
如果验证返回错误诊断，则返回诊断并无初始化或注册地停止。
通过PluginContext注册运行时行为，而不是在应用启动中手工注册全局行为。
测试激活、禁用组件、验证失败和注册失败回滚。
记录如何启用插件、支持哪些配置字段以及如何回滚组件。
对于需要在nemo-relay plugins edit中提供结构化字段的动态插件，声明config_schema能力，并在relay-plugin.toml中从[config_schema].path引用本地Draft 7或Draft 2020-12 JSON Schema文件。无模式插件仍可作为原始JSON对象编辑。

配置形状

顶层插件文档包含version、components和policy。每个组件提供插件kind、enabled和组件局部config：

{
  "version": 1,
  "components": [
    {
      "kind": "redaction-policy",
      "enabled": true,
      "config": {
        "preset": "strict"
      }
    }
  ],
  "policy": {
    "unknown_component": "warn",
    "unknown_field": "warn",
    "unsupported_value": "error"
  }
}

业务逻辑保留在插件代码中，而非配置中。使用对密钥或端点的引用，而不是嵌入敏感值。

绑定指导

Python: nemo_relay.plugin
Node.js: nemo-relay-node/plugin
Rust: nemo_relay::plugin
Go 和原始 FFI 是源码优先或高级表面。

在绑定和文件之间使用相同的规范snake_case配置键。Node辅助函数可为camelCase，但插件配置对象保持snake_case。

动态包要点

保持清单包契约与运维人员的插件文档分离。清单必须声明特定于通道的kind和加载契约、常规SemVer Relay兼容范围、工件完整性和仅需要的功能。仅在需要结构化命令行编辑时，才使用本地config_schema。

原生版本兼容性

基于目标Relay版本选择原生回调模型；不要将0.8 SDK呈现为与0.7源码兼容：

Relay 0.7： 保持类型化Rust中间件回调同步。仅在异步工作必需时，使用原始原生ABI v3基于完成的注册路径，并约束清单compat.relay = ">=0.7,<0.8"。
Relay 0.8： 通过类型化Rust SDK返回future，并约束清单compat.relay = ">=0.8.0,<1.0"。SDK在SDK拥有的Tokio执行器上运行类型化中间件；订阅者和原始同步ABI注册仍同步。不要阻塞执行器工作线程。作用域上下文不会自动传播到用tokio::spawn创建的任务，且teardown必须在卸载前停止新回调并清除已接受的工作。

0.8类型化SDK允许原生组件用正数executor.worker_threads值配置其执行器。当清单公开了config_schema时，将该SDK拥有的对象和字段包含在模式中。对于原生ABI细节、回调结算或取消，以及完整的工作器协议，请查阅相关的公开动态插件指南，而不是扩展此技能。

要避免的失败模式

请勿将可调用对象、客户端、凭据、框架对象、文件句柄或缓存放入插件配置。
不要验证期间执行运行时注册。
不要跳过禁用组件的验证。
当PluginContext应拥有运行时行为时，不要直接通过全局启动代码注册。
不要在第一个插件中混合无关的订阅者、请求转换和策略检查，除非一个配置文档明确拥有该捆绑。
数据离开进程前，不要导出原始生产负载或秘密。添加遥测清理。
不要忽略部分激活失败。回滚或显示清晰诊断。
不要将原生进程隔离当作安全边界，或声称worker是沙箱。
不要将0.8异步回调契约用于Relay 0.7，也不要将0.7原始完成契约用于类型化0.8中间件。
不要阻塞0.8 SDK拥有的执行器。

验证检查清单

[ ] 已选择稳定插件kind。
[ ] 已选择交付模型：嵌入式组件、rust_dynamic或worker。
[ ] 配置形状JSON兼容并使用snake_case。
[ ] 必填字段和不支持的值产生稳定诊断。
[ ] 未知字段遵循配置策略。
[ ] 禁用组件仍尽可能报告配置问题。
[ ] 初始化通过PluginContext安装行为。
[ ] 强制注册失败不会留下部分运行时行为激活。
[ ] 文档或示例说明如何启用和回滚插件。
[ ] 需要结构化CLI编辑的动态插件打包有效本地JSON Schema并在relay-plugin.toml中声明config_schema。
[ ] 动态清单验证通道特定kind、加载契约、SemVer兼容性、完整性和禁用记录行为。
[ ] 原生回调API和兼容性约束匹配目标Relay版本：同步类型化回调和原始ABI v3完成用于0.7；类型化异步SDK中间件和执行器配置用于0.8。
[ ] 异步原生路径覆盖取消、结算和卸载前排出行为。

何时使用其他技能

如果只需要包装直接工具或LLM调用 -> nemo-relay-instrument-calls
如果需要在未打包插件的情况下设置跟踪或导出器 -> nemo-relay-plugin-observability
如果需要调试插件激活、缺失事件或加载失败 -> nemo-relay-debug-runtime-integration