xg-cli 1.0__py3-none-any.whl

xg/memory/store.py

@@ -0,0 +1,144 @@
+"""项目级 SQLite 长期记忆仓库。"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+from xg.memory.models import MemoryEntry
+
+
+SCHEMA_VERSION = 1
+
+
+def normalize_content(content: str) -> str:
+    return " ".join(content.split()).casefold()
+
+
+def _parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value)
+
+
+class SQLiteMemoryStore:
+    def __init__(self, db_path: str | Path) -> None:
+        self.db_path = Path(db_path)
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path, timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA busy_timeout=5000")
+        conn.execute("PRAGMA foreign_keys=ON")
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def _initialize(self) -> None:
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            version = int(conn.execute("PRAGMA user_version").fetchone()[0])
+            if version < 1:
+                conn.executescript(
+                    """
+                    CREATE TABLE IF NOT EXISTS memories (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        content TEXT NOT NULL CHECK (length(trim(content)) > 0),
+                        normalized_content TEXT NOT NULL,
+                        source TEXT NOT NULL DEFAULT 'manual',
+                        created_at TEXT NOT NULL,
+                        updated_at TEXT NOT NULL
+                    );
+                    CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_normalized
+                        ON memories(normalized_content);
+                    CREATE INDEX IF NOT EXISTS idx_memories_updated
+                        ON memories(updated_at DESC, id DESC);
+                    PRAGMA user_version = 1;
+                    """
+                )
+
+    @staticmethod
+    def _entry(row: sqlite3.Row) -> MemoryEntry:
+        return MemoryEntry(
+            id=int(row["id"]),
+            content=str(row["content"]),
+            source=str(row["source"]),
+            created_at=_parse_time(str(row["created_at"])),
+            updated_at=_parse_time(str(row["updated_at"])),
+        )
+
+    def save(self, content: str, source: str = "manual") -> tuple[MemoryEntry, bool]:
+        content = content.strip()
+        if not content:
+            raise ValueError("记忆内容不能为空")
+        if len(content) > 4000:
+            raise ValueError("单条记忆最多 4000 个字符")
+        normalized = normalize_content(content)
+        now = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM memories WHERE normalized_content = ?", (normalized,)
+            ).fetchone()
+            if row is not None:
+                conn.execute(
+                    "UPDATE memories SET updated_at = ?, source = ? WHERE id = ?",
+                    (now, source, int(row["id"])),
+                )
+                row = conn.execute(
+                    "SELECT * FROM memories WHERE id = ?", (int(row["id"]),)
+                ).fetchone()
+                assert row is not None
+                return self._entry(row), False
+            cursor = conn.execute(
+                """
+                INSERT INTO memories(content, normalized_content, source, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (content, normalized, source, now, now),
+            )
+            row = conn.execute(
+                "SELECT * FROM memories WHERE id = ?", (cursor.lastrowid,)
+            ).fetchone()
+            assert row is not None
+            return self._entry(row), True
+
+    def list(self, limit: int = 20, offset: int = 0) -> list[MemoryEntry]:
+        limit = max(1, min(int(limit), 100))
+        offset = max(0, int(offset))
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM memories ORDER BY updated_at DESC, id DESC LIMIT ? OFFSET ?",
+                (limit, offset),
+            ).fetchall()
+        return [self._entry(row) for row in rows]
+
+    def search(self, query: str, limit: int = 20) -> list[MemoryEntry]:
+        query = normalize_content(query)
+        if not query:
+            return []
+        limit = max(1, min(int(limit), 100))
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM memories
+                WHERE instr(normalized_content, ?) > 0
+                ORDER BY updated_at DESC, id DESC
+                LIMIT ?
+                """,
+                (query, limit),
+            ).fetchall()
+        return [self._entry(row) for row in rows]
+
+    def delete(self, memory_id: int) -> bool:
+        with self._connect() as conn:
+            cursor = conn.execute("DELETE FROM memories WHERE id = ?", (int(memory_id),))
+            return cursor.rowcount > 0
+
+    def clear(self) -> int:
+        with self._connect() as conn:
+            count = int(conn.execute("SELECT count(*) FROM memories").fetchone()[0])
+            conn.execute("DELETE FROM memories")
+            return count
+
+    def count(self) -> int:
+        with self._connect() as conn:
+            return int(conn.execute("SELECT count(*) FROM memories").fetchone()[0])

xg/router/__init__.py

@@ -0,0 +1,124 @@
+"""SmartRouter 路由核心包。
+
+按输入文本的规则特征判断复杂度档位（Basic / Enhanced / Superior / Ultimate），
+并解析出该档位应使用的 provider / model。
+
+第 1 期子步骤 A：仅提供纯函数路由能力，尚未接入主循环与命令开关
+（见 XG-docs/smart-docs/states/phase-01-smart-router-core.md）。
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from .features import extract
+from .model_tiers import TIER_NAMES, TierTarget, resolve
+from .postprocess import postprocess
+from .rule_router import RuleDecision, confidence, rule_route, rule_score
+
+
+@dataclass(frozen=True)
+class RouteResult:
+    """一次完整路由的结果。"""
+
+    tier: str                  # Basic / Enhanced / Superior / Ultimate
+    tier_idx: int              # 0..3
+    provider: str
+    model: str
+    configured: bool           # 档位是否来自用户显式配置
+    confidence: float          # 0~1，规则路由的置信度估计
+    score: float               # 规则加权总分
+    hard_rule: bool            # 是否由硬规则直接决定
+    features: dict = field(default_factory=dict)  # 特征快照（测试/调试/后续反馈采集用）
+
+
+def _tier_index(prev_tier: str | int | None) -> int | None:
+    """把档位名（或索引）统一转成索引；未知名称返回 None。"""
+    if prev_tier is None:
+        return None
+    if isinstance(prev_tier, int):
+        return prev_tier
+    try:
+        return TIER_NAMES.index(prev_tier)
+    except ValueError:
+        return None
+
+
+def route(text: str, *,
+          prev_tier: str | int | None = None,
+          prev_ts: float | None = None,
+          ts: float | None = None,
+          context_tokens: int = 0,
+          fallback_provider: str = "",
+          fallback_model: str = "",
+          tiers_config: dict | None = None,
+          manager=None,
+          calibration=None,
+          learned_rules=None,
+          hysteresis=None,
+          ml_router=None) -> RouteResult:
+    """对一段用户输入做完整路由：特征 → 规则打分 → 校准/ML精判 → 后处理 → 档位解析。
+
+    ``manager``（ConfigManager）可选，传入时对显式配置档做 provider/API Key 校验。
+    ``calibration``（adaptive.Calibration）可选，phase-03 步骤 C 只读注入：
+    在规则打分后、安全后处理前应用档位偏置与置信门；不传即第 1 期纯规则行为。
+    ``learned_rules``（adaptive.LearnedRules）可选，phase-04 步骤 A1 只读注入：
+    postprocess 末尾对其命中的 ±1 档微调，硬规则强制时无效；不传即第 3 期行为。
+    ``hysteresis``（router.postprocess.Hysteresis）可选，phase-04 步骤 A2 只读注入：
+    作为最后一道闸抑制会话内短时跳档，硬规则强制时解冻；不传即 A1 行为。
+    ``ml_router``（router.ml_router.MLRouter）可选，phase-05 步骤 B2 只读注入：
+    规则打分后参与精判（概率最高档 + 置信门 + 校准偏置），不可用/信心不足时
+    静默回落规则档位；硬规则决策不参与精判；不传即 A1+A2 行为。
+    """
+    f = extract(text)
+    decision: RuleDecision = rule_route(f)
+    tier_idx = decision.tier_idx
+    hard_rule = decision.hard_rule
+    from xg.adaptive.calibrate import apply_calibration
+
+    # 优先：ML 精判（仅软规则决策、且产物可用时）→ 置信门 + 校准偏置
+    if ml_router is not None and not hard_rule and ml_router.available:
+        ml_tier = ml_router.decide(text, f, calibration)
+        if ml_tier is not None:
+            tier_idx = ml_tier
+    else:
+        if calibration is not None:
+            tier_idx = apply_calibration(
+                tier_idx, confidence(decision), hard_rule, calibration,
+            )
+    final_idx = postprocess(
+        tier_idx, text, f,
+        prev_tier=_tier_index(prev_tier), prev_ts=prev_ts,
+        ts=ts if ts is not None else time.time(),
+        context_tokens=context_tokens,
+        learned_rules=learned_rules,
+        hysteresis=hysteresis,
+    )
+    target: TierTarget = resolve(final_idx, fallback_provider, fallback_model,
+                                 tiers_config, manager)
+    return RouteResult(
+        tier=target.tier,
+        tier_idx=final_idx,
+        provider=target.provider,
+        model=target.model,
+        configured=target.configured,
+        confidence=confidence(decision),
+        score=decision.score,
+        hard_rule=decision.hard_rule,
+        features=f,
+    )
+
+
+__all__ = [
+    "RouteResult",
+    "TierTarget",
+    "TIER_NAMES",
+    "extract",
+    "route",
+    "resolve",
+    "rule_route",
+    "rule_score",
+    "postprocess",
+    "KEYWORDS",
+]

