命名 Provider Profile 注册表 — 多租户场景下的运行时 provider/opts 寻址中心。

让 Agent 创建路径上 model: "registry:tenant-A-anthropic:claude-sonnet-4-5" 字符串一句话替代 200 µs 量级的 per-Agent provider_opts 拼装。

Registry 是 CMDC.Config.providers（启动期静态多路由）的运行时动态补集， 二者并存：model 字符串带 "registry:" prefix 走 Registry，否则走 Config。

设计

• 每节点本地 ETS（:set + read_concurrency: true）—— lookup/1 ≤ 1 µs hot path
• 写串行化 GenServer call — register/2 / unregister/1 走 GenServer 保证原子
• 跨节点同步 由 CMDC.Provider.Registry.Broadcaster behaviour 解耦 （默认 Broadcaster.PG best-effort，生产推荐 Phoenix.PubSub）
• Local-first —— 节点重启 = 集成方自家持久层 init 时 re-register

5 公开 API

:ok = Registry.register("tenant-A-anthropic",
        provider: "anthropic",
        opts: [api_key: System.get_env("TENANT_A_KEY"),
               base_url: "https://litellm.tenant-a.internal"])

{:ok, %{provider: "anthropic", opts: [...]}} = Registry.lookup("tenant-A-anthropic")
{:error, :not_found} = Registry.lookup("not-exist")

:ok = Registry.unregister("tenant-A-anthropic")

["tenant-A-anthropic", "tenant-B-openai"] = Registry.list()

:ok = Registry.subscribe("tenant-A-anthropic")
# 本进程 mailbox 收 {:cmdc_registry, :profile_changed, name, new_opts | nil}

v0.6+ resolver_fn 选项

:ok = Registry.register("tenant-vault",
        provider: "anthropic",
        opts: [vault_path: "/secret/tenant-vault/anthropic"],
        resolver_fn: fn opts ->
          {path, rest} = Keyword.pop!(opts, :vault_path)
          {:ok, key} = MyApp.Vault.read(path)
          Keyword.put(rest, :api_key, key)
        end)

# lookup 命中时 resolver_fn 自动调用,opts 已解析为运行态
{:ok, %{opts: opts}} = Registry.lookup("tenant-vault")
assert opts[:api_key] # 已是真实 key,vault_path 已剥离

# resolver_fn 失败分支(v0.6+ 新增)
{:error, {:resolver_failed, exception}} = Registry.lookup("vault-down")
{:error, :resolver_invalid_return} = Registry.lookup("bad-resolver")

详见下方「Vault / 静态加密集成模式」段。

与 Agent / Checkpoint 的关系

• Agent 启动时若 options.model 是 "registry:profile:model_id"， Agent.init/1 一次性 Registry.lookup/1 写入 state.config.provider_opts， 此后 profile 改动不再影响该 Agent（运行时一致性）
• 想切到新 profile 走 CMDC.switch_model(sid, "registry:new-profile:model_id") 显式触发，所有切换都有 EventBus :model_switched 事件留痕
• CMDC.Checkpoint.Snapshot.state.options.model 可能含 "registry:" prefix； resume 时该 profile 必须仍在 Registry，否则 CMDC.resume_session!/2 返 {:error, {:registry_profile_missing, name}}

profile name 约束

• 必须是非空 binary
• 不能含 : 字符（否则 "registry:#{name}:#{model_id}" 解析时 name 会被吃掉一段）

• 违反返 {:error, {:invalid_name, :contains_colon | :empty | :not_binary}}

Studio 现有 "tenant-#{tid}-#{provider}" 风格继续可用；UUID / 自定义 ID 含 : 时调用方需自行替换为 - 或 _。

Vault / 静态加密集成模式（v0.6+ :resolver_fn）

生产环境一般不在内存里直接存明文 api_key，而是把密文 / vault 引用存进 opts，运行时通过 resolver_fn 懒解密。cmdc 不内置 vault 协议 / 全局 resolver / LRU cache，所有策略推回应用层；:resolver_fn 只是 per-profile 函数注入点，~30 行实现。

模式 1 — 启动时全量解密注入（推荐 99% 场景）

