foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/finance/policy.py

@@ -15,7 +15,6 @@ from typing import Optional
 from .models import FinancePolicyRule, PolicyVerdict, Transaction
 
 
-# 内置默认规则(对应用户设计里的示例规则)
 DEFAULT_RULES = [
     FinancePolicyRule(
         id="subscription_limit",
@@ -27,9 +26,6 @@ DEFAULT_RULES = [
         source="builtin",
     ),
     FinancePolicyRule(
-        # 阈值 500(原 200):200 会让几乎每次日常消费都要确认 → 误报爆炸 → 用户索性
-        # 把守门人关掉,那它就形同虚设。守门人的价值不在"规则多",而在**误报低到你愿意一直开着**。
-        # 这是可调项:按自己的消费水平改 finance_policy.yaml 即可,不用动代码。
         id="large_purchase_check",
         condition="单笔支出 > 500",
         action="require_confirmation",
@@ -47,14 +43,11 @@ DEFAULT_RULES = [
         severity="critical",
         source="builtin",
     ),
-    # ── 用户点名要的 4 条(2026-07-16)────────────────────────────────
-    # 前两条的**检测早就实现了**(detect_duplicate_charges / overspend_forecast),
-    # 但此前只进分析报告、从不产生裁决 —— 检测到了却不吭声。现接成规则。
     FinancePolicyRule(
         id="duplicate_charge_alert",
         condition="同商户短时间内重复扣款 ≥2 次",
         action="require_confirmation",
-        threshold=2.0,              # 次数阈值
+        threshold=2.0,
         scope="merchant",
         severity="warn",
         source="builtin",
@@ -72,18 +65,16 @@ DEFAULT_RULES = [
         id="renewal_reminder",
         condition="订阅/年费将在 7 天内自动续订",
         action="alert",
-        threshold=7.0,              # 提前几天提醒
+        threshold=7.0,
         scope="subscription",
         severity="info",
         source="builtin",
     ),
     FinancePolicyRule(
-        # 注:必须由用户给交易打 tag `refund_expected` —— 系统无法从交易流推断
-        # "我期待一笔退款"(退款只是一笔入账)。不标记则此规则恒不触发。
         id="refund_overdue_alert",
         condition="标记了 refund_expected 的支出,14 天内未收到等额退款",
         action="alert",
-        threshold=14.0,             # 等待天数
+        threshold=14.0,
         scope="merchant",
         severity="warn",
         source="builtin",
@@ -100,8 +91,6 @@ DEFAULT_RULES = [
 ]
 
 
-# 出厂阈值快照(模块加载时取,此后 DEFAULT_RULES 不再被改 —— 见 _load_or_init 的 deepcopy)。
-# 自校准靠它判断某条规则"是否还停在出厂状态"。
 FACTORY_THRESHOLDS = {r.id: r.threshold for r in DEFAULT_RULES}
 
 
@@ -111,10 +100,6 @@ class FinancePolicyEngine:
     def __init__(self, policy_path: str = "./finance_policy.yaml"):
         self.policy_path = Path(policy_path).resolve()
         self.rules: list = []
-        # 线程安全铁律:finance_runtime 是单例(Foxclaw.__init__),analyze()→apply_calibration
-        # 会被请求线程并发调用,改 rule.threshold 并 save() 写 yaml(非原子)。写侧必须串行,
-        # 否则并发 save 可能把 yaml 写坏。RLock:apply_calibration 持锁时还要调 save()。
-        # 读侧(evaluate_*)只读单个 float,GIL 下原子(读到旧值或新值都合法),不加锁省热路径开销。
         self._write_lock = threading.RLock()
         self._load_or_init()
 
@@ -122,9 +107,6 @@ class FinancePolicyEngine:
         if self.policy_path.exists():
             self._load()
         else:
-            # deepcopy 而非 list():list() 只复制**列表**、不复制里面的 FinancePolicyRule 对象,
-            # 于是所有实例共享同一批可变规则 —— 任何一处改阈值(rule.threshold=...)会污染
-            # 其它 runtime **以及模块级 DEFAULT_RULES**(要重启才恢复)。规则是可变对象,必须深拷。
             self.rules = copy.deepcopy(DEFAULT_RULES)
             self.save()
 
@@ -135,8 +117,6 @@ class FinancePolicyEngine:
             if not self.rules:
                 self.rules = copy.deepcopy(DEFAULT_RULES)
         except Exception:
-            # 同 _load_or_init:必须 deepcopy。这两个兜底分支是上次漏改的 ——
-            # 自校准会写 rule.threshold,一旦走到这里就会污染模块级 DEFAULT_RULES。
             self.rules = copy.deepcopy(DEFAULT_RULES)
 
     def save(self):
@@ -147,7 +127,6 @@ class FinancePolicyEngine:
                 "domain": "finance",
                 "rules": [r.to_dict() for r in self.rules],
             }
-            # 写临时文件再原子 rename:避免并发/崩溃时读到写了一半的 yaml
             tmp = self.policy_path.with_suffix(self.policy_path.suffix + ".tmp")
             tmp.write_text(
                 yaml.safe_dump(data, allow_unicode=True, sort_keys=False),
@@ -161,7 +140,6 @@ class FinancePolicyEngine:
             self.rules.append(rule)
             self.save()
 
-    # ── 阈值自校准 ────────────────────────────────────────
     def _may_calibrate(self, rule: FinancePolicyRule) -> bool:
         """这条规则的阈值,自动校准能不能动?
 
@@ -196,18 +174,17 @@ class FinancePolicyEngine:
                     continue
                 new_val, basis = s
                 if new_val == rule.threshold:
-                    continue                   # 值没变 → 不写盘(analyze 每次都会调到这里)
+                    continue
                 changed.append({"rule_id": rule.id, "from": rule.threshold,
                                 "to": new_val, "basis": basis})
                 rule.threshold = new_val
-                rule.calibrated_value = new_val   # 留痕:此后有人改动就能认出来
+                rule.calibrated_value = new_val
                 rule.calibrated_from = basis
                 rule.source = "learned"
             if changed:
                 self.save()
             return changed
 
-    # ── 守门人裁决 ────────────────────────────────────────
     def evaluate_transaction(self, txn: Transaction,
                              account_balance: Optional[float] = None) -> list:
         """对单笔交易做规则裁决,返回所有触发的 verdict。"""
@@ -243,9 +220,9 @@ class FinancePolicyEngine:
         return None
 
     def evaluate_state(self, subscription_total: float = 0.0,
-                       anomalies: list = None, duplicates: list = None,
-                       forecasts: list = None, renewals: list = None,
-                       pending_refunds: list = None) -> list:
+                       anomalies: list | None = None, duplicates: list | None = None,
+                       forecasts: list | None = None, renewals: list | None = None,
+                       pending_refunds: list | None = None) -> list:
         """对整体财务状态做裁决。
 
         分工:**runtime 算派生信号,本引擎只裁决**(沿用既有纹理)。
@@ -262,7 +239,6 @@ class FinancePolicyEngine:
             if not rule.enabled:
                 continue
 
-            # 同一商家高频/重复扣款(悄悄连扣)
             if rule.id == "duplicate_charge_alert":
                 for d in duplicates:
                     if d.get("count", 0) >= (rule.threshold or 2):
@@ -271,10 +247,8 @@ class FinancePolicyEngine:
                             message=f"疑似重复扣款:{d.get('reason', '')}",
                             requires_user_action=True))
 
-            # 跨月预算超支**趋势**(还没超,但按当前速度月底会超)
             if rule.id == "overspend_trend_alert":
                 for f in forecasts:
-                    # reliable 闸:月初 7 天内样本太少,外推是噪音,不报(见 overspend_forecast)
                     if (f.get("reliable", True) and f.get("will_overspend")
                             and f.get("spent_so_far", 0) <= f.get("monthly_limit", 0)):
                         verdicts.append(PolicyVerdict(
@@ -285,7 +259,6 @@ class FinancePolicyEngine:
                                      f"限额 {f.get('monthly_limit', 0):.0f})"),
                             requires_user_action=False))
 
-            # 订阅/年费自动续订**前**提醒
             if rule.id == "renewal_reminder":
                 for r in renewals:
                     if r.get("days_until", 999) <= (rule.threshold or 7):
@@ -295,7 +268,6 @@ class FinancePolicyEngine:
                                      f"{r.get('amount', 0):.0f}({r.get('cadence', '')})"),
                             requires_user_action=True))
 
