xg-cli 1.0__py3-none-any.whl

xg/__init__.py

@@ -0,0 +1,3 @@
+"""XG-CLI: a commercial-grade Python Agent CLI."""
+
+__version__ = "1.0"

xg/__main__.py

@@ -0,0 +1,3 @@
+from xg.cli.app import main
+
+main()

xg/adaptive/__init__.py

@@ -0,0 +1,27 @@
+"""SmartRouter 自适应反馈子系统。
+
+负责把用户的隐式行为信号（interrupt / clarify / cmd_retry / short_high_tier）
+落盘到 ``~/.xg/adaptive/``，并在后续步骤（阶段三 C、阶段四）聚合校准。
+
+设计依据：XG-docs/smart-docs/states/phase-03-smart-router-adaptive-feedback.md
+数据目录沿用项目用户级配置约定（``~/.xg``），env 变量可覆盖。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# adaptive 数据目录的 env 覆盖键（可选，不设时用默认 ~/.xg/adaptive）
+ADAPTIVE_DIR_ENV = "XG_ADAPTIVE_DIR"
+
+
+def data_dir() -> Path:
+    """解析 adaptive 数据目录：env ``XG_ADAPTIVE_DIR`` 覆盖，默认 ``~/.xg/adaptive``。
+
+    仅做路径解析，不创建目录；目录懒创建由 store 在写入时处理。
+    """
+    override = os.environ.get(ADAPTIVE_DIR_ENV)
+    if override:
+        return Path(override)
+    return Path.home() / ".xg" / "adaptive"

xg/adaptive/calibrate.py

@@ -0,0 +1,191 @@
+"""校准聚合与应用（phase-03 步骤 C）。
+
+聚合 feedback.log 的隐式信号 → 每档偏置 per_class_bias 与全局阈值调整
+threshold_adjust，硬夹紧（±0.15 / ±0.1），单档加权样本不足 20 不校准。
+
+设计依据：ADAPTIVE_ROUTING §8.1（聚合公式）、§6.5（置信门应用）。
+与文档的两处有意落地决策（文档 §6.5 示意为 ML 路由的"回落默认档"，
+本项目为纯规则路由，按方向注释落地为对称升降一档）：
+1. 偏置方向：bias[t] < 0（该档 upgrade 信号多、偏弱）→ 置信门不通过的
+   边界输入升一档；bias[t] > 0（downgrade 多、偏强）→ 降一档。
+2. 置信门为对称双门：文档门公式只对升档方向生效（bias>0 时 gate_conf
+   恒不低于门），此处按"偏强档对称降档"补齐另一方向。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Sequence
+
+from .feedback import read_feedback
+from .store import atomic_write_json, calibration_path, read_json_safe
+
+# 档位名（与 xg.router.model_tiers.TIER_NAMES 一致；本地定义避免包环）
+TIER_NAMES: tuple[str, ...] = ("Basic", "Enhanced", "Superior", "Ultimate")
+
+MIN_SAMPLES_PER_TIER = 20   # 单档加权样本不足时不校准
+MAX_BIAS = 0.15             # per_class_bias 硬夹紧
+MAX_THRESHOLD_ADJUST = 0.1  # threshold_adjust 硬夹紧
+CONFIDENCE_BASE = 0.5       # 置信门基础阈值
+
+
+@dataclass(frozen=True)
+class Calibration:
+    """一次校准的聚合结果。bias/sample 按档位索引 0..3 排列。"""
+
+    bias: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)
+    threshold_adjust: float = 0.0
+    samples: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0)  # 加权样本量
+    total: float = 0.0
+
+    def bias_of(self, tier_idx: int) -> float:
+        return self.bias[tier_idx] if 0 <= tier_idx < 4 else 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "bias": dict(zip(TIER_NAMES, self.bias)),
+            "threshold_adjust": self.threshold_adjust,
+            "samples": dict(zip(TIER_NAMES, self.samples)),
+            "total": self.total,
+        }
+
+    @staticmethod
+    def from_dict(data: dict[str, Any] | None) -> Calibration:
+        """从持久化 JSON 恢复；结构异常时回退空校准（不抛错）。"""
+        if not isinstance(data, dict):
+            return Calibration()
+        try:
+            bias_map = data.get("bias") or {}
+            samples_map = data.get("samples") or {}
+            bias = tuple(float(bias_map.get(name, 0.0)) for name in TIER_NAMES)
+            samples = tuple(float(samples_map.get(name, 0.0)) for name in TIER_NAMES)
+            return Calibration(
+                bias=bias,  # type: ignore[arg-type]
+                threshold_adjust=float(data.get("threshold_adjust", 0.0)),
+                samples=samples,  # type: ignore[arg-type]
+                total=float(data.get("total", 0.0)),
+            )
+        except (TypeError, ValueError):
+            return Calibration()
+
+
+def _clamp(v: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, v))
+
+
+def aggregate(
+    records: Sequence[dict[str, Any]],
+    tier_names: Sequence[str] = TIER_NAMES,
+    min_samples: float = MIN_SAMPLES_PER_TIER,
+) -> Calibration:
+    """按 §8.1 公式聚合反馈记录。
+
+    up[t]/down[t] 为该档 upgrade/downgrade 信号的加权和（weight 求和）；
+    n[t] = up+down；n < min_samples → bias=0；否则
+    r[t]=(up-down)/n，bias[t]=clamp(-r[t]*0.15, ±0.15)。
+    全局 threshold_adjust=clamp(r_global*0.1, ±0.1)。
+    未知档位/信号方向的记录跳过不计。
+    """
+    names = list(tier_names)
+    up = [0.0] * len(names)
+    down = [0.0] * len(names)
+    for rec in records:
+        try:
+            tier = rec.get("model_tier")
+            if tier not in names:
+                continue
+            idx = names.index(tier)
+            weight = float(rec.get("weight", 0.0))
+            direction = rec.get("signal")
+        except (TypeError, ValueError):
+            continue
+        if direction == "upgrade":
+            up[idx] += weight
+        elif direction == "downgrade":
+            down[idx] += weight
+
+    bias: list[float] = []
+    samples: list[float] = []
+    for i in range(len(names)):
+        n = up[i] + down[i]
+        samples.append(n)
+        if n < min_samples:
+            bias.append(0.0)
+        else:
+            r = (up[i] - down[i]) / n
+            bias.append(_clamp(-r * MAX_BIAS, -MAX_BIAS, MAX_BIAS))
+
+    total = sum(up) + sum(down)
+    if total > 0:
+        r_global = (sum(up) - sum(down)) / total
+        threshold_adjust = _clamp(r_global * MAX_THRESHOLD_ADJUST,
+                                  -MAX_THRESHOLD_ADJUST, MAX_THRESHOLD_ADJUST)
+    else:
+        threshold_adjust = 0.0
+    return Calibration(
+        bias=tuple(bias),  # type: ignore[arg-type]
+        threshold_adjust=threshold_adjust,
+        samples=tuple(samples),  # type: ignore[arg-type]
+        total=total,
+    )
+
+
+def save_calibration(calibration: Calibration, path=None) -> None:
+    """原子写 calibration.json（tmp+os.replace）。"""
+    from .store import ensure_dir
+
+    p = path or calibration_path()
+    if path is None:
+        ensure_dir()
+    atomic_write_json(p, calibration.to_dict())
+
+
+def load_calibration(path=None) -> Calibration:
+    """读取 calibration.json；缺失/损坏回退空校准，绝不抛错。"""
+    return Calibration.from_dict(read_json_safe(path or calibration_path()))
+
+
+def recalibrate(log_path=None, cal_path=None) -> Calibration:
+    """读 feedback.log → 聚合 → 落盘 calibration.json → 返回结果。
+
+    无记录时返回空校准且不写盘（保证"删掉 ~/.xg/adaptive/ 即回到
+    第 1 期行为"的验收：不重建目录）。
+    """
+    records = read_feedback(log_path)
+    if not records:
+        return Calibration()
+    calibration = aggregate(records)
+    save_calibration(calibration, cal_path)
+    return calibration
+
+
+def apply_calibration(
+    tier_idx: int,
+    confidence: float,
+    hard_rule: bool,
+    calibration: Calibration,
+) -> int:
+    """置信门 + 档位偏置：返回校准后的档位索引。
+
+    只读纯函数，供 route() 在规则打分后、安全后处理前调用：
+    - 硬规则决策（confidence=1.0 的安全兜底）不受校准影响；
+    - bias == 0（样本不足或恰好均衡）不动；
+    - 对称双置信门（§6.5 的门公式按方向注释落地为双向）：
+      偏弱档（bias<0）：confidence + bias < 0.5 + threshold_adjust 时升一档；
+      偏强档（bias>0）：confidence - bias < 0.5 + threshold_adjust 时降一档。
+      即 |bias| 把置信门的适用窗口向两侧对称放宽，threshold_adjust 整体平移。
+    单次最多移动一档，夹在 0..3，不会跳档。
+    """
+    if hard_rule:
+        return tier_idx
+    bias = calibration.bias_of(tier_idx)
+    if bias == 0.0:
+        return tier_idx
+    gate = CONFIDENCE_BASE + calibration.threshold_adjust
+    if bias < 0:
+        if confidence + bias < gate:
+            return min(tier_idx + 1, 3)
+    else:
+        if confidence - bias < gate:
+            return max(tier_idx - 1, 0)
+    return tier_idx

