foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/core/recovery.py

@@ -50,25 +50,22 @@ def _pid_alive(pid: int) -> bool:
         handle = kernel32.OpenProcess(
             PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
         if not handle:
-            return False       # 打不开句柄 = 进程不存在(或无权限)→ 保守判不存活
+            return False
         try:
             code = wintypes.DWORD()
             if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
                 return False
-            # STILL_ACTIVE=259 表示仍在运行。极少数进程恰以 259 退出会被误判存活,
-            # 但这是"只读探测"的可接受代价——绝不误杀才是首要目标(psutil 同此取舍)。
             return code.value == STILL_ACTIVE
         finally:
             kernel32.CloseHandle(handle)
 
-    # POSIX
     try:
         os.kill(pid, 0)
         return True
     except ProcessLookupError:
         return False
     except PermissionError:
-        return True       # 存在但无权限 → 视为存活
+        return True
     except Exception:
         return False
 
@@ -79,14 +76,13 @@ class TaskRecord:
     description: str
     pid: int
     started: float
-    status: str = "in_progress"        # in_progress / done / failed / interrupted
+    status: str = "in_progress"
     session_id: str = ""
     channel: str = ""
     finished: float = 0.0
-    boot_id: str = ""                  # 哪次启动产生的(防 pid 复用误判)
-    # 【P2-4】恢复策略字段
-    retryable: bool = False            # 调用方标记"可安全重试"(无副作用/幂等)
-    start_count: int = 1               # 同一 task_id 被 start 的次数(重复 start 保留最后一次)
+    boot_id: str = ""
+    retryable: bool = False
+    start_count: int = 1
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -95,10 +91,10 @@ class TaskRecord:
 @dataclass
 class RecoveryPlan:
     """【P2-4】恢复计划:把中断任务分类,调用方(API 层/前端)据此决定动作。"""
-    retryable: list = field(default_factory=list)      # 可重试的 task_id
-    notify_user: list = field(default_factory=list)    # 需通知用户的(来自某个渠道)
-    needs_manual: list = field(default_factory=list)   # 需人工处理的(保守默认)
-    details: list = field(default_factory=list)        # [{task_id,description,channel,...,action}]
+    retryable: list = field(default_factory=list)
+    notify_user: list = field(default_factory=list)
+    needs_manual: list = field(default_factory=list)
+    details: list = field(default_factory=list)
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -107,20 +103,17 @@ class RecoveryPlan:
 class RestartRecovery:
     """任务生命周期日志 + 启动恢复扫描。"""
 
-    def __init__(self, log_path: str, current_pid: int = None, boot_id: str = None,
+    def __init__(self, log_path: str, current_pid: int | None = None, boot_id: str | None = None,
                  spine=None, fsync: bool = True):
         self.log_path = log_path
         self.current_pid = current_pid or os.getpid()
-        # boot_id:每次启动唯一。任务记录带上它,扫描时"非本次启动的 in_progress"
-        # 即属于上一次运行 —— 比单纯靠 pid 可靠(pid 会被 OS 复用)。
         import uuid
         self.boot_id = boot_id or uuid.uuid4().hex[:16]
-        self._active: dict[str, TaskRecord] = {}   # 当前进程内进行中的任务
-        self._spine = spine                        # 【P2-4】审计脊柱(可空,None 静默)
-        self._fsync = fsync                        # 【P2-4】fsync 可配(默认开=崩溃安全;高频场景可关)
+        self._active: dict[str, TaskRecord] = {}
+        self._spine = spine
+        self._fsync = fsync
         os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
 
-    # ── 任务生命周期 ──────────────────────────────────────
     def task_started(self, task_id: str, description: str,
                      session_id: str = "", channel: str = "",
                      retryable: bool = False) -> TaskRecord:
@@ -142,7 +135,6 @@ class RestartRecovery:
                       "status": status, "pid": self.current_pid,
                       "finished": time.time()})
 
-    # ── 步骤级 checkpoint(P1 断点可续)─────────────────────
     def record_step(self, task_id: str, step: dict) -> None:
         """记一条「已完成的步骤」。管线每完成一个 stage、工具轮每完成一个工具调用各落一条,
         崩溃/断连后 `steps_of()` 能回答「跑到哪一步」,也让续跑知道哪些步骤不必重做。
@@ -171,7 +163,7 @@ class RestartRecovery:
                     try:
                         ev = json.loads(line)
                     except Exception:
-                        continue        # 末行可能写一半(append 崩溃),跳过
+                        continue
                     if ev.get("event") == "step" and ev.get("task_id") == task_id:
                         out.append({k: v for k, v in ev.items()
                                     if k not in ("event", "task_id")})
@@ -179,7 +171,6 @@ class RestartRecovery:
             return out
         return out[-limit:] if limit else out
 
-    # ── 启动恢复扫描 ──────────────────────────────────────
     def scan_interrupted(self) -> list[TaskRecord]:
         """启动时调用:重建日志状态,找出被中断的任务。
 
