foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/core/steering_queue.py

@@ -21,17 +21,18 @@ import threading
 import time
 import uuid
 from dataclasses import dataclass, field
+from typing import Any
 
 
 @dataclass
 class SteeringItem:
     item_id: str
-    requester: str                 # 谁在等这个结果(主任务/会话标识)
-    source_agent: str              # 哪个子 Agent 产出的
-    payload: dict                  # 结果内容
+    requester: str
+    source_agent: str
+    payload: dict
     created: float = field(default_factory=time.time)
-    leased_until: float = 0.0      # 0 = 未租出;>0 = 租约到期时间戳
-    lease_id: str = ""             # 当前租约持有者标识
+    leased_until: float = 0.0
+    lease_id: str = ""
 
     @property
     def is_leased(self) -> bool:
@@ -60,7 +61,7 @@ class SteeringQueue:
                 source_agent=source_agent, payload=payload)
             return item_id
 
-    def lease(self, requester: str = None, max_items: int = 10) -> list[SteeringItem]:
+    def lease(self, requester: str | None = None, max_items: int = 10) -> list[SteeringItem]:
         """租走一批待处理结果(可按 requester 过滤)。
 
         原子地:挑出未被租用(或租约已过期)的项,标记为 leased,返回。
@@ -69,7 +70,7 @@ class SteeringQueue:
         with self._lock:
             self._reclaim_expired()
             now = time.time()
-            leased = []
+            leased: list[Any] = []
             lease_id = uuid.uuid4().hex[:12]
             for item in self._items.values():
                 if len(leased) >= max_items:
@@ -83,7 +84,7 @@ class SteeringQueue:
                 leased.append(item)
             return leased
 
-    def ack(self, item_id: str, lease_id: str = None) -> bool:
+    def ack(self, item_id: str, lease_id: str | None = None) -> bool:
         """消费者确认处理完 → 移除该项。
 
         校验 lease_id:只有持有当前租约的消费者能 ack(防止过期租约误删
@@ -94,7 +95,7 @@ class SteeringQueue:
             if item is None:
                 return False
             if lease_id is not None and item.lease_id != lease_id:
-                return False        # 租约不匹配(可能已过期被别人租走)
+                return False
             del self._items[item_id]
             return True
 
@@ -114,7 +115,7 @@ class SteeringQueue:
                 item.leased_until = 0.0
                 item.lease_id = ""
 
-    def pending_count(self, requester: str = None) -> int:
+    def pending_count(self, requester: str | None = None) -> int:
         """待处理(未被有效租用)的项数。"""
         with self._lock:
             self._reclaim_expired()
@@ -145,7 +146,7 @@ class SteeringQueue:
                 if item.requester != requester:
                     continue
                 if item.is_leased:
-                    continue        # 正被租用 → 留给租约消费者,drain 不碰
+                    continue
                 out.append(item.payload)
                 to_del.append(item_id)
             for item_id in to_del:

package/python/foxclaw/core/system_bus.py

@@ -73,7 +73,7 @@ class SystemBus:
     def publish(self, channel: str, payload: dict):
         return self.spine.publish(channel, payload, source="system_bus")
 
-    def history(self, channel: str = None, limit: int = 50,
+    def history(self, channel: str | None = None, limit: int = 50,
                 exact: bool = False) -> list:
         """历史事件(dict 列表)。exact=True 时只返回 topic 完全匹配的事件
         (默认前缀匹配,与 EventSpine 原生一致)。"""

package/python/foxclaw/core/thought_chain.py

@@ -16,16 +16,16 @@ from pathlib import Path
 
 
 NodeType = Literal[
-    "goal",        # 目标基线节点（根）
-    "reasoning",   # 推理步骤
-    "memory_retrieval",  # 记忆检索
-    "tool_intent", # 工具意图
-    "tool_use",    # 工具实际调用（augment.py 已在用；此前漏登记，类型面是欠账）
-    "plan",        # 显式计划（steps/flow 落在 metadata，供回显与审计）
-    "decision",    # 行动决策
-    "policy_update",  # Policy 候选更新
-    "consolidation",  # 记忆巩固写回
-    "reflection",  # 执行后反思
+    "goal",
+    "reasoning",
+    "memory_retrieval",
+    "tool_intent",
+    "tool_use",
+    "plan",
+    "decision",
+    "policy_update",
+    "consolidation",
+    "reflection",
 ]
 
 HarnessStatus = Literal["BASELINE", "PASS", "WARN", "BLOCK", "PENDING", "REGRESSION"]
@@ -39,15 +39,15 @@ class ThoughtNode:
     agent_id: str
     type: NodeType
     content: str
-    conf: float                        # 置信度 0.0-1.0
-    mem_refs: list[str]               # 引用的 HMR 记忆 ID
-    parent_ids: list[str]             # 父节点 ID（因果依赖）
+    conf: float
+    mem_refs: list[str]
+    parent_ids: list[str]
     harness_status: HarnessStatus
-    harness_reason: Optional[str]     # BLOCK/WARN 时的原因
-    harness_delta: Optional[float]    # 目标漂移量
-    dominant_dim: Optional[str]       # 主导漂移维度
-    tool_name: Optional[str]          # 如果是 tool_intent 节点
-    entities: list[str]              # 涉及的实体集合
+    harness_reason: Optional[str]
+    harness_delta: Optional[float]
+    dominant_dim: Optional[str]
+    tool_name: Optional[str]
+    entities: list[str]
     timestamp: str
     metadata: dict
 
@@ -59,11 +59,11 @@ class ThoughtNode:
         type: NodeType,
         content: str,
         conf: float = 1.0,
-        mem_refs: list[str] = None,
-        parent_ids: list[str] = None,
-        tool_name: str = None,
-        entities: list[str] = None,
-        metadata: dict = None,
+        mem_refs: list[str] | None = None,
+        parent_ids: list[str] | None = None,
+        tool_name: str | None = None,
+        entities: list[str] | None = None,
+        metadata: dict | None = None,
     ) -> "ThoughtNode":
         return cls(
             id=f"tn_{uuid.uuid4().hex[:12]}",
@@ -150,7 +150,7 @@ class ThoughtChain:
         try:
             conn.execute("PRAGMA journal_mode=WAL")
         except sqlite3.OperationalError:
-            pass  # 个别文件系统不支持 WAL(如网络盘)→ 退回默认日志模式,timeout 仍生效
+            pass
         try:
             yield conn
             conn.commit()
@@ -183,9 +183,9 @@ class ThoughtChain:
         self,
         node_id: str,
         status: HarnessStatus,
-        reason: str = None,
-        delta: float = None,
-        dominant_dim: str = None,
+        reason: str | None = None,
+        delta: float | None = None,
+        dominant_dim: str | None = None,
     ):
         """Harness 校验完成后更新节点标注"""
         with self._conn() as conn:
@@ -202,7 +202,7 @@ class ThoughtChain:
             ).fetchone()
         return self._row_to_node(row) if row else None
 
