foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/core/content_guard.py

@@ -0,0 +1,341 @@
+"""内容安全闸门 (ContentGuard):合规红线的确定性拦截,输入与输出两端。
+
+为什么要有这一层
+────────────────
+KERNEL_PROMPT 的【五、安全】管的是「指令 vs 数据」(别被外部内容骗),behavior.yaml 的
+confirm_* 管的是「别乱动高危动作」。两者都不管「这话题本身不能碰」:模型仍可能被诱导
+生成违规内容,或用户直接索要。提示词只能降低概率,对外交付的产品需要可复现的兜底。
+
+所以这里只做确定性判定:**不做语义理解、不调模型**。命中就按固定话术切断,
+不解释、不延伸、不反问 —— 拒绝本身不能变成信息泄漏或继续纠缠的入口。
+
+三层词表来源
+────────────
+1. 内置规则(本文件 `_BUILTIN_RULES`):只放**请求型教唆**的高置信度模式 ——「怎么制作
+   炸药」「教我自杀方法」这类。措辞窄,误伤率极低,开箱即用。
+2. 外部词表(`FOXCLAW_CONTENT_LEXICON`,逗号分隔多个路径):一行一词,`#` 注释,
+   可选 `词<TAB>类别`。平台审核要求的大类词表(政治/色情/暴力)体量在数万条量级,
+   硬编码进代码既不现实也无法随监管口径更新,交由部署方挂载。
+3. 自定义类别:外部词表里的类别名会原样出现在命中结果里,便于审计归类。
+
+为什么不内置大词表
+────────────────
+六万条量级的词表进仓库,一是体积与构建成本,二是监管口径变化时改代码而非改配置。
+更重要的是:知识库导入、文档解析属于**用户自己的资料**,不在这里过滤 —— 过滤器只挂在
+「用户请求」与「模型输出」两端,避免把历史书、法律条文、医学教材的内容当成违规请求。
+
+三档模式 (FOXCLAW_CONTENT_GUARD_MODE)
+────────────────────────────────────
+  enforce  真正拦截:输入命中直接回固定话术、不进模型;输出命中整段替换。
+  audit    只记录不拦截(默认之外的灰度档,用于观察误伤率)。
+  off      完全关闭。
+
+默认 enforce:这一层是给对外产品兜底的,默认不生效等于没做。内置规则范围窄,
+所以默认强制不会误伤日常对话;是否挂平台大类词表由 `FOXCLAW_CONTENT_LEXICON` 决定。
+
+归一化对抗
+──────────
+全角、零宽字符、空格插字、大小写是最常见的绕过手法,扫描前统一归一化,
+并对「去掉空白标点后的紧凑串」再扫一遍。拼音/谐音/拆字改写不在确定性层面处理 ——
+那是提示词与人工审核的职责,这里明确只做限速带,不做墙。
+"""
+from __future__ import annotations
+
+import os
+import re
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+MODE_ENV = "FOXCLAW_CONTENT_GUARD_MODE"
+LEXICON_ENV = "FOXCLAW_CONTENT_LEXICON"
+VALID_MODES = ("off", "audit", "enforce")
+
+REFUSAL_ZH = "我们换个话题聊聊吧。"
+REFUSAL_EN = "Let's talk about something else."
+
+# 内置规则只覆盖「请求型教唆」:有明确动作词 + 明确对象,措辞窄、误伤低。
+_BUILTIN_RULES: dict[str, tuple[str, ...]] = {
+    "illegal_solicit": (
+        r"(?:怎么|如何|教我|教我如何|帮我|求|来个|写个|写一个).{0,12}"
+        r"(?:制作|合成|提炼|配制|自制).{0,8}(?:毒品|冰毒|海洛因|摇头丸|炸弹|炸药|雷管|枪支)",
+        r"(?:毒品|冰毒|海洛因|炸弹|炸药).{0,8}(?:制作|合成|提炼|配方|教程|方法)",
+        r"(?:洗钱|跑分|杀猪盘|电信诈骗).{0,8}(?:教程|方法|流程|怎么|如何|话术)",
+        # 负向前瞻:排除「如何防止/避免入侵」这类防御性提问,那是正常需求。
+        r"(?:怎么|如何|教我|帮我|求)(?!.{0,6}(?:防止|避免|防范|抵御|修复)).{0,12}"
+        r"(?:入侵|攻击|破解).{0,10}(?:别人|他人|网站|服务器|系统|账号)",
+        r"(?:伪造|办假).{0,6}(?:身份证|护照|证件|发票|公章)",
+    ),
+    "self_harm": (
+        r"(?:怎么|如何|教我|最好的方式|最不痛|无痛).{0,10}(?:自杀|轻生|结束生命)",
+        r"(?:自杀|自残|割腕).{0,8}(?:方法|教程|最不痛|无痛|怎么才)",
+    ),
+    "minor_sexual": (
+        r"(?:未成年|儿童|幼女|幼童|萝莉).{0,8}(?:色情|裸照|裸体|性行为|做爱|性交)",
+        r"(?:色情|裸照).{0,8}(?:未成年|儿童|幼女)",
+    ),
+}
+
+_BUILTIN_COMPILED = {cat: [re.compile(p, re.IGNORECASE) for p in pats]
+                     for cat, pats in _BUILTIN_RULES.items()}
+
+_ZERO_WIDTH = dict.fromkeys(map(ord, "\u200b\u200c\u200d\u2060\ufeff\u00ad"))
+# 紧凑串去掉的字符:空白 + 常见中英标点,用来对抗「敏 感 词」「敏*感*词」这类插字绕过。
+_STRIP_RX = re.compile(r"[\s\u3000·・\-_*~,.;:!?/\\|'\"`()\[\]{}<>@#$%^&+=、。，；：！？…—～《》“”‘’（）【】]")
+
+
+def _has_cjk(text: str) -> bool:
+    return any("\u4e00" <= ch <= "\u9fff" for ch in text)
+
+
+def refusal_for(text: str) -> str:
+    """固定话术:跟随输入语种,只有中英两种 —— 拒绝语本身不该携带任何额外信息。"""
+    return REFUSAL_ZH if _has_cjk(text) else REFUSAL_EN
+
+
+def normalize(text: str) -> str:
+    """NFKC(全半角/兼容字符)+ 去零宽 + 小写。"""
+    s = unicodedata.normalize("NFKC", str(text or "")).translate(_ZERO_WIDTH)
+    return s.lower()
+
+
+def compact(text: str) -> str:
+    """归一化后再去掉空白与标点,用于抗插字绕过。"""
+    return _STRIP_RX.sub("", normalize(text))
+
+
+@dataclass(frozen=True)
+class Hit:
+    category: str
+    word: str
+    source: str  # builtin / lexicon
+
+    def to_dict(self) -> dict:
+        return {"category": self.category, "word": self.word, "source": self.source}
+
+
+class _Trie:
+    """Aho-Corasick:一次性建表,之后线性扫描。
+
+    词表可能上万条,逐词 `in text` 是不可接受的;纯 Python 实现避免为此引入新依赖。
+    """
+
+    __slots__ = ("goto", "fail", "out")
+
+    def __init__(self, entries: Iterable[tuple[str, str, str]]):
+        self.goto: list[dict[str, int]] = [{}]
+        self.fail: list[int] = [0]
+        self.out: list[list[tuple[str, str, str]]] = [[]]
+        for word, cat, src in entries:
+            self._add(word, cat, src)
+        self._build()
+
+    def _add(self, word: str, cat: str, src: str) -> None:
+        node = 0
+        for ch in word:
+            nxt = self.goto[node].get(ch)
+            if nxt is None:
+                nxt = len(self.goto)
+                self.goto[node][ch] = nxt
+                self.goto.append({})
+                self.fail.append(0)
+                self.out.append([])
+            node = nxt
+        self.out[node].append((word, cat, src))
+
+    def _build(self) -> None:
+        queue = list(self.goto[0].values())
+        for n in queue:
+            self.fail[n] = 0
+        head = 0
+        while head < len(queue):
+            node = queue[head]
+            head += 1
+            for ch, nxt in self.goto[node].items():
+                queue.append(nxt)
+                f = self.fail[node]
+                while f and ch not in self.goto[f]:
+                    f = self.fail[f]
+                self.fail[nxt] = self.goto[f].get(ch, 0)
+                self.out[nxt].extend(self.out[self.fail[nxt]])
+
+    def find(self, text: str) -> list[tuple[str, str, str]]:
+        node, found = 0, []
+        for ch in text:
+            while node and ch not in self.goto[node]:
+                node = self.fail[node]
+            node = self.goto[node].get(ch, 0)
+            if self.out[node]:
+                found.extend(self.out[node])
+        return found
+
+
+def load_lexicon(paths: Iterable[str | Path]) -> list[tuple[str, str, str]]:
+    """读取外部词表。一行一词:`词` 或 `词<TAB>类别`;`#` 开头为注释。
+
+    读不到或格式不对的词直接跳过 —— 词表是部署方维护的外部输入,
+    不能因为一个坏行让整个守卫启动失败(那样只会被关掉)。
+    """
+    entries: list[tuple[str, str, str]] = []
+    for raw in paths:
+        p = Path(raw).expanduser()
+        try:
+            text = p.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            s = line.strip()
+            if not s or s.startswith("#"):
+                continue
+            word, _, cat = s.partition("\t")
+            word = compact(word)
+            if len(word) < 2:
+                continue
+            entries.append((word, (cat.strip() or "platform"), "lexicon"))
+    return entries
+
+
+@dataclass
+class Decision:
+    blocked: bool
+    mode: str
+    hit: Hit | None = None
+    text: str = ""
+
+    def to_dict(self) -> dict:
+        return {"blocked": self.blocked, "mode": self.mode,
+                "hit": self.hit.to_dict() if self.hit else None}
+
+
+class ContentGuard:
+    """输入/输出两端的内容安全闸门。无状态判定 + 可挂载,与 SensitiveWritePolicy 同构。"""
+
+    def __init__(self, mode: str | None = None, lexicon_paths: Iterable[str] | None = None,
+                 builtin: bool = True):
+        self.mode = self._resolve_mode(mode)
+        self._builtin = _BUILTIN_COMPILED if builtin else {}
+        entries = load_lexicon(lexicon_paths if lexicon_paths is not None
+                               else self._env_lexicons())
+        self._trie = _Trie(entries) if entries else None
+        self.lexicon_size = len(entries)
+
+    @staticmethod
+    def _resolve_mode(mode: str | None = None) -> str:
+        m = (mode or os.environ.get(MODE_ENV, "") or "enforce").strip().lower()
+        return m if m in VALID_MODES else "enforce"
+
+    @staticmethod
+    def _env_lexicons() -> list[str]:
+        raw = os.environ.get(LEXICON_ENV, "").strip()
+        return [x.strip() for x in raw.split(",") if x.strip()]
+
+    def enabled(self) -> bool:
+        return self.mode != "off"
+
+    def scan(self, text: str) -> tuple[Hit, ...]:
+        """返回命中项(去重,保序)。文本为空或未启用时返回空。"""
+        if not self.enabled() or not text:
+            return ()
+        hits: list[Hit] = []
+        seen: set = set()
+
+        def _push(word: str, cat: str, src: str) -> None:
+            key = (cat, word)
+            if key not in seen:
+                seen.add(key)
+                hits.append(Hit(cat, word, src))
+
+        # 原文 + 紧凑串两遍:原文保住命中片段可读,紧凑串对付全角与插字绕过。
+        variants = (text, compact(text))
+        for cat, patterns in self._builtin.items():
+            for rx in patterns:
+                for v in variants:
+                    m = rx.search(v)
+                    if m:
+                        _push(m.group(0), cat, "builtin")
+                        break
+                else:
+                    continue
+                break
+
+        if self._trie is not None:
+            for word, cat, src in self._trie.find(compact(text)):
+                _push(word, cat, src)
+        return tuple(hits)
+
+    def check(self, text: str) -> Decision:
+        """判定一段文本。enforce 命中 → blocked=True;audit 只记录。"""
+        hits = self.scan(text)
+        if not hits:
+            return Decision(False, self.mode)
+        hit = hits[0]
+        if self.mode == "enforce":
+            return Decision(True, self.mode, hit, refusal_for(text))
+        print(f"[Foxclaw] ⚠ 内容命中(未拦截): category={hit.category} word={hit.word!r}")
+        return Decision(False, self.mode, hit)
+
+    def guard_input(self, text: str) -> Decision:
+        return self.check(text)
+
+    def sanitize_output(self, text: str) -> Decision:
+        """输出端:命中则整段替换为固定话术(不保留任何原文片段)。"""
+        d = self.check(text)
+        if d.blocked:
+            d.text = refusal_for(text)
+        return d
+
+
+class StreamFilter:
+    """流式输出的增量过滤。
+
+    词可能跨 chunk,所以保留尾部 `window` 字符不立即下发,命中即中止整段输出。
+    这只能保证「命中点之后不再吐字」,已经流出去的片段收不回 —— 流式的固有代价,
+    换来的是不在每个 token 上做全量重扫。
+    """
+
+    def __init__(self, guard: ContentGuard, window: int = 24):
+        self.guard = guard
+        self.window = max(4, int(window))
+        self.buf = ""
+        self.tripped = False
+        self.decision: Decision | None = None
+
+    def feed(self, chunk: str) -> str:
+        """喂一个增量,返回可以安全下发的部分。命中后恒返回空串。"""
+        if not self.guard.enabled():
+            return chunk
+        if self.tripped:
+            return ""
+        self.buf += chunk or ""
+        d = self.guard.check(self.buf)
+        if d.blocked:
+            self.tripped = True
+            self.decision = d
+            self.buf = ""
+            return ""
+        if len(self.buf) <= self.window:
+            return ""
+        out, self.buf = self.buf[:-self.window], self.buf[-self.window:]
+        return out
+
+    def finish(self) -> str:
+        """收尾:吐出缓冲;若已命中则改用固定话术。"""
+        if self.tripped:
+            return self.decision.text if self.decision else REFUSAL_ZH
+        tail, self.buf = self.buf, ""
+        return tail
+
+
+def attach(router, guard: ContentGuard | None = None):
+    """挂到 ModelRouter(LLM 唯一咽喉),输出端过滤对所有 Agent 一次性生效。"""
+    router.content_guard = guard or ContentGuard()
+    return router.content_guard
+
+
+def guard_input(router, text: str) -> Decision:
+    """对话入口的统一闸门:未挂守卫时一律放行(向后兼容)。"""
+    g = getattr(router, "content_guard", None)
+    if g is None:
+        return Decision(False, "off")
+    return g.guard_input(text)