xg/adaptive/feedback.py

@@ -0,0 +1,170 @@
+"""隐式反馈信号：枚举、事件结构、内存缓冲 + 定时 flush 到 feedback.log（JSONL）。
+
+设计依据：phase-03 步骤 A/B。
+- A 步骤交付骨架：SignalType 枚举、FeedbackEvent、FeedbackRecorder 的
+  内存缓冲与 flush、read_feedback 读取。
+- B 步骤才接入真实采集挂点；在此之前的 recorder 不会产生任何写入
+  （缓冲区为空时 flush 是 no-op）。
+
+信号清单（四类可采集 + file_revert 预留位，本期不采集 file_revert）：
+- interrupt     用户在回答中途 Ctrl+C（upgrade，weight 0.9）
+- clarify       上一轮后紧接追问/否定，且上轮档 ≤Superior（upgrade，weight 1.0）
+- cmd_retry     紧接重试类输入（upgrade，weight 0.6）
+- short_high_tier 简短闲聊却落到中高档（downgrade，weight 0.3）
+"""
+
+from __future__ import annotations
+
+import enum
+import hashlib
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from .store import append_jsonl, ensure_dir, feedback_log_path
+
+DEFAULT_FLUSH_INTERVAL = 10.0  # 秒，缓冲不足或未到周期时不下盘
+
+
+class SignalType(str, enum.Enum):
+    INTERRUPT = "interrupt"
+    CLARIFY = "clarify"
+    CMD_RETRY = "cmd_retry"
+    SHORT_HIGH_TIER = "short_high_tier"
+    FILE_REVERT = "file_revert"  # 预留占位：本期不采集
+
+
+# 各信号的 vector：upgrade=True 表示该升档，False 表示该降档；weight 表示可信度
+SIGNAL_META: dict[SignalType, dict[str, Any]] = {
+    SignalType.INTERRUPT: {"upgrade": True, "weight": 0.9},
+    SignalType.CLARIFY: {"upgrade": True, "weight": 1.0},
+    SignalType.CMD_RETRY: {"upgrade": True, "weight": 0.6},
+    SignalType.SHORT_HIGH_TIER: {"upgrade": False, "weight": 0.3},
+    SignalType.FILE_REVERT: {"upgrade": False, "weight": 0.5},  # 预留，未实现
+}
+
+
+def text_hash(text: str) -> str:
+    """对输入文本取短哈希，用于对账/去重，不存原文。"""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]
+
+
+@dataclass(frozen=True)
+class FeedbackEvent:
+    """一条反馈记录，对应 feedback.log 的一行 JSON。"""
+
+    source: SignalType
+    model_tier: str  # 触发信号时路出的档位名（如 "Superior"）
+    session: str  # 当前项目目录标识（可空，如无项目）
+    text_hash_val: str = ""
+    signal: str = ""  # 冗余命中类型名，聚合时用
+    weight: float = 0.0
+    ts: float = field(default_factory=time.time)
+    features: dict | None = None  # 当轮特征快照（第 4 期 A1 learned_rules 聚合用）
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "ts": self.ts,
+            "session": self.session,
+            "source": self.source.value,
+            "signal": "upgrade" if self.signal == "upgrade" else
+                      ("downgrade" if self.signal == "downgrade" else ""),
+            "text_hash": self.text_hash_val,
+            "model_tier": self.model_tier,
+            "weight": self.weight,
+        }
+        if self.features:  # 仅当存在时落盘，向后兼容（旧记录无此字段）
+            d["features"] = self.features
+        return d
+
+
+class FeedbackRecorder:
+    """内存缓冲 + 定时 flush 的反馈记录器。
+
+    用法：
+        rec = FeedbackRecorder(session="proj-abc")
+        rec.capture(SignalType.CLARIFY, model_tier="Superior")
+        # 定期调用 rec.flush()，或依赖 __del__ / 显式 flush
+    """
+
+    def __init__(
+        self,
+        session: str = "",
+        flush_interval: float = DEFAULT_FLUSH_INTERVAL,
+        log_path: Path | None = None,
+    ) -> None:
+        self.session = session
+        self.flush_interval = flush_interval
+        self._buffer: list[FeedbackEvent] = []
+        self._path = log_path or feedback_log_path()
+
+    def capture(
+        self,
+        source: SignalType,
+        model_tier: str,
+        text: str = "",
+        ts: float | None = None,
+        features: dict | None = None,
+    ) -> None:
+        """入内存缓冲（不立即写盘）。"""
+        meta = SIGNAL_META[source]
+        ev = FeedbackEvent(
+            source=source,
+            model_tier=model_tier,
+            session=self.session,
+            text_hash_val=text_hash(text) if text else "",
+            signal="upgrade" if meta["upgrade"] else "downgrade",
+            weight=meta["weight"],
+            ts=ts if ts is not None else time.time(),
+            features=features,
+        )
+        self._buffer.append(ev)
+
+    def flush(self, force: bool = False) -> int:
+        """把缓冲逐行追加写入 feedback.log，返回写入条数。
+
+        仅当 buffer 非空时写盘；返回值为本次追加的行数。
+        force 参数保留（语义：即便 buffered 条数不足也写），A 步骤无定时器，
+        调用方负责按 flush_interval 控制节奏。
+        """
+        if not self._buffer:
+            return 0
+        ensure_dir()
+        n = 0
+        for ev in self._buffer:
+            append_jsonl(self._path, ev.to_dict())
+            n += 1
+        self._buffer.clear()
+        return n
+
+    def count(self) -> int:
+        """当前缓冲区未 flush 的条数。"""
+        return len(self._buffer)
+
+
+def read_feedback(path: Path | None = None) -> list[dict[str, Any]]:
+    """读取 feedback.log 全部记录；文件不存在返回空列表，单行损坏跳过不抛错。"""
+    path = path or feedback_log_path()
+    if not path.exists():
+        return []
+    records: list[dict[str, Any]] = []
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    records.append(_json_loads(line))
+                except Exception:
+                    continue  # 单行损坏跳过，不拖垮整体
+    except OSError:
+        return []
+    return records
+
+
+def _json_loads(line: str) -> dict[str, Any]:
+    import json
+
+    return json.loads(line)

