foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/core/tracing.py

@@ -29,14 +29,11 @@ import contextvars
 from collections import deque
 from contextlib import contextmanager
 from . import settings
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
-# ── 采样策略 ────────────────────────────────────────────────
-# 内存环存只留最近 N 条、重启即失 → 查不了"昨天那次慢请求"。持久化解决它,但不能无脑全存:
-# 正常请求的 trace 数量大、价值低。故:**慢的 / 出错的必存**(那才是你要查的),
-# 其余按采样率(默认 0 —— 个人 OS 留下的每条都值得看)。
 def _slow_ms() -> float:
     return float(settings.get_safe("FOXCLAW_TRACE_SLOW_MS"))
 
@@ -50,14 +47,9 @@ def _retain() -> int:
 
 _current: contextvars.ContextVar = contextvars.ContextVar("foxclaw_trace", default=None)
 
-MAX_SPANS_PER_TRACE = 200          # 单条 trace 的 span 上限,防病态循环把内存撑爆
+MAX_SPANS_PER_TRACE = 200
 
 
-# ── W3C Trace Context(零依赖跨进程传播)────────────────────────
-# 为什么不上 opentelemetry-sdk:Foxclaw 是单进程 + local-first,为它装 SDK/exporter/grpc、
-# 再要求跑个 Jaeger,代价远大于收益。但它确实有一条真实跨进程边界——**MCP 双向**。
-# traceparent 是 W3C 标准、纯字符串、零依赖,恰好覆盖这条边界:
-#   00-{trace_id:32hex}-{span_id:16hex}-{flags:2hex}
 _TP_RE = __import__("re").compile(r"^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$")
 
 
@@ -69,12 +61,12 @@ def parse_traceparent(header: str):
     if not m:
         return None
     tid = m.group(1)
-    if tid == "0" * 32:                       # 全零非法(规范要求)
+    if tid == "0" * 32:
         return None
     return tid
 
 
-def to_traceparent(trace_id: str, span_id: str = None) -> str:
+def to_traceparent(trace_id: str, span_id: str | None = None) -> str:
     """给出站请求生成 traceparent。span_id 缺省随机(本进程作为对端的 parent)。"""
     tid = (trace_id or uuid.uuid4().hex)[:32].rjust(32, "0")
     sid = (span_id or uuid.uuid4().hex[:16])[:16].rjust(16, "0")
@@ -88,13 +80,12 @@ def current_traceparent():
 
 
 class Trace:
-    def __init__(self, name: str, trace_id: str = None):
-        # 32 hex:直接符合 W3C traceparent 的 trace-id 规格(跨进程可对齐)
+    def __init__(self, name: str, trace_id: str | None = None):
         self.trace_id = trace_id or uuid.uuid4().hex
         self.name = name
         self.start_ts = time.time()
         self._t0 = time.perf_counter()
-        self.duration_ms = None
+        self.duration_ms: float | None = None
         self.spans: list = []
         self._lock = threading.Lock()
         self._dropped = 0
@@ -135,9 +126,8 @@ class TraceStore:
     def __init__(self, limit: int = 200):
         self._d: deque = deque(maxlen=limit)
         self._lock = threading.Lock()
-        self._db_path = None
+        self._db_path: str | None = None
 
-    # ── 持久化 ───────────────────────────────────────────
     def attach_db(self, path):
         """开启持久化并建表。连接**即建即弃、不跨线程复用**(与 ThoughtChain 同款):
         SQLite 连接不可跨线程共享,而 trace 写入发生在请求线程/to_thread 工作线程。"""
@@ -154,19 +144,21 @@ class TraceStore:
             self._db_path = None
 
     def _conn(self):
+        if self._db_path is None:
+            raise RuntimeError("trace 持久化未启用:先 attach_db")
         conn = sqlite3.connect(self._db_path, timeout=5.0)
         try:
-            conn.execute("PRAGMA journal_mode=WAL")   # 单写多读,降锁竞争
+            conn.execute("PRAGMA journal_mode=WAL")
         except sqlite3.OperationalError:
             pass
         return conn
 
     def _should_persist(self, tr: Trace) -> bool:
         if tr.has_error():
-            return True                                   # 出错的必留
+            return True
         if (tr.duration_ms or 0) >= _slow_ms():