-    def get_chain(self, session_id: str, agent_id: str = None) -> list[ThoughtNode]:
+    def get_chain(self, session_id: str, agent_id: str | None = None) -> list[ThoughtNode]:
         """获取一个会话的完整推理链，按时间排序"""
         with self._conn() as conn:
             if agent_id:
@@ -217,7 +217,7 @@ class ThoughtChain:
                 ).fetchall()
         return [self._row_to_node(r) for r in rows]
 
-    def get_blocked_nodes(self, agent_id: str = None, limit: int = 50) -> list[ThoughtNode]:
+    def get_blocked_nodes(self, agent_id: str | None = None, limit: int = 50) -> list[ThoughtNode]:
         """获取被 Harness 截断的节点，用于审计"""
         with self._conn() as conn:
             if agent_id:
@@ -232,7 +232,7 @@ class ThoughtChain:
                 ).fetchall()
         return [self._row_to_node(r) for r in rows]
 
-    def search_nodes(self, keyword: str, agent_id: str = None,
+    def search_nodes(self, keyword: str, agent_id: str | None = None,
                      limit: int = 20) -> list[ThoughtNode]:
         """按关键词在推理节点内容里检索(LIKE 子串匹配)。供 HSR 的 AgentSourcePort
         把「各 Agent 想过/判过什么」连通进内部搜索。只读。"""
@@ -307,8 +307,6 @@ class ThoughtChain:
             "timestamp", "metadata"
         ]
         d = dict(zip(cols, row))