xg/router/features.py

@@ -0,0 +1,66 @@
+"""SmartRouter 规则特征管线。
+
+纯 Python 字符串统计，无需训练、零第三方依赖。
+特征定义来源：XG-docs/smart-docs/ADAPTIVE_ROUTING.md §4.1。
+"""
+
+from __future__ import annotations
+
+import re
+
+from .keywords import KEYWORDS
+
+# 附件/文件类提及词（has_attachment 特征用，不属于 KEYWORDS 打分类别）
+_ATTACHMENT_WORDS = ("附件", "文件", "目录", "上传", "file", "attachment")
+
+# 围栏代码块：``` 开头（可带语言标注）到 ``` 结束
+_FENCE_RE = re.compile(r"```[^\n]*\n(.*?)```", re.S)
+# 围栏块的语言标注（用于 num_json / num_xml 统计）
+_FENCE_LANG_RE = re.compile(r"```(json|xml)[^\n]*\n", re.I)
+# 列表项：数字编号（1. / 1、 / 1)）或无序列表（- / * / +）
+_LIST_ITEM_RE = re.compile(r"^\s*(?:\d+[.、)]|[-*+])\s+", re.M)
+
+
+def code_blocks(text: str) -> list[str]:
+    """提取 ``` 围栏代码块；无围栏时按行首缩进 >=4 空格的行聚合成块。"""
+    blocks = _FENCE_RE.findall(text)
+    if blocks:
+        return blocks
+    lines = [ln for ln in text.splitlines() if ln.startswith(("    ", "\t"))]
+    return ["\n".join(lines)] if lines else []
+
+
+def extract(text: str) -> dict:
+    """从用户输入文本提取规则特征，返回扁平特征字典。"""
+    lower = text.lower()
+    blocks = code_blocks(text)
+    code_chars = sum(len(b) for b in blocks)
+
+    f: dict = {
+        "len_chars": len(text),
+        "len_words": len(text.split()),
+        "num_code_blocks": len(blocks),
+        "code_chars_ratio": (code_chars / len(text)) if text else 0.0,
+    }
+
+    # JSON / XML 片段数：统计带语言标注的围栏块（```json / ```xml）
+    fence_langs = [m.lower() for m in _FENCE_LANG_RE.findall(text)]
+    f["num_json"] = fence_langs.count("json")
+    f["num_xml"] = fence_langs.count("xml")
+
+    # 列表项数
+    f["num_lists"] = len(_LIST_ITEM_RE.findall(text))
+
+    # 是否提及文件/附件
+    f["has_attachment"] = 1 if any(w in lower for w in _ATTACHMENT_WORDS) else 0
+
+    # 各类关键词命中数（英文转小写后子串匹配，按出现次数累计）
+    for cat, words in KEYWORDS.items():
+        f[f"num_{cat}_kw"] = sum(lower.count(w.lower()) for w in words)
+
+    # 闲聊标记：命中任一闲聊词
+    f["is_chatty"] = 1 if f["num_chatty_kw"] > 0 else 0
+    # 疑问句标记：含中/英文问号
+    f["question_mark"] = 1 if ("?" in text or "？" in text) else 0
+
+    return f

