nemo-relay-plugin-build

构建插件

当用户希望将可复用的 NeMo Relay 运行时行为封装在插件配置中时，使用此技能。 将可复用的插件行为与一次性的应用启动代码分开。

适用场景

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

常见情况：

• 注册订阅器、护栏、拦截器，或一组相关的运行时行为。
• 在更改运行时行为前，验证运维人员提供的配置。
• 为可复用行为指定稳定的插件 kind 和激活生命周期。
• 将行为打包，使其能够通过插件配置启用、禁用或逐步推出，而不是在应用启动代码中重复实现。

不适用场景

如果更精简的 NeMo Relay 功能已足够，就不要构建插件：

• 一个请求或租户需要临时行为 -> 使用作用域本地中间件。
• 用户只需要首次创建作用域、工具调用或大模型调用 -> 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 为插件系统提供足够的所有权，以限定运行时名称，并在激活失败时回滚部分设置。
• 在可行的情况下，禁用的组件仍应进行验证，以便运维人员能在发布前发现配置问题。

默认路径

1. 判断是否确实需要插件。如果用例不涉及可复用的进程级行为，应优先采用直接插桩或作用域内行为。
2. 选择嵌入式组件或可发现的动态包。对于动态包，应先建立由清单支持的原生或 worker 边界，再实现行为。
3. 对于原生动态插件，在选择回调 API 之前，根据包约束、锁文件或部署目标确定目标 Relay 版本。
4. 选择一个首要运行时接口：面向订阅者的导出、清理防护栏、条件防护栏、请求拦截、执行拦截或流式执行拦截。
5. 选择稳定的插件 kind 和最精简的 JSON 兼容配置结构。
6. 为缺失字段、不受支持的值、未知字段、不安全配置和无效字段组合定义诊断信息。
7. 在初始化前验证配置。验证不得打开网络连接、创建客户端、注册中间件或更改进程状态。
8. 如果验证返回错误诊断信息，则返回这些信息并停止，不进行初始化或注册。
9. 通过 PluginContext 注册运行时行为，不要在应用启动时手动注册全局行为。
10. 测试激活、已禁用的组件、验证失败以及注册失败回滚。
11. 说明如何启用插件、支持哪些配置字段，以及如何回滚组件。
12. 对于需要在 nemo-relay plugins edit 中提供结构化字段的动态插件，请声明 config_schema 功能，并在 relay-plugin.toml 的 [config_schema].path 中引用本地 Draft 7 或 Draft 2020-12 JSON Schema 文件。没有 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 兼容范围、制品完整性，以及插件所需的功能。仅在需要结构化 CLI 编辑时才使用本地 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 返回 futures，并将清单约束为 compat.relay = ">=0.8.0,<1.0"。SDK 在自身管理的 Tokio 执行器上运行类型化中间件；订阅者和原始同步 ABI 注册仍为同步。不要阻塞执行器工作线程。作用域上下文不会自动传播到通过 tokio::spawn 创建的任务，卸载前必须停止接受新回调，并排空已接受的工作。

0.8 类型化 SDK 允许原生组件使用正数 executor.worker_threads 值配置其执行器。当其清单公开 config_schema 时，请在架构中包含这个由 SDK 管理的对象及字段。有关原生 ABI 细节、回调完成或取消，以及完整的工作线程协议，请参阅相应的公开动态插件指南，而不要在此技能中展开说明。

应避免的失败模式

• 不要在插件配置中放入可调用对象、客户端、凭据、框架对象、文件句柄或缓存。
• 不要在验证期间执行运行时注册。
• 不要跳过对已禁用组件的验证。
• 当运行时行为应由 PluginContext 管理时，不要直接通过全局启动代码进行注册。
• 除非一个配置文档明确管理整个组合，否则不要在首个插件中组合无关的订阅者、请求转换和策略检查。
• 不要导出原始生产负载或机密信息。数据离开进程前，请先进行遥测脱敏。
• 不要忽略部分激活失败。请回滚或提供明确的诊断信息。
• 不要将原生进程隔离视为安全边界，也不要声称工作线程处于沙箱中。
• 不要将 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。
• 动态清单会验证其通道专属的种类、加载契约、SemVer 兼容性、完整性以及禁用记录行为。
• 原生回调 API 和兼容性约束与目标 Relay 版本一致：0.7 使用同步类型化回调和原始 ABI v3 完成机制；0.8 使用类型化异步 SDK 中间件和执行器配置。
• 原生异步路径涵盖取消、完成以及卸载前排空行为。

以下情况请使用其他技能

• 只需要封装直接的工具调用或大模型调用 -> nemo-relay-instrument-calls
• 需要设置跟踪或导出器，但不需要打包插件 -> nemo-relay-plugin-observability
• 需要调试插件激活、缺失事件或加载失败 -> nemo-relay-debug-runtime-integration