foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/finance/runtime.py

@@ -11,12 +11,13 @@ from dataclasses import fields
 from datetime import datetime
 from pathlib import Path
 
-from .models import Transaction, Budget, FinancialEntity
+from .models import Budget, EntityType, FinancialEntity, Transaction
 from .reasoning import FinanceReasoning
 from .policy import FinancePolicyEngine
 from .graph import FinancialDataGraph
 from .fx import FxTable
 from .nlparse import CATEGORY_LABELS, parse as parse_expense_text
+from typing import Any
 
 
 def _period_of(txn, default: str = "") -> str:
@@ -46,27 +47,22 @@ class FinanceRuntime:
     """财务 Agent 的资金行为操作系统内核。"""
 
     def __init__(self, policy_path: str = "./finance_policy.yaml", hmr=None,
-                 data_path: str = None):
+                 data_path: str | None = None):
         self.transactions: list = []
         self.budgets: list = []
-        self.entities: dict = {}            # name -> FinancialEntity
-        self.account_balances: dict = {}    # account -> balance
+        self.entities: dict = {}
+        self.account_balances: dict = {}
         self.policy = FinancePolicyEngine(policy_path)
         self.reasoning = FinanceReasoning()
-        self.hmr = hmr                      # 可选:把交易写入 HMR 共享认知
-        # 交易/预算/余额/实体的落盘点:默认与 policy 同目录(调用方传的就是 data_dir)。
-        # 此前这些只在内存,进程一重启就清零 → 财务分析永远是"0 笔交易"。
+        self.hmr = hmr
         self._data_path = Path(data_path) if data_path else (
             Path(policy_path).resolve().parent / "finance_data.json")
-        # 写侧串行:runtime 是单例,请求线程会并发 add/import,analyze 还会触发阈值自校准写盘。
         self._lock = threading.RLock()
         self.load_error: str = ""
         self.save_error: str = ""
-        # 多币种:账本按本位币(CNY)算账,汇率表与账本同目录
         self.fx = FxTable(str(self._data_path.parent / "finance_fx.json"))
         self.load()
 
-    # ── 持久化(原子写 tmp→replace;损坏文件只降级、不阻断启动)──────
     def load(self) -> int:
         """从落盘点恢复交易/预算/余额/实体,返回恢复的交易条数。
 
@@ -106,7 +102,7 @@ class FinanceRuntime:
                 except (TypeError, ValueError):
                     continue
         if not self.entities and self.transactions:
-            self._rebuild_entities()        # 实体段缺失(旧格式/被裁)→ 按交易重算
+            self._rebuild_entities()
         return len(self.transactions)
 
     def save(self) -> bool:
@@ -127,11 +123,9 @@ class FinanceRuntime:
                                encoding="utf-8")
                 tmp.replace(self._data_path)
                 self.save_error = ""
-                # 文件已被本进程的完整快照覆盖 → 上一轮"读不进来"的原因作废(自愈)
                 self.load_error = ""
                 return True
             except Exception as e:
-                # 落盘失败不能假装成功:留在内存里 + 暴露错误,让调用方/界面能看到
                 self.save_error = f"{type(e).__name__}: {e}"
                 return False
 
@@ -140,7 +134,7 @@ class FinanceRuntime:
         for txn in self.transactions:
             ent = self.entities.get(txn.entity)
             if not ent:
-                etype = "subscription" if txn.is_recurring else "merchant"
+                etype: EntityType = "subscription" if txn.is_recurring else "merchant"
                 ent = FinancialEntity(name=txn.entity, entity_type=etype)
                 self.entities[txn.entity] = ent
             ent.txn_count += 1
@@ -149,17 +143,15 @@ class FinanceRuntime:
             if txn.is_recurring:
                 ent.recurring_amount = abs(txn.amount)
 
-    # ── 数据录入 ──────────────────────────────────────────
     def add_transaction(self, txn: Transaction,
                         run_gatekeeper: bool = True,
                         save: bool = True) -> dict:
         """录入一笔交易,经过守门人裁决,并落盘(save=False 供批量导入只写一次)。"""
         with self._lock:
             self.transactions.append(txn)
-            # 更新实体统计
             ent = self.entities.get(txn.entity)
             if not ent:
-                etype = "subscription" if txn.is_recurring else "merchant"
+                etype: EntityType = "subscription" if txn.is_recurring else "merchant"
                 ent = FinancialEntity(name=txn.entity, entity_type=etype)
                 self.entities[txn.entity] = ent
             ent.txn_count += 1
@@ -168,7 +160,6 @@ class FinanceRuntime:
             if txn.is_recurring:
                 ent.recurring_amount = abs(txn.amount)
 
-            # 写入 HMR(可选)
             if self.hmr:
                 try:
                     self.hmr.ingest(
@@ -179,7 +170,6 @@ class FinanceRuntime:
                 except Exception:
                     pass
 
-            # 守门人裁决
             verdicts = []
             if run_gatekeeper:
                 bal = self.account_balances.get(txn.account)
@@ -190,7 +180,6 @@ class FinanceRuntime:
                 "gated": any(v.action in ("veto", "freeze", "require_confirmation")
                              for v in verdicts),
             }
-        # 写盘放在锁外:避免一次磁盘 IO 把并发进来的读请求全堵住
         if save:
             self.save()
         return result
@@ -206,9 +195,8 @@ class FinanceRuntime:
             self.account_balances[account] = balance
         self.save()
 
-    # ── 自然语言记账(第一线功能)────────────────────────────
     def record_text(self, text: str, account: str = "default",
-                    now: datetime = None, dry_run: bool = False) -> dict:
+                    now: datetime | None = None, dry_run: bool = False) -> dict:
         """「今天买了一件衣服花了 105 块」→ 落一笔账,返回可读回执。
 
         识别(金额/币种/时间/分类)全部走 `nlparse` 的确定性规则,LLM 不参与算钱。
