认知解析链（Cognitive Resolver Chain）

wesgine 的认知子系统通过 Resolver 链将 LLM 请求路由到合适的 Provider。

架构概述

AppRunRequest
  ↓
CellCognitive（内层五层装配）
  ↓
Resolver 链
  ↓
Provider.Stream(ctx, cellID, req) → Stream

每次 LLM 调用带 cellID，实现 per-cell 的健康追踪、速率限制和使用量统计。

Resolver 链构建

internal/cognitive/cellchain/BuildCellCognitive 装配内层五层：

Health Check：per-cell Provider 健康状态
Rate Limit：per-cell 请求速率控制
Retry / Backoff：失败重试与退避
Image Recovery：视觉请求降级处理
实际 Provider：LLM API 调用

Provider 三归属

归属	说明
Shared	Hypervisor 共享池
Named	Hypervisor 命名分配
Private（BYOK）	Cell 私有 Provider

ProviderStrategy 四模式

策略	行为
`own_only`	只用 Cell 私有 Provider
`shared_only`	只用共享池
`own_first`	优先私有，fallback 共享
`shared_first`	优先共享，fallback 私有

自动推导

只有私有 → 自动 own_only
只有共享 → 自动 shared_only
两侧皆有 → 必须显式声明，否则 ErrProviderStrategyUnset

韧性机制

Retry

失败请求按指数退避重试：

429（速率限制）
503（服务不可用）
网络超时

Health Tracking

per-cell 追踪每个 Provider 的健康状态：

连续失败计数
最后成功时间
降级标记

Image Recovery

当请求包含图片但 Provider 不支持 vision 时：

降级为纯文本请求
剥离图片 ContentBlock

SequentialFallbackResolver

多 Provider 场景下的 fallback 机制：

按优先级尝试第一个 Provider
失败后尝试下一个
全部失败返回最后一个错误

Billing 场景（INV-BILLING-04）

BillingRequired=true 的 Provider JWT 过期时：

上游返回 401
Resolver 正常 fallback 到 BYOK Provider

Vision 能力声明

Vision 声明在 Model 级别，不是 Provider 级别：

ProviderConfig{
    Models: []ModelConfig{
        {Name: "gpt-4o", SupportsVision: true},
        {Name: "gpt-4o-mini", SupportsVision: false},
    },
}

请求含 image ContentBlock + model 未声明 SupportsVision=true： → ErrVisionNotSupported 硬错误（不静默剥离图片）

Provider 探测

POST /cells/{id}/providers/test 支持三种模式：

mode	探测内容
空（默认）	chat 能力
`embedding`	embedding 能力
`vision`	vision 能力

密钥管理

Provider 密钥通过 SecretRef 三源管理：

Source	说明
`inline`	AES-256-GCM 封套存储
`env`	环境变量引用
`live`	运行时动态获取（JWT）

监控

Token 用量查询

GET /cells/{id}/observe/token-usage

支持 GroupBy（model / agent / session / day / tag:actor）多维过滤。

Provider 延迟统计

GET /admin/observe/provider-latency

跨 Cell 的 Provider 响应延迟统计。