xg/router/keywords.py

@@ -0,0 +1,50 @@
+"""SmartRouter 关键词表（中英双语）。
+
+词表来源：XG-docs/smart-docs/ADAPTIVE_ROUTING.md §4.1。
+命中判定用子串匹配（``kw in text``），中文词无需分词即可工作；
+英文词统一转小写后匹配。可按业务增删，但不改变类别键名
+（features/rule_router/postprocess 依赖类别名）。
+"""
+
+from __future__ import annotations
+
+KEYWORDS: dict[str, list[str]] = {
+    "arch": [  # 架构词（命中→高风险/高复杂度）
+        "架构", "重构", "扩展", "依赖", "分布式", "微服务", "模块化", "集成",
+        "迁移", "设计模式", "系统设计", "扩展性", "性能优化",
+        "architecture", "refactor", "microservice", "distributed",
+        "scalable", "modular", "integration",
+    ],
+    "risk": [  # 风险词（命中→强制升档）
+        "部署", "回滚", "迁移", "生产", "客户", "法务", "上线", "宕机",
+        "故障", "安全", "合规", "数据丢失", "备份", "恢复", "资损",
+        "deploy", "rollback", "production", "compliance", "security",
+        "outage", "failure", "data-loss", "incident",
+    ],
+    "planning": [  # 规划词（方案/设计类）
+        "设计", "方案", "对比", "取舍", "路线图", "规划", "roadmap",
+        "权衡", "tradeoff", "plan", "design", "compare", "evaluate",
+    ],
+    "impl": [  # 实现词（具体动手任务）
+        "写", "实现", "改", "生成", "修复", "添加", "创建", "优化",
+        "帮我", "实现一个", "封装", "接入",
+        "write", "implement", "create", "fix", "build", "refactor",
+    ],
+    "teach": [  # 教学词（解释/问答类）
+        "解释", "为什么", "原理", "区别", "对比", "是什么", "如何",
+        "什么是", "讲解", "说明",
+        "explain", "why", "difference", "how", "what is", "describe",
+    ],
+    "constraint": [  # 约束词（有硬性要求→偏复杂）
+        "必须", "不能", "不允许", "性能", "安全", "精确", "严格",
+        "restriction", "constraint", "must", "cannot", "strict",
+    ],
+    "chatty": [  # 闲聊词（命中→降档）
+        "你好", "谢谢", "在吗", "ok", "好的", "嗨", "嗯", "没问题", "再见",
+        "hello", "hi", "thanks", "bye", "okay", "sure", "fine",
+    ],
+    "debug": [  # 调试词（命中→升一档）
+        "报错", "失败", "还是不行", "异常", "崩溃", "超时",
+        "error", "exception", "debug", "crash", "timeout", "bug",
+    ],
+}