-            return True                                   # 慢的必留(正是要查的)
-        return random.random() < _sample_rate()           # 其余按采样率(默认 0)
+            return True
+        return random.random() < _sample_rate()
 
     def _persist(self, tr: Trace):
         d = tr.to_dict()
@@ -176,7 +168,6 @@ class TraceStore:
                           (tr.trace_id, tr.name, tr.start_ts, tr.duration_ms,
                            d["span_count"], 0 if tr.has_error() else 1,
                            json.dumps(d["spans"], ensure_ascii=False)))
-                # 保留上限:超出删最旧 → 有界增长(不会把磁盘吃光)
                 c.execute("DELETE FROM traces WHERE trace_id IN ("
                           "SELECT trace_id FROM traces ORDER BY start_ts DESC "
                           "LIMIT -1 OFFSET ?)", (_retain(),))
@@ -187,10 +178,10 @@ class TraceStore:
         with self._lock:
             self._d.append(tr)
         if self._db_path and self._should_persist(tr):
-            self._persist(tr)                             # 锁外落库(慢 I/O 不挡内存环)
+            self._persist(tr)
         try:
-            OTLP.submit(tr)                               # 可选导出:未配 endpoint 即 no-op;
-        except Exception:                                 # 队列满则丢,绝不阻塞请求
+            OTLP.submit(tr)
+        except Exception:
             pass
 
     def get(self, trace_id: str):
@@ -219,7 +210,7 @@ class TraceStore:
                 "duration_ms": row[3], "span_count": row[4],
                 "spans": json.loads(row[5] or "[]"), "persisted": True}
 
-    def query(self, limit: int = 30, slow_ms: float = None, errors_only: bool = False):
+    def query(self, limit: int = 30, slow_ms: float | None = None, errors_only: bool = False):
         """查已落库的历史 trace(内存环之外)。这才是"找出昨天那次慢请求"的入口。"""
         if not self._db_path:
             return []
@@ -250,10 +241,6 @@ class TraceStore:
             self._d.clear()
 
 
-# ── OTLP/HTTP-JSON 导出(可选、零依赖)────────────────────────
-# 想接 Jaeger/Tempo/collector 的人设 FOXCLAW_OTLP_ENDPOINT 即可;不设则完全不启用、零成本。
-# 刻意**不引 opentelemetry-sdk**:OTLP 有 HTTP+JSON 传输,stdlib urllib 就能发。
-# 铁律:遥测**绝不能拖慢请求** —— 后台守护线程 + 有界队列,满了就丢(宁丢遥测不拖请求)。
 def _otlp_endpoint() -> str:
     return os.environ.get("FOXCLAW_OTLP_ENDPOINT", "").strip().rstrip("/")
 
@@ -272,16 +259,16 @@ def _trace_to_otlp(tr: "Trace") -> dict:
     root_id = uuid.uuid4().hex[:16]
     dur = (tr.duration_ms or 0.0) / 1000.0
     spans = [{
-        "traceId": tr.trace_id, "spanId": root_id, "name": tr.name, "kind": 2,   # SERVER
+        "traceId": tr.trace_id, "spanId": root_id, "name": tr.name, "kind": 2,
         "startTimeUnixNano": t_ns(tr.start_ts),
         "endTimeUnixNano": t_ns(tr.start_ts + dur),
         "status": {"code": 2 if tr.has_error() else 1},
     }]
     for s in tr.to_dict()["spans"]:
