feat(v1): T-R1 采纳 ai-model-router 可解释路由评分——五维加权+硬过滤带拒绝理由+置信度分差推导

- 新增 router_system/explain.py：CandidateProfile（capability/cost/latency/
  reliability/difficulty 画像）+ explain_routing（硬过滤先行、逐条人话拒绝理由、
  五维归一评分、同分按领域字典序、confidence=0.8+分差推导封顶 0.99）
- Router._explain 纯解释层装配（解释层任何异常不影响主链路，D-G4 同款纪律）；
  路由胜负与既有决策完全等价，/chat 响应新增 route_explanation 字段（缓存命中为 None）
- experts：Expert.nominal_latency_ms 标称延迟元数据（mock 1/hf 300/api 800）
- stats：upgraded_by_domain 计数 + domain_reliability()（无数据给 0.9 中性先验）
- .gitignore 登记 extra/（参考项目目录不入库）
- 新增 tests/test_explain.py 8 项；全量 33 passed（基线 25）

.gitignore

@@ -28,3 +28,6 @@ Thumbs.db
 
 # 安全扫描器工作目录（不入库）
 .mimosa/
+
+# 参考项目目录（不入库，仅作设计吸收来源）
+extra/

gateway/api.py

@@ -9,7 +9,7 @@
 """
 from __future__ import annotations
 
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field
 
@@ -46,6 +46,7 @@ class QueryResponse(BaseModel):
     cache_level: Optional[str]
     cost_est: float
     error: Optional[str] = None
+    route_explanation: Optional[Dict[str, Any]] = None  # T-R1 可解释评分（缓存命中为 None）
 
 
 class HealthResponse(BaseModel):

router_system/experts.py

@@ -75,6 +75,7 @@ _STOPWORDS_EN = {
 
 class Expert:
     name: str = "expert"
+    nominal_latency_ms: float = 100.0   # 标称延迟元数据（可解释评分 speed 维输入）
 
     async def generate(self, query: str, difficulty: str) -> ExpertResponse:
         raise NotImplementedError
@@ -87,6 +88,8 @@ class MockExpert(Expert):
     使端到端管线（分类 -> 专家 -> Judge -> 缓存）可被稳定测试与演示。
     """
 
+    nominal_latency_ms = 1.0
+
     def __init__(self, name: str, domain: str, model: str = "mock"):
         self.name = name
         self.domain = domain
@@ -162,6 +165,8 @@ class MockExpert(Expert):
 class HFExpert(Expert):
     """可选：HuggingFace 真实小模型（需 requirements-ml.txt）。"""
 
+    nominal_latency_ms = 300.0
+
     def __init__(self, name: str, domain: str, model: str):
         self.name = name
         self.domain = domain
@@ -210,6 +215,8 @@ class HFExpert(Expert):
 class APIExpert(Expert):
     """可选：OpenAI 兼容 Chat Completions（DeepSeek / OpenAI / 本地 vLLM）。"""
 
+    nominal_latency_ms = 800.0
+
     def __init__(self, name: str, domain: str, model: str, base_url: str, api_key: str):
         self.name = name
         self.domain = domain

router_system/explain.py

