foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/finance/reasoning.py

@@ -8,16 +8,16 @@ from collections import defaultdict
 from datetime import datetime, timedelta
 
 from .models import Budget
+from typing import Any
 
 
 class FinanceReasoning:
     """财务推理引擎:把交易流变成可决策的洞察。"""
 
-    # ── 预算推理 ──────────────────────────────────────────
     @staticmethod
-    def spend_by_category(transactions: list, period: str = None) -> dict:
+    def spend_by_category(transactions: list, period: str | None = None) -> dict:
         """按分类汇总支出(绝对值)。period 形如 '2026-06',None=全部。"""
-        out = defaultdict(float)
+        out: defaultdict[str, float] = defaultdict(float)
         for t in transactions:
             if not t.is_expense:
                 continue
@@ -27,7 +27,7 @@ class FinanceReasoning:
         return dict(out)
 
     @staticmethod
-    def budget_status(transactions: list, budgets: list, period: str = None) -> list:
+    def budget_status(transactions: list, budgets: list, period: str | None = None) -> list:
         """计算每个预算分类的使用状态。"""
         period = period or datetime.now().strftime("%Y-%m")
         spent = FinanceReasoning.spend_by_category(transactions, period)
@@ -40,22 +40,18 @@ class FinanceReasoning:
 
     @staticmethod
     def overspend_forecast(transactions: list, budget: Budget,
-                           period: str = None, now=None) -> dict:
+                           period: str | None = None, now=None) -> dict:
         """分类超支预测:按当前消费速度,推算月底是否超预算。"""
         now = now or datetime.now()
         period = period or now.strftime("%Y-%m")
         spent = FinanceReasoning.spend_by_category(transactions, period).get(
             budget.category, 0.0)
-        # 当前是本月第几天
         day = now.day
-        days_in_month = 30  # 简化
+        days_in_month = 30
         if day <= 0:
             day = 1
         daily_rate = spent / day
         projected = daily_rate * days_in_month
-        # 月初外推不可信:day=1 时一笔正常消费就被 ×30 放大成"月底将超支"。
-        # 前 7 天样本太少,趋势是噪音 —— 标记 reliable=False,让裁决层(overspend_trend_alert)
-        # 这一周内闭嘴。宁可晚一周提醒真超支,也不要天天误报把用户逼到关掉守门人。
         reliable = day >= 7
         return {
             "category": budget.category,
@@ -69,7 +65,6 @@ class FinanceReasoning:
             "day_of_month": day,
         }
 
-    # ── 风险判断 ──────────────────────────────────────────
     @staticmethod
     def detect_anomalies(transactions: list, threshold: float = 3.5) -> list:
         """异常消费检测:用 MAD(中位数绝对偏差)而非均值/标准差,
@@ -86,13 +81,10 @@ class FinanceReasoning:
             if len(amounts) < 3:
                 continue
             med = median(amounts)
-            # MAD = 偏离中位数的中位数
             mad = median([abs(a - med) for a in amounts])
             if mad == 0:
-                # 退化:用均值兜底
                 mad = (sum(abs(a - med) for a in amounts) / len(amounts)) or 1e-9
             for t in txns:
-                # 修正 Z 分数(0.6745 是正态分布常数)
                 mz = 0.6745 * (abs(t.amount) - med) / mad
                 if mz >= threshold:
                     anomalies.append({
@@ -102,8 +94,6 @@ class FinanceReasoning:
                         "category": cat,
                         "z_score": round(mz, 2),
                         "category_median": round(med, 2),
-                        # med>0 才显示"倍数"(当前 is_expense 排除非负额已保证 med>0,
-                        # 此处显式防御,避免未来改动 is_expense 定义后除零)
                         "reason": (f"{cat} 类异常消费,金额是中位数的 {abs(t.amount)/med:.1f} 倍"
                                    if med > 0 else f"{cat} 类异常消费(金额 {abs(t.amount):.0f})"),
                     })
@@ -144,7 +134,7 @@ class FinanceReasoning:
         同一商户按"最近一次扣款"代表其当前月度订阅价(订阅可能涨价,
         取最新而非遍历到的任意一条;也避免同商户多月记录被累加成虚高总额)。
         """