xg/router/ml_router.py

@@ -0,0 +1,178 @@
+"""SmartRouter ML 精判接入与静默回落（第 5 期 B2）。
+
+职责：加载离线训练的产物（tools/train_router.py 生成的 router.lgb），
+在规则路由之后、安全后处理之前参与精判——取"概率最高档"，受 置信门 +
+校准偏置 约束；任何缺依赖 / 缺产物 / 产物损坏 情形一律**静默回落**，
+行为退化为纯规则（与本模块不存在的第 4 期行为完全一致）。
+
+导入保护（主进程零硬性 ML 依赖）：
+    joblib / lightgbm / sklearn / numpy 仅在 onnx 运行期 import，
+    任一把 import 失败即在初始化时把本模块标记为不可用（available=False），
+    主进程绝不因缺依赖而报错。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..adaptive.calibrate import CONFIDENCE_BASE, apply_calibration
+
+# 产物格式版本（与 tools/train_router.py 的 ARTIFACT_FORMAT 一致）
+ARTIFACT_FORMAT = 1
+_DEFAULT_ARTIFACT = "router.lgb"  # 默认文件名，相对 data_dir
+
+
+@dataclass(frozen=True)
+class MLPrediction:
+    """一次可用的 ML 精判结果。"""
+
+    tier: int        # 概率最高档 0..3
+    prob: float      # 该档预测概率 0..1
+
+
+class MLRouter:
+    """产物加载与精判；不可用时全链路静默回落。"""
+
+    def __init__(self, artifact_path: Path | None = None,
+                 semantic=None) -> None:
+        self._payload = None
+        self._vectorizer = None
+        self._model = None
+        self._feature_keys: tuple[str, ...] = ()
+        # 第 6 期 C2：可选语义编码器（bge 512 维）。训练产物带 sem_dim>0 时，
+        # 预测需语义列；语义不可用则整个静默回落（无法提供既定列宽）。
+        self._semantic = semantic
+        self._sem_dim = 0
+        # 随包兜底：默认产物缺失时首启自动落位（clone 后开箱可用）
+        if artifact_path is None:
+            self._ensure_bundled()
+        self._load(artifact_path)
+
+    def _ensure_bundled(self) -> None:
+        """把随包默认产物（router.lgb 等）复制到数据目录；已存在则跳过。"""
+        from ..adaptive.store import ensure_default_artifacts
+        ensure_default_artifacts()
+
+    # -- 加载 -----------------------------------------------------------
+    def _load(self, artifact_path: Path | None) -> None:
+        """加载产物；任何异常（缺依赖/缺文件/损坏/格式不符）→ 不可用。"""
+        path = artifact_path or self._default_path()
+        if path is None or not path.exists():
+            return
+        try:
+            import joblib  # noqa: PLC0415
+            from sklearn.utils.validation import check_is_fitted  # noqa: PLC0415
+            payload = joblib.load(path)
+            if not isinstance(payload, dict) or payload.get("format") != ARTIFACT_FORMAT:
+                return
+            model = payload.get("model")
+            vec = payload.get("vectorizer")
+            keys = payload.get("feature_keys") or ()
+            if not hasattr(model, "predict_proba"):
+                return
+            check_is_fitted(model)
+            sem_dim = payload.get("sem_dim", 0) or 0
+            # 产物声明需要语义列，但语义编码器不可用 → 整链静默回落
+            if sem_dim > 0 and (self._semantic is None or not self._semantic.available):
+                return
+            self._vectorizer = vec
+            self._model = model
+            self._feature_keys = tuple(keys)
+            self._sem_dim = int(sem_dim)
+            self._payload = payload
+        except Exception:
+            self._payload = None
+            self._vectorizer = None
+            self._model = None
+            self._feature_keys = ()
+            self._sem_dim = 0
+
+    def _default_path(self) -> Path | None:
+        from ..adaptive.store import data_dir
+        return data_dir() / _DEFAULT_ARTIFACT
+
+    @property
+    def available(self) -> bool:
+        """产物已成功加载且模型可用。"""
+        return self._model is not None
+
+    @property
+    def n_samples(self) -> int | None:
+        return self._payload.get("n_samples") if self._payload else None
+
+    @property
+    def sem_dim(self) -> int:
+        """训练时并入的语义特征维度（0=无语义，纯第 5 期行为）。"""
+        return self._sem_dim
+
+    @property
+    def semantic(self) -> object | None:
+        """绑定的语义编码器（可能为 None）；供 status 观测。"""
+        return self._semantic
+
+    # -- 预测 -----------------------------------------------------------
+    def _encode(self, text: str, features: dict | None):
+        """把 text + 数值特征 拼成 (TF-IDF, 数值) 稀疏输入；无需义时行为同第 5 期。
+
+        语义列（sem_dim>0，第 6 期）追加在数值列之后，顺序为
+        [TF-IDF] + [数值] + [语义512]，与 train_router 训练矩阵严格一致。
+        """
+        import numpy as np  # noqa: PLC0415
+        from scipy.sparse import csr_matrix, hstack  # noqa: PLC0415
+        if self._vectorizer is not None:
+            x_text = self._vectorizer.transform([text or " "])
+        else:
+            x_text = csr_matrix((1, 0))
+        row = [float((features or {}).get(k, 0.0)) for k in self._feature_keys]
+        cols = [x_text, csr_matrix(np.array([row]))]
+        if self._sem_dim > 0:
+            import numpy as _np  # noqa: PLC0415
+            sem = self._semantic.encode(text)
+            if sem is None:
+                # 语义列不可得（理论上 available 已兜底，防御万一）
+                sem = [0.0] * self._sem_dim
+            cols.append(csr_matrix(_np.array([sem[:self._sem_dim]])))
+        return hstack(cols).tocsr()
+
+    def predict(self, text: str, features: dict | None = None) -> MLPrediction | None:
+        """训练产物预测：返回概率最高档；不可用返回 None（静默回落）。"""
+        if not self.available:
+            return None
+        x = self._encode(text, features)
+        probs = self._model.predict_proba(x)[0]
+        tier = int(probs.argmax())
+        return MLPrediction(tier=tier, prob=float(probs[tier]))
+
+    def decide(
+        self,
+        text: str,
+        features: dict | None = None,
+        calibration=None,
+    ) -> int | None:
+        """精判入口：置信门 + 校准偏置后返回档位；不采用返回 None。
+
+        与规则路径复用一个置信门/偏置逻辑（apply_calibration）：
+        - 预测最高档概率 < 门（CONFIDENCE_BASE + threshold_adjust）→ 信心不足，
+          返回 None，由 route() 保留规则档位；
+        - 否则对最高档应用 apply_calibration（偏强档降/偏弱档升，最多一档）。
+        硬规则档位由 route() 在调用方排除（decision.hard_rule 时不走精判）。
+        """
+        if not self.available:
+            return None
+        pred = self.predict(text, features)
+        if pred is None:
+            return None
+        gate = CONFIDENCE_BASE + (
+            calibration.threshold_adjust if calibration is not None else 0.0
+        )
+        if pred.prob < gate:
+            return None
+        if calibration is not None:
+            return apply_calibration(pred.tier, pred.prob, False, calibration)
+        return pred.tier
+
+
+def load_ml_router(artifact_path: Path | None = None) -> MLRouter:
+    """便捷工厂：缺依赖/缺产物时返回一个 available=False 的 MLRouter。"""
+    return MLRouter(artifact_path)

xg/router/model_tiers.py

@@ -0,0 +1,73 @@
+"""SmartRouter 档位→模型映射。
+
+接入 ConfigManager（phase-01 子步骤 B）：
+- ``tiers_config`` 形如 ``{"Basic": {"provider": "glm", "model": "glm-4-flash"}, ...}``，
+  通常来自 ``ConfigManager.smart_router_config()["tiers"]``；
+- 传入 ``manager`` 时启用完整校验链：provider 必须可解析、API Key 必须已配置，
+  否则该档回落 fallback（active 模型）并标记 ``configured=False``；
+- 未配置的档位同样回落 fallback。
+
+校验失败的档位在 UI 上应显示为不可用（阶段 2 的暗淡 + (x) 标记）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .postprocess import TIER
+
+if TYPE_CHECKING:
+    from xg.config.manager import ConfigManager
+
+TIER_NAMES = TIER
+
+
+@dataclass(frozen=True)
+class TierTarget:
+    """某档位解析出的模型目标。"""
+
+    tier: str            # Basic / Enhanced / Superior / Ultimate
+    provider: str
+    model: str
+    configured: bool     # 显式配置且校验通过（False 表示回落默认/校验失败）
+
+
+def resolve(tier_idx: int, fallback_provider: str, fallback_model: str,
+            tiers_config: dict | None = None,
+            manager: "ConfigManager | None" = None) -> TierTarget:
+    """把档位索引解析成 (provider, model)。
+
+    结算规则：
+    1. 档位指定了 ``provider``：model 缺省时用该 provider 的默认模型（D5），
+       需 ``manager`` 解析；传 None 时无法取默认模型，回落 fallback_model。
+    2. 档位未指定 ``provider``：整体回落 fallback（base provider 及其生效模型），
+       model 取档位显式 ``model`` 或 fallback_model。
+    3. 显式配置经 ``manager`` 校验：provider 必须可解析、API Key 必须已配置，
+       否则整档回落 fallback 并标记 ``configured=False``。
+    """
+    tier_name = TIER_NAMES[tier_idx]
+    cfg = (tiers_config or {}).get(tier_name) or {}
+    provided_provider = str(cfg.get("provider") or "")
+
+    if provided_provider:
+        provider = provided_provider
+        default_model = fallback_model
+        if manager is not None:
+            prov = manager.resolve_provider(provider)
+            if prov is not None and prov.default_model:
+                default_model = prov.default_model
+        model = str(cfg.get("model") or "") or default_model
+        configured = bool(cfg.get("provider") or cfg.get("model"))
+    else:
+        provider = fallback_provider
+        model = str(cfg.get("model") or "") or fallback_model
+        configured = bool(cfg.get("model"))
+
+    if configured and manager is not None and (provider, model) != (fallback_provider, fallback_model):
+        prov = manager.resolve_provider(provider)
+        if prov is None or not manager.resolve_api_key(prov):
+            # provider 不存在或 API Key 未配置：整档回落 active
+            return TierTarget(tier=tier_name, provider=fallback_provider,
+                              model=fallback_model, configured=False)
+    return TierTarget(tier=tier_name, provider=provider, model=model, configured=configured)