xg/adaptive/learned_rules.py

@@ -0,0 +1,284 @@
+"""自学习局部规则（phase-04 步骤 A1）。
+
+从 feedback.log 聚合"特征谓词 → 信号方向"的高频规律，生成受限规则
+（±1 档微调、置信度上限、支持度门槛），原子写 learned_rules.json。
+
+与 calibration（第 3 期）的区别：calibration 是**全局**档位偏置，
+对同一档位的所有输入一视同仁；learned_rules 是**局部**规则，只影响
+命中某个特征谓词（如"含 debug 词""文本 ≤60 字"）的输入。二者叠加生效，
+learned_rules 注入点在 postprocess 的 6 条规则之后、防降级之后。
+
+关键约（验收，见 phase-04 §7）：
+- 规则 action 恒为 ±1，不跳档；
+- 永不覆盖风险/闲聊/长上下文硬规则（由 postprocess 的 forced 标志保证）；
+- 单条规则 support < MIN_SUPPORT 不生成；
+- 多数派占比 < MIN_PRECISION 不生成（避免弱规则）；
+- 删除 learned_rules.json 即回到第 3 期行为。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from .feedback import read_feedback
+from .store import atomic_write_json, learned_rules_path, read_json_safe
+
+MIN_SUPPORT = 20        # 单候选谓词加权样本量下限（与校准样本门槛一致）
+MIN_PRECISION = 0.6     # 多数派占比下限（低于则不生成，避免弱规则）
+MAX_CONFIDENCE = 0.9    # 规则置信度上限（受限规则不允许满置信）
+MAX_RULES = 20          # 规则条数上限（按 support 降序保留，防爆炸）
+
+# 特殊数值特征集合：非关键词类别计数，单独判定谓词
+_SPECIAL_INT = ("has_attachment", "is_chatty", "question_mark", "num_code_blocks")
+
+# 简短文本长度上限（len_chars 谓词阈值，与 signals 的 SHORT_TEXT_CHARS 一致）
+_SHORT_CHARS = 60
+
+
+def _predicate_key(feature: str, op: str, value: float) -> tuple[str, str, float]:
+    """谓词的三元唯一标识（用于聚合去重）。"""
+    return (feature, op, value)
+
+
+def _candidates(f: dict) -> list[tuple[str, str, float]]:
+    """从一条特征的 features dict 提取其命中的候选谓词列表。
+
+    只描述"这一条满足什么条件"：
+    - num_<cat>_kw 关键词类别计数 >0 → num_<cat>_kw >= 1
+    - 特殊整型特征 ==1 → <feature> >= 1
+    - len_chars <= _SHORT_CHARS 且 >0 → len_chars <= 60
+
+    不 import router 类别名（避免 adaptive→router 包环），谓词由
+    features dict 里实际存在的键动态推导。
+    """
+    preds: list[tuple[str, str, float]] = []
+    for k, v in f.items():
+        if k == "len_chars":
+            if isinstance(v, (int, float)) and 0 < v <= _SHORT_CHARS:
+                preds.append((k, "<=", float(_SHORT_CHARS)))
+        elif k in _SPECIAL_INT:
+            if v == 1:
+                preds.append((k, ">=", 1.0))
+        elif k.startswith("num_") and k.endswith("_kw"):
+            if isinstance(v, (int, float)) and v >= 1:
+                preds.append((k, ">=", 1.0))
+    return preds
+
+
+@dataclass(frozen=True)
+class LearnedRule:
+    """一条自学习规则。predicate 为单个特征谓词。"""
+
+    feature: str
+    op: str            # ">=" 或 "<="
+    value: float
+    action: int        # +1（相关输入升档）或 -1（降档）
+    confidence: float  # 多数派占比，上限 MAX_CONFIDENCE
+    support: float     # 加权样本量
+
+    @property
+    def predicate(self) -> dict[str, float]:
+        return {f"{self.feature}{self.op}": self.value}
+
+    def matches(self, f: dict) -> bool:
+        """该记录的特征是否命中本条规则谓词。"""
+        v = f.get(self.feature)
+        if not isinstance(v, (int, float)):
+            return False
+        return (v >= self.value) if self.op == ">=" else (v <= self.value)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "predicate": self.predicate,
+            "action": self.action,
+            "confidence": self.confidence,
+            "support": self.support,
+        }
+
+
+@dataclass(frozen=True)
+class LearnedRules:
+    """规则集。rules 按 support 降序排列，apply 取第一条命中的 action。"""
+
+    rules: tuple[LearnedRule, ...] = ()
+
+    @property
+    def count(self) -> int:
+        return len(self.rules)
+
+    def apply(self, f: dict) -> int:
+        """返回命中规则的 action（+1/-1/0=无命中）。只取第一条（最确信）。
+
+        同一 features 可能命中多条规则，取 support 最高的一条，不叠加，
+        保证单次最多偏移一档。
+        """
+        for r in self.rules:
+            if r.matches(f):
+                return r.action
+        return 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"rules": [r.to_dict() for r in self.rules]}
+
+    @staticmethod
+    def from_dict(data: dict[str, Any] | None) -> LearnedRules:
+        """从持久化 JSON 恢复；结构异常回退空规则集（不抛错）。"""
+        if not isinstance(data, dict):
+            return LearnedRules()
+        try:
+            rules: list[LearnedRule] = []
+            for item in data.get("rules") or []:
+                pred = item.get("predicate") or {}
+                # predicate 格式 {"feature>=1": 1} 或 {"feature<=60": 60}
+                key = next(iter(pred)) if pred else None
+                value = float(pred.get(key, 0.0)) if key else 0.0
+                if not key:
+                    continue
+                op = "<=" if "<=" in key else (">=" if ">=" in key else "")
+                feature = key.split(op)[0] if op else ""
+                if not feature or op not in (">=", "<="):
+                    continue
+                # 归一化 value 为谓词里声明的值
+                value = float(pred.get(key, value))
+                rules.append(LearnedRule(
+                    feature=feature, op=op, value=value,
+                    action=int(item.get("action", 0)),
+                    confidence=float(item.get("confidence", 0.0)),
+                    support=float(item.get("support", 0.0)),
+                ))
+            rules.sort(key=lambda r: (-r.support, r.feature))
+            return LearnedRules(tuple(rules))  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            return LearnedRules()
+
+
+def aggregate(
+    records: Sequence[dict[str, Any]],
+    min_support: float = MIN_SUPPORT,
+    min_precision: float = MIN_PRECISION,
+    max_confidence: float = MAX_CONFIDENCE,
+    max_rules: int = MAX_RULES,
+) -> LearnedRules:
+    """聚合 feedback.log → 规则集。
+
+    对每条带 features 的记录，生成其命中的候选谓词，按"upgrade/downgrade
+    加权和"累计每个谓词的支持度；支持度过门槛且多数派占比清晰才生成规则。
+    旧记录（无 features 字段）跳过不计，保证向后兼容。
+    """
+    # 谓词唯一键 -> [up, down]
+    stats: dict[tuple[str, str, float], list[float]] = {}
+    for rec in records:
+        feats = rec.get("features")
+        if not isinstance(feats, dict) or not feats:
+            continue
+        direction = rec.get("signal")
+        if direction not in ("upgrade", "downgrade"):
+            continue
+        try:
+            weight = float(rec.get("weight", 0.0))
+        except (TypeError, ValueError):
+            continue
+        for pred in _candidates(feats):
+            bucket = stats.setdefault(pred, [0.0, 0.0])
+            if direction == "upgrade":
+                bucket[0] += weight
+            else:
+                bucket[1] += weight
+
+    rules: list[LearnedRule] = []
+    for (feature, op, value), (up, down) in stats.items():
+        n = up + down
+        if n < min_support:
+            continue
+        # 多数派占比；up > down -> 升规则，down > up -> 降规则
+        if up > down:
+            prec = up / n
+            action = 1
+        elif down > up:
+            prec = down / n
+            action = -1
+        else:
+            continue  # 完全对半，无方向
+        if prec < min_precision:
+            continue
+        rules.append(LearnedRule(
+            feature=feature, op=op, value=value, action=action,
+            confidence=min(prec, max_confidence), support=n,
+        ))
+    rules.sort(key=lambda r: (-r.support, r.feature))
+    return LearnedRules(tuple(rules[:max_rules]))  # type: ignore[arg-type]
+
+
+def save_learned_rules(rules: LearnedRules, path=None) -> None:
+    """原子写 learned_rules.json。空规则集也写（清空语义）。"""
+    from .store import ensure_dir
+
+    p = path or learned_rules_path()
+    if path is None:
+        ensure_dir()
+    atomic_write_json(p, rules.to_dict())
+
+
+def load_learned_rules(path=None) -> LearnedRules:
+    """读取 learned_rules.json；缺失/损坏回退空规则集，绝不抛错。"""
+    return LearnedRules.from_dict(read_json_safe(path or learned_rules_path()))
+
+
+def re_learn(log_path=None, rules_path=None) -> LearnedRules:
+    """读 feedback.log → 聚合 → 落盘 learned_rules.json → 返回结果。
+
+    无记录时返回空规则集且不写盘（沿用第 3 期"删掉 ~/.xg/adaptive/ 即
+    回到纯规则行为"的验收：不重建目录）。
+    """
+    records = read_feedback(log_path)
+    if not records:
+        return LearnedRules()
+    rules = aggregate(records)
+    save_learned_rules(rules, rules_path)
+    return rules
+
+
+def rule_hit_stats(
+    records: Sequence[dict[str, Any]], rules: LearnedRules,
+) -> dict[str, Any]:
+    """统计规则集在 feedback.log 上的命中情况，供 `/smartRouter status` 展示。
+
+    返回 {"rule_count", "sample_records", "hit_records", "per_rule"}：
+    - rule_count：规则条数；
+    - sample_records：带 features 的可命中样本记录数；
+    - hit_records：命中至少一条规则的样本记录数；
+    - per_rule：每条规则的 predicate/action/confidence/support 及命中次数
+      （一条记录可能命中多条，各自累计）。
+    """
+    per: dict[int, int] = {id(r): 0 for r in rules.rules}
+    sample_records = 0
+    hit_records = 0
+    for rec in records:
+        feats = rec.get("features")
+        if not isinstance(feats, dict) or not feats:
+            continue
+        sample_records += 1
+        hit_any = False
+        for r in rules.rules:
+            if r.matches(feats):
+                per[id(r)] += 1
+                hit_any = True
+        if hit_any:
+            hit_records += 1
+    per_rule = [
+        {
+            "predicate": r.predicate,
+            "action": r.action,
+            "confidence": r.confidence,
+            "support": r.support,
+            "hits": per[id(r)],
+        }
+        for r in rules.rules
+    ]
+    return {
+        "rule_count": rules.count,
+        "sample_records": sample_records,
+        "hit_records": hit_records,
+        "per_rule": per_rule,
+    }