foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/core/failure_policy.py

@@ -0,0 +1,142 @@
+"""失败策略表:把「工具失败了」映射成「下一步做什么」。
+
+病根:工具轮的失败此前只有两种归宿——原样回注给模型,或直接丢掉。于是「超时了该重试
+一次还是放弃」「没配搜索服务该降级还是换参数」全靠模型临场发挥;而模型最常见的反应是
+**换个说法把没做成的事说成做成了**(静默假成功)。这张表把那类决策从模型手里拿走:
+错误特征 → 动作,查表即得,和 recover 层「由策略表决定,不猜」同一原则。
+
+设计取舍:
+- **按文本特征分类,不按异常类型**。工具跑在守护线程里(见 agents/mixins/tool_exec),
+  跨线程、跨工具之后剩下的只有一句回注文本;异常类型在这里已经丢失。
+- **只有只读工具才自动重试**。写/发送/支付类动作重试一次 = 可能重复扣款、重复发消息;
+  这类一律交人。
+- 分类是**启发式**的,因此:匹配不到 → 当作未知失败(不重试、交人),绝不乐观当成功。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+OK = "ok"
+TIMEOUT = "timeout"
+TRANSIENT = "transient"
+NOT_CONFIGURED = "not_configured"
+EMPTY = "empty"
+INVALID_ARGS = "invalid_args"
+DENIED = "denied"
+NEEDS_HUMAN = "needs_human"
+EXCEPTION = "exception"
+UNKNOWN = "unknown"
+
+NONE = "none"
+RETRY = "retry"
+REPARAM = "reparam"
+DEGRADE = "degrade"
+HAND_TO_HUMAN = "hand_to_human"
+STOP = "stop"
+
+_RULES: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (DENIED, ("已被策略禁用", "被权限策略拒绝", "未知工具")),
+    (NEEDS_HUMAN, ("需确认的动作", "需要你确认", "请用户确认", "只能由你亲自确认")),
+    (INVALID_ARGS, ("入参不合法", "缺少必填", "类型应为")),
+    (TIMEOUT, ("超过", "超时", "timed out", "timeout")),
+    (NOT_CONFIGURED, ("未配置", "not configured", "未设置", "缺少 api", "缺少 key")),
+    (EMPTY, ("未返回结果", "未召回到", "no result", "未命中", "没有找到")),
+    (TRANSIENT, ("网络", "连接失败", "connection", "502", "503", "504", "429", "rate limit")),
+    (EXCEPTION, ("执行异常",)),
+)
+
+_ACTIONS: dict[str, tuple[str, bool, str]] = {
+    TIMEOUT: (RETRY, True,
+              "这一步超时未完成,已自动重试一次仍有问题。请如实说明这一步没做成,不要编造结果。"),
+    TRANSIENT: (RETRY, True,
+                "这次失败像是临时的网络/服务问题,已自动重试一次。若仍失败,如实说明当前无法获取。"),
+    EXCEPTION: (RETRY, True,
+                "工具内部异常,已自动重试一次。若仍失败,如实说明该步骤未能执行。"),
+    EMPTY: (REPARAM, False,
+            "调用成功但没有拿到内容。可以换一个更具体的查询词或放宽条件再试一次;"
+            "仍为空就如实回答「没有查到」,不要用常识补全成确定结论。"),
+    INVALID_ARGS: (REPARAM, False,
+                   "参数不合法,这一步没有执行。请按工具声明修正参数后再调用;"
+                   "不要把失败当成已完成。"),
+    NOT_CONFIGURED: (DEGRADE, False,
+                     "该能力当前未配置(服务/密钥缺失),不是暂时故障,重试无用。"
+                     "请告知用户这项能力暂不可用,不要假装查到了。"),
+    NEEDS_HUMAN: (HAND_TO_HUMAN, False,
+                  "这是需要用户确认的动作,我没有执行。把要做的操作拟成草稿交用户确认。"),
+    DENIED: (STOP, False, "该工具被策略禁止,不要换个名字或换个参数再试。"),
+    UNKNOWN: (HAND_TO_HUMAN, False,
+              "这一步的结果不可信(无法判定成功还是失败)。不要向用户断言它已完成。"),
+    OK: (NONE, False, ""),
+}
+
+
+@dataclass(frozen=True)
+class Decision:
+    """一次失败判定:类型 → 动作 + 给模型看的提示。"""
+
+    kind: str
+    action: str
+    retryable: bool
+    hint: str
+
+    @property
+    def is_ok(self) -> bool:
+        return self.kind == OK
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "action": self.action,
+                "retryable": self.retryable, "hint": self.hint}
+
+
+_FAILURE_MARKERS = ("执行异常", "入参不合法", "被权限策略拒绝", "缺少必填")
+
+
+def looks_like_failure(text: str) -> bool:
+    t = (text or "").strip()
+    if not t:
+        return True
+    return t.startswith("(") or any(m in t for m in _FAILURE_MARKERS)
+
+
+def classify(text: str) -> str:
+    """把回注文本归类:``ok`` / 具体失败类型 / ``unknown``(认不出来,保守交人)。"""
+    t = (text or "").strip()
+    if not t:
+        return UNKNOWN
+    if not looks_like_failure(t):
+        return OK
+    low = t.lower()
+    for kind, needles in _RULES:
+        if any(n in low for n in needles):
+            return kind
+    return UNKNOWN
+
+
+def decide(text: str, tool: str = "", capability: dict | None = None,
+           attempt: int = 1, max_attempts: int = 2) -> Decision:
+    """查表得到动作。
+
+    ``attempt`` 是**已尝试次数**(第一次调用传 1)。可重试类型在 ``attempt < max_attempts``
+    时给 ``retry``;只读工具才真的会被重试 —— 这里只判定,是否执行由调用方决定,
+    因为"这个工具能不能安全重复执行"属于能力声明(capability),不是文本语义。
+    """
+    kind = classify(text)
+    action, retryable, hint = _ACTIONS.get(kind, _ACTIONS[UNKNOWN])
+    read_only = bool((capability or {}).get("read_only"))
+    if action == RETRY and (not read_only or attempt >= max_attempts):
+        action = HAND_TO_HUMAN
+        if not read_only:
+            hint = ("这一步有副作用,重试可能重复执行,因此没有自动重试。"
+                    "请如实说明它没有完成。")
+    return Decision(kind=kind, action=action, retryable=retryable, hint=hint)
+
+
+def annotate(text: str, decision: Decision) -> str:
+    """把动作提示拼到回注文本后面(仅失败时;成功文本一个字都不改)。
+
+    为什么要拼在文本里而不是另走一路:回注给模型的是**纯文本**,多一条通道意味着
+    模型可能只读到其中一条;拼在末尾让"结果"和"该怎么对待这个结果"不可分割。
+    """
+    if decision.is_ok or not decision.hint:
+        return text or ""
+    return f"{text or ''}\n[执行策略] {decision.hint}"

package/python/foxclaw/core/gateway.py

@@ -0,0 +1,81 @@
+"""
+统一 API 网关限流(gateway.py)
+
+把散落在各处(MCP、/chat/stream)的单点限流收敛成一层**统一网关**:
+  · per-client 令牌桶——突发限流(每分钟额度,允许瞬时打满桶)
+  · 固定窗口配额——持续限流(每小时总额度)
+  · 空闲客户端淘汰——防攻击者轮换 key/IP 把 per-client 字典撑爆内存(与 metrics「unmatched」同款教训)
+
+client 身份 = X-API-Key(有则)否则来源 IP。线程安全(单锁,check 内无 await/无阻塞 I/O)。
+默认宽松:本地单用户近乎无感;对外暴露时经环境变量收紧。
+"""
+from __future__ import annotations
+
+import time
+import threading
+
+
+class Gateway:
+    def __init__(self, rate_per_min: int = 600, quota_per_hour: int = 20000,
+                 max_clients: int = 4096):
+        self.rate = max(1, int(rate_per_min))
+        self.capacity = float(self.rate)
+        self.refill = self.capacity / 60.0
+        self.quota = max(1, int(quota_per_hour))
+        self.max_clients = max(64, int(max_clients))
+        self._lock = threading.Lock()
+        self._buckets: dict = {}
+        self._quota: dict = {}
+        self._seen: dict = {}
+        self.rejected = 0
+
+    def check(self, client: str):
+        """判定一次请求。返回 (allowed: bool, retry_after: int, reason: str)。
+        reason ∈ {'', 'rate', 'quota'}。allowed=False 时 retry_after 为建议重试秒数。"""
+        now = time.time()
+        with self._lock:
+            self._evict_locked(now)
+            self._seen[client] = now
+
+            q = self._quota.get(client)
+            if q is None or now - q[1] >= 3600.0:
+                q = [0, now]
+                self._quota[client] = q
+            if q[0] >= self.quota:
+                self.rejected += 1
+                return False, int(3600.0 - (now - q[1])) + 1, "quota"
+
+            b = self._buckets.get(client)
+            if b is None:
+                b = [self.capacity, now]
+                self._buckets[client] = b
+            b[0] = min(self.capacity, b[0] + (now - b[1]) * self.refill)
+            b[1] = now
+            if b[0] < 1.0:
+                self.rejected += 1
+                return False, int((1.0 - b[0]) / self.refill) + 1, "rate"
+
+            b[0] -= 1.0
+            q[0] += 1
+            return True, 0, ""
+
+    def _evict_locked(self, now: float):
+        """超过 max_clients 时淘汰最久未见的一批(降到 ~90%)。必须在锁内调用。"""
+        if len(self._seen) <= self.max_clients:
+            return
+        n_drop = len(self._seen) - self.max_clients + max(1, self.max_clients // 10)
+        victims = sorted(self._seen.items(), key=lambda kv: kv[1])[:n_drop]
+        for c, _ in victims:
+            self._seen.pop(c, None)
+            self._buckets.pop(c, None)
+            self._quota.pop(c, None)
+
+    def stats(self) -> dict:
+        with self._lock:
+            return {
+                "tracked_clients": len(self._seen),
+                "rate_per_min": self.rate,
+                "quota_per_hour": self.quota,
+                "max_clients": self.max_clients,
+                "rejected_total": self.rejected,
+            }

package/python/foxclaw/core/governance_audit.py

@@ -0,0 +1,171 @@
+"""
+治理决策统一审计(P1-2 基础 / P3-4 decision_id)。
+
+系统的裁决点分散在四层,各说各话:
+  · Harness(推理漂移:语义/工具/范围)—— emit harness_pass/warn/block
+  · Permission(动作权限:deny>ask>allow 四阶段)—— 经 PolicyGate emit policy.decision.*
+  · Orchestrator(跨 Agent 委派裁决)—— 原本**无任何事件**
+  · SkillAdapter(执行终态:成功/失败/断路器/封杀)—— 原本**无任何事件**
+
+本模块提供一条**统一治理审计流**,不改变任何裁决行为,只做记录:
+
+  事件通道:脊柱广播 `governance.decision`(不在 WS 静音列表 → 前端可见)
+  落盘通道:{data_dir}/audit/governance.jsonl(环形缓冲之外的持久样本)
+
+每条记录带 **decision_id**(本次裁决的唯一 ID)与 **correlation_id**(跨层关联键):
+  · permission 裁决生成 decision_id → 同一 SkillAdapter.invoke 的执行审计用它做
+    correlation_id ⇒ 「谁批准的这个动作、执行结果如何」可join
+  · Orchestrator 用 req.id 做 correlation_id ⇒ 多轮协商的历次裁决串成一条链
+
+verdict 词汇(两类,查询时注意区分):
+  · 裁决类:allow / warn / deny / confirm(与 PolicyGate 归一词汇一致)
+  · 执行类:success / failed(SkillAdapter 的执行终态)
+
+记录策略(防止高频正常路径淹没审计流):
+  · harness / permission 层只记**非 allow**(warn/deny/confirm)——PASS 是每步推理的常态
+  · orchestration 层全量(跨 Agent 委派本来就低频)
+  · skill 层全量(执行审计是 P2-0 的核心价值;一次任务仅个位数调用)
+
+与 shared_write 审计(audit_sink.py)的关系:那是「记忆写入准入」专项,这是「治理裁决」
+总流;两者并存、各自落盘,互不替代。
+
+开关:FOXCLAW_GOVERNANCE_AUDIT=0 关闭(默认开;每条 <500 字节,量级可忽略)。
+审计一律 fail-safe:任何记录异常都静默吞掉,绝不影响裁决主流程(与闸门同约束)。
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import audit_chain
+
+ENV_SWITCH = "FOXCLAW_GOVERNANCE_AUDIT"
+TOPIC = "governance.decision"
+
+VERDICTS_RULING = ("allow", "warn", "deny", "confirm")
+VERDICTS_EXECUTION = ("success", "failed")
+
+LAYERS = ("harness", "permission", "orchestration", "skill")
+
+
+def new_decision_id() -> str:
+    """生成一次治理裁决的唯一 ID。短 hex 够用(单机审计,非全局唯一约束)。"""
+    return f"dec_{uuid.uuid4().hex[:12]}"
+
+
+class GovernanceAuditor:
+    """统一治理审计记录器:发脊柱事件 + 可选 JSONL 落盘。
+
+    线程安全:记录可能来自任意 Agent 的任意线程(事件脊柱 handler 在锁外执行,
+    但 invoke/route_request 本身可被并发调用)——落盘用进程内锁串行。
+    多进程部署(FOXCLAW_ALLOW_INSECURE 的多 worker)不在本机开发场景内,从略。
+    """
+
+    def __init__(self, spine=None, sink_path: Path | None = None):
+        self._spine = spine
+        self._path = Path(sink_path) if sink_path else None
+        self._lock = threading.Lock()
+        self._last_hash: str | None = None
+
+    @property
+    def path(self) -> Path | None:
+        return self._path
+
+    def record(self, *, layer: str, actor: str, action: str, verdict: str,
+               reason: str = "", detail: dict | None = None,
+               decision_id: str | None = None,
+               correlation_id: str | None = None) -> str:
+        """记录一条治理裁决/执行审计,返回 decision_id(显式传入则原样返回)。
+
+        全参数关键字化:调用点必须写明每个字段是什么,避免位置参数错位造成
+        「审计记错层」这种难以察觉的污染。
+        """
+        did = decision_id or new_decision_id()
+        rec = {
+            "decision_id": did,
+            "correlation_id": correlation_id or "",
+            "layer": layer,
+            "actor": actor,
+            "action": action,
+            "verdict": verdict,
+            "reason": (reason or "")[:200],
+            "detail": detail or {},
+            "ts": datetime.now(timezone.utc).isoformat(),
+        }
+        self._emit(rec)
+        self._persist(rec)
+        return did
+
+
+    def _emit(self, rec: dict) -> None:
+        if self._spine is None:
+            return
+        try:
+            self._spine.publish(TOPIC, dict(rec), source="governance_audit",
+                                correlation_id=rec["correlation_id"] or None)
+        except Exception:
+            pass
+
+    def _persist(self, rec: dict) -> None:
+        """落盘时接哈希链(见 core/audit_chain.py):改一行/删中间一行都能被 verify 发现。
+
+        事件通道仍发**不带链字段**的原始 rec —— 前端只关心裁决内容,而链是落盘证据;
+        两个通道内容不同是有意的,别拿 WS 事件当真伪校验的依据。
+        """
+        if self._path is None:
+            return
+        try:
+            with self._lock:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                if self._last_hash is None:
+                    self._last_hash = audit_chain.tail_hash(self._path)
+                chained = audit_chain.link(rec, self._last_hash)
+                with open(self._path, "a", encoding="utf-8") as f:
+                    f.write(json.dumps(chained, ensure_ascii=False) + "\n")
+                self._last_hash = chained["hash"]
+        except Exception:
+            pass
+
+    def read(self, limit: int = 200) -> list:
+        """读落盘记录(新→旧),坏行跳过。供工具/测试/未来 API 用。"""
+        if self._path is None or not self._path.exists():
+            return []
+        out = []
+        try:
+            with open(self._path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        out.append(json.loads(line))
+                    except Exception:
+                        continue
+        except Exception:
+            return []
+        return out[-limit:][::-1]
+
+    def verify(self) -> tuple:
+        """校验落盘链 → (ok, 条数, 问题)。无落盘时视为通过。
+
+        用法:`python -m foxclaw.core.audit_chain {data_dir}/audit/governance.jsonl`。
+        """
+        if self._path is None:
+            return True, 0, ""
+        return audit_chain.verify(self._path)
+
+
+def attach(spine, data_dir) -> GovernanceAuditor | None:
+    """装配工厂:FOXCLAW_GOVERNANCE_AUDIT=0 时返回 None(各层按 None 跳过记录)。
+
+    落盘到 {data_dir}/audit/governance.jsonl(该目录已被 .gitignore 覆盖)。
+    spine 为 None 时仍可落盘(standalone/测试场景),只是没有事件通道。
+    """
+    if os.environ.get(ENV_SWITCH, "1") == "0":
+        return None
+    sink = Path(data_dir) / "audit" / "governance.jsonl" if data_dir else None
+    return GovernanceAuditor(spine=spine, sink_path=sink)

package/python/foxclaw/core/idempotency.py

@@ -0,0 +1,282 @@
+"""
+Foxclaw Core — 幂等守卫 (Idempotency Guard)
+
+借鉴 OpenClaw 的幂等原理,适配 Foxclaw。核心思想:
+  给每个"只应发生一次"的操作算一个稳定 key,执行前查重——
+  记录过就跳过(返回上次结果),没记录才执行并落记录。
+
+为什么需要:消息平台天生会重发(网络抖动、平台重试、轮询游标边界),
+没有幂等,用户会收到重复回复、同一操作被记两次。
+
+设计要点:
+  · key 稳定:同一逻辑操作每次算出同一 key(版本+域+标识)
+  · 跨重启:可选落盘,进程重启后仍能识别"这条处理过了"
+  · 不膨胀:TTL 过期清理 + 容量上限(LRU 淘汰)
+  · 并发安全:RLock 保护
+"""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+
+
+@dataclass
+class _Record:
+    key: str
+    created: float
+    result: dict = field(default_factory=dict)
+
+
+def make_key(domain: str, *parts: str, version: str = "v1") -> str:
+    """构造稳定幂等 key:version:domain:hash(parts)。
+
+    domain 区分用途(message/dispatch/reply...),parts 是业务标识
+    (渠道+消息ID、会话+步骤号等)。相同输入永远得到相同 key。
+    """
+    raw = "|".join(str(p) for p in parts)
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:20]
+    return f"{version}:{domain}:{digest}"
+
+
+class IdempotencyGuard:
+    """幂等守卫。check_and_mark 是核心:原子地"查重 + 标记"。
+
+    【P2-3】持久化从"全量快照"改为"追加日志 + 定期 compact":
+      · 每次操作(mark/check_and_mark/update_result/容量淘汰)只追加一行 JSONL(O(1) 写);
+      · 每 compact_every 次操作(或启动加载后)compact 成快照并清空日志;
+      · 启动时读快照 + 回放追加日志(兼容旧的纯快照格式:无日志可回放,自然兼容);
+      · 持久化失败不再静默:计数进 stats(),有 spine 时发 idempotency.persist_failed 事件。
+    """
+
+    def __init__(self, ttl_seconds: float = 3600, max_size: int = 10000,
+                 persist_path: str | None = None, spine=None,
+                 compact_every: int = 1000):
+        self.ttl = ttl_seconds
+        self.max_size = max_size
+        self.persist_path = persist_path
+        self._store: dict[str, _Record] = {}
+        self._lock = threading.RLock()
+        self._spine = spine
+        self._log_path = (persist_path + ".log") if persist_path else None
+        self._compact_every = compact_every
+        self._ops_since_compact = 0
+        self._persist_failures = 0
+        self._compact_lock = threading.Lock()
+        if persist_path:
+            self._load()
+
+    def seen(self, key: str) -> bool:
+        """该 key 是否已记录(且未过期)。"""
+        with self._lock:
+            self._evict_expired()
+            return key in self._store
+
+    def get_result(self, key: str) -> dict | None:
+        """取上次执行结果(用于重发时原样返回,避免重复执行副作用)。"""
+        with self._lock:
+            rec = self._store.get(key)
+            return dict(rec.result) if rec else None
+
+    def mark(self, key: str, result: dict | None = None):
+        """标记 key 已执行,记录结果。"""
+        with self._lock:
+            self._store[key] = _Record(key=key, created=time.time(),
+                                       result=dict(result or {}))
+            self._enforce_capacity()
+            self._persist_op("mark", key, created=self._store[key].created,
+                             result=self._store[key].result)
+            need_compact = self._ops_since_compact >= self._compact_every
+        if need_compact:
+            self._try_compact()
+
+    def check_and_mark(self, key: str, result: dict | None = None) -> bool:
+        """原子操作:若 key 未见过 → 标记并返回 True(应执行);
+        若已见过 → 返回 False(应跳过)。
+
+        这是防并发重复的关键:查重和标记在同一把锁里完成,
+        避免"两个重发同时查到未记录、都去执行"。
+        """
+        with self._lock:
+            self._evict_expired()
+            if key in self._store:
+                return False
+            self._store[key] = _Record(key=key, created=time.time(),
+                                       result=dict(result or {}))
+            self._enforce_capacity()
+            self._persist_op("mark", key, created=self._store[key].created,
+                             result=self._store[key].result)
+            need_compact = self._ops_since_compact >= self._compact_every
+        if need_compact:
+            self._try_compact()
+        return True
+
+    def update_result(self, key: str, result: dict):
+        """补写结果(check_and_mark 先占位、执行完再回填结果时用)。"""
+        with self._lock:
+            rec = self._store.get(key)
+            if rec:
+                rec.result = dict(result or {})
+                self._persist_op("update", key, result=rec.result)
+                need_compact = self._ops_since_compact >= self._compact_every
+            else:
+                need_compact = False
+        if need_compact:
+            self._try_compact()
+
+    def _evict_expired(self):
+        if self.ttl <= 0:
+            return
+        now = time.time()
+        expired = [k for k, r in self._store.items() if now - r.created > self.ttl]
+        for k in expired:
+            del self._store[k]
+
+    def _enforce_capacity(self):
+        if len(self._store) <= self.max_size:
+            return
+        items = sorted(self._store.items(), key=lambda kv: kv[1].created)
+        for k, _ in items[: len(self._store) - self.max_size]:
+            del self._store[k]
+            self._persist_op("delete", k)
+
+    def _persist_op(self, event: str, key: str, **fields):
+        """【P2-3】追加一条日志(O(1) 写,不写全量)。锁内调用(append 很快,
+        且在锁内可避免并发写同一文件交错)。失败计数 + 发事件,不影响主流程。"""
+        if not self._log_path:
+            return
+        try:
+            entry = {"event": event, "key": key, "ts": time.time(), **fields}
+            with open(self._log_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+            self._ops_since_compact += 1
+        except Exception:
+            self._persist_failures += 1
+            self._emit_persist_failed()
+
+    def _emit_persist_failed(self):
+        """【P2-3】持久化失败发事件(有 spine 时),失败本身绝不再抛。"""
+        if self._spine is None:
+            return
+        try:
+            self._spine.publish("idempotency.persist_failed", {
+                "failures": self._persist_failures,
+                "log_path": self._log_path,
+            }, source="idempotency")
+        except Exception:
+            pass
+
+    def _try_compact(self):
+        """【P2-3】触发 compact,**全量写盘在主锁外**:
+        主锁内只做两件快事——日志轮转(rename,新 append 自动开新文件)和内存快照拷贝;
+        慢的全量 JSON 写盘在锁外做,不阻塞并发 mark/check。
+        独立 _compact_lock 非阻塞抢占:抢不到说明另一线程正在 compact,直接跳过。
+        正确性:轮转后新 append 进新 .log,写快照+删轮转本不影响它们,无丢失窗口。"""
+        if not self.persist_path:
+            return
+        if not self._compact_lock.acquire(blocking=False):
+            return
+        try:
+            with self._lock:
+                rotated = None
+                if self._log_path and os.path.exists(self._log_path):
+                    rotated = self._log_path + ".rot"
+                    os.replace(self._log_path, rotated)
+                now = time.time()
+                snapshot = {k: {"created": r.created, "result": r.result}
+                            for k, r in self._store.items()
+                            if self.ttl <= 0 or now - r.created <= self.ttl}
+                self._ops_since_compact = 0
+            tmp = self.persist_path + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as f:
+                json.dump(snapshot, f, ensure_ascii=False)
+            os.replace(tmp, self.persist_path)
+            if rotated and os.path.exists(rotated):
+                os.remove(rotated)
+        except Exception:
+            with self._lock:
+                self._persist_failures += 1
+                self._emit_persist_failed()
+        finally:
+            self._compact_lock.release()
+
+    def _compact(self):
+        """启动加载后的同步 compact(单线程上下文,直接全量写)。"""
+        if not self.persist_path:
+            return
+        try:
+            now = time.time()
+            data = {k: {"created": r.created, "result": r.result}
+                    for k, r in self._store.items()
+                    if self.ttl <= 0 or now - r.created <= self.ttl}
+            tmp = self.persist_path + ".tmp"
+            with open(tmp, "w", encoding="utf-8") as f:
+                json.dump(data, f, ensure_ascii=False)
+            os.replace(tmp, self.persist_path)
+            if self._log_path and os.path.exists(self._log_path):
+                os.remove(self._log_path)
+            self._ops_since_compact = 0
+        except Exception:
+            self._persist_failures += 1
+            self._emit_persist_failed()
+
+    def _apply_log_event(self, ev: dict, now: float):
+        """回放一条追加日志事件。"""
+        kind = ev.get("event")
+        key = ev.get("key")
+        if not key:
+            return
+        if kind == "mark":
+            created = ev.get("created", now)
+            if self.ttl <= 0 or now - created <= self.ttl:
+                self._store[key] = _Record(key=key, created=created,
+                                           result=ev.get("result", {}))
+        elif kind == "update":
+            rec = self._store.get(key)
+            if rec:
+                rec.result = ev.get("result", {})
+        elif kind == "delete":
+            self._store.pop(key, None)
+
+    def _load(self):
+        """读全量快照 + 回放追加日志。兼容旧的纯快照格式(无日志,回放为空)。
+        仅当真有日志被回放时才 compact 一次(合并进快照)——否则每次构造都白写
+        一份全量快照,失去"追加日志 O(1)"的意义。"""
+        try:
+            now = time.time()
+            snapshot = self.persist_path
+            if snapshot is not None and os.path.exists(snapshot):
+                with open(snapshot, encoding="utf-8") as f:
+                    data = json.load(f)
+                for k, v in data.items():
+                    created = v.get("created", now)
+                    if self.ttl <= 0 or now - created <= self.ttl:
+                        self._store[k] = _Record(key=k, created=created,
+                                                 result=v.get("result", {}))
+            replayed = False
+            if self._log_path and os.path.exists(self._log_path):
+                with open(self._log_path, encoding="utf-8") as f:
+                    for line in f:
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            ev = json.loads(line)
+                        except Exception:
+                            continue
+                        self._apply_log_event(ev, now)
+                        replayed = True
+            if replayed:
+                self._compact()
+        except Exception:
+            pass
+
+    def stats(self) -> dict:
+        with self._lock:
+            self._evict_expired()
+            return {"size": len(self._store), "max_size": self.max_size,
+                    "ttl_seconds": self.ttl, "persisted": bool(self.persist_path),
+                    "persist_failures": self._persist_failures,
+                    "ops_since_compact": self._ops_since_compact}