-        st = s.get("ts", tr.start_ts)                       # 缺 ts(手工 add_span)→ 兜底
+        st = s.get("ts", tr.start_ts)
         spans.append({
             "traceId": tr.trace_id, "spanId": uuid.uuid4().hex[:16], "parentSpanId": root_id,
-            "name": s.get("name", "span"), "kind": 1,       # INTERNAL
+            "name": s.get("name", "span"), "kind": 1,
             "startTimeUnixNano": t_ns(st),
             "endTimeUnixNano": t_ns(st + (s.get("ms", 0.0) / 1000.0)),
             "attributes": _attrs(s.get("meta")),
@@ -298,8 +285,8 @@ class _OtlpExporter:
 
     def __init__(self, maxsize: int = 512):
         import queue
-        self._q = queue.Queue(maxsize=maxsize)
-        self._th = None
+        self._q: queue.Queue[Any] = queue.Queue(maxsize=maxsize)
+        self._th: threading.Thread | None = None
         self._lock = threading.Lock()
         self.dropped = 0
         self.sent = 0
@@ -319,7 +306,7 @@ class _OtlpExporter:
         try:
             self._q.put_nowait(tr)
         except queue.Full:
-            self.dropped += 1        # 宁可丢遥测,也不让导出拖住请求线程
+            self.dropped += 1
 
     def _run(self):
         import urllib.request
@@ -338,7 +325,7 @@ class _OtlpExporter:
                 self.sent += 1
             except Exception as e:
                 self.failed += 1
-                if self.failed <= 3:      # 限量告警,别把日志刷爆
+                if self.failed <= 3:
                     logger.warning("OTLP 导出失败(不影响请求): %s", e)
 
     def stats(self) -> dict:
@@ -351,7 +338,7 @@ OTLP = _OtlpExporter()
 TRACES = TraceStore()
 
 
-def start_trace(name: str, trace_id: str = None) -> Trace:
+def start_trace(name: str, trace_id: str | None = None) -> Trace:
     """开一条 trace 并绑到当前上下文(由 API 中间件按请求调用)。"""
     tr = Trace(name, trace_id)
     _current.set(tr)
@@ -375,8 +362,6 @@ def span(name: str, **meta):
         yield None
         return
     t0 = time.perf_counter()
-    # ts:span 开始的 epoch 秒。内部只需 ms 就够,但 OTLP 要求每个 span 有 start/end 绝对时刻,
-    # 故一并记下(开销可忽略;缺失时导出侧会优雅兜底)。
     rec = {"name": name, "ts": time.time(), "ok": True,
            **({"meta": meta} if meta else {})}
     try:

package/python/foxclaw/core/truth_pipeline.py

@@ -16,6 +16,7 @@
 """
 from __future__ import annotations
 from datetime import datetime
+from typing import Any
 
 
 class TruthPipeline:
@@ -34,13 +35,10 @@ class TruthPipeline:
 
     def __init__(self, bus, hmr=None):
         self.bus = bus
-        self.hmr = hmr                 # 真实 HMR 记忆后端(可空,空则跳过记忆沉淀)
+        self.hmr = hmr
         self.last_trace = None
         self.last_memory_update = None
 
-        # 订阅事件链。【P4-1】三个都是精确 channel 名 → exact=True:
-        # 门面化后 SystemBus 默认是前缀匹配,不锁定的话 "execution.completed.extra"
-        # 之类的前缀事件也会触发真值链(语义漂移)。
         bus.subscribe("execution.completed", self._on_execution_completed, exact=True)
         bus.subscribe("trace.recorded", self._on_trace_recorded, exact=True)
         bus.subscribe("truth.appended", self._on_truth_appended, exact=True)
@@ -72,7 +70,6 @@ class TruthPipeline:
             self.last_memory_update = {"persisted": False, "reason": "blocked"}
             self.bus.publish("truth.skipped", {**p, "reason": "blocked"})
             return
-        # 真值 = "任务被如此处理"的事实 + 产出要点(信息量足够供日后召回)
         result_brief = str(p.get("result", ""))[:200]
         truth = {
             "fact": (f"任务「{p.get('task')}」由 {p.get('agent_id')} 处理。"
@@ -93,18 +90,17 @@ class TruthPipeline:
         【P3-5】双保险:_on_trace_recorded 已挡 blocked,这里再检查一次。
         """
         p = msg.payload
-        update = {"persisted": False}
+        update: dict[str, Any] = {"persisted": False}
         if self.hmr is not None and not p.get("blocked"):
             try:
-                # 沉淀到 HMR 共享层(所有 Agent 可见),用真实的 ingest 接口
                 content = p.get("truth", {}).get("fact", "")
                 origin_agent = p.get("agent_id", "unknown")
                 self.hmr.ingest(
                     content,
                     type="execution",
-                    agent_id="system",      # 【P3-0】系统级写入(非来源 Agent)
+                    agent_id="system",
                     title=f"真值_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
-                    tags=["truth_pipeline", f"origin:{origin_agent}"],   # 来源可追溯
+                    tags=["truth_pipeline", f"origin:{origin_agent}"],
                     shared=True,
                 )
                 update = {"persisted": True, "content": content}

package/python/foxclaw/core/update_check.py

@@ -0,0 +1,149 @@
+"""可选的新版本检查(默认关)。
+
+为什么默认关:foxclaw 的定位是本地优先 —— 默认外呼会让「断网也能用」多一个
+例外,也给安全审计多一个出网点。**只有** 设置 ``FOXCLAW_UPDATE_CHECK=1`` 时才会
+访问 PyPI,其余情况 ``status()`` 里 ``enabled=False``、``update_available=False``。
+
+失败一律静默:查版本是锦上添花,不能因为它让 ``/api/system/info`` 变慢或报错。
+- 结果按 24h 缓存到 ``<FOXCLAW_DATA_DIR>/update_check.json``;
+- 查询在 daemon 线程里跑,不阻塞请求;
+- 查失败时保留上次成功的结果(只是不刷新时间),避免一次网络抖动让提示消失。
+
+只发一个 GET ``https://pypi.org/pypi/foxclaw/json``,不带任何本机信息。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+_PYPI_URL = "https://pypi.org/pypi/foxclaw/json"
+_TTL = 24 * 3600
+_TIMEOUT = 3.0
+
+_lock = threading.Lock()
+_inflight = False
+_last_error: str | None = None
+
+
+def _enabled() -> bool:
+    return os.environ.get("FOXCLAW_UPDATE_CHECK", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _current() -> str:
+    from foxclaw import __version__
+
+    return __version__
+
+
+def _data_dir() -> Path:
+    return Path(os.environ.get("FOXCLAW_DATA_DIR") or "./foxclaw_data").expanduser()
+
+
+def _cache_path() -> Path:
+    return _data_dir() / "update_check.json"
+
+
+def parse_version(value: str) -> tuple[int, ...]:
+    """``"0.1.10"`` → ``(0, 1, 10)``。只取各段的前导数字,预发布/本地后缀丢掉。
+
+    不引入 ``packaging``:这里只需要「谁更新」,自己比数字段足够,也少一个依赖。
+    """
+    parts: list[int] = []
+    for chunk in str(value or "").strip().split("."):
+        digits = ""
+        for ch in chunk:
+            if not ch.isdigit():
+                break
+            digits += ch
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts)
+
+
+def is_newer(latest: str, current: str) -> bool:
+    """latest 是否严格新于 current(逐段比,缺的段补 0)。"""
+    left, right = parse_version(latest), parse_version(current)
+    width = max(len(left), len(right))
+    return left + (0,) * (width - len(left)) > right + (0,) * (width - len(right))
+
+
+def _read_cache() -> dict[str, Any]:
+    try:
+        data = json.loads(_cache_path().read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    try:
+        path = _cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _fetch_latest() -> str:
+    import urllib.request
+
+    req = urllib.request.Request(
+        _PYPI_URL,
+        headers={"Accept": "application/json", "User-Agent": f"foxclaw/{_current()}"},
+    )
+    with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:  # noqa: S310 - 地址是常量 https
+        payload = json.loads(resp.read().decode("utf-8", "replace"))
+    version = ((payload or {}).get("info") or {}).get("version") or ""
+    if not version:
+        raise ValueError("PyPI 响应里没有 info.version")
+    return str(version)
+
+
+def _refresh() -> None:
+    global _inflight, _last_error
+    try:
+        latest = _fetch_latest()
+        _write_cache({"latest": latest, "checked_at": time.time(), "current": _current()})
+        _last_error = None
+    except Exception as exc:
+        _last_error = f"{type(exc).__name__}: {exc}"
+    finally:
+        with _lock:
+            _inflight = False
+
+
+def maybe_refresh() -> None:
+    """启用且缓存过期 → 后台查一次。幂等、非阻塞,可放心在每个 system/info 里调。"""
+    global _inflight
+    if not _enabled():
+        return
+    checked = _read_cache().get("checked_at")
+    if isinstance(checked, (int, float)) and time.time() - checked < _TTL:
+        return
+    with _lock:
+        if _inflight:
+            return
+        _inflight = True
+    threading.Thread(target=_refresh, name="foxclaw-update-check", daemon=True).start()
+
+
+def status() -> dict[str, Any]:
+    """给 ``/api/system/info`` 的只读快照。未启用时 latest 仍是缓存值,但不报可更新。"""
+    enabled = _enabled()
+    current = _current()
+    cache = _read_cache()
+    latest = str(cache.get("latest") or "")
+    return {
+        "enabled": enabled,
+        "current": current,
+        "latest": latest or None,
+        "update_available": bool(enabled and latest and is_newer(latest, current)),
+        "checked_at": cache.get("checked_at"),
+        "error": _last_error,
+    }

package/python/foxclaw/core/vec_recall_adapter.py

@@ -31,9 +31,8 @@ from pathlib import Path
 from types import SimpleNamespace
 
 from .shared_write import guard_shared_write
+from typing import Any
 
-# Foxclaw 的 type 白名单 → vecRecall 的 memory_type(episodic/semantic/procedural)。
-# 分错不影响读写，但影响 vecRecall 的遗忘曲线与 procedural 精确匹配。
 _FOXCLAW_TO_VR = {
     "concept": "semantic",
     "project": "semantic",
@@ -52,7 +51,6 @@ _VR_TO_FOXCLAW = {
 }
 _VALID_TYPES = set(_FOXCLAW_TO_VR)
 
-# 偏好类记忆走 topic_key（精确查询），因为"总是注入的偏好"不该做语义模糊匹配。
 _PREFERENCE_TAG = "preference"
 
 
@@ -77,7 +75,7 @@ class _HKCSharedEmbedding:
     def __init__(self, model_name: str):
         self.model_name = model_name
         self._model = None
-        self._dim = None
+        self._dim: int | None = None
 
     def _load(self):
         if self._model is None:
@@ -85,8 +83,6 @@ class _HKCSharedEmbedding:
             from hkc_search.embedding_backends import get_st_model
             model = get_st_model(self.model_name)
             if model is None:
-                # 不回退到直连 SentenceTransformer：那会绕过 HKC 的进程级共享缓存、
-                # 多加载一份模型(bge-m3 常驻约 1GB)。失败就明确报错让工厂回退 HMR。
                 raise RuntimeError(
                     f"embedding 模型不可用: {self.model_name}(HKC 共享缓存加载失败)")
             self._model = model
@@ -105,7 +101,6 @@ class _HKCSharedEmbedding:
         if self._dim is None:
             try:
                 model = self._load()
-                # ST 6.x 把 get_sentence_embedding_dimension 改名了,两个都试
                 getter = (getattr(model, "get_embedding_dimension", None)
                           or getattr(model, "get_sentence_embedding_dimension", None))
                 self._dim = (int(getter() or 0) or None) if getter else None
@@ -120,7 +115,7 @@ class VecRecallAdapter:
     backend = "vecRecall"
 
     def __init__(self, storage_path: str = "./vecrecall_data", wing: str = "foxclaw",
-                 use_chain: bool = False, embedding_model: str = None,
+                 use_chain: bool = False, embedding_model: str | None = None,
                  dedup: bool = True, embedding_backend=None, vector_backend=None):
         """`embedding_backend` / `vector_backend` 用于注入（测试传轻量实现）。
 
@@ -133,9 +128,6 @@ class VecRecallAdapter:
         self.wing = wing
         self.storage_path = str(storage_path)
         self.version = self._resolve_version()
-        # vecRecall 本体没有任何锁（只有 REST server 层有 RLock），而它用的是
-        # check_same_thread=False 的单条 sqlite 连接 + 内存 dict 索引。并行子 Agent
-        # 同时 add/search 属于未定义行为，和 HMR 是同一类坑 —— 这里沿用同一套串行化。
         self._lock = threading.RLock()
 
         self._emb = embedding_backend or _HKCSharedEmbedding(
@@ -152,7 +144,6 @@ class VecRecallAdapter:
             **extra,
         )
 
-    # ── 构造辅助 ──────────────────────────────────────────
     @staticmethod
     def _resolve_version() -> str:
         try:
@@ -162,7 +153,7 @@ class VecRecallAdapter:
             return "unknown"
 
     @staticmethod
-    def _resolve_model(embedding_model: str = None) -> str:
+    def _resolve_model(embedding_model: str | None = None) -> str:
         """与 HMRAdapter 同一条解析链，保证两套后端用同一个模型（分数与维度可比）。"""
         return (embedding_model
                 or os.environ.get("EMBEDDING_MODEL")
@@ -188,14 +179,13 @@ class VecRecallAdapter:
         except Exception:
             return
         dims = {int(r[0]) for r in rows}
-        want = getattr(self._emb, "dim", None)   # 轻量后端无 dim 属性时跳过
+        want = getattr(self._emb, "dim", None)
         if dims and want and dims != {int(want)}:
             raise RuntimeError(
                 f"已有向量维度 {sorted(dims)} 与当前嵌入维度 {want} 不一致。"
                 f"换 embedding 模型必须重建索引：删除 {self.storage_path} 后重启"
             )
 
-    # ── 摄入 ──────────────────────────────────────────────
     _AUTO_TITLE = re.compile(r"^[A-Za-z_]+\s+\d{1,2}:\d{2}$")
 
     @staticmethod
@@ -214,8 +204,8 @@ class VecRecallAdapter:
         s = re.split(r"[。！？!?\n\r]", s, 1)[0].strip()
         return " ".join(s.split())[:80]
 
-    def ingest(self, content: str, type: str = "concept", agent_id: str = None,
-               title: str = None, tags: list = None, shared: bool = False, **kwargs):
+    def ingest(self, content: str, type: str = "concept", agent_id: str | None = None,
+               title: str | None = None, tags: list | None = None, shared: bool = False, **kwargs):
         """统一摄入。签名与 `HMRAdapter.ingest` 一致。
 
         隔离承载：`agent_id` → owner，`shared=True` → visibility="shared"。
@@ -231,8 +221,6 @@ class VecRecallAdapter:
         if not title:
             title = self._derive_title(content) or ""
 
-        # 【P0-3】共享层写入闸门：必须在落库之前判定，语义与 HMR 路径完全一致，
-        # 否则同一个策略在两个后端上表现不同。
         if shared:
             guard_shared_write(self, agent_id, content, mtype, meta_tags)
 
@@ -240,8 +228,6 @@ class VecRecallAdapter:
         if "confidence" in kwargs:
             metadata["confidence"] = kwargs["confidence"]
 
-        # execution 是审计证据：被遗忘曲线衰减或被去重合并，就无法再证明"当时确实
-        # 这么做了"。vecRecall 的 immutable 同时免于衰减与去重，正好对上这个语义。
         retention = "immutable" if mtype == "execution" else "decay"
         topic_key = kwargs.get("topic_key") or (
             _PREFERENCE_TAG if _PREFERENCE_TAG in meta_tags else "")
@@ -260,8 +246,7 @@ class VecRecallAdapter:
                 topic_key=topic_key,
             )
 
-    # ── 召回 ──────────────────────────────────────────────
-    def _visible(self, mem, agent_id: str, include_shared: bool) -> bool:
+    def _visible(self, mem, agent_id: str | None, include_shared: bool) -> bool:
         """可见性判定，与 vecRecall `_visible_to` 规则保持同源。
 
         - shared 记忆：仅当 include_shared 时可见
@@ -276,7 +261,7 @@ class VecRecallAdapter:
             return include_shared
         return owner == agent_id or not owner
 
-    def recall(self, query: str = "", agent_id: str = None, top_k: int = 5,
+    def recall(self, query: str = "", agent_id: str | None = None, top_k: int = 5,
                include_shared: bool = True, **kwargs):
         """统一召回，返回 list[dict]。
 
@@ -300,9 +285,6 @@ class VecRecallAdapter:
                 results = list(getattr(bundle, "l2_topic_context", []) or []) + \
                           list(getattr(bundle, "l3_deep_results", []) or [])
                 if not results and (query or "").strip():
-                    # L2 有 0.55 阈值：命中偏弱时整层为空。HMR 的 recall 是无条件
-                    # 返回 top_k，为不改变上层"总能拿到几条"的预期，退化到全量语义
-                    # 检索，再在下面用 _visible 补上隔离（search 本身不隔离）。
                     results = list(self._vr.search(query, n=fetch_k) or [])
         except Exception:
             return []
@@ -384,8 +366,7 @@ class VecRecallAdapter:
             row["_ts"] = getattr(m, "timestamp", "") or ""
             rows.append(row)
 
-        rows.sort(key=lambda x: str(x.get("_ts")), reverse=True)   # 新近优先
-        # 同一偏好反复表达会存成多条，去重保留最新，否则会挤满 limit
+        rows.sort(key=lambda x: str(x.get("_ts")), reverse=True)
         deduped, seen_c = [], set()
         for x in rows:
             if x["content"] in seen_c:
@@ -401,7 +382,6 @@ class VecRecallAdapter:
             except Exception:
                 return False
 
-    # ── 展示 ──────────────────────────────────────────────
     def recent(self, limit: int = 20) -> list:
         """最近的记忆条目（新→旧），供前端右栏"记忆信息条"。"""
         rows = []
@@ -435,11 +415,6 @@ class VecRecallAdapter:
             })
         return rows
 
-    # ── HMR 专有接口的占位 ────────────────────────────────
-    # vecRecall 没有"会话工作区 / 运行时快照"这两个概念。留占位而不是让调用方
-    # AttributeError：上层有统一的"后端接口"假设，缺方法会炸在一个与被调用能力
-    # 无关的地方。agents/base.py 取到 workspace 后并不读其字段（active_goal 的
-    # 写入已移除），所以空壳没有实际成本。
     def get_workspace(self, agent_id: str):
         return SimpleNamespace(agent_id=agent_id, active_goal="", status="idle",
                                push_task=lambda _t: None)
@@ -453,14 +428,13 @@ class VecRecallAdapter:
     def restore_runtime_state(self):
         return None
 
-    # ── 状态 ──────────────────────────────────────────────
     def get_system_status(self):
         return {"backend": self.backend, "version": self.version, "wing": self.wing}
 
     def stats(self) -> dict:
         """记忆统计：前端记忆中心展示真实数字。字段与 HMRAdapter.stats 一致。"""
         total = shared_count = relations = 0
-        by_agent = {}
+        by_agent: dict[str, Any] = {}
         embedding = type(self._emb).__name__
         try:
             with self._lock:

package/python/foxclaw/core/verify.py

@@ -25,17 +25,15 @@ from dataclasses import dataclass, field
 from urllib.parse import urlparse
 
 from . import failure_policy as _policy
+from typing import Callable
 
 VERIFIED = "verified"
 UNVERIFIED = "unverified"
 FAILED = "failed"
 
-#: 每条工具结果最多挂几条证据(再多就成了噪声,用户不会看)
 MAX_EVIDENCE = 8
 
 _URL_RE = re.compile(r"https?://[^\s<>\"'）)\]}]+")
-#: 只保留"真实存在"的路径 —— 正则从文本里认出来的路径九成是误报(URL 片段、示例路径),
-#: 只有能在磁盘上 stat 到的才算证据。这不是限制,是"证据"二字的含义。
 _WIN_PATH_RE = re.compile(r"[A-Za-z]:[\\/][^\s\"'<>|*?，。；]+")
 _POSIX_PATH_RE = re.compile(r"(?<![\w:])/(?:[\w.\-]+/)+[\w.\-]+")
 
@@ -44,10 +42,10 @@ _POSIX_PATH_RE = re.compile(r"(?<![\w:])/(?:[\w.\-]+/)+[\w.\-]+")
 class Evidence:
     """一条可核对的凭据:一个链接、一个真实存在的文件、或一次工具的原始命中。"""
 
-    kind: str                     # url / file
-    ref: str                      # 链接或绝对路径
-    label: str                    # 展示名(域名 / 文件名)
-    source: str                   # 哪个工具产出的
+    kind: str
+    ref: str
+    label: str
+    source: str
     at: float = field(default_factory=time.time)
 
     def to_dict(self) -> dict:
@@ -121,14 +119,10 @@ def extract_evidence(source: str, text: str, limit: int = MAX_EVIDENCE) -> list[
     return out
 
 
-#: 工具专属的后置条件检查。返回 (是否通过, 不通过的原因)。
-#: 没登记的工具走通用规则(见 verify),不会被当成"已验证"。
-_CHECKERS: dict[str, "callable"] = {
-    # 联网搜索:结论必须能指回来源,否则就是"模型自己写的" —— 标未核验而不是验证通过
+_CHECKERS: dict[str, Callable[..., tuple[bool, str]]] = {
     "web_search": lambda args, text: (
         (True, "") if _URL_RE.search(text or "")
         else (False, "搜索结果没有可核对的来源链接")),
-    # 个人记忆:召回为空是合法结果(确实没记过),非空即有凭据
     "recall_memory": lambda args, text: (
         (True, "") if (text or "").strip().startswith("【召回的相关记忆】")
         else (False, "未返回记忆条目")),
@@ -157,9 +151,7 @@ def verify(name: str, args: dict | None, text: str,
 
     read_only = bool((capability or {}).get("read_only"))
     if read_only:
-        # 只读 + 有返回 = 这一步确实发生过(内容是否可信由污点/证据层管)
         return Verification(VERIFIED, evidence=ev)
-    # 有副作用但没登记后置条件:不能证明效果已发生 → 未核验(不许声称完成)
     return Verification(UNVERIFIED, reason="该工具未声明可观察的后置条件", evidence=ev)