-            # 退款未到账(需用户显式标记 refund_expected —— 见 detect_pending_refunds)
             if rule.id == "refund_overdue_alert":
                 for p in pending_refunds:
                     if p.get("days_waiting", 0) >= (rule.threshold or 14):

package/python/foxclaw/finance/reasoner.py

@@ -13,14 +13,11 @@ from ..cognitive.reasoner import DomainReasoner, ReasonedVerdict, Evidence
 class FinanceGatekeeperReasoner(DomainReasoner):
     """subject = (txn, account_balance)。"""
 
-    # Step3:LLM 只裁决"逼近阈值"的模糊带 [band×阈值, 阈值)——低于此=明显安全(省成本),
-    # 高于阈值=规则已触发确认(不在本路径)。
     AMBIGUITY_BAND = 0.7
 
     def __init__(self, policy, runtime=None, llm=None, llm_enabled: bool = False):
         self.policy = policy
-        self.runtime = runtime      # 可选:FinanceRuntime,用于 Step2 的情境证据(历史/预算/频率)
-        # Step3:模糊情形的 LLM 裁决器(可选、默认关)。llm 需有 complete(system,messages)->str + is_stub。
+        self.runtime = runtime
         self.llm = llm
         self.llm_enabled = bool(llm_enabled) and llm is not None and not getattr(llm, "is_stub", True)
 
