[RFC] LLM provider catalog & routing —— detect-all scripting + agent state 作为事实源

[eanzhao]

相关：#400（per-sender NyxID binding，同属 NyxID ↔ aevatar 边界）

背景

aevatar 目前选模型只有"用户 prefer 一个 model"或"每次 chat 单选"两种方式。问题：

1. 缺事实源：NyxID 上 LLM 入口实际有两条路径，aevatar 只看到一条
   • 内置 LLM gateway：/api/v1/llm/status 只返回 auto-seeded provider（OpenAI/Anthropic/Google 等），过滤是 provider_config_id != null（NyxID backend/src/services/llm_gateway_service.rs:319-335）
   • 通用 service 注册：用户可以把 chrono-llm、自托管 Ollama、任何 OpenAI-compatible endpoint 注册成普通 DownstreamService，gateway 看不到，只能走 /api/v1/proxy/s/{slug}/...
   • aevatar 现在 hardcode 走 gateway path（NyxIdLlmEndpointResolver.cs:17），通用 service 上的 LLM 入口完全不可见
2. 缺路由策略：用户只能 per-prefer 或 per-chat 选；"代码任务走 sonnet、闲聊走 haiku、超 100k 上下文走 opus、Anthropic 限流降级 OpenAI"这种规则无处落
3. 不应重造 LiteLLM：NyxID 已经在做凭证注入和 provider 转换，aevatar 这边缺的是 发现 + 业务规则路由

提议

切成三层，每层职责清晰，事实流单向：

Layer 1 — Detect-all scripting 做发现

写一个 aevatar scripting（Aevatar.Scripting.* 体系），用户触发或 cron 调度后自动跑：

1. 调 NyxIdApiClient.DiscoverProxyServicesAsync()（已存在，src/Aevatar.AI.ToolProviders.NyxId/NyxIdApiClient.cs:247-248），列出该用户所有 connected service
2. 对每个 service 探测 GET /api/v1/proxy/s/{slug}/v1/models，NyxID 的 proxy_request_via_slug（backend/src/handlers/proxy.rs:130-173）自动注入凭证转发到上游
3. 能解析成 OpenAI-compatible model list 的就是 LLM endpoint，记录所有 model id；non-JSON / 401 / 404 / shape 不符的丢弃
4. 把成功结果写入 catalog state

关键性质：探测出来的事实——不依赖 NyxID metadata（"不会被 NyxID 欺骗"），NyxID 自己加不加 capability 字段都不影响信任源。

Layer 2 — LlmProviderCatalogGAgent 持有事实源

actor 化的 catalog，按 CLAUDE.md "actor 即业务实体"：

项	说明
范围	per user（或 per org）
state	Map<binding_id, ProviderBinding>，每条 { nyxid_slug, base_path, discovered_models[], last_probed_at, probe_status, capabilities, user_disabled }
command	RescanProviders / RefreshBinding / MarkDisabled / MarkEnabled
event	ProvidersDiscovered / BindingUpdated / BindingDisabled
readmodel	LlmProviderCatalogReadModel，UI 选择和 policy resolver 都从这里读
触发	scripting 跑完写入；用户可在 UI 二次审核（disable 不想要的项）

跟 scripting 的合一/解耦是待决问题 #2。

Layer 3 — Workflow 只做机械的 model 选择

workflow 不承担 router 职责：

• policy 字段挂在多个 scope（org > user > agent > workflow > session），按优先级栈合并
• policy schema：{ preferred_binding, conditions[], fallback_chain[], budget_cap }
• resolver 是纯函数：(context, catalog_readmodel, policy, attempt_n) → (binding, model_id)，挂在 LLMCallModule.HandleStepRequestAsync 的 model 解析 hook 上
• attempt-aware：第 N 次尝试返回 fallback chain 第 N 项；workflow 现有 retry / on_error: fallback 直接驱动 attempt 自增，不用炸图
• catalog 是唯一可选集，policy 选不到 catalog 之外的 model

这一层全程机械执行，不涉及发现、信任判断、metadata 推理。

对 NyxID 的依赖

MVP 不需要 NyxID 改动：/api/v1/proxy/services + /api/v1/proxy/s/{slug}/v1/models 转发已经够。

可推动但不阻塞：让 NyxID 在 service model 上加 capability hint（如 service_type: llm、openai_compatible: true），只作为 probe 提示——优先扫这些 service、其他降优先级，不作为信任源。理由是"减少无效 probe 流量 + 加速发现"，谈判位置好。

待决问题

1. scripting 怎么做 HTTP：IScriptBehaviorRuntimeCapabilities 目前不含 HTTP。开 IHttpInvokeCapability 单独走？还是 scripting orchestrate + 专门 ProbeAgent 做 I/O（scripting 只发命令、收事件、写状态）？倾向后者
2. catalog actor 与 scripting actor 合一：直接把 catalog state 挂在 ScriptBehaviorGAgent 上（layer 1+2 合并，scripting evolution 自带 catalog 演进）？还是 scripting 写外部 catalog（解耦但多一跳）？
3. 再发现策略：one-shot 触发 vs cron 兜底 vs "用户在 NyxID 新连服务"事件触发？倾向显式触发 + cron daily
4. capability 探测深度：除了 /v1/models 外要不要做最小 chat completion / tool-use probe 验证能力？还是只信 model id 命名规则？
5. per-session override：临时切 model 的优先级是否高于 agent default policy？会不会被 fallback 链覆盖？
6. observability 落点：cost / latency / failure rate 谁来观测、归到哪个 readmodel？
7. 多 binding 同 model：同一个 model id（如 claude-sonnet-4-5）在多个 NyxID service 上都能跑，policy 怎么 disambiguate（cost / latency / 用户指定 binding）？

落地顺序（建议）

1. catalog actor + proto + readmodel
2. NyxIdApiClient.ProbeModelsAsync(slug) + OpenAI-compatible model list 解析
3. detect-all scripting（含 ProbeAgent，如果走待决问题 1 后者方案）
4. policy schema + 纯函数 resolver
5. LLMCallModule 接入 resolver hook，替换 Metadata["aevatar.model_override"] 的硬来源
6. workflow definition 扩展 model_policy 字段
7. CLI / UI 入口：aevatar llm catalog list/rescan/disable {slug}
8. （可选）推动 NyxID 加 capability hint

评论区留给 layer 边界、scripting 形态（待决 1 + 2）、policy schema、observability 选型讨论。