-        # JSON 字段容错:单行某字段损坏时降级为默认值,而非让整个审计链读取崩溃。
-        # 审计系统的可靠性要求"一条坏数据不拖垮全部"。
         for field, default in (("mem_refs", []), ("parent_ids", []),
                                ("entities", []), ("metadata", {})):
             try:

package/python/foxclaw/core/token_meter.py

@@ -36,7 +36,6 @@ def estimate_tokens(text: str, model: str = "") -> int:
             enc = tiktoken.get_encoding("cl100k_base")
         return len(enc.encode(text))
     except Exception:
-        # 字符估算:中文(非ASCII)按 1.1 字符/token,英文(ASCII)按 4 字符/token。
         ascii_chars = sum(1 for c in text if ord(c) < 128)
         cjk_chars = len(text) - ascii_chars
         return int(ascii_chars / 4 + cjk_chars * 1.1) + 1
@@ -50,8 +49,8 @@ class CallRecord:
     agent_id: str
     input_tokens: int
     output_tokens: int
-    estimated: bool          # True=估算,False=API真实usage
-    task_kind: str = ""      # 可选:single/multi/...
+    estimated: bool
+    task_kind: str = ""
 
     @property
     def total_tokens(self) -> int:
@@ -66,14 +65,14 @@ class CallRecord:
 class TokenMeter:
     """Token 计量器。线程安全,可聚合,可落盘。"""
 
-    def __init__(self, log_path: str = None, max_records: int = 10000,
+    def __init__(self, log_path: str | None = None, max_records: int = 10000,
                  max_log_mb: float = 10.0):
         self.log_path = log_path
         self.max_records = max_records
         self.max_log_bytes = int(max_log_mb * 1024 * 1024)
         self._records: list[CallRecord] = []
         self._lock = threading.RLock()
-        self._append_count = 0     # 触发轮转检查的计数器
+        self._append_count = 0
         if log_path:
             os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
 
@@ -94,7 +93,7 @@ class TokenMeter:
 
     def measure_call(self, *, system: str, messages: list, output: str,
                      provider: str, model: str, agent_id: str = "",
-                     usage: dict = None, task_kind: str = "") -> CallRecord:
+                     usage: dict | None = None, task_kind: str = "") -> CallRecord:
         """计量一次调用。优先用 API 返回的 usage,否则估算。
 
         usage 形如 {"input_tokens": N, "output_tokens": M}(已由 router 归一化)。
@@ -104,7 +103,6 @@ class TokenMeter:
                                usage.get("input_tokens", 0),
                                usage.get("output_tokens", 0),
                                estimated=False, task_kind=task_kind)
-        # 估算:输入 = system + 所有 message content,输出 = output
         input_text = (system or "") + "\n".join(
             str(m.get("content", "")) for m in (messages or []))
         in_tok = estimate_tokens(input_text, model)
@@ -112,7 +110,6 @@ class TokenMeter:
         return self.record(provider, model, agent_id, in_tok, out_tok,
                            estimated=True, task_kind=task_kind)
 
-    # ── 聚合查询 ──────────────────────────────────────────
     def summary(self) -> dict:
         """总体统计。"""
         with self._lock:
@@ -211,8 +208,7 @@ class TokenMeter:
             with open(self.log_path, "a", encoding="utf-8") as f:
                 f.write(json.dumps(rec.to_dict(), ensure_ascii=False) + "\n")
         except Exception:
-            pass        # 计量落盘失败不影响主流程
-        # 每 100 次追加检查一次文件大小,超限则轮转(防磁盘无限膨胀)
+            pass
         self._append_count += 1
         if self._append_count % 100 == 0:
             self._rotate_if_needed()
@@ -226,10 +222,10 @@ class TokenMeter:
                 return
             with open(self.log_path, encoding="utf-8") as f:
                 lines = f.readlines()
-            keep = lines[len(lines) // 2:]      # 保留较新的一半
+            keep = lines[len(lines) // 2:]
             tmp = self.log_path + ".tmp"
             with open(tmp, "w", encoding="utf-8") as f:
                 f.writelines(keep)
-            os.replace(tmp, self.log_path)      # 原子替换
+            os.replace(tmp, self.log_path)
         except Exception:
-            pass        # 轮转失败不影响主流程
+            pass

package/python/foxclaw/core/tools.py

@@ -15,6 +15,7 @@ Foxclaw — 工具注册表(ToolRegistry / P2 function-calling)
 """
 from __future__ import annotations
 import os
