跳到主要内容

插件系统

当前能力面​

一个插件当前可以提供：

  1. route middleware
  2. route pipeline stages
  3. management ConnectRPC services

所有的插件均在全局 Registry plugins/registry.go 注册，在运行时会根据 Route 配置动态选择插件并构建 pipeline。

Route pipeline​

现在的 route pipeline 不再是“启动时构建一条固定链”，而是：

  1. 根据请求前缀查找 route
  2. 根据 route 信息去拿 route config, tenant config, plugin config 等
  3. 根据这些信息动态构建请求 pipeline

这让插件可以按 route 条件注入运行时阶段，而不是全局固定开启。

当前 route pipeline 按顺序支持四类 stage：

  1. Authenticator
  2. SelectorAugmenter
  3. UpstreamSelector
  4. ForwardBuilder

Authenticator​

Authenticator 负责认证请求，并可把认证结果写入 runtime state。

当前内置认证相关插件主要有：

  • passthrough-auth-token
  • legacy-api-key-auth
  • consumer

route 级注入优先级：

  1. disable_auth
  2. passthrough_auth_token
  3. legacy_bearer_auth_tokens
  4. consumer

其中：

  • passthrough-auth-token 命中后直接 allow
  • legacy-api-key-auth 校验 route 自带 bearer token
  • consumer 负责 consumer_api_keys 鉴权和 consumer / api key 约束

多认证插件并存时，语义是 AND。

SelectorAugmenter​

SelectorAugmenter 运行在认证之后、upstream 选择之前，用于动态追加 upstream / model selector。

典型用途：

  • 根据 route 策略追加系统 selector
  • 根据认证结果追加临时约束
  • 根据请求上下文收紧候选范围

动态 selector 会进入 runtime state：

  • AdditionalUpstreamSelectors
  • AdditionalModelSelectors

这些 selector 不会写回数据库，只影响当前请求。

当前 core 插件会使用这个能力实现协议筛选：

  • 当 protocol_transformation_type = disabled
  • 且请求是 chat 协议路径
  • runtime 会追加 aidy/protocol = 入站协议
  • 之后 upstream 选择自然只保留同协议 upstream

UpstreamSelector​

UpstreamSelector 负责解析可用 upstream 集合，并生成本次请求的 routing plan。

当前默认实现是 core 插件提供的 FirstAvailableUpstreamSelector。它会：

  • 从 route.upstreams[] 开始解析候选
  • 应用 route / 动态 / consumer / api key 的 upstream selector
  • 应用 route / 动态 / consumer / api key 的 model selector
  • 过滤不可用协议、能力和候选
  • 按 priority / lb_weight 排序
  • 按 route.max_attempts 截断候选

ForwardBuilder​

ForwardBuilder 负责把 routing plan 转成最终 HTTP handler。

当前默认实现由 core 插件提供，主要负责：

  • /models 本地聚合
  • chat / embeddings / options / unknown 请求转发
  • 构造 forwarder handler 与失败处理策略

Route middleware hooks​

route middleware 是实际转发链路上的 hook。它们在 route handler 构建时按插件顺序和 hook order 组合。

当前支持的 hook：

  • inbound
  • before_handler
  • forward_chat
  • forward_embeddings
  • forward_models
  • forward_options
  • forward_unknown
  • forward_request

其中 forward_chat 是 IR 能力最完整的 hook：

  • 可以读取 RequestIR
  • 可以替换 RequestIR
  • 可以读取或替换 ResponseIR
  • 可以处理 StreamEventIR
  • 可以设置 terminal response 直接短路请求

其它 forward hook 主要围绕 HTTP request / response 转发链路工作，不提供完整 chat IR。

请求内共享状态​

插件之间共享当前请求状态时使用 mux.Store，按约定的 namespace/key 读写。

当前约定的共享字段包括：

  • 会话（session）：namespace session，key session_id，值为 route 级 session 插件提取到的 session id

Selector 约束​

规则是：

  • 空 selector 表示“不额外限制”
  • 非空 selector 会和其它 selector 一起逐层收紧 upstream / model 候选

当前 upstream 选择会先从 route.upstreams[] 开始，再用 selector 去筛 upstreams.labels 与 upstream_models.labels。

selector 来源按层次包括：

  • route selector
  • runtime 动态追加 selector
  • consumer selector
  • api key selector

系统 label 可直接用于 selector，例如 aidy/upstream-id、aidy/model-name、aidy/protocol。详见 Label & Selector。