package/python/foxclaw/core/envfile.py

@@ -37,10 +37,10 @@ def load_env_file(path: str | Path) -> List[str]:
     shadows: List[str] = []
     for key, value in (dotenv_values(target) or {}).items():
         if not key:
-            continue                    # 文件里的注释行会解出 None 键
+            continue
         value = (value or "").strip()
         if not value:
-            continue                    # 空值 = 未配置,不覆盖系统环境
+            continue
         current = os.environ.get(key, "").strip()
         if current and current != value:
             shadows.append(key)

package/python/foxclaw/core/failure_policy.py

@@ -16,29 +16,24 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-# ── 失败类型 ────────────────────────────────────────────────────────────
 OK = "ok"
-TIMEOUT = "timeout"                    # 单工具硬超时(工具轮主动放弃)
-TRANSIENT = "transient"                # 网络抖动/限流/5xx —— 重试有意义
-NOT_CONFIGURED = "not_configured"      # 没配 key/服务 —— 重试一万次也没用
-EMPTY = "empty"                        # 调通了但没内容(搜不到/没召回)
-INVALID_ARGS = "invalid_args"          # 模型给的参数不合法 —— 让模型自己改
-DENIED = "denied"                      # 策略禁用/未知工具 —— 不许绕过
-NEEDS_HUMAN = "needs_human"            # 红线动作需确认 —— 只能人来做
-EXCEPTION = "exception"                # 工具内部抛异常
-UNKNOWN = "unknown"                    # 认不出来:保守(不重试、交人)
-
-#: 动作
+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"                          # 终止,不许再试
-
-#: 特征表。**顺序敏感**:先命中先返回。顺序上的两个坑都踩过:
-#:   · "未返回结果"(empty)不能先被 "未返回"(timeout) 吃掉;
-#:   · "不合法"(invalid_args)要在 "拒绝"(denied) 之前,否则参数错误被当成越权。
+RETRY = "retry"
+REPARAM = "reparam"
+DEGRADE = "degrade"
+HAND_TO_HUMAN = "hand_to_human"
+STOP = "stop"
+
 _RULES: tuple[tuple[str, tuple[str, ...]], ...] = (
     (DENIED, ("已被策略禁用", "被权限策略拒绝", "未知工具")),
     (NEEDS_HUMAN, ("需确认的动作", "需要你确认", "请用户确认", "只能由你亲自确认")),
@@ -50,7 +45,6 @@ _RULES: tuple[tuple[str, tuple[str, ...]], ...] = (
     (EXCEPTION, ("执行异常",)),
 )
 
-#: 类型 → (动作, 是否可重试, 给模型的一句硬提示)。提示写进回注文本,模型没法装作没看见。
 _ACTIONS: dict[str, tuple[str, bool, str]] = {
     TIMEOUT: (RETRY, True,
               "这一步超时未完成,已自动重试一次仍有问题。请如实说明这一步没做成,不要编造结果。"),
@@ -94,9 +88,6 @@ class Decision:
                 "retryable": self.retryable, "hint": self.hint}
 
 
-#: 失败回注的形态标记。工具执行侧的失败文本统一以 "(" 开头(见 tool_exec 的兜底),
-#: 另有少数异常文本不带括号。**不能**用"含 未/失败 就算失败"这种宽松判据:
-#: 搜索正文里"未来""失败案例"都会误伤,把成功结果标成失败。
 _FAILURE_MARKERS = ("执行异常", "入参不合法", "被权限策略拒绝", "缺少必填")
 
 
@@ -111,7 +102,7 @@ def classify(text: str) -> str:
     """把回注文本归类:``ok`` / 具体失败类型 / ``unknown``(认不出来,保守交人)。"""
     t = (text or "").strip()
     if not t:
-        return UNKNOWN                      # 空结果:不能当成功,也不确定成因
+        return UNKNOWN
     if not looks_like_failure(t):
         return OK
     low = t.lower()

package/python/foxclaw/core/gateway.py

@@ -19,15 +19,15 @@ 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.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 = {}    # client -> [tokens, last_ts]
-        self._quota: dict = {}      # client -> [count, window_start]
-        self._seen: dict = {}       # client -> last_ts(用于空闲淘汰)
-        self.rejected = 0           # 累计拒绝数(可观测)
+        self._buckets: dict = {}
+        self._quota: dict = {}
+        self._seen: dict = {}
+        self.rejected = 0
 
     def check(self, client: str):
         """判定一次请求。返回 (allowed: bool, retry_after: int, reason: str)。
@@ -37,7 +37,6 @@ class Gateway:
             self._evict_locked(now)
             self._seen[client] = now
 
-            # ① 配额(固定 1 小时窗口)
             q = self._quota.get(client)
             if q is None or now - q[1] >= 3600.0:
                 q = [0, now]
@@ -46,7 +45,6 @@ class Gateway:
                 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]
@@ -57,7 +55,6 @@ class Gateway:
                 self.rejected += 1
                 return False, int((1.0 - b[0]) / self.refill) + 1, "rate"
 
-            # 放行:扣 1 令牌 + 计 1 配额
             b[0] -= 1.0
             q[0] += 1
             return True, 0, ""
@@ -67,7 +64,6 @@ class Gateway:
         if len(self._seen) <= self.max_clients:
             return
         n_drop = len(self._seen) - self.max_clients + max(1, self.max_clients // 10)
-        # 按 last_ts 升序取最旧的 n_drop 个
         victims = sorted(self._seen.items(), key=lambda kv: kv[1])[:n_drop]
         for c, _ in victims:
             self._seen.pop(c, None)

package/python/foxclaw/core/governance_audit.py

@@ -46,11 +46,9 @@ from . import audit_chain
 ENV_SWITCH = "FOXCLAW_GOVERNANCE_AUDIT"
 TOPIC = "governance.decision"
 
-# verdict 合法取值(文档用,不做硬校验——审计不该因词汇笔误崩掉主流程)
-VERDICTS_RULING = ("allow", "warn", "deny", "confirm")   # 裁决类
-VERDICTS_EXECUTION = ("success", "failed")               # 执行类
+VERDICTS_RULING = ("allow", "warn", "deny", "confirm")
+VERDICTS_EXECUTION = ("success", "failed")
 
-# 已知层名(同上,仅文档)
 LAYERS = ("harness", "permission", "orchestration", "skill")
 
 
@@ -71,7 +69,6 @@ class GovernanceAuditor:
         self._spine = spine
         self._path = Path(sink_path) if sink_path else None
         self._lock = threading.Lock()
-        # 链尾 hash:首次落盘时从文件尾部补齐(重启后接着上一条链,而不是重开 GENESIS)
         self._last_hash: str | None = None
 
     @property
@@ -95,7 +92,7 @@ class GovernanceAuditor:
             "actor": actor,
             "action": action,
             "verdict": verdict,
-            "reason": (reason or "")[:200],          # 理由截断,防巨型异常串灌爆审计
+            "reason": (reason or "")[:200],
             "detail": detail or {},
             "ts": datetime.now(timezone.utc).isoformat(),
         }
@@ -103,7 +100,6 @@ class GovernanceAuditor:
         self._persist(rec)
         return did
 
-    # ── 内部:两个通道,各自独立 fail-safe ─────────────────────
 
     def _emit(self, rec: dict) -> None:
         if self._spine is None:

package/python/foxclaw/core/idempotency.py

@@ -27,7 +27,7 @@ from dataclasses import dataclass, field
 class _Record:
     key: str
     created: float
-    result: dict = field(default_factory=dict)   # 上次执行的结果(重发时原样返回)
+    result: dict = field(default_factory=dict)
 
 
 def make_key(domain: str, *parts: str, version: str = "v1") -> str:
@@ -52,16 +52,14 @@ class IdempotencyGuard:
     """
 
     def __init__(self, ttl_seconds: float = 3600, max_size: int = 10000,
-                 persist_path: str = None, spine=None,
+                 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()
-        # 【P2-3】审计脊柱(可空,None 时静默)
         self._spine = spine
-        # 【P2-3】追加日志 + 定期 compact
         self._log_path = (persist_path + ".log") if persist_path else None
         self._compact_every = compact_every
         self._ops_since_compact = 0
@@ -82,7 +80,7 @@ class IdempotencyGuard:
             rec = self._store.get(key)
             return dict(rec.result) if rec else None
 
-    def mark(self, key: str, result: dict = None):
+    def mark(self, key: str, result: dict | None = None):
         """标记 key 已执行,记录结果。"""
         with self._lock:
             self._store[key] = _Record(key=key, created=time.time(),
@@ -92,9 +90,9 @@ class IdempotencyGuard:
                              result=self._store[key].result)
             need_compact = self._ops_since_compact >= self._compact_every
         if need_compact:
-            self._try_compact()     # 全量写盘放主锁外(见 _try_compact)
+            self._try_compact()
 
-    def check_and_mark(self, key: str, result: dict = None) -> bool:
+    def check_and_mark(self, key: str, result: dict | None = None) -> bool:
         """原子操作:若 key 未见过 → 标记并返回 True(应执行);
         若已见过 → 返回 False(应跳过)。
 
@@ -104,7 +102,7 @@ class IdempotencyGuard:
         with self._lock:
             self._evict_expired()
             if key in self._store:
-                return False        # 已处理过,跳过
+                return False
             self._store[key] = _Record(key=key, created=time.time(),
                                        result=dict(result or {}))
             self._enforce_capacity()
@@ -128,7 +126,6 @@ class IdempotencyGuard:
         if need_compact:
             self._try_compact()
 
-    # ── 内部:过期/容量/持久化 ──────────────────────────────
     def _evict_expired(self):
         if self.ttl <= 0:
             return
@@ -138,9 +135,6 @@ class IdempotencyGuard:
             del self._store[k]
 
     def _enforce_capacity(self):
-        # 超容量 → 淘汰最旧的(按 created)。
-        # 【P2-3】淘汰必须落 delete 日志:否则重启回放追加日志时,被淘汰的 key
-        # 会"复活"(mark 日志还在,没有对应的删除记录)。锁内调用。
         if len(self._store) <= self.max_size:
             return
         items = sorted(self._store.items(), key=lambda kv: kv[1].created)
@@ -148,7 +142,6 @@ class IdempotencyGuard:
             del self._store[k]
             self._persist_op("delete", k)
 
-    # ── 内部:持久化(追加日志 + 定期 compact)─────────────────
     def _persist_op(self, event: str, key: str, **fields):
         """【P2-3】追加一条日志(O(1) 写,不写全量)。锁内调用(append 很快,
         且在锁内可避免并发写同一文件交错)。失败计数 + 发事件,不影响主流程。"""
@@ -196,11 +189,10 @@ class IdempotencyGuard:
                             for k, r in self._store.items()
                             if self.ttl <= 0 or now - r.created <= self.ttl}
                 self._ops_since_compact = 0
-            # ── 以下为主锁外的慢 IO ──
             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)   # 原子替换,防写一半损坏
+            os.replace(tmp, self.persist_path)
             if rotated and os.path.exists(rotated):
                 os.remove(rotated)
         except Exception:
@@ -222,7 +214,7 @@ class IdempotencyGuard:
             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)   # 原子替换,防写一半损坏
+            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
@@ -254,8 +246,9 @@ class IdempotencyGuard:
         一份全量快照,失去"追加日志 O(1)"的意义。"""
         try:
             now = time.time()
-            if os.path.exists(self.persist_path):
-                with open(self.persist_path, encoding="utf-8") as f:
+            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)
@@ -272,18 +265,18 @@ class IdempotencyGuard:
                         try:
                             ev = json.loads(line)
                         except Exception:
-                            continue    # 跳过损坏行(append 末行可能写一半)
+                            continue
                         self._apply_log_event(ev, now)
                         replayed = True
             if replayed:
                 self._compact()
         except Exception:
-            pass        # 加载失败 → 从空开始,不影响启动
+            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,      # 【P2-3】
-                    "ops_since_compact": self._ops_since_compact}    # 【P2-3】
+                    "persist_failures": self._persist_failures,
+                    "ops_since_compact": self._ops_since_compact}