@@ -0,0 +1,106 @@
+"""可解释路由评分层（T-R1，采纳 ai-model-router 五维评分 + 硬过滤带拒绝理由设计）。
+
+对分类产生的候选领域专家做透明评分与解释。路由胜负保持既有逻辑不变
+（本模块是纯解释层，不参与决策）：
+
+- 硬过滤先行：无规则命中/低置信度/缺专家的候选先淘汰，逐条记录人话拒绝理由
+- 五维加权评分（各维归一到 0-1，权重可配）：
+    capability   分类器该领域原始分归一（语义匹配强度）
+    cost_efficiency  1/(1+cost*100) 平滑映射，零成本本地模型恒 1.0
+    speed        1/(1+标称延迟/200)（200ms 参考延迟）
+    reliability  Judge 通过率（无数据时 0.9 中性先验）
+    quality      难度 × 领域纵深启发式
+- 置信度可推导：confidence = 0.8 + (最高分 - 次高分)，分差越大越自信（封顶 0.99）
+- 同分决胜按领域名字典序（与仓库既有确定性约定一致）
+
+输出 RoutingExplanation.to_dict() 直接进 /chat 响应的 route_explanation 字段。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+# 领域纵深启发式（该领域知识可承载的任务深度，0-1）
+_DOMAIN_DEPTH = {
+    "code": 0.90, "math": 0.90, "legal": 0.85, "medical": 0.85, "general": 0.60,
+}
+
+DEFAULT_WEIGHTS: Dict[str, float] = {
+    "capability": 0.35,
+    "cost_efficiency": 0.20,
+    "speed": 0.15,
+    "reliability": 0.20,
+    "quality": 0.10,
+}
+
+
+@dataclass
+class CandidateProfile:
+    """一个候选领域专家的评分输入（由 Router 从分类/专家池/统计装配）。"""
+    domain: str
+    model: str                          # 专家模型名
+    capability: float                   # 分类器该领域原始分归一 0-1
+    cost_per_mtok: float                # $ / 1M output tokens 估计
+    nominal_latency_ms: float           # 标称延迟（专家后端元数据）
+    reliability: float                  # Judge 通过率（无数据给中性先验）
+    difficulty_score: float             # 查询难度分 0-1（质量维输入）
+    hard_fail_reason: Optional[str] = None   # 非 None 即硬过滤淘汰（人话理由）
+
+
+@dataclass
+class RoutingExplanation:
+    """一次路由的完整解释：胜者 + 排名 + 拒绝名单 + 权重快照。"""
+    winner: str                         # 胜出领域；无存活候选时为 "fallback"
+    confidence: float                   # 0.8 + 分差推导（封顶 0.99）
+    ranked: List[Dict[str, Any]] = field(default_factory=list)
+    rejected: List[Dict[str, Any]] = field(default_factory=list)
+    weights: Dict[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "winner": self.winner,
+            "confidence": round(self.confidence, 4),
+            "ranked": self.ranked,
+            "rejected": self.rejected,
+            "weights": dict(self.weights),
+        }
+
+
+def score_candidate(c: CandidateProfile, weights: Dict[str, float]) -> Dict[str, Any]:
+    """单候选五维评分（全部绝对映射 0-1，跨候选可比、可单测）。"""
+    dims = {
+        "capability": max(0.0, min(1.0, c.capability)),
+        "cost_efficiency": 1.0 / (1.0 + max(0.0, c.cost_per_mtok) * 100.0),
+        "speed": 1.0 / (1.0 + max(0.0, c.nominal_latency_ms) / 200.0),
+        "reliability": max(0.0, min(1.0, c.reliability)),
+        "quality": max(0.0, min(1.0, c.difficulty_score)) * _DOMAIN_DEPTH.get(c.domain, 0.60),
+    }
+    total = sum(dims[k] * weights.get(k, 0.0) for k in dims)
+    return {"domain": c.domain, "model": c.model,
+            "total": round(total, 4), "dims": {k: round(v, 4) for k, v in dims.items()}}
+
+
+def explain_routing(candidates: List[CandidateProfile],
+                    weights: Optional[Dict[str, float]] = None) -> RoutingExplanation:
+    """硬过滤 -> 五维加权 -> 排名与置信度推导（确定性：同分按领域名字典序）。"""
+    w = dict(DEFAULT_WEIGHTS if weights is None else weights)
+    rejected: List[Dict[str, Any]] = []
+    alive: List[CandidateProfile] = []
+    for c in candidates:
+        if c.hard_fail_reason is not None:
+            rejected.append({"domain": c.domain, "reason": c.hard_fail_reason})
+        else:
+            alive.append(c)
+
+    scored = [score_candidate(c, w) for c in alive]
+    scored.sort(key=lambda s: (-s["total"], s["domain"]))
+
+    if not scored:
+        # 全部被硬过滤（含低置信度直连回退路径）：决策即走大模型回退
+        return RoutingExplanation(winner="fallback", confidence=0.80,
+                                  ranked=[], rejected=rejected, weights=w)
+
+    gap = scored[0]["total"] - (scored[1]["total"] if len(scored) > 1 else 0.0)
+    confidence = min(0.99, 0.80 + max(0.0, gap))
+    return RoutingExplanation(winner=scored[0]["domain"], confidence=confidence,
+                              ranked=scored, rejected=rejected, weights=w)

router_system/models.py

@@ -44,6 +44,7 @@ class RouterResult:
     cache_level: Optional[str] = None    # exact | semantic
     cost_est: float = 0.0
     error: Optional[str] = None
+    route_explanation: Optional[Dict[str, Any]] = None  # 可解释评分（T-R1，缓存命中为 None）
 
     def to_dict(self) -> Dict[str, Any]:
         return {
@@ -61,6 +62,7 @@ class RouterResult:
             "cache_level": self.cache_level,
             "cost_est": round(self.cost_est, 6),
             "error": self.error,
+            "route_explanation": self.route_explanation,
         }
 
 

router_system/router.py

@@ -45,6 +45,8 @@ class Router:
         self.low_confidence_threshold = rcfg.get("low_confidence_threshold", 0.60)
         self.judge_fallback_threshold = rcfg.get("judge_fallback_threshold", 0.70)
         self.cache_enabled = cfg.get("cache", {}).get("enabled", True)
+        # T-R1：可解释路由评分层（纯解释，不影响决策；默认开启）
+        self.explain_enabled = bool(rcfg.get("explain_enabled", True))
 
     # ---------------------------------------------------------------
     async def route(self, query: str) -> RouterResult:
@@ -80,10 +82,16 @@ class Router:
         classification = self.classifier.classify(query)
         route.append(f"classify:{classification.domain}@{classification.confidence:.2f}/{classification.difficulty}")
 
+        # T-R1：候选装配与可解释评分（纯解释层，不改变后续任何决策分支）
+        explanation = self._explain(classification) if self.explain_enabled else None
+        if explanation is not None:
+            route.append(f"explain:{explanation.winner}@{explanation.confidence:.2f}")
+
         # 低置信度 -> 直接走大模型
         if self.classifier.should_fallback(classification, self.low_confidence_threshold):
             route.append("direct_fallback")
-            return await self._fallback_result(query, classification, route, start)
+            return await self._fallback_result(query, classification, route, start,
+                                               explanation=explanation)
 
         # ---- Step 3: 选择专家 ----
         domain = classification.domain
@@ -101,7 +109,7 @@ class Router:
             self.stats.record_error()
             route.append(f"expert_error:{type(e).__name__}")
             return await self._fallback_result(query, classification, route, start,
-                                               error=str(e))
+                                               error=str(e), explanation=explanation)
 
         # ---- Step 5: Judge 评估 ----
         try:
@@ -123,19 +131,46 @@ class Router:
         latency = now_ms() - start
         result = self._finalize(query, classification, final_resp, quality_score=quality_score,
                                 upgraded=upgraded, route=route, latency_ms=latency,
-                                model_used=final_resp.model_used, cost_est=final_resp.cost_est)
+                                model_used=final_resp.model_used, cost_est=final_resp.cost_est,
+                                explanation=explanation)
         self._record(result, latency)
 
-        # 未升级的结果写缓存
+        # 未升级的结果写缓存（解释不随缓存复用——缓存命中路径 explanation=None）
         if self.cache_enabled and not upgraded and result.response:
             self.cache.put(query, result.to_dict())
 
         return result
 
+    # ---------------------------------------------------------------
+    def _explain(self, classification: Classification):
+        """装配候选画像并生成可解释评分（T-R1；任何异常不影响主链路）。"""
+        try:
+            from .explain import CandidateProfile, explain_routing
+            from .experts import _cost_for
+
+            raw = classification.raw_scores or {}
+            raw_max = max(raw.values()) if raw else 0.0
+            candidates = []
+            for dom, expert in self.experts.items():
+                cap = (raw.get(dom, 0.0) / raw_max) if raw_max > 0 else 0.0
+                reason = "无规则命中（capability=0）" if cap <= 0.0 else None
+                candidates.append(CandidateProfile(
+                    domain=dom, model=getattr(expert, "model", expert.name),
+                    capability=cap,
+                    cost_per_mtok=_cost_for(getattr(expert, "model", "mock")),
+                    nominal_latency_ms=getattr(expert, "nominal_latency_ms", 100.0),
+                    reliability=self.stats.domain_reliability(dom),
+                    difficulty_score=classification.difficulty_score,
+                    hard_fail_reason=reason))
+            return explain_routing(candidates)
+        except Exception:  # noqa: BLE001  解释层故障不影响路由（D-G4 同款纪律）
+            return None
+
     # ---------------------------------------------------------------
     async def _fallback_result(self, query: str, classification: Classification,
                                route: list, start: float,
-                               error: Optional[str] = None) -> RouterResult:
+                               error: Optional[str] = None,
+                               explanation=None) -> RouterResult:
         """兜底路径的公共收尾：调用大模型回退 -> finalize -> 记录指标。
 
         低置信度直连、专家异常两条路径共用，避免收尾逻辑三处重复。