@@ -194,9 +185,7 @@ class RestartRecovery:
             if rec.status != "in_progress":
                 continue
             if rec.boot_id == self.boot_id:
-                continue        # 本次启动自己的任务,跳过
-            # 非本次启动的 in_progress = 上次运行遗留 = 被中断
-            # (pid 是否存活作为辅助信息记录,但不作为唯一判据)
+                continue
             rec.status = "interrupted"
             interrupted.append(rec)
             self._append({"event": "interrupted", "task_id": task_id,
@@ -220,7 +209,7 @@ class RestartRecovery:
                     try:
                         ev = json.loads(line)
                     except Exception:
-                        continue        # 跳过损坏行(append 模式下末行可能写一半)
+                        continue
                     self._apply_event(records, ev)
         except Exception:
             pass
@@ -233,7 +222,6 @@ class RestartRecovery:
             return
         kind = ev.get("event")
         if kind == "start":
-            # 【P2-4】同一 task_id 多次 start:保留最后一次,但累计 start_count
             existing = records.get(tid)
             start_count = (existing.start_count + 1) if existing else 1
             records[tid] = TaskRecord(
@@ -249,7 +237,7 @@ class RestartRecovery:
             if kind == "finish":
                 records[tid].finished = ev.get("finished", 0)
 
-    def plan_recovery(self, interrupted: list = None) -> RecoveryPlan:
+    def plan_recovery(self, interrupted: list | None = None) -> RecoveryPlan:
         """【P2-4】给中断任务分类,返回恢复计划(不改 scan_interrupted 的返回,兼容)。
 
         分类规则:
@@ -304,9 +292,9 @@ class RestartRecovery:
                 f.write(json.dumps(entry, ensure_ascii=False) + "\n")
                 f.flush()
                 if self._fsync:
-                    os.fsync(f.fileno())     # 落盘,防崩溃丢最后一条
+                    os.fsync(f.fileno())
         except Exception:
-            pass        # 日志失败不影响主流程
+            pass
 
     def compact_log(self, keep_recent_days: float = 7):
         """压实日志:丢弃已完成且超过 N 天的记录,防文件无限膨胀。
@@ -317,7 +305,6 @@ class RestartRecovery:
         cutoff = time.time() - keep_recent_days * 86400
         keep = []
         for rec in records.values():
-            # 保留:仍在进行的,或最近有活动(开始或完成)的
             last_activity = max(rec.started, rec.finished or 0)
             if rec.status == "in_progress" or last_activity >= cutoff:
                 keep.append({"event": "start", **rec.to_dict()})
@@ -331,7 +318,7 @@ class RestartRecovery:
             with open(tmp, "w", encoding="utf-8") as f:
                 for e in keep:
                     f.write(json.dumps(e, ensure_ascii=False) + "\n")
-                for e in steps:              # 保留任务的 step 事件随记录一起搬走
+                for e in steps:
                     f.write(json.dumps(e, ensure_ascii=False) + "\n")
             os.replace(tmp, self.log_path)
         except Exception:

package/python/foxclaw/core/scheduler.py

@@ -9,45 +9,46 @@
 """
 from __future__ import annotations
 from dataclasses import dataclass
+from typing import Optional
 
 
 @dataclass
 class TaskIntent:
     """任务意图:粗粒度类别 + 三个亲和度提示。"""
-    category: str                 # reasoning / memory / workflow / tool
+    category: str
     confidence: float
-    memory_affinity: float        # 记忆依赖度
-    reasoning_depth: float        # 推理深度提示
+    memory_affinity: float
+    reasoning_depth: float
 
 
 @dataclass
 class TaskFeatures:
-    complexity: float             # 复杂度
-    memory_dependency: float      # 记忆依赖
-    tool_cost: float              # 工具成本
-    reasoning_depth: float        # 推理深度
-    urgency: float                # 紧急度
-    expected_runtime: float       # 预期耗时
+    complexity: float
+    memory_dependency: float
+    tool_cost: float
+    reasoning_depth: float
+    urgency: float
+    expected_runtime: float
 
 
 @dataclass
 class SystemContext:
     """系统负载上下文。主管据此调整优先级、决定是否抢占。"""
-    active_agents: int = 0        # 当前活跃 Agent 数
-    queue_depth: int = 0          # 待处理任务队列深度
-    system_load: float = 0.1      # 系统负载 0-1
+    active_agents: int = 0
+    queue_depth: int = 0
+    system_load: float = 0.1
 
 
 @dataclass
 class ScheduleDecision:
-    priority: float               # 最终优先级 0-1
-    route_hint: str               # 路由倾向:agent / tool / workflow
-    execution_mode: str           # preemptive(抢占) / standard(标准)
-    preemptible: bool             # 是否可触发抢占
-    expected_budget: float        # 预期预算(耗时×优先级修正)
-    intent: TaskIntent = None
-    features: TaskFeatures = None
-    preemption_reason: str = None
+    priority: float
+    route_hint: str
+    execution_mode: str
+    preemptible: bool
+    expected_budget: float
+    intent: Optional[TaskIntent] = None
+    features: Optional[TaskFeatures] = None
+    preemption_reason: Optional[str] = None
     reason: str = ""
 
     def to_dict(self) -> dict:
@@ -63,7 +64,6 @@ class ScheduleDecision:
 class CognitiveScheduler:
     """意图感知的认知调度器。"""
 
-    # 意图识别关键词(粗分类)
     _REASONING = ["规划", "计划", "分析", "设计", "推理", "为什么", "怎么办", "策略", "方案"]
     _MEMORY = ["记得", "记忆", "之前", "上次", "回忆", "查一下我", "我说过"]
     _WORKFLOW = ["然后", "接着", "之后", "依次", "批量", "流程", "再然后", "下一步"]
@@ -86,7 +86,6 @@ class CognitiveScheduler:
             complexity, tool_cost, urgency, runtime = 0.7, 0.6, 0.65, 0.8
         elif intent.category == "memory":
             complexity, tool_cost, urgency, runtime = 0.5, 0.2, 0.55, 0.6
-        # 紧急词加成
         if any(w in task for w in ["紧急", "立刻", "马上", "尽快", "急"]):
             urgency = min(1.0, urgency + 0.3)
         return TaskFeatures(complexity, intent.memory_affinity, tool_cost,
@@ -117,16 +116,14 @@ class CognitiveScheduler:
             return "tool"
         return "agent" if priority > 0.35 else "tool"
 
-    def preemption_reason(self, priority: float, ctx: SystemContext) -> str:
-        # 阈值匹配实际优先级范围(本调度器优先级多在 0.4 以内,
-        # 原 0.55/0.7 几乎不可达,会让抢占形同虚设)
+    def preemption_reason(self, priority: float, ctx: SystemContext) -> str | None:
         if priority > 0.35 and ctx.active_agents >= 3:
             return "高优先级 + Agent 压力大"
         if priority > 0.4 and ctx.queue_depth >= 2:
             return "高优先级 + 队列积压"
         return None
 
-    def schedule(self, task: str, ctx: SystemContext = None) -> ScheduleDecision:
+    def schedule(self, task: str, ctx: SystemContext | None = None) -> ScheduleDecision:
         """主入口:给一个任务做完整调度决策。"""
         ctx = ctx or SystemContext()
         intent = self.parse_intent(task)

package/python/foxclaw/core/secrets.py

@@ -22,8 +22,6 @@ import base64
 
 SERVICE = "foxclaw.llm"
 
-# 后端探测结果缓存(含失败):每个请求都 import + 探测一次没必要。
-# 失败也缓存是有意的 —— 没有可用后端时不该反复重试。
 _kr_cache = None
 _kr_probed = False
 
@@ -37,7 +35,6 @@ def _keyring():
     try:
         import keyring
         from keyring.backends.fail import Keyring as _FailBackend
-        # 默认后端是 Fail 时说明系统上没有可用凭据库(典型:无桌面会话的 Linux)
         if isinstance(keyring.get_keyring(), _FailBackend):
             _kr_cache = None
         else:

package/python/foxclaw/core/sensitive_write.py

@@ -0,0 +1,283 @@
+"""高敏感记忆写入的同意闸门 (SensitiveWritePolicy)。
+
+问题
+────
+`memory_adapter.ingest` 此前对「写什么内容」不做任何判定:凭据、证件号、诊断结论
+一旦被抽进长期记忆,就会在之后每次召回里反复出现在上下文中,而且会随 prompt 发往云端
+模型。spec 的 `confirm_high_sensitivity` 要求这类内容落库前得到用户显式同意。
+
+判定必须是确定性的
+──────────────────
+不用 LLM 判定敏感度:写入路径再调一次模型既贵,结果又不可复现,同一句话今天拦明天放,
+用户无法建立预期。这里只用正则 + Luhn 校验,命中即命中,可单测。
+
+误判方向是刻意的
+────────────────
+漏判 = 该拦的不拦,等于没做;误判 = 用户多点一次确认。所以宁可多拦:「我最近焦虑」
+也会被拦一次。反过来,财务 Agent 天天谈金额,因此 finance 类**只匹配卡号/账户号**,
+绝不匹配普通金额 —— 否则功能一开就无法使用。
+
+三档模式 (FOXCLAW_SENSITIVE_WRITE_MODE)
+──────────────────────────────────────
+  audit  (默认)  只记录不拦截。落库照常,事件里标 allowed。
+  warn           记录 + 进程内告警,仍不落 pending。
+  enforce        真正拦截:高敏感内容不进长期记忆,转成待确认项,用户同意后才落库。
+
+为什么默认 audit
+────────────────
+分类规则在真实流量上跑通之前只是**待验证的假设**。先在 audit 下看清命中长什么样、
+误判率多少,再切 enforce —— 与 shared_write 的灰度立场一致。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+MODE_ENV = "FOXCLAW_SENSITIVE_WRITE_MODE"
+VALID_MODES = ("audit", "warn", "enforce")
+
+PENDING_FILE = "sensitive_pending.json"
+MAX_PENDING = 200
+
+
+def _mask(s: str) -> str:
+    """打码后才允许进事件/日志 —— 审计出口本身不能变成泄露点。"""
+    s = str(s or "")
+    if len(s) <= 6:
+        return "*" * len(s)
+    return f"{s[:2]}{'*' * (len(s) - 4)}{s[-2:]}"
+
+
+def _luhn_ok(digits: str) -> bool:
+    total, alt = 0, False
+    for ch in reversed(digits):
+        if not ch.isdigit():
+            return False
+        d = int(ch)
+        if alt:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+        alt = not alt
+    return total % 10 == 0
+
+
+@dataclass(frozen=True)
+class Hit:
+    category: str
+    pattern: str
+    sample: str
+
+    def to_dict(self) -> dict:
+        return {"category": self.category, "pattern": self.pattern, "sample": self.sample}
+
+
+# 每个模式都是「有上下文锚点」的,不裸匹配长数字 —— 裸匹配会把订单号、时间戳全卷进来。
+_RULES: dict[str, tuple[str, ...]] = {
+    "credential": (
+        r"(?:密码|口令|password|passwd|pwd)\s*[:：=是为]\s*\S{3,}",
+        r"(?:api[_-]?key|secret|token|access[_-]?key)\s*[:：=]\s*[A-Za-z0-9_\-]{12,}",
+        r"\bsk-[A-Za-z0-9]{16,}",
+        r"\bghp_[A-Za-z0-9]{20,}",
+        r"\bAKIA[0-9A-Z]{16}\b",
+        r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
+    ),
+    "identity": (
+        r"\b[1-9]\d{5}(?:18|19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])\d{3}[\dXx]\b",
+        r"(?:身份证|护照|港澳通行证|社保卡|驾驶证)[号编]?\s*[:：]?\s*[A-Za-z0-9]{6,}",
+    ),
+    "health": (
+        r"(?:确诊|诊断为|病历|住院|手术|处方|服药|用药|过敏史|既往史)",
+        r"(?:抑郁症|焦虑症|糖尿病|高血压|心脏病|癌|HIV|乙肝)",
+    ),
+    "finance_detail": (
+        r"(?:银行卡|账户|卡号|账号)\s*[:：]?\s*\d{6,}",
+        r"(?:CVV|CVC|安全码|有效期)\s*[:：]?\s*\d{3,4}",
+        r"\b(?:信用卡|储蓄卡|借记卡)\b",
+    ),
+}
+
+_COMPILED = {cat: [re.compile(p) for p in pats] for cat, pats in _RULES.items()}
+
+# 卡号单独走一次 Luhn:16-19 位裸数字只有校验通过才算,避免误伤订单号/流水号。
+_CARD_CANDIDATE = re.compile(r"\b(?:\d[ -]?){15,18}\d\b")
+
+
+class SensitivityClassifier:
+    """确定性判定:返回命中的类别与打码后的样本。无状态,并发安全。"""
+
+    def __init__(self, categories: Iterable[str] | None = None):
+        allowed = set(categories) if categories is not None else set(_COMPILED)
+        self.categories = tuple(c for c in _COMPILED if c in allowed)
+
+    def classify(self, content: str) -> tuple[Hit, ...]:
+        text = str(content or "")
+        if not text:
+            return ()
+        hits: list[Hit] = []
+        for cat in self.categories:
+            for rx in _COMPILED[cat]:
+                m = rx.search(text)
+                if m:
+                    hits.append(Hit(cat, rx.pattern, _mask(m.group(0))))
+                    break
+        if "finance_detail" in self.categories:
+            for m in _CARD_CANDIDATE.finditer(text):
+                digits = re.sub(r"\D", "", m.group(0))
+                if len(digits) >= 16 and _luhn_ok(digits):
+                    hits.append(Hit("finance_detail", "luhn", _mask(digits)))
+                    break
+        return tuple(hits)
+
+
+@dataclass
+class Decision:
+    allowed: bool
+    reason: str
+    mode: str
+    categories: tuple = ()
+    hits: tuple = ()
+    pending_id: str = ""
+
+    @property
+    def is_pending(self) -> bool:
+        return bool(self.pending_id)
+
+    def to_dict(self) -> dict:
+        return {
+            "allowed": self.allowed, "reason": self.reason, "mode": self.mode,
+            "categories": list(self.categories),
+            "hits": [h.to_dict() for h in self.hits],
+            "pending_id": self.pending_id,
+        }
+
+
+class PendingStore:
+    """待确认的高敏感写入。落盘是因为写入可能跨进程/重启发生,内存队列会静默丢内容。"""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self._lock = threading.RLock()
+
+    def _read(self) -> list:
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except Exception:
+            return []
+        return data if isinstance(data, list) else []
+
+    def _write(self, items: list) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(items, ensure_ascii=False, indent=1), encoding="utf-8")
+        os.replace(tmp, self.path)
+
+    def add(self, entry: dict) -> str:
+        with self._lock:
+            items = self._read()
+            pid = uuid.uuid4().hex[:12]
+            items.append({"id": pid, **entry})
+            self._write(items[-MAX_PENDING:])
+            return pid
+
+    def list(self) -> list:
+        with self._lock:
+            return self._read()
+
+    def pop(self, pid: str) -> dict | None:
+        with self._lock:
+            items = self._read()
+            kept = [it for it in items if it.get("id") != pid]
+            found = next((it for it in items if it.get("id") == pid), None)
+            if found is not None:
+                self._write(kept)
+            return found
+
+
+class SensitiveWritePolicy:
+    """判定「这条内容能否直接写入长期记忆」。纯函数式判定 + 挂载式装配(同 shared_write)。"""
+
+    def __init__(self, mode: str | None = None,
+                 classifier: SensitivityClassifier | None = None,
+                 pending_path: str | Path | None = None):
+        self.mode = self._resolve_mode(mode)
+        self.classifier = classifier or SensitivityClassifier()
+        self.pending = PendingStore(pending_path or _default_pending_path())
+
+    @staticmethod
+    def _resolve_mode(mode: str | None = None) -> str:
+        m = (mode or os.environ.get(MODE_ENV, "") or "audit").strip().lower()
+        return m if m in VALID_MODES else "audit"
+
+    def evaluate(self, content: str, **entry: Any) -> Decision:
+        hits = self.classifier.classify(content)
+        if not hits:
+            return Decision(True, "无高敏感特征", self.mode)
+        cats = tuple(dict.fromkeys(h.category for h in hits))
+        if self.mode == "enforce":
+            return Decision(False, "高敏感内容需用户同意后才能写入长期记忆",
+                            self.mode, cats, hits)
+        label = "audit 不拦截" if self.mode == "audit" else "warn 不拦截"
+        return Decision(True, f"高敏感特征({label})", self.mode, cats, hits)
+
+    def stash(self, content: str, entry: dict, decision: Decision) -> Decision:
+        """enforce 下把被拦的写入转成待确认项,返回带 pending_id 的 Decision。"""
+        pid = self.pending.add({**entry, "content": str(content or ""),
+                                "categories": list(decision.categories)})
+        return Decision(decision.allowed, decision.reason, decision.mode,
+                        decision.categories, decision.hits, pid)
+
+
+def _default_pending_path() -> Path:
+    root = os.environ.get("FOXCLAW_DATA_DIR") or "./foxclaw_data"
+    return Path(root) / PENDING_FILE
+
+
+def guard_sensitive_write(backend, agent_id: str | None, content: str,
+                          memory_type: str = "concept", **entry: Any) -> Decision | None:
+    """记忆落库前的统一闸门。未挂策略时返回 None(向后兼容,与 guard_shared_write 一致)。
+
+    enforce 且命中高敏感 → 返回 allowed=False 的 Decision,调用方**必须**据此跳过落库;
+    被拦内容此时已进入待确认队列,不会丢。
+    """
+    policy = getattr(backend, "sensitive_write_policy", None)
+    if policy is None:
+        return None
+
+    decision = policy.evaluate(content, **entry)
+    spine = getattr(backend, "sensitive_write_spine", None)
+    if spine is not None:
+        try:
+            spine.publish("memory.sensitive", {
+                "agent_id": agent_id or "",
+                "type": memory_type,
+                "allowed": decision.allowed,
+                "mode": decision.mode,
+                "categories": list(decision.categories),
+                "hits": [_mask(h.sample) for h in decision.hits],
+            }, source=agent_id or "memory")
+        except Exception:
+            pass
+
+    if not decision.allowed:
+        if policy.mode == "enforce":
+            return policy.stash(content, {"agent_id": agent_id or "",
+                                          "type": memory_type}, decision)
+        if policy.mode == "warn":
+            print(f"[Foxclaw] ⚠ 高敏感记忆写入(未拦截): agent={agent_id!r} "
+                  f"categories={list(decision.categories)}")
+    return decision
+
+
+def attach(backend, policy: SensitiveWritePolicy | None = None, spine=None):
+    """挂到记忆后端。与 shared_write.attach 同因:装配顺序上脊柱晚于 memory_adapter。"""
+    backend.sensitive_write_policy = policy or SensitiveWritePolicy()
+    backend.sensitive_write_spine = spine
+    return backend.sensitive_write_policy

package/python/foxclaw/core/sessions.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 import json
 import re
+import builtins
 import threading
 import time
 import uuid
@@ -42,9 +43,7 @@ class SessionStore:
         self.base.mkdir(parents=True, exist_ok=True)
         self._lock = threading.RLock()
 
-    # ── 内部 ──────────────────────────────────────────────
     def _path(self, sid: str) -> Path:
-        # 只允许我们自己生成的 id 形态,杜绝 ../ 之类路径穿越
         if not re.fullmatch(r"[A-Za-z0-9_-]{1,64}", str(sid or "")):
             raise ValueError("非法会话 id")
         return self.base / f"{sid}.json"
@@ -64,9 +63,8 @@ class SessionStore:
         tmp = p.with_suffix(".tmp")
         with open(tmp, "w", encoding="utf-8") as f:
             json.dump(data, f, ensure_ascii=False, indent=1)
-        tmp.replace(p)          # 原子替换,防写一半崩坏
+        tmp.replace(p)
 
-    # ── 公开 API ──────────────────────────────────────────
     def create(self, title: str = "", agent_id: str = "supervisor") -> dict:
         sid = uuid.uuid4().hex[:12]
         data = {"id": sid, "title": (title or "新会话")[:60], "agent_id": agent_id,
@@ -105,7 +103,8 @@ class SessionStore:
         with self._lock:
             return self._read(sid)
 
-    def append(self, sid: str, role: str, content: str, attachments: list = None) -> bool:
+    def append(self, sid: str, role: str, content: str,
+               attachments: builtins.list | None = None) -> bool:
         """追加一条消息;会话不存在则忽略。首条用户消息会顺带定标题。
         attachments(可选)= 聊天附件元数据 [{name,size,mime,url}];只落盘轻字段(不存 text,
         避免会话文件随附件正文膨胀),供「会话历史」回看时渲染附件卡片。"""
@@ -128,7 +127,6 @@ class SessionStore:
                 if atts:
                     msg["attachments"] = atts
             msgs.append(msg)
-            # 标题仍是默认值时,用首条用户消息提炼
             if role == "user" and (not d.get("title") or d["title"] == "新会话"):
                 d["title"] = derive_title(content)
             d["updated_at"] = _now()