-        latest = {}   # entity -> (dt, amount)
+        latest: dict[str, tuple[Any, Any]] = {}
         for t in transactions:
             if t.is_recurring and t.is_expense:
                 prev = latest.get(t.entity)
@@ -184,7 +174,7 @@ class FinanceReasoning:
         out = []
         for entity, txns in by_entity.items():
             if len(txns) < 2:
-                continue                      # 只有一次扣款 → 无法判周期
+                continue
             ts = sorted(txns, key=lambda x: x.dt)
             gaps = [(ts[i].dt - ts[i - 1].dt).days for i in range(1, len(ts))]
             gaps = [g for g in gaps if g > 0]
@@ -195,7 +185,7 @@ class FinanceReasoning:
             elif 85 <= g <= 95:   cadence, period = "季订", 90
             elif 355 <= g <= 375: cadence, period = "年订", 365
             else:
-                continue                      # 间隔紊乱 → 不预测(不制造误报)
+                continue
             next_dt = ts[-1].dt + timedelta(days=period)
             days_until = (next_dt - now).days
             if 0 <= days_until <= horizon_days:
@@ -215,17 +205,13 @@ class FinanceReasoning:
         """
         now = now or datetime.now()
         credits = [t for t in transactions if not t.is_expense]
-        claimed = set()                 # 已被某笔退款认领的入账(按 id)
+        claimed = set()
         out = []
-        # 先处理较早的支出,让它优先认领入账(FIFO,符合"先欠先还")
         expected = sorted((t for t in transactions
                            if t.is_expense and "refund_expected" in (t.tags or [])),
                           key=lambda x: x.dt)
         for t in expected:
             amt = abs(t.amount)
-            # 同商户、等额、在该支出之后、且**尚未被别的退款认领**的入账 → 退款到账
-            # 消耗式匹配:一笔入账只抵一笔支出。否则用户标了两笔同额 refund_expected、
-            # 只收到一笔退款时,两笔都被误判为已退款 → 第二笔漏报(其实还没到账)。
             match = next((c for c in credits
                           if id(c) not in claimed and c.entity == t.entity
                           and abs(abs(c.amount) - amt) < 0.01 and c.dt >= t.dt), None)
@@ -238,9 +224,6 @@ class FinanceReasoning:
                             "days_waiting": waiting, "transaction_id": t.id})
         return out
 
-    # ── 阈值自校准 ────────────────────────────────────────
-    # 样本门槛:少于这些就不校准,继续用出厂默认。宁可用"公认的经验值",
-    # 也不要用 3 笔数据算出来的、听起来很个性化的垃圾阈值。
     CALIB_MIN_TXNS = 20
     CALIB_MIN_DAYS = 30
 
@@ -272,22 +255,19 @@ class FinanceReasoning:
         dts = [t.dt for t in expenses]
         span_days = (max(dts) - min(dts)).days
         if span_days < FinanceReasoning.CALIB_MIN_DAYS:
-            return {}                      # 跨度太短 → 分布不可信
+            return {}
 
         def _round100(v):
-            # 取整到百:阈值是给人看的,"800" 比 "783.42" 可信也好记
             return max(100.0, round(v / 100.0) * 100.0)
 
         amts = [abs(t.amount) for t in expenses]
         med = median(amts)
         mad = median([abs(a - med) for a in amts])
-        if mad == 0:                       # 退化(消费高度一致)→ 用平均绝对偏差兜底
+        if mad == 0:
             mad = (sum(abs(a - med) for a in amts) / len(amts)) or 1e-9
-        # 3.5/0.6745:把 detect_anomalies 的修正 Z 阈值(3.5)换算回原尺度偏移量,
-        # 使 large 阈值 = 恰好触发异常检测的单笔金额。两条规则从此共用一把尺。
         large = min(_round100(med + (3.5 / 0.6745) * mad), 20000.0)
 
-        by_day = defaultdict(float)
+        by_day: defaultdict[Any, float] = defaultdict(float)
         for t in expenses:
             by_day[t.dt.date()] += abs(t.amount)
         daily_med = median(by_day.values())
@@ -301,7 +281,6 @@ class FinanceReasoning:
                          f"{len(expenses)} 笔 / {span_days} 天)"),
         }
 
-    # ── 预测 ──────────────────────────────────────────────
     @staticmethod
     def burn_rate(transactions: list, days: int = 30) -> dict:
         """烧钱速度:近 N 天的日均净流出。"""

package/python/foxclaw/finance/reconcile.py

@@ -24,9 +24,9 @@ class ExternalRecord:
     """外部流水记录(来自银行/支付宝账单)。"""
     amount: float
     entity: str
-    date: str                      # ISO 日期或 YYYY-MM-DD
+    date: str
     account: str = ""
-    ref: str = ""                  # 外部流水号
+    ref: str = ""
 
     def to_dict(self) -> dict:
         return {"amount": self.amount, "entity": self.entity,
@@ -95,7 +95,7 @@ class Reconciler:
 
     def __init__(self, tolerance_days: int = 3, amount_tolerance: float = 0.01):
         self.tolerance_days = tolerance_days
-        self.amount_tolerance = amount_tolerance   # 金额绝对差容忍(<=此值视为相等)
+        self.amount_tolerance = amount_tolerance
 
     def _amount_eq(self, a: float, b: float) -> bool:
         """金额模糊相等:绝对值在容差范围内 且 收支方向一致(都支出或都收入)。"""
@@ -105,12 +105,11 @@ class Reconciler:
     def reconcile(self, transactions: list, external: list) -> ReconciliationResult:
         """对账主流程。transactions=系统交易,external=[ExternalRecord]。"""
         res = ReconciliationResult()
-        used_ext = set()      # 已匹配的外部记录索引
+        used_ext = set()
 
         for t in transactions:
             t_date = _date_only(t.timestamp)
-            best = None       # (ext_idx, match_type)
-            # 1. 精确匹配:金额 + 商户 + 同日
+            best = None
             for j, ext in enumerate(external):
                 if j in used_ext:
                     continue
@@ -118,7 +117,6 @@ class Reconciler:
                         and _entity_similar(t.entity, ext.entity)
                         and _days_apart(t_date, ext.date) == 0):
                     best = (j, "exact"); break
-            # 2. 模糊匹配:金额同 + 日期容忍内 + 商户相似
             if best is None:
                 for j, ext in enumerate(external):
                     if j in used_ext:
@@ -127,7 +125,6 @@ class Reconciler:
                             and _entity_similar(t.entity, ext.entity)
                             and _days_apart(t_date, ext.date) <= self.tolerance_days):
                         best = (j, "fuzzy_date"); break
-            # 3. 金额不符匹配:商户同 + 日期接近 + 同方向 + 金额不等(可能手续费)
             if best is None:
                 for j, ext in enumerate(external):
                     if j in used_ext:
@@ -140,7 +137,6 @@ class Reconciler:
                         best = (j, "amount_mismatch"); break
 
             if best is None:
-                # 系统有、外部无
                 res.unmatched_internal.append(self._txn_brief(t))
                 res.audit_log.append(
                     f"[未匹配·内部] 「{t.entity} ¥{abs(t.amount):.0f}」"
@@ -165,7 +161,6 @@ class Reconciler:
                 res.audit_log.append(
                     f"[已匹配·{mtype}] 「{t.entity} ¥{abs(t.amount):.0f}」({t_date})")
 
-        # 剩余未匹配的外部记录:外部有、系统无
         for j, ext in enumerate(external):
             if j not in used_ext:
                 res.unmatched_external.append(ext.to_dict())

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