@@ -145,7 +180,7 @@ class Router:
         result = self._finalize(query, classification, fb, quality_score=0.0,
                                 upgraded=True, route=route, latency_ms=latency,
                                 model_used=fb.model_used, cost_est=fb.cost_est,
-                                error=error)
+                                error=error, explanation=explanation)
         self._record(result, latency)
         return result
 
@@ -164,7 +199,7 @@ class Router:
     def _finalize(query: str, classification: Classification, resp: ExpertResponse,
                   quality_score: float, upgraded: bool, route: list,
                   latency_ms: float, model_used: str, cost_est: float,
-                  error: Optional[str] = None) -> RouterResult:
+                  error: Optional[str] = None, explanation=None) -> RouterResult:
         return RouterResult(
             query=query,
             response=resp.text,
@@ -179,6 +214,7 @@ class Router:
             cache_hit=False,
             cost_est=cost_est,
             error=error,
+            route_explanation=explanation.to_dict() if explanation is not None else None,
         )
 
     def _record(self, result: RouterResult, latency_ms: float):

router_system/stats.py

@@ -13,6 +13,7 @@ class Stats:
         self.domain_counter: Counter = Counter()
         self.difficulty_counter: Counter = Counter()
         self.upgraded = 0
+        self.upgraded_by_domain: Counter = Counter()   # 可解释评分 reliability 维输入
         self.cache_hits = 0
         self.cache_levels: Counter = Counter()
         self.errors = 0