@@ -279,7 +267,6 @@ class FinanceRuntime:
             lines.append(f"· {day} {it.get('description') or it.get('entity') or ''}"
                          f" {money} · {label}{flag}")
 
-        # 汇总期跟着这笔账走:记的是上月 5 号的账,就别报"本月已花"
         period = (items[0].get("timestamp") or "")[:7] or None
         led = self.ledger(period)
         head = "本月" if period == datetime.now().strftime("%Y-%m") else f"{period} "
@@ -298,7 +285,7 @@ class FinanceRuntime:
             lines.append("提示:" + "；".join(warns))
         return "\n".join(lines)
 
-    def ledger(self, period: str = None) -> dict:
+    def ledger(self, period: str | None = None) -> dict:
         """记账本:按月汇总(已发生 vs 计划、按天、按分类、按币种)。"""
         period = period or datetime.now().strftime("%Y-%m")
         with self._lock:
@@ -311,7 +298,9 @@ class FinanceRuntime:
         expense = round(sum(t.amount for t in settled if t.amount < 0), 2)
         income = round(sum(t.amount for t in settled if t.amount > 0), 2)
 
-        by_day, by_cat, by_cur = {}, {}, {}
+        by_day: dict[str, dict[str, Any]] = {}
+        by_cat: dict[str, dict[str, Any]] = {}
+        by_cur: dict[str, dict[str, Any]] = {}
         for t in settled:
             day = (t.timestamp or "")[:10]
             d = by_day.setdefault(day, {"date": day, "expense": 0.0, "income": 0.0,
@@ -376,14 +365,12 @@ class FinanceRuntime:
     def import_csv(self, path: str) -> int:
         """从 CSV 导入交易。列:amount,category,entity,account,timestamp,tags
         真实银行 API 接口可在此处替换/扩展。"""
-        path = Path(path)
+        csv_path = Path(path)
         count = 0
-        with open(path, encoding="utf-8") as f:
+        with open(csv_path, encoding="utf-8") as f:
             reader = csv.DictReader(f)
             for row in reader:
                 tags = [t.strip() for t in (row.get("tags") or "").split("|") if t.strip()]
-                # 可选的 currency 列:外币行按当天记账汇率折成本位币再入账,
-                # 否则「100 美元」会和「100 元」一起被求和。
                 cur = (row.get("currency") or row.get("币种") or "CNY").strip().upper()
                 raw = float(row["amount"])
                 base, rate = self.fx.to_base(abs(raw), cur)
@@ -401,11 +388,10 @@ class FinanceRuntime:
                 self.add_transaction(txn, run_gatekeeper=False, save=False)
                 count += 1
         if count:
-            self.save()      # 批量导入只落盘一次,不按每笔交易各做一次磁盘 IO
+            self.save()
         return count
 
-    # ── 综合分析(财务 Agent 的核心输出)──────────────────
-    def analyze(self, period: str = None, current_balance: float = None,
+    def analyze(self, period: str | None = None, current_balance: float | None = None,
                 calibrate: bool = True) -> dict:
         """一次性产出完整财务洞察:预算/风险/预测/守门人裁决。
 
@@ -413,17 +399,12 @@ class FinanceRuntime:
         再裁决 —— 让阈值随消费水平自己长,而不是永远停在出厂拍的经验值上。
         """
         period = period or datetime.now().strftime("%Y-%m")
-        # 快照:分析期间可能有并发录入(持久化后 import 端点就是可并发的写方),
-        # 直接遍历 self.transactions 会撞上 "list changed size during iteration"。
-        # 计划支出(明天/下个月)必须排除:还没发生的钱不能算进"本月已花",
-        # 否则「明天交房租 3000」会立刻把这个月的预算打爆。
         txns = [t for t in self.transactions if not getattr(t, "is_planned", False)]
         budgets = list(self.budgets)
         bal = current_balance
         if bal is None and self.account_balances:
             bal = sum(dict(self.account_balances).values())
 
-        # 阈值自校准:必须在裁决**之前**,否则这次分析用的还是上一轮的旧阈值
         calibration = (self.policy.apply_calibration(
             self.reasoning.calibrate_thresholds(txns)) if calibrate else [])
 
@@ -435,21 +416,16 @@ class FinanceRuntime:
         cashflow = (self.reasoning.cashflow_projection(txns, bal)
                     if bal is not None else None)
 
-        # 超支预测(对每个有预算的分类)—— 提到裁决之前算,好一并交给守门人
         forecasts = [self.reasoning.overspend_forecast(txns, b, period)
                      for b in budgets]
         renewals = self.reasoning.detect_upcoming_renewals(txns)
         pending_refunds = self.reasoning.detect_pending_refunds(txns)
 
-        # 守门人对整体状态裁决
-        # duplicates/forecasts 此前已被算出来、却只进报告不进裁决(检测到了却不吭声);
-        # renewals/pending_refunds 为新增信号。现在一并交给守门人。
         state_verdicts = self.policy.evaluate_state(
             subscription_total=sub_creep["monthly_total"], anomalies=anomalies,
             duplicates=duplicates, forecasts=forecasts,
             renewals=renewals, pending_refunds=pending_refunds)
 
-        # 结构化证据链(可解释决策,可沉淀到 ThoughtChain)
         from .evidence import FinanceExplainer
         evidence_chains = [
             FinanceExplainer.explain_budget_risk(budget_status).to_dict(),
@@ -467,11 +443,10 @@ class FinanceRuntime:
             "burn_rate": burn,
             "cashflow_projection": cashflow,
             "gatekeeper_verdicts": [v.to_dict() for v in state_verdicts],
-            "threshold_calibration": calibration,   # 阈值自己变了要让用户看见,不能偷偷改
+            "threshold_calibration": calibration,
             "evidence_chains": evidence_chains,
         }
 
-    # ── 守门人审批流(不自动动钱)─────────────────────────
     def request_action(self, action_type: str, detail: dict) -> dict:
         """请求一个资金操作(如取消订阅、转账)。
         不自动执行——返回审批请求,标记需用户确认 / 需接真实支付 API。"""
@@ -489,7 +464,6 @@ class FinanceRuntime:
             "entities": len(self.entities),
             "accounts": self.account_balances,
             "policy": self.policy.summary(),
-            # 落盘状态一并回给界面:否则"数据到底存哪了/为什么重启就没了"只能靠猜
             "persist": {"path": str(self._data_path),
                         "exists": self._data_path.exists(),
                         "load_error": self.load_error,
@@ -513,7 +487,6 @@ class FinanceRuntime:
         返回:匹配/差异分类 + 审计日志。
         """
         from .reconcile import Reconciler, ExternalRecord
-        # 容忍 dict 输入,自动转 ExternalRecord
         ext = []
         for r in external_records:
             if isinstance(r, ExternalRecord):

package/python/foxclaw/governance/middleware.py

@@ -13,25 +13,25 @@ import functools
 import tempfile
 import uuid
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import Optional, cast
 
 from ..harness.harness import Harness
 from ..harness.loop_detection import ToolLoopDetector
-from ..core.thought_chain import ThoughtChain, ThoughtNode
+from ..core.thought_chain import NodeType, ThoughtChain, ThoughtNode
 
 
 @dataclass
 class GovResult:
     """一步治理判定的结果(框架无关,不泄露 Foxclaw 内部类型)。"""
-    status: str                      # PASS / WARN / BLOCK
+    status: str
     blocked: bool
     warned: bool
     delta: float
-    dimension: str                   # 主导漂移维度 semantic/tool/scope
+    dimension: str
     reason: Optional[str]
     node_id: str
-    scores: dict = field(default_factory=dict)   # 各维度分 semantic/tool/scope
-    loop: Optional[dict] = None      # 若检出工具死循环,填充告警
+    scores: dict = field(default_factory=dict)
+    loop: Optional[dict] = None
 
     @property
     def tool_violation(self) -> bool:
@@ -74,8 +74,8 @@ class GovernanceSession:
 
     def __init__(self, goal: str, allowed_tools=None, entities=None,
                  agent_id: str = "agent", shadow_rounds: int = 0,
-                 db_path: str = None, policy_path: str = None,
-                 embedding_model: str = None):
+                 db_path: str | None = None, policy_path: str | None = None,
+                 embedding_model: str | None = None):
         self.agent_id = agent_id
         self._session_id = f"gov_{uuid.uuid4().hex[:10]}"
         self.thought_chain = ThoughtChain(
@@ -88,17 +88,13 @@ class GovernanceSession:
             goal_text=goal,
             allowed_tool_categories=set(allowed_tools or {"read"}),
             baseline_entities=set(entities or []))
-        # shadow_rounds<=0:中间件默认**即时按默认阈值判定**(warn 0.15 / block 0.25),
-        # 不做"拿第一个样本自校准"(那会让首步逃逸并用单样本污染阈值)。想用真实分布
-        # 校准的调用方,显式传 shadow_rounds>0 走观测期。
         if shadow_rounds <= 0:
             self.harness._shadow_mode = False
         self._loop = ToolLoopDetector()
         self._blocked_count = 0
 
-    # ── 核心:观测一步 ────────────────────────────────────────
-    def observe(self, content: str, tool: str = None, entities=None,
-                node_type: str = None, conf: float = 0.9,
+    def observe(self, content: str, tool: str | None = None, entities=None,
+                node_type: str | None = None, conf: float = 0.9,
                 semantic: bool = True) -> GovResult:
         """观测一个推理/工具步骤,返回治理判定。不抛异常(判定在结果里)。
 
@@ -106,7 +102,7 @@ class GovernanceSession:
         工具调用串对目标的语义距离是噪声。"""
         node = ThoughtNode.create(
             session_id=self._session_id, agent_id=self.agent_id,
-            type=node_type or ("tool_intent" if tool else "reasoning"),
+            type=cast(NodeType, node_type or ("tool_intent" if tool else "reasoning")),
             content=content, conf=conf, tool_name=tool, entities=entities or [])
         self.thought_chain.add_node(node)
         r = self.harness.check(node, ignore_semantic=not semantic)
@@ -121,14 +117,13 @@ class GovernanceSession:
                          delta=r.delta, dimension=r.dominant_dim, reason=r.reason,
                          node_id=node.id, scores=dict(r.scores), loop=loop_warn)
 
-    def guard(self, content: str, tool: str = None, entities=None) -> GovResult:
+    def guard(self, content: str, tool: str | None = None, entities=None) -> GovResult:
         """与 observe 相同,但被 BLOCK 时**抛 GovernanceBlocked**(fail-closed 风格)。"""
         r = self.observe(content, tool=tool, entities=entities)
         if r.blocked:
             raise GovernanceBlocked(r)
         return r
 
-    # ── 审计 ────────────────────────────────────────────────
     def audit(self) -> list[dict]:
         """取回本会话的完整可审计推理链(带每步 Harness 判定)。"""
         return [n.to_dict() for n in
@@ -148,7 +143,7 @@ class GovernanceSession:
         return False
 
 
-def governed(session: GovernanceSession, tool_name: str = None, entities=None):
+def governed(session: GovernanceSession, tool_name: str | None = None, entities=None):
     """装饰器:把一个工具函数包成"调用前先过 Harness"。
 
     命中越权/跑题/范围蔓延 → 抛 GovernanceBlocked,函数不执行。同步/异步函数都支持。
@@ -158,9 +153,6 @@ def governed(session: GovernanceSession, tool_name: str = None, entities=None):
         def delete_row(...): ...     # 调用即被拦(delete 不在 read 允许集)
     """
     def _check(name):
-        # 工具装饰器只对"这个工具授权了吗"负责 → semantic=False 只按 tool/scope 判定
-        # (语义是 observe() 的职责;工具名对目标的语义距离是噪声,跨语言时更会饱和,
-        # 不能作为工具授权依据)。这样中间件语言无关、行为确定、审计不被语义噪声污染。
         r = session.observe(f"tool call: {name}", tool=name, entities=entities,
                             semantic=False)
         if r.blocked or r.tool_violation or r.scope_violation:

package/python/foxclaw/harness/_base.py

@@ -8,11 +8,6 @@ import numpy as np
 from ..core.thought_chain import HarnessStatus
 
 
-# 目标基线是**每任务**语义(register_goal 每次任务设一次),却存在 Harness 实例上——
-# 并发顶层任务打同一 Agent 的 harness 时会互相覆盖,导致 check 对着错误的目标算漂移。
-# 与 base.py 同构:放进单个 module 级 contextvar 承载的 dict、按实例 token 分槽。
-# 累积学习态(weights/_policy/_delta_history/_run_count/_shadow_mode)仍留在实例上——
-# 那本就该按 Agent 累积,且同步 check 内无 await,协作调度下读改写原子安全。
 _harness_ctx: contextvars.ContextVar = contextvars.ContextVar(
     "foxclaw_harness_ctx", default=None)
 
@@ -27,7 +22,6 @@ def _harness_ctx_set(token: str, baseline):
     _harness_ctx.set(d)
 
 
-# ── 工具类别白名单 ─────────────────────────────────────────
 TOOL_CATEGORIES: dict[str, set[str]] = {
     "read":    {"read_file", "search", "fetch", "list", "get", "query"},
     "write":   {"write_file", "create", "update", "save", "append"},
@@ -43,8 +37,8 @@ TOOL_CATEGORIES: dict[str, set[str]] = {
 class HarnessResult:
     status: HarnessStatus
     delta: float
-    dominant_dim: str          # 主导漂移维度
-    scores: dict               # 各维度分数
+    dominant_dim: str
+    scores: dict
     reason: Optional[str] = None
 
     @property

package/python/foxclaw/harness/_policy.py

@@ -4,17 +4,30 @@
 等实例状态协同工作。纯搬移、零行为变更。
 """
 import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
 
 import numpy as np
 import yaml
-from datetime import datetime, timezone
 
 from ..core.thought_chain import ThoughtNode
 from ._base import HarnessResult
 
+if TYPE_CHECKING:
+    from .event_bus import HarnessEventBus
+
 
 class PolicyMixin:
-    # ── 学习规则的 action 编译 / 应用 ─────────────────────────
+    agent_id: str
+    bus: "HarnessEventBus"
+    policy_path: Path
+    weights: dict[str, float]
+    promote_min_obs: int
+    _policy: dict
+    _baseline: Any
+    _delta_history: list[float]
+
 
     def _reindex_learned_actions(self):
         """把 self._policy['rules'] 里已学习的 action 编译成 check() 用得上的结构。
@@ -35,7 +48,6 @@ class PolicyMixin:
             elif atype == "restrict_scope":
                 lim = action.get("entity_expansion_limit")
                 if isinstance(lim, int):
-                    # 多条 restrict 取最严(最小)上限
                     scope_limit = lim if scope_limit is None else min(scope_limit, lim)
         self._penalized_tools = penalized
         self._scope_limit = scope_limit
@@ -46,11 +58,7 @@ class PolicyMixin:
             return False
         return any(tool_name == p or p in tool_name for p in self._penalized_tools)
 
-    # ── Policy 学习(P0-1:影子验证 + 回滚 + 边界)────────────────
 
-    # 【P0-1 边界】可生成影子规则的维度。semantic 可学但**仅权重级**(不生成规则——
-    # 原 increase_semantic_threshold 规则本就无规则级应用,判定行为不变);
-    # 不在 weights 里的未知维度 → 只记录不学习(fail-closed,防未来新维度被默认自学)。
     _LEARNABLE_RULE_DIMS = frozenset({"tool", "scope"})
 
     def _trigger_policy_learning(self, node: ThoughtNode, result: HarnessResult):
@@ -64,16 +72,14 @@ class PolicyMixin:
         """
         dim = result.dominant_dim
 
-        # ── 边界:未知维度 fail-closed,只记录不学习(权重也不动)──
         if dim not in self.weights:
             self._record_history("skip", "",
                                  note=f"未知维度 '{dim}' 禁止自学习(fail-closed)")
             self._save_policy()
             return
 
-        # ── 规则级:tool/scope 生成影子候选;semantic 仅权重级 ──
         if dim in self._LEARNABLE_RULE_DIMS:
-            new_rule = {
+            new_rule: dict[str, Any] = {
                 "id": f"rule_{node.id}",
                 "trigger": {
                     "harness_status": "BLOCK",
@@ -84,8 +90,6 @@ class PolicyMixin:
                 "created_at": datetime.now(timezone.utc).isoformat(),
                 "source": "harness_learned",
                 "agent_id": self.agent_id,
-                # 影子账本:observations=适用次数;would_block=若生效会多拦;
-                # would_pass=若生效会多放。三者是 promote/discard 的全部证据。
                 "shadow": {
                     "created_at": datetime.now(timezone.utc).isoformat(),
                     "observations": 0, "would_block": 0, "would_pass": 0,
@@ -95,19 +99,12 @@ class PolicyMixin:
             self._policy.setdefault("shadow_rules", []).append(new_rule)
             self._record_history("propose", new_rule["id"],
                                  note=f"{dim} 维度 BLOCK → 影子观察")
-            # 不 _reindex_learned_actions —— 影子规则**不得**影响判定
             self.bus.emit("shadow_rule_proposed", {
                 "agent_id": self.agent_id, "rule_id": new_rule["id"],
                 "dominant_dim": dim,
                 "action_type": new_rule["action"].get("type", ""),
             })
 
-        # 更新权重：触发截断的维度权重 +δ
-        # 必须**先把新权重算完整再整体赋值**,不能"原地 +0.05 再归一化":
-        # 后者会让 self.weights 出现「各维之和 = 1.05」的瞬时中间态,而此刻若有人读到它
-        # (get_policy_summary / policy_updated 的监听者),拿到的就是未归一化的错值。
-        # 实测:同一份 summary 持有的 weights 引用会被读出 0.35,而稍后再取是 0.333 —— 正是
-        # 这个中间态被观察到。
         bumped = dict(self.weights)
         bumped[dim] = min(bumped[dim] + 0.05, 0.8)
         total = sum(bumped.values())
@@ -121,7 +118,6 @@ class PolicyMixin:
             "new_weights": dict(self.weights),
         })
 
-    # ── 影子观察(双轨判定)──────────────────────────────────
 
     def _observe_shadow_rules(self, node: ThoughtNode, result: HarnessResult,
                               real_scores: dict):
@@ -146,7 +142,6 @@ class PolicyMixin:
 
             sh["observations"] = sh.get("observations", 0) + 1
 
-            # 双轨:把该规则的 action 应用到 scores 副本,用**同一套权重与阈值**判定
             shadow_status = self._status_with_action(rule, node, real_scores)
             real_blocked = result.is_blocked
             shadow_blocked = shadow_status == "BLOCK"
@@ -163,7 +158,7 @@ class PolicyMixin:
                 self._discard_rule(rule, "影子证据不达标")
                 need_save = True
             elif sh["observations"] % 10 == 0:
-                need_save = True                    # 计数节流持久化
+                need_save = True
         if need_save:
             self._save_policy()
 
@@ -176,13 +171,9 @@ class PolicyMixin:
         if atype == "penalize_tool":
             pat = action.get("tool_pattern", "")
             tool_name = getattr(node, "tool_name", "") or ""
-            # 与 _is_penalized_tool 同语义:**仅当前工具命中 pattern 才抬分**。
-            # 若不看匹配、凡 tool 分非零就抬,会把「毫不相干工具的场景」误记成
-            # would_block —— 影子证据完全失真,好规则会被冤判成误伤 discard。
             if pat and tool_name and (tool_name == pat or pat in tool_name):
                 scores["tool"] = 1.0
         elif atype == "restrict_scope":
-            # 与 check() 里 restrict_scope 的判定同构:新增实体超限则抬 scope
             lim = action.get("entity_expansion_limit")
             baseline = self._baseline
             if isinstance(lim, int) and baseline is not None and baseline.baseline_entities:
@@ -202,10 +193,8 @@ class PolicyMixin:
         if obs < self.promote_min_obs:
             return None
         wb, wp = sh.get("would_block", 0), sh.get("would_pass", 0)
-        # 会多拦很多(可能误伤)→ 不 promote
         if wb / max(obs, 1) > 0.3:
             return False
-        # 几乎不改变判定 → promote 没意义
         if wb == 0 and wp == 0:
             return False
         return True
@@ -214,7 +203,7 @@ class PolicyMixin:
         """影子 → 生效:移入 rules、重建索引、记 history、发事件。"""
         rule.get("shadow", {})["status"] = "promoted"
         self._policy.setdefault("shadow_rules", []).remove(rule)
-        rule.pop("shadow", None)                      # 生效规则不再背影子账本
+        rule.pop("shadow", None)
         self._policy.setdefault("rules", []).append(rule)
         self._reindex_learned_actions()
         self._record_history("promote", rule["id"],
@@ -303,7 +292,6 @@ class PolicyMixin:
                 "delta": -0.05,
             }
 
-    # ── 阈值校准 ───────────────────────────────────────────
 
     def _calibrate_thresholds(self):
         """Shadow mode 结束 — 用真实 Δ 分布校准阈值。
@@ -311,20 +299,15 @@ class PolicyMixin:
         只有真正离群的(如完全跑题)才被拦截。
         否则用中位数附近的分位数会拦掉一半正常流量。
         """
-        arr = np.array(sorted(self._delta_history), dtype=float)
+        arr = np.array(sorted(self._delta_history), dtype=np.float64)
         if arr.size == 0:
-            # 空历史(理论上不会发生,因调用前每次 check 都 append)→ 用默认阈值,避免 nan
             self._shadow_mode = False
             return
         mean = float(arr.mean())
         std = float(arr.std())
         p90 = float(np.percentile(arr, 90))
-        # BLOCK 阈值取"高分位 / 均值+1.5σ"的较大者,再留 10% 余量,
-        # 保证正常任务(集中在均值附近)不被误拦
         block = max(p90, mean + 1.5 * std) * 1.10
-        # WARN 阈值取 block 的 0.8 倍,给出渐进预警区
         warn = block * 0.8
-        # 下限保护:阈值不低于默认值,避免样本噪声把阈值压得过紧
         self._block_threshold = max(block, 0.25)
         self._warn_threshold = max(warn, 0.18)
         self._shadow_mode = False
@@ -337,13 +320,11 @@ class PolicyMixin:
             "std": round(std, 3),
         })
 
-    # ── Policy 持久化 ──────────────────────────────────────
 
     def _load_policy(self) -> dict:
         if self.policy_path.exists():
             with open(self.policy_path, encoding="utf-8") as f:
                 return yaml.safe_load(f) or {}
-        # 默认 Policy 骨架（格式从第一天锁定）
         return {
             "version": 1,
             "agent_id": self.agent_id,

package/python/foxclaw/harness/drift.py

@@ -7,18 +7,12 @@ from sklearn.metrics.pairwise import cosine_similarity
 from ._base import TOOL_CATEGORIES
 
 
-# 文本向量由 foxclaw.capability.embedding_service 统一提供(进程内共享,同名只加载一次)。
-# 不可用时该服务返回 None,SemanticDrift 自动降级为 n-gram 哈希嵌入。
-
-
 class SemanticDrift:
     """维度一：语义距离。优先 sentence-transformers,不可用则降级 n-gram 哈希嵌入。"""
 
     DIM = 256
 
     def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
-        # P0:走进程内共享 EmbeddingService,同名模型全系统只加载一次
-        # (原来每个 Harness 各 load 一份;5 Agent = 5 份 → 现 1 份共享,只读并发 encode 安全)。
         from ..capability.embedding_service import get_text_embedder
         self._model = get_text_embedder(model_name)
         self._mode = "transformer" if self._model is not None else "hash"
@@ -58,8 +52,6 @@ class SemanticDrift:
             return 0.0
         node_vec = self._encode(content)
         sim = cosine_similarity([baseline_vec], [node_vec])[0][0]
-        # 余弦相似度范围 [-1, 1],哈希嵌入带符号累加可能产生负相似度,
-        # 1 - sim 会超过 1.0 → 必须双向裁剪到 [0, 1],否则漂移分超出阈值范围使判定失真。
         return float(min(1.0, max(0.0, 1.0 - sim)))
 
 
@@ -72,17 +64,13 @@ class ToolIntentDrift:
         for cat, patterns in TOOL_CATEGORIES.items():
             if any(tool_name.startswith(p) or p in tool_name for p in patterns):
                 return 0.0 if cat in allowed_categories else 1.0
-        return 0.3  # 未知工具：中等风险
+        return 0.3
 
 
 class ScopeCreepDrift:
     """维度三：范围蔓延"""
 
     def score(self, node_entities: set[str], baseline_entities: set[str]) -> float:
-        # 空基线返回 0 是有意设计:范围蔓延是"相对基线的偏离",没有基线参照就无从
-        # 谈蔓延。若此处对空基线返回高分,会让所有尚未建立实体基线的早期任务被误判为
-        # 范围越界(误报)。范围检测的有效性依赖基线实体提取——若该维度长期为 0,
-        # 应排查实体提取(register_goal 的 entities)是否为空,而非改动本函数。
         if not baseline_entities:
             return 0.0
         new_entities = node_entities - baseline_entities

package/python/foxclaw/harness/event_bus.py

@@ -5,25 +5,22 @@ from typing import Callable
 class HarnessEventBus:
     """阶段一：事件总线（观测优先）"""
 
-    # 高频且纯内部的信号不上脊柱,避免 WS 噪音(见审计"哪些事件不应该广播")
     _SPINE_SKIP = {"goal_registered"}
 
     def __init__(self, spine=None, source: str = ""):
         self._handlers: dict[str, list[Callable]] = {}
-        self._spine = spine        # 【P0·统一脊柱】非空则把 emit 同时转发进全局 EventSpine
-        self._source = source      # 事件来源(agent_id),便于投影侧区分
+        self._spine = spine
+        self._source = source
 
     def on(self, event: str, handler: Callable):
         self._handlers.setdefault(event, []).append(handler)
 
     def emit(self, event: str, data: dict):
-        # 1) 本地订阅者(向后兼容:agent.harness.bus.on / harness 自订阅 / governance)
         for h in self._handlers.get(event, []):
             try:
                 h(data)
             except Exception as e:
                 print(f"[Harness EventBus] handler error: {e}")
-        # 2) 汇入全局脊柱:harness 事件与系统事件走同一条脊柱、被同一 WS 投影观测
         if self._spine is not None and event not in self._SPINE_SKIP:
             try:
                 self._spine.publish(event, data, source=self._source or "harness")