@@ -39,12 +36,11 @@ class FinanceGatekeeperReasoner(DomainReasoner):
 
     def gather_evidence(self, subject, obs: dict) -> list:
         txn, bal = subject
-        verdicts = self.policy.evaluate_transaction(txn, bal)   # 规则=裁决证据(raw 非空)
+        verdicts = self.policy.evaluate_transaction(txn, bal)
         ev = [Evidence(factor=v.rule_id, detail=v.message, weight=1.0, raw=v)
               for v in verdicts]
         if not verdicts:
             ev.append(Evidence(factor="rules_clear", detail="未触发任何财务规则", weight=0.5))
-        # Step2:结构化情境证据(informational,raw=None → **不参与裁决**,只让证据链更丰满)
         ev += self._context_evidence(txn)
         return ev
 
@@ -79,15 +75,12 @@ class FinanceGatekeeperReasoner(DomainReasoner):
     def arbitrate(self, subject, obs: dict, hyps: list, ev: list) -> ReasonedVerdict:
         triggered = [e.raw for e in ev if e.raw is not None]
         if triggered:
-            # 【硬约束权威】规则触发 → 规则说了算(reject/confirm),**绝不问 LLM**。
             actions = [v.action for v in triggered]
             decision = "reject" if ("veto" in actions or "freeze" in actions) else "confirm"
             return ReasonedVerdict(decision, " / ".join(v.message for v in triggered),
                                    ev, hyps, "rules")
-        # 规则批准:若"逼近阈值"的模糊情形且启用了 LLM,让 LLM 就证据复核(**只能 approve/confirm**)。
         if self.llm_enabled and self._is_ambiguous(obs):
             return self._llm_arbitrate(obs, hyps, ev)
-        # 明显安全 / 未启用 LLM → 规则批准(rationale 与原守门人逐字一致)
         return ReasonedVerdict(
             "approve", f"财务批准:{obs['category']} 预算 {obs['amount']} 在规则内",
             ev, hyps, "rules")
@@ -102,7 +95,7 @@ class FinanceGatekeeperReasoner(DomainReasoner):
         thr = self._large_threshold()
         if thr <= 0 or not obs.get("is_expense"):
             return False
-        return self.AMBIGUITY_BAND * thr <= obs["amount"] < thr   # 逼近阈值但未触发规则
+        return self.AMBIGUITY_BAND * thr <= obs["amount"] < thr
 
     def _llm_arbitrate(self, obs: dict, hyps: list, ev: list) -> ReasonedVerdict:
         """【安全不变量】只在"规则已批准"的模糊情形被调;**只能返回 approve 或 confirm**,
@@ -124,6 +117,5 @@ class FinanceGatekeeperReasoner(DomainReasoner):
             return ReasonedVerdict(
                 "approve", f"财务批准:{obs['category']} 预算 {obs['amount']}(LLM 复核无异常)",
                 ev, hyps, "llm")
-        # 响应不明 → fail-safe(绝不因 LLM 含糊而自动放行)
         return ReasonedVerdict("confirm", "LLM 响应不明,保守转确认(fail-safe)",
                                ev, hyps, "llm_failsafe")

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())