@@ -29,6 +30,7 @@ class Stats:
             self.difficulty_counter[difficulty] += 1
             if upgraded:
                 self.upgraded += 1
+                self.upgraded_by_domain[domain] += 1
             if cache_hit:
                 self.cache_hits += 1
                 if cache_level:
@@ -41,6 +43,15 @@ class Stats:
         with self._lock:
             self.errors += 1
 
+    def domain_reliability(self, domain: str, prior: float = 0.9) -> float:
+        """领域可靠性 = 1 - 升级率（无数据时返回中性先验，可解释评分用）。"""
+        with self._lock:
+            n = self.domain_counter.get(domain, 0)
+            if n <= 0:
+                return prior
+            up = self.upgraded_by_domain.get(domain, 0)
+            return max(0.0, min(1.0, 1.0 - up / n))
+
     def summary(self) -> Dict[str, Any]:
         with self._lock:
             n = self.requests

tests/test_explain.py

@@ -0,0 +1,90 @@
+"""可解释路由评分层单元测试（T-R1，采纳 ai-model-router 设计）。"""
+import pytest
+
+from router_system.explain import CandidateProfile, explain_routing
+from router_system.router import build_router
+
+
+def _cand(domain, capability, cost=1.0, latency=100.0, reliability=0.9, fail=None):
+    return CandidateProfile(domain=domain, model=f"m-{domain}", capability=capability,
+                            cost_per_mtok=cost, nominal_latency_ms=latency,
+                            reliability=reliability, difficulty_score=0.5,
+                            hard_fail_reason=fail)
+
+
+def test_hard_filter_rejects_with_reason():
+    """硬过滤淘汰带人话理由，被拒者不进排名。"""
+    exp = explain_routing([
+        _cand("code", 1.0),
+        _cand("math", 0.0, fail="无规则命中（capability=0）"),
+    ])
+    assert exp.winner == "code"
+    assert any(r["domain"] == "math" and "无规则命中" in r["reason"] for r in exp.rejected)
+    assert all(s["domain"] != "math" for s in exp.ranked)
+
+
+def test_all_rejected_falls_back():
+    """全部候选被硬过滤：决策者是大模型回退，置信度取基准 0.8。"""
+    exp = explain_routing([_cand("code", 0.0, fail="x"), _cand("math", 0.0, fail="y")])
+    assert exp.winner == "fallback"
+    assert exp.confidence == 0.80
+    assert len(exp.rejected) == 2
+
+
+def test_zero_cost_local_beats_costly():
+    """成本效率维平滑映射：零成本恒 1.0，贵模型显著吃亏。"""
+    cheap = explain_routing([_cand("code", 1.0, cost=0.0, latency=1.0)]).ranked[0]
+    pricey = explain_routing([_cand("math", 1.0, cost=2.5, latency=800.0)]).ranked[0]
+    assert cheap["dims"]["cost_efficiency"] == 1.0
+    assert pricey["dims"]["cost_efficiency"] < 0.5
+    assert cheap["total"] > pricey["total"]
+
+
+def test_confidence_gap_derivation():
+    """置信度 = 0.8 + 分差：独苗封顶 0.99，双候选同分回落 0.8。"""
+    single = explain_routing([_cand("code", 1.0)])
+    tied = explain_routing([_cand("code", 1.0), _cand("math", 1.0)])
+    assert single.confidence == 0.99
+    assert tied.confidence == 0.80
+
+
+def test_tie_break_is_deterministic():
+    """同分决胜按领域名字典序（与仓库既有确定性约定一致）。"""
+    exp = explain_routing([_cand("zeta", 1.0), _cand("alpha", 1.0)])
+    assert exp.winner == "alpha"
+
+
+def test_weights_snapshot_and_rank_order():
+    """排名按 total 降序，权重快照随解释输出。"""
+    exp = explain_routing([
+        _cand("code", 1.0, cost=0.0, latency=1.0),
+        _cand("math", 0.5, cost=2.0, latency=900.0),
+    ])
+    totals = [s["total"] for s in exp.ranked]
+    assert totals == sorted(totals, reverse=True)
+    assert exp.weights["capability"] == 0.35
+
+
+@pytest.mark.asyncio
+async def test_route_attaches_explanation():
+    """主链路返回结构化 route_explanation；缓存命中路径为 None。"""
+    router = build_router()
+    r1 = await router.route("用 Python 写一个快速排序函数")
+    assert r1.route_explanation is not None
+    assert r1.route_explanation["winner"] == "code"
+    assert any("explain:" in step for step in r1.route)
+    assert any("无规则命中" in r["reason"]
+               for r in r1.route_explanation["rejected"])
+    r2 = await router.route("用 Python 写一个快速排序函数")
+    assert r2.cache_hit is True
+    assert r2.route_explanation is None
+
+
+@pytest.mark.asyncio
+async def test_low_confidence_explains_fallback():
+    """低置信度直连回退：解释层给出 fallback 胜者与拒绝名单。"""
+    router = build_router()
+    r = await router.route("今天天气怎么样")
+    assert r.upgraded is True
+    assert r.route_explanation is not None
+    assert r.route_explanation["winner"] == "fallback"