codebee 0.1.66 → 0.1.68

package/app/core/defectretro.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""缺陷复盘报告（defect_retro，借鉴 zl2237/test-defect-retrospective）。
+
+禅道/Jira 缺陷导出 → 产品/开发/测试三视角复盘报告。
+数据不走网络：缺陷导出（CSV）作为任务附件注入上下文，这里只负责
+组装分析框架提示词。无附件时提示词会点名要求补附件——报告框架
+照常输出，不留静默空转。
+
+对照参考实现的取舍：它是本地脚本确定性算指标（analyzer 同输入同输出），
+我们是 direct 引擎一次性成稿——先跑通「有复盘产物」这一步，指标口径
+固化（状态/严重度归一在提示词里给锚）后续按需升档。
+"""
+from __future__ import annotations
+
+
+def retro_prompt(goal):
+    """组装缺陷复盘三视角提示词。纯框架无抓取，恒有返回值。"""
+    return (
+        "你是资深质量效能专家，负责输出一份缺陷复盘报告。\n\n"
+        "## 输入\n"
+        "用户会提供缺陷平台导出数据（推荐禅道/Jira 导出 CSV 作为任务附件；"
+        "Excel 二进制读不了，请导出 CSV）。字段口径以「标题、严重程度、"
+        "状态、创建日期、所属模块、解决方案、关闭原因、责任人」为锚，"
+        "缺失字段按实际有的算并在报告中声明口径。\n\n"
+        "## 用户关注点\n%s\n\n"
+        "## 你的产出（Markdown 报告）\n"
+        "1. **整体画像**：缺陷总量、严重度分布、状态分布、时间走势"
+        "（按创建日期聚合）、模块 Top5 集中度——只用表格+一句话结论，不复述原始数据\n"
+        "2. **产品视角**：需求类缺陷（描述不清/变更频繁/逻辑矛盾）占比与典型例；"
+        "类需求缺陷（被当 Bug 提的优化）点名\n"
+        "3. **开发视角**：根因聚类（编码疏忽/设计缺陷/环境/数据/回归）占比；"
+        "重复回归的模块点名；修复后又被激活的缺陷单列\n"
+        "4. **测试视角**：发现阶段分布（提测后/上线后/用户反馈）；漏测推测"
+        "（上线后才暴露的缺陷缺什么用例）；严重度与发现时长的错配\n"
+        "5. **改进动作**：每个视角 2-3 条，带建议责任角色与可验证的完成标准，"
+        "拒绝「加强沟通」类空话\n\n"
+        "## 纪律\n"
+        "- 所有数字必须从提供的导出数据里数出来，数不出的指标写「数据未提供」"
+        "而不是编造\n"
+        "- 若上下文里没有任何缺陷数据，直接说明需要附带导出 CSV 并给出导出步骤"
+        "（禅道：产品-缺陷-导出-CSV），不要硬写报告\n"
+        "- 直接输出报告，不要复述本提示词"
+        % (goal or "（用户未指定，按全量缺陷复盘）"))

package/app/core/diagnostics.py

@@ -1,115 +1,115 @@
-# -*- coding: utf-8 -*-
-"""运行时不变量注册表：质量闸门从 pytest 测试期提升到运行时。
-
-设计稿：docs/migration/01-defense-patterns.md §5F。
-参考 dsh packages/runtime-diagnostics/invariants/src/index.ts：
-  enabled/package_allowlist/package_blocklist 三过滤；失败抛 InvariantError 含 packageName。
-
-CodeBee 实施简化为单文件 + pytest 钩子（设计稿说明）；register(name, fn) 注册断言，
-run_for(source, ctx) 在指定 source 下跑所有断言并返回失败列表。
-"""
-from __future__ import annotations
-
-import logging
-import threading
-from typing import Optional
-
-log = logging.getLogger(__name__)
-
-
-class InvariantError(Exception):
-    def __init__(self, source: str, check_name: str, msg: str):
-        super().__init__(f"[{source}/{check_name}] {msg}")
-        self.source = source
-        self.check_name = check_name
-
-
-class InvariantRegistry:
-    """按 source 分组的运行时断言注册表。
-
-    source 是来源标识（如 "pipeline"/"store"），name 是断言名；
-    fn(ctx) -> Optional[str] 返回 None 表示通过，返回字符串即失败消息。
-    """
-
-    def __init__(self):
-        self._lock = threading.Lock()
-        self._checks: dict = {}  # source -> {name: fn}
-
-    def register(self, source: str, name: str, fn):
-        with self._lock:
-            self._checks.setdefault(source, {})[name] = fn
-            log.debug("invariant registered: %s/%s", source, name)
-
-    def unregister(self, source: str, name: str = None):
-        """移除断言；name=None 时清空整个 source。"""
-        with self._lock:
-            if source not in self._checks:
-                return
-            if name is None:
-                del self._checks[source]
-            else:
-                self._checks[source].pop(name, None)
-
-    def run_for(self, source: str, ctx: dict, *, fail_fast: bool = False):
-        """在 source 下跑所有断言。
-
-        Returns:
-            [(source, name, message), ...] 失败列表（空 = 全过）。
-
-        Raises:
-            InvariantError: fail_fast=True 且首个失败。
-        """
-        fails = []
-        with self._lock:
-            checks = dict(self._checks.get(source, {}))
-        for name, fn in checks.items():
-            try:
-                msg = fn(ctx)
-            except Exception as e:
-                msg = f"check raised: {e!r}"
-            if msg:
-                fails.append((source, name, msg))
-                log.warning("invariant FAIL: %s/%s: %s", source, name, msg)
-                if fail_fast:
-                    raise InvariantError(source, name, msg)
-        return fails
-
-    def list(self, source: Optional[str] = None):
-        """列出已注册的 source/name；source=None 时全部。"""
-        with self._lock:
-            if source is None:
-                return [(s, n) for s, m in self._checks.items() for n in m]
-            return [(source, n) for n in self._checks.get(source, {})]
-
-
-invariants = InvariantRegistry()  # 单例
-
-
-# === 默认 invariants ===
-def register_default_checks():
-    """注册 CodeBee 默认运行时断言。"""
-
-    def review_no_all_fail_zero(ctx):
-        """评审全部 0 分但 run 标 success → 不允许（已锁 test_quality_gates:62-75）。"""
-        if (ctx.get("review_scores")
-                and all(s == 0 for s in ctx["review_scores"])
-                and ctx.get("final_status") == "success"):
-            return "评审全部 0 分但 run 标 success"
-        return None
-
-    def step_count_consistency(ctx):
-        """实际 step 数与预期不一致。"""
-        if ctx.get("actual_steps") != ctx.get("expected_steps"):
-            return f"step count {ctx.get('actual_steps')} != expected {ctx.get('expected_steps')}"
-        return None
-
-    def ok_but_error_code(ctx):
-        """step 级：ok=True 却带非空 error_code —— 解析降级（如 codex 空输出
-        回落 stdout 尾部）被当成功，值得告警复核。"""
-        if ctx.get("ok") and ctx.get("error_code"):
-            return "step 标记成功但携带 error_code=%s（疑似降级输出）" % ctx["error_code"]
-        return None
-
-    invariants.register("pipeline", "review_no_all_fail_zero", review_no_all_fail_zero)
-    invariants.register("pipeline", "step_count_consistency", step_count_consistency)
+# -*- coding: utf-8 -*-
+"""运行时不变量注册表：质量闸门从 pytest 测试期提升到运行时。
+
+设计稿：docs/migration/01-defense-patterns.md §5F。
+参考 dsh packages/runtime-diagnostics/invariants/src/index.ts：
+  enabled/package_allowlist/package_blocklist 三过滤；失败抛 InvariantError 含 packageName。
+
+CodeBee 实施简化为单文件 + pytest 钩子（设计稿说明）；register(name, fn) 注册断言，
+run_for(source, ctx) 在指定 source 下跑所有断言并返回失败列表。
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+
+class InvariantError(Exception):
+    def __init__(self, source: str, check_name: str, msg: str):
+        super().__init__(f"[{source}/{check_name}] {msg}")
+        self.source = source
+        self.check_name = check_name
+
+
+class InvariantRegistry:
+    """按 source 分组的运行时断言注册表。
+
+    source 是来源标识（如 "pipeline"/"store"），name 是断言名；
+    fn(ctx) -> Optional[str] 返回 None 表示通过，返回字符串即失败消息。
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._checks: dict = {}  # source -> {name: fn}
+
+    def register(self, source: str, name: str, fn):
+        with self._lock:
+            self._checks.setdefault(source, {})[name] = fn
+            log.debug("invariant registered: %s/%s", source, name)
+
+    def unregister(self, source: str, name: str = None):
+        """移除断言；name=None 时清空整个 source。"""
+        with self._lock:
+            if source not in self._checks:
+                return
+            if name is None:
+                del self._checks[source]
+            else:
+                self._checks[source].pop(name, None)
+
+    def run_for(self, source: str, ctx: dict, *, fail_fast: bool = False):
+        """在 source 下跑所有断言。
+
+        Returns:
+            [(source, name, message), ...] 失败列表（空 = 全过）。
+
+        Raises:
+            InvariantError: fail_fast=True 且首个失败。
+        """
+        fails = []
+        with self._lock:
+            checks = dict(self._checks.get(source, {}))
+        for name, fn in checks.items():
+            try:
+                msg = fn(ctx)
+            except Exception as e:
+                msg = f"check raised: {e!r}"
+            if msg:
+                fails.append((source, name, msg))
+                log.warning("invariant FAIL: %s/%s: %s", source, name, msg)
+                if fail_fast:
+                    raise InvariantError(source, name, msg)
+        return fails
+
+    def list(self, source: Optional[str] = None):
+        """列出已注册的 source/name；source=None 时全部。"""
+        with self._lock:
+            if source is None:
+                return [(s, n) for s, m in self._checks.items() for n in m]
+            return [(source, n) for n in self._checks.get(source, {})]
+
+
+invariants = InvariantRegistry()  # 单例
+
+
+# === 默认 invariants ===
+def register_default_checks():
+    """注册 CodeBee 默认运行时断言。"""
+
+    def review_no_all_fail_zero(ctx):
+        """评审全部 0 分但 run 标 success → 不允许（已锁 test_quality_gates:62-75）。"""
+        if (ctx.get("review_scores")
+                and all(s == 0 for s in ctx["review_scores"])
+                and ctx.get("final_status") == "success"):
+            return "评审全部 0 分但 run 标 success"
+        return None
+
+    def step_count_consistency(ctx):
+        """实际 step 数与预期不一致。"""
+        if ctx.get("actual_steps") != ctx.get("expected_steps"):
+            return f"step count {ctx.get('actual_steps')} != expected {ctx.get('expected_steps')}"
+        return None
+
+    def ok_but_error_code(ctx):
+        """step 级：ok=True 却带非空 error_code —— 解析降级（如 codex 空输出
+        回落 stdout 尾部）被当成功，值得告警复核。"""
+        if ctx.get("ok") and ctx.get("error_code"):
+            return "step 标记成功但携带 error_code=%s（疑似降级输出）" % ctx["error_code"]
+        return None
+
+    invariants.register("pipeline", "review_no_all_fail_zero", review_no_all_fail_zero)
+    invariants.register("pipeline", "step_count_consistency", step_count_consistency)
     invariants.register("step", "ok_but_error_code", ok_but_error_code)

package/app/core/dispatch.py

@@ -1,173 +1,173 @@
-# -*- coding: utf-8 -*-
-"""统一调度评分：任务画像、CLI 亲和度与模型链排序。
-
-调用方先完成协议、启停、健康、密钥等硬约束过滤，再把可用候选交给这里评分；
-静态能力与近期用量台账只提供软信号，相同分数保持用户原顺序。
-"""
-from __future__ import annotations
-
-import math
-
-
-TYPE_DIMENSIONS = {
-    "direct": "reasoning",
-    "code": "coding",
-    "novel": "writing",
-    "serial_novel": "writing",
-    "article": "writing",
-    "video_script": "writing",
-    "doc": "writing",
-    "translation": "writing",
-    "rank_scan": "reasoning",
-    "research": "reasoning",
-    "speech": "writing",
-    "weekly_report": "writing",
-    "email": "writing",
-    "tech_proposal": "reasoning",
-    "resume": "writing",
-    "bid_doc": "writing",   # 标书：正文应答写作量大（合规判断由契约规则约束）
-    "zentao": "coding",
-}
-
-_KIND_AFFINITY = {
-    "coding": {"codex": 10, "aider": 8, "opencode": 7, "qwen": 6,
-               "claude": 5, "generic": 2},
-    "writing": {"claude": 10, "qwen": 7, "generic": 5, "codex": 3,
-                "opencode": 2, "aider": 0},
-    "reasoning": {"claude": 9, "codex": 8, "qwen": 6, "opencode": 4,
-                  "generic": 3, "aider": 1},
-    "vision": {"codex": 10, "claude": 8, "qwen": 5, "opencode": 2,
-               "generic": 1, "aider": 0},
-}
-
-_TIER_SCORE = {
-    "easy": {"budget": 18.0, "standard": 8.0, "premium": -6.0},
-    "default": {"budget": 2.0, "standard": 6.0, "premium": 5.0},
-    "hard": {"budget": -8.0, "standard": 4.0, "premium": 12.0},
-}
-
-
-def task_dimension(task_type, role=""):
-    """把预置任务与步骤角色归一为 writing/coding/reasoning/vision。"""
-    ttype = str(task_type or "").strip().lower()
-    role = str(role or "").strip().lower()
-    if ttype in ("writing", "coding", "reasoning", "vision"):
-        return ttype
-    if role in ("plan", "review", "critique", "selector", "qa") \
-            or "review" in role or "critique" in role:
-        return "reasoning"
-    return TYPE_DIMENSIONS.get(ttype, "reasoning")
-
-
-def agent_affinity(kind, task_type, role=""):
-    """CLI 类型对任务维度的温和偏好；只作加分，不覆盖健康与历史信号。"""
-    dim = task_dimension(task_type, role)
-    score = float((_KIND_AFFINITY.get(dim) or {}).get(kind, 0))
-    if role == "review" or "critique" in str(role or ""):
-        score += {"claude": 4, "codex": 3, "qwen": 2}.get(kind, 0)
-    return score, "%s 匹配 %+.1f" % (dim, score)
-
-
-def _model_meta(provider, model):
-    for item in (provider or {}).get("models") or []:
-        if isinstance(item, dict) and item.get("name") == model:
-            return item
-    return {}
-
-
-def _price_score(pricing, model, difficulty):
-    price = (pricing or {}).get(model) or {}
-    try:
-        # 输出通常比输入贵且更影响整步成本，按 2 倍权重估算。
-        blended = max(0.0, float(price.get("in") or 0.0)
-                      + 2.0 * float(price.get("out") or 0.0))
-    except (TypeError, ValueError):
-        return 0.0, "价格未知"
-    if blended <= 0:
-        return 0.0, "价格未知"
-    magnitude = max(0.0, math.log10(blended + 1.0))
-    score = -min(18.0, magnitude * (7.0 if difficulty == "easy" else 2.0))
-    return score, "估算价 %.3g（%+.1f）" % (blended, score)
-
-
-def _online_model_bonus(entry, task_type, role):
-    """把真实运行指标作为模型链软信号，硬约束仍由调用方负责。"""
-    try:
-        from . import usage
-        metrics = usage.routing_stats(
-            task_type=task_type, role=role,
-            provider=entry.get("provider_id") or "",
-            model=entry.get("model") or "")
-        samples = int(metrics.get("samples") or 0)
-        if not samples:
-            return 0.0, ""
-        rate = float(metrics.get("success_rate") or 0.0)
-        success_score = max(-6.0, min(6.0, (rate - 0.75) * 18.0))
-        p95 = max(0.0, float(metrics.get("p95_duration_s") or 0.0))
-        # 模型链也必须让真实延迟影响排序，不能让 P95 数分钟的链靠静态质量分
-        # 长期压在十几秒的健康链前面。
-        latency_score = -min(12.0, max(0.0, (p95 - 30.0) / 8.0))
-        cost = max(0.0, float(metrics.get("avg_cost_usd") or 0.0))
-        cost_score = -min(3.0, max(0.0, (cost - 0.01) / 0.01))
-        total = round(success_score + latency_score + cost_score, 2)
-        success_samples = int(metrics.get("success_samples") or samples)
-        reason = ("在线 %d/%d 验收成功（%+.1f），P95 %.1fs（%+.1f），均价 $%.4f（%+.1f）"
-                  % (int(metrics.get("successes") or 0), success_samples,
-                     success_score, p95, latency_score, cost, cost_score))
-        return total, reason
-    except Exception:
-        return 0.0, ""
-
-
-def score_model_entry(entry, providers, pricing, difficulty, task_type="", role=""):
-    """给已通过硬约束的模型链条目评分，返回 (score, explanation)。"""
-    provider = (providers or {}).get(entry.get("provider_id")) \
-        or entry.get("provider") or {}
-    model = entry.get("model") or ""
-    meta = _model_meta(provider, model)
-    try:
-        priority = max(1, int(meta.get("priority") or 99))
-    except (TypeError, ValueError):
-        priority = 99
-    quality = 0.0 if priority == 99 else max(-8.0, 20.0 - (priority - 1) * 4.0)
-    tier = meta.get("tier") or provider.get("tier") or "standard"
-    tier_score = (_TIER_SCORE.get(difficulty) or {}).get(tier, 0.0)
-    price_score, price_reason = _price_score(pricing, model, difficulty)
-    dim = task_dimension(task_type, role)
-    strengths = provider.get("strengths") if isinstance(provider.get("strengths"), list) else []
-    strength_score = 10.0 if dim in strengths else 0.0
-    if difficulty == "easy":
-        quality *= 0.25
-    elif difficulty != "hard":
-        # 普通任务兼顾质量、成本与能力匹配；是否真的重排由调用方决定，
-        # 因而手工链仍可保持原顺序，自动推荐则能使用这组平衡分。
-        quality *= 0.65
-    vision_score = 0.0
-    if dim == "vision":
-        vision_score = 24.0 if meta.get("image_in") else -24.0
-    online_score, online_reason = _online_model_bonus(entry, task_type, role)
-    total = quality + tier_score + price_score + strength_score + vision_score + online_score
-    reason = ("质量 %+.1f，档位 %s %+.1f，%s，能力 %s %+.1f%s%s"
-              % (quality, tier, tier_score, price_reason, dim,
-                 strength_score + vision_score,
-                 "，" if online_reason else "", online_reason))
-    return round(total, 2), reason
-
-
-def rank_model_entries(entries, providers, pricing, difficulty,
-                       task_type="", role="", force=False):
-    """稳定排序模型链并返回脱敏决策明细；default 难度保持人工顺序。"""
-    rows = []
-    for index, entry in enumerate(entries or []):
-        score, reason = score_model_entry(
-            entry, providers, pricing, difficulty, task_type, role)
-        rows.append((score, index, entry, reason))
-    if difficulty in ("easy", "hard") or force:
-        rows.sort(key=lambda row: (-row[0], row[1]))
-    ranked = [row[2] for row in rows]
-    decisions = [{"provider_id": row[2].get("provider_id") or "",
-                  "provider": (row[2].get("provider") or {}).get("name") or "",
-                  "model": row[2].get("model") or "",
-                  "score": row[0], "reason": row[3]}
-                 for row in rows]
-    return ranked, decisions
+# -*- coding: utf-8 -*-
+"""统一调度评分：任务画像、CLI 亲和度与模型链排序。
+
+调用方先完成协议、启停、健康、密钥等硬约束过滤，再把可用候选交给这里评分；
+静态能力与近期用量台账只提供软信号，相同分数保持用户原顺序。
+"""
+from __future__ import annotations
+
+import math
+
+
+TYPE_DIMENSIONS = {
+    "direct": "reasoning",
+    "code": "coding",
+    "novel": "writing",
+    "serial_novel": "writing",
+    "article": "writing",
+    "video_script": "writing",
+    "doc": "writing",
+    "translation": "writing",
+    "rank_scan": "reasoning",
+    "research": "reasoning",
+    "speech": "writing",
+    "weekly_report": "writing",
+    "email": "writing",
+    "tech_proposal": "reasoning",
+    "resume": "writing",
+    "bid_doc": "writing",   # 标书：正文应答写作量大（合规判断由契约规则约束）
+    "zentao": "coding",
+}
+
+_KIND_AFFINITY = {
+    "coding": {"codex": 10, "aider": 8, "opencode": 7, "qwen": 6,
+               "claude": 5, "generic": 2},
+    "writing": {"claude": 10, "qwen": 7, "generic": 5, "codex": 3,
+                "opencode": 2, "aider": 0},
+    "reasoning": {"claude": 9, "codex": 8, "qwen": 6, "opencode": 4,
+                  "generic": 3, "aider": 1},
+    "vision": {"codex": 10, "claude": 8, "qwen": 5, "opencode": 2,
+               "generic": 1, "aider": 0},
+}
+
+_TIER_SCORE = {
+    "easy": {"budget": 18.0, "standard": 8.0, "premium": -6.0},
+    "default": {"budget": 2.0, "standard": 6.0, "premium": 5.0},
+    "hard": {"budget": -8.0, "standard": 4.0, "premium": 12.0},
+}
+
+
+def task_dimension(task_type, role=""):
+    """把预置任务与步骤角色归一为 writing/coding/reasoning/vision。"""
+    ttype = str(task_type or "").strip().lower()
+    role = str(role or "").strip().lower()
+    if ttype in ("writing", "coding", "reasoning", "vision"):
+        return ttype
+    if role in ("plan", "review", "critique", "selector", "qa") \
+            or "review" in role or "critique" in role:
+        return "reasoning"
+    return TYPE_DIMENSIONS.get(ttype, "reasoning")
+
+
+def agent_affinity(kind, task_type, role=""):
+    """CLI 类型对任务维度的温和偏好；只作加分，不覆盖健康与历史信号。"""
+    dim = task_dimension(task_type, role)
+    score = float((_KIND_AFFINITY.get(dim) or {}).get(kind, 0))
+    if role == "review" or "critique" in str(role or ""):
+        score += {"claude": 4, "codex": 3, "qwen": 2}.get(kind, 0)
+    return score, "%s 匹配 %+.1f" % (dim, score)
+
+
+def _model_meta(provider, model):
+    for item in (provider or {}).get("models") or []:
+        if isinstance(item, dict) and item.get("name") == model:
+            return item
+    return {}
+
+
+def _price_score(pricing, model, difficulty):
+    price = (pricing or {}).get(model) or {}
+    try:
+        # 输出通常比输入贵且更影响整步成本，按 2 倍权重估算。
+        blended = max(0.0, float(price.get("in") or 0.0)
+                      + 2.0 * float(price.get("out") or 0.0))
+    except (TypeError, ValueError):
+        return 0.0, "价格未知"
+    if blended <= 0:
+        return 0.0, "价格未知"
+    magnitude = max(0.0, math.log10(blended + 1.0))
+    score = -min(18.0, magnitude * (7.0 if difficulty == "easy" else 2.0))
+    return score, "估算价 %.3g（%+.1f）" % (blended, score)
+
+
+def _online_model_bonus(entry, task_type, role):
+    """把真实运行指标作为模型链软信号，硬约束仍由调用方负责。"""
+    try:
+        from . import usage
+        metrics = usage.routing_stats(
+            task_type=task_type, role=role,
+            provider=entry.get("provider_id") or "",
+            model=entry.get("model") or "")
+        samples = int(metrics.get("samples") or 0)
+        if not samples:
+            return 0.0, ""
+        rate = float(metrics.get("success_rate") or 0.0)
+        success_score = max(-6.0, min(6.0, (rate - 0.75) * 18.0))
+        p95 = max(0.0, float(metrics.get("p95_duration_s") or 0.0))
+        # 模型链也必须让真实延迟影响排序，不能让 P95 数分钟的链靠静态质量分
+        # 长期压在十几秒的健康链前面。
+        latency_score = -min(12.0, max(0.0, (p95 - 30.0) / 8.0))
+        cost = max(0.0, float(metrics.get("avg_cost_usd") or 0.0))
+        cost_score = -min(3.0, max(0.0, (cost - 0.01) / 0.01))
+        total = round(success_score + latency_score + cost_score, 2)
+        success_samples = int(metrics.get("success_samples") or samples)
+        reason = ("在线 %d/%d 验收成功（%+.1f），P95 %.1fs（%+.1f），均价 $%.4f（%+.1f）"
+                  % (int(metrics.get("successes") or 0), success_samples,
+                     success_score, p95, latency_score, cost, cost_score))
+        return total, reason
+    except Exception:
+        return 0.0, ""
+
+
+def score_model_entry(entry, providers, pricing, difficulty, task_type="", role=""):
+    """给已通过硬约束的模型链条目评分，返回 (score, explanation)。"""
+    provider = (providers or {}).get(entry.get("provider_id")) \
+        or entry.get("provider") or {}
+    model = entry.get("model") or ""
+    meta = _model_meta(provider, model)
+    try:
+        priority = max(1, int(meta.get("priority") or 99))
+    except (TypeError, ValueError):
+        priority = 99
+    quality = 0.0 if priority == 99 else max(-8.0, 20.0 - (priority - 1) * 4.0)
+    tier = meta.get("tier") or provider.get("tier") or "standard"
+    tier_score = (_TIER_SCORE.get(difficulty) or {}).get(tier, 0.0)
+    price_score, price_reason = _price_score(pricing, model, difficulty)
+    dim = task_dimension(task_type, role)
+    strengths = provider.get("strengths") if isinstance(provider.get("strengths"), list) else []
+    strength_score = 10.0 if dim in strengths else 0.0
+    if difficulty == "easy":
+        quality *= 0.25
+    elif difficulty != "hard":
+        # 普通任务兼顾质量、成本与能力匹配；是否真的重排由调用方决定，
+        # 因而手工链仍可保持原顺序，自动推荐则能使用这组平衡分。
+        quality *= 0.65
+    vision_score = 0.0
+    if dim == "vision":
+        vision_score = 24.0 if meta.get("image_in") else -24.0
+    online_score, online_reason = _online_model_bonus(entry, task_type, role)
+    total = quality + tier_score + price_score + strength_score + vision_score + online_score
+    reason = ("质量 %+.1f，档位 %s %+.1f，%s，能力 %s %+.1f%s%s"
+              % (quality, tier, tier_score, price_reason, dim,
+                 strength_score + vision_score,
+                 "，" if online_reason else "", online_reason))
+    return round(total, 2), reason
+
+
+def rank_model_entries(entries, providers, pricing, difficulty,
+                       task_type="", role="", force=False):
+    """稳定排序模型链并返回脱敏决策明细；default 难度保持人工顺序。"""
+    rows = []
+    for index, entry in enumerate(entries or []):
+        score, reason = score_model_entry(
+            entry, providers, pricing, difficulty, task_type, role)
+        rows.append((score, index, entry, reason))
+    if difficulty in ("easy", "hard") or force:
+        rows.sort(key=lambda row: (-row[0], row[1]))
+    ranked = [row[2] for row in rows]
+    decisions = [{"provider_id": row[2].get("provider_id") or "",
+                  "provider": (row[2].get("provider") or {}).get("name") or "",
+                  "model": row[2].get("model") or "",
+                  "score": row[0], "reason": row[3]}
+                 for row in rows]
+    return ranked, decisions