+from typing import Any
 
 
 def _tool(name: str, description: str, properties: dict, required: list) -> dict:
@@ -33,7 +34,6 @@ def _tool(name: str, description: str, properties: dict, required: list) -> dict
     }
 
 
-# ── 首批工具声明(高价值、正好替掉现有关键词坑)──────────────────────────────
 WEB_SEARCH = _tool(
     "web_search",
     "联网搜索实时/时效性的**外部**信息:新闻、产品的版本与型号、发布动态、价格、汇率、"
@@ -113,15 +113,15 @@ class ToolRegistry:
         for k in required:
             if k not in args or args[k] in (None, ""):
                 errs.append(f"缺少必填参数 {k}")
-        _tmap = {"string": str, "integer": int, "number": (int, float),
+        _tmap: dict[str, Any] = {"string": str, "integer": int, "number": (int, float),
                  "boolean": bool, "array": list, "object": dict}
         for k, v in args.items():
             spec = props.get(k)
             if not isinstance(spec, dict):
                 continue
-            want = _tmap.get(spec.get("type"))
+            stype = spec.get("type")
+            want = _tmap.get(stype) if isinstance(stype, str) else None
             if not want or not isinstance(v, want):
-                # bool 是 int 的子类,须排除,否则 True 会被当成合法 integer
                 if not (want is not bool and isinstance(v, bool)):
                     errs.append(f"参数 {k} 类型应为 {spec.get('type')},"
                                 f"实为 {type(v).__name__}")
@@ -143,20 +143,12 @@ def default_registry() -> ToolRegistry:
     return ToolRegistry().register(WEB_SEARCH).register(RECALL_MEMORY)
 
 
-# ── 工具能力分级(供 permission.evaluate 四阶段管线判定)────────────────────────
-# 病根提醒:prompt 级隔离挡不住弱模型被块内强指令诱导(实测 flash ~2/3 被劫持),真正的
-# 安全阀在**动作级**——工具执行前过权限管线,写/副作用/不可逆动作走人在回路(HITL)。
-# 字段对齐 permission.evaluate:side_effect(read/write/send/pay)/ read_only / external / destructive。
-# parallel_safe 不在权限语义里,只用于**同轮多工具是否可并发**:置 True 表示"纯读、可与其他
-# parallel_safe 工具同时跑"(见 agents/mixins/tool_exec.py::_run_tools)。未声明 = 串行。
-# **新增任何工具都应在此声明能力;未声明者 fail-closed 当作有副作用 → 强制 HITL(见 _DEFAULT_CAP)。**
 TOOL_CAPABILITIES: dict[str, dict] = {
     "web_search":    {"side_effect": "read", "read_only": True, "external": False,
                       "destructive": False, "parallel_safe": True},
     "recall_memory": {"side_effect": "read", "read_only": True, "external": False,
                       "destructive": False, "parallel_safe": True},
 }
-# 未声明工具的兜底:当有副作用 + 外部 → permission 管线判 ask → 强制人在回路。宁误拦不漏放。
 _DEFAULT_CAP = {"side_effect": "write", "read_only": False, "external": True, "destructive": False}
 
 

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}