集成方在节点启动 init 时一次性把密文解密成明文 opts，不传 :resolver_fn:

defmodule MyApp.Boot.RegistryWarmup do
  def run do
    for tenant <- MyApp.Repo.all(Tenant) do
      {:ok, api_key} = MyApp.Vault.decrypt(tenant.encrypted_provider_key)

      Registry.register("tenant-#{tenant.id}",
        provider: tenant.provider,
        opts: [api_key: api_key, base_url: tenant.base_url]
      )
    end
  end
end

优点:

• 简单 —— lookup hot path 零额外开销（~500 ns ETS read）
• 故障早暴露 —— vault 不可达时启动直接 fail，不会等到首个 Agent 创建才报错
• 与 Broadcaster 完全兼容 —— 明文 opts 直接跨节点同步

缺点:

• 明文驻留 BEAM 堆，被 BEAM crash dump 暴露的风险
• vault rotate 需要全节点 Registry.register 重灌

模式 2 — 懒解密 + 自管 cache（高安全 / 频繁 rotate 场景）

在 :resolver_fn 闭包里挂业务自定义解密 + cache（cmdc 不负责 cache 策略， 集成方按需要选 ETS / Cachex / persistent_term）:

defmodule MyApp.RegistryWithVault do
  @cache_table :my_app_provider_opts_cache
  @ttl_ms 5 * 60 * 1000

  def warmup do
    :ets.new(@cache_table, [:set, :public, :named_table, read_concurrency: true])

    for tenant <- MyApp.Repo.all(Tenant) do
      Registry.register("tenant-#{tenant.id}",
        provider: tenant.provider,
        opts: [vault_path: tenant.vault_key_path, base_url: tenant.base_url],
        resolver_fn: &resolve_opts/1
      )
    end
  end

  defp resolve_opts(opts) do
    path = Keyword.fetch!(opts, :vault_path)
    now = System.monotonic_time(:millisecond)

    case :ets.lookup(@cache_table, path) do
      [{^path, decrypted, expires_at}] when expires_at > now ->
        Keyword.put(opts, :api_key, decrypted) |> Keyword.delete(:vault_path)

      _ ->
        {:ok, decrypted} = MyApp.Vault.read(path)
        :ets.insert(@cache_table, {path, decrypted, now + @ttl_ms})
        Keyword.put(opts, :api_key, decrypted) |> Keyword.delete(:vault_path)
    end
  end
end

优点:

• 明文不长期驻留（cache TTL 控制）
• vault rotate 自动生效（旧 TTL 过期即重新读 vault）
• resolver 失败时 Agent 创建路径返 {:error, {:registry_resolver_failed, name, ...}}, 集成方可在 EventBus / monitor 捕获

缺点:

• lookup hot path 多一次函数调用 + cache 检查（首次约 50µs，后续约 1µs）
• resolver 闭包只在本地节点有效，多节点部署集成方需在每个节点 init 时各自传入相同的 &resolve_opts/1 引用

与 Broadcaster 的交互

:resolver_fn 闭包在跨节点 Broadcaster 同步时会被自动剥离——cmdc 内部 发往 broadcaster 的 {:register, name, opts} payload 不含 :resolver_fn， 远端节点接收后 profile.resolver_fn = nil，按"无 resolver"路径处理。 集成方多节点部署务必在每个节点初始化代码里各自调用一次 Registry.register/2 传入本节点版本的 resolver_fn。

跨节点同步语义

默认 Broadcaster.PG（基于 OTP :pg 模块）是 best-effort send-only：

• 无重试 —— send/2 失败丢消息
• 无 ack —— 不知道远端是否收到
• 网络分区会丢更新 —— 集群恢复后不会自动重放

生产多节点推荐实现 Broadcaster behaviour 接 Phoenix.PubSub / Redis Streams， 详见 CMDC.Provider.Registry.Broadcaster moduledoc。

配置

# config/config.exs（可选，默认 Broadcaster.PG）
config :cmdc, CMDC.Provider.Registry,
  broadcaster: MyApp.PhoenixPubSubBroadcaster

Telemetry

详见 CMDC.Telemetry。