foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/finance/nlparse.py

@@ -24,8 +24,6 @@ from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from typing import Optional
 
-# ── 币种 ──────────────────────────────────────────────────
-# 别名按长度倒序匹配:"块钱" 必须先于 "块","人民币" 先于 "元",否则会切错。
 CURRENCY_ALIASES = {
     "人民币": "CNY", "块钱": "CNY", "块": "CNY", "元": "CNY", "圆": "CNY",
     "软妹币": "CNY", "rmb": "CNY", "cny": "CNY",
@@ -43,23 +41,17 @@ _SYMBOLS = {"¥": "CNY", "￥": "CNY", "$": "USD", "€": "EUR", "£": "GBP", "
 _UNIT_ALT = "|".join(re.escape(u) for u in
                      sorted(CURRENCY_ALIASES, key=len, reverse=True))
 
-# 倍数后缀:1.5k / 2w / 3万 —— 不是币种,只是量级
 _SCALE = {"k": 1000, "千": 1000, "w": 10000, "万": 10000}
 
-# ── 中文数字 ──────────────────────────────────────────────
 _CN_DIGITS = {"零": 0, "〇": 0, "一": 1, "二": 2, "两": 2, "三": 3, "四": 4,
               "五": 5, "六": 6, "七": 7, "八": 8, "九": 9}
 _CN_UNITS = {"十": 10, "百": 100, "千": 1000, "万": 10000, "亿": 100000000}
 _CN_NUM = "[零〇一二两三四五六七八九十百千万亿]{1,12}"
 
-# ── 量词:数字 + 量词是"几件/2 袋",不是金额,必须先剔除 ─────────
-# 注意「块」不在此表 —— 它是货币单位(105 块),不是量词。
-# 「人」「位」故意不收:会吃掉「105 人民币」的「人」。
 _QUANTIFIERS = ("件|个|只|双|条|包|袋|瓶|杯|斤|公斤|kg|克|张|台|部|本|支|盒|箱|"
                 "次|份|碗|串|根|桶|套|顿|晚|小时|分钟|公里|千米|米|升|码|岁|ml")
 _QUANT_PAT = re.compile(rf"(?:\d[\d,.]*|{_CN_NUM})\s*(?:{_QUANTIFIERS})", re.I)
 
-# ── 花费/收入动词 ────────────────────────────────────────
 _EXPENSE_VERBS = ("花了", "花费", "花", "付了", "付款", "支付", "买了", "买", "购",
                   "消费", "充值", "充了", "交", "缴", "扣", "订", "租", "打车", "吃")
 _INCOME_VERBS = ("收入", "工资", "发了", "发工资", "收到", "收款", "进账", "退款",
@@ -68,7 +60,6 @@ _INCOME_VERBS = ("收入", "工资", "发了", "发工资", "收到", "收款",
 _VERB_PAT = re.compile("|".join(sorted(_EXPENSE_VERBS, key=len, reverse=True)))
 _INCOME_PAT = re.compile("|".join(sorted(_INCOME_VERBS, key=len, reverse=True)))
 
-# ── 分类关键词(顺序即优先级:订阅要先于娱乐,否则「腾讯视频会员」会归到娱乐)──
 CATEGORY_LABELS = {
     "food": "餐饮食品", "clothing": "服饰", "transport": "交通出行",
     "housing": "居住", "subscription": "订阅服务", "entertainment": "娱乐",
@@ -81,7 +72,6 @@ _CATEGORY_RULES = [
     ("food", ["大米", "米面", "面粉", "菜", "肉", "排骨", "水果", "奶茶", "咖啡",
               "饭", "早餐", "午餐", "晚餐", "夜宵", "外卖", "零食", "超市", "牛奶",
               "鸡蛋", "面包", "饮料", "火锅", "烧烤", "酒", "水饺", "面条", "油盐",
-              # 常见餐饮商户:用户报备时往往只说店名
               "星巴克", "瑞幸", "麦当劳", "肯德基", "海底捞", "喜茶", "蜜雪", "食堂"]),
     ("clothing", ["衣服", "裤子", "鞋", "外套", "裙子", "衬衫", "t恤", "帽子",
                   "包", "袜子", "内衣", "羽绒服", "西装", "围巾", "手套", "牛仔裤"]),
@@ -96,14 +86,13 @@ _CATEGORY_RULES = [
     ("entertainment", ["电影", "游戏", "ktv", "演出", "演唱会", "剧本杀", "健身", "按摩"]),
 ]
 
-# ── 时间表达 ─────────────────────────────────────────────
-_DAY_WORDS = [  # 长的先匹配,避免「大后天」被「后天」吃掉
+_DAY_WORDS = [
     ("大后天", 3), ("大前天", -3), ("后天", 2), ("前天", -2),
     ("昨天", -1), ("昨日", -1), ("昨晚", -1), ("昨儿", -1),
     ("今天", 0), ("今日", 0), ("今儿", 0), ("刚刚", 0), ("刚才", 0),
     ("明天", 1), ("明日", 1), ("明儿", 1),
 ]
-_MONTH_WORDS = [  # (词, 月偏移)
+_MONTH_WORDS = [
     ("上上个月", -2), ("上上月", -2), ("上个月", -1), ("上一个月", -1),
     ("上月", -1), ("下下个月", 2), ("下下月", 2), ("下个月", 1),
     ("下一个月", 1), ("下月", 1), ("这个月", 0), ("本月", 0), ("这月", 0),
@@ -115,24 +104,21 @@ _WEEK_WORDS = [("上周", -7), ("上星期", -7), ("上个星期", -7),
                ("下周", 7), ("下星期", 7), ("下个星期", 7)]
 
 
-# ══════════════════════════════════════════════════════════
-# 解析结果
-# ══════════════════════════════════════════════════════════
 @dataclass
 class ParsedExpense:
     """一句话里解析出的一笔钱(还没落账)。"""
-    text: str                     # 原始片段
-    direction: str = "expense"    # expense / income
-    amount: float = 0.0           # 原币金额(正数)
+    text: str
+    direction: str = "expense"
+    amount: float = 0.0
     currency: str = "CNY"
     when: datetime = field(default_factory=datetime.now)
     category: str = "misc"
-    description: str = ""         # 买了什么
-    entity: str = ""              # 商户/物品(账本里按它归类)
+    description: str = ""
+    entity: str = ""
     account: str = "default"
     confidence: float = 0.5
     warnings: list = field(default_factory=list)
-    planned: bool = False         # 未来时间 → 计划支出,不进"已发生"汇总
+    planned: bool = False
 
     @property
     def is_planned(self) -> bool:
@@ -151,9 +137,6 @@ class ParsedExpense:
         }
 
 
-# ══════════════════════════════════════════════════════════
-# 中文数字
-# ══════════════════════════════════════════════════════════
 def cn_to_number(s: str) -> Optional[float]:
     """「一百零五」→105、「两千三」→2300、「十万」→100000。解析不了返回 None。
 
@@ -184,18 +167,15 @@ def cn_to_number(s: str) -> Optional[float]:
             section += num * unit
             num, last_unit = 0, unit
     if num:
-        if zero:                              # 一百零五
+        if zero:
             section += num
-        elif last_unit >= 10:                 # 两千三 → 2300
+        elif last_unit >= 10:
             section += num * max(1, last_unit // 10)
         else:
             section += num
     return float(total + section)
 
 
-# ══════════════════════════════════════════════════════════
-# 时间
-# ══════════════════════════════════════════════════════════
 def _shift_month(now: datetime, months: int, day: Optional[int] = None) -> datetime:
     """按月份偏移,并把日 clamp 到目标月的合法范围(1 月 31 日 −1 月 → 2 月 28/29)。"""
     y, m = now.year, now.month + months
@@ -229,7 +209,6 @@ def _parse_when(text: str, now: datetime):
             when, explicit = dt, True
             cleaned = cleaned[:m.start()] + " " + cleaned[m.end():]
 
-    # 1) 绝对日期 2026-11-05 / 2026年11月5日
     m = re.search(r"(\d{4})\s*[-/年]\s*(\d{1,2})\s*[-/月]\s*(\d{1,2})\s*[日号]?", cleaned)
     if m:
         try:
@@ -238,7 +217,6 @@ def _parse_when(text: str, now: datetime):
         except ValueError:
             pass
 
-    # 2) 月份偏移(可带"5号"):上个月 / 下个月 5 号
     if when is None:
         m = re.search(rf"({_MONTH_ALT})\s*(?:份)?\s*(?:(\d{{1,2}}|[二三四五六七八九十]{{1,3}})\s*[号日])?",
                       cleaned)
@@ -250,7 +228,6 @@ def _parse_when(text: str, now: datetime):
                 day = day if 1 <= day <= 31 else None
             _take(m, _shift_month(now, offset, day))
 
-    # 3) N 月 / N 月 M 号(不带"上/下"修饰)
     if when is None:
         m = re.search(rf"(\d{{1,2}}|{_CN_NUM})\s*月份?\s*(?:(\d{{1,2}}|{_CN_NUM})\s*[号日])?",
                       cleaned)
@@ -261,13 +238,10 @@ def _parse_when(text: str, now: datetime):
                 if m.group(2):
                     day = int(m.group(2)) if m.group(2).isdigit() else int(cn_to_number(m.group(2)) or 0)
                     day = day if 1 <= day <= 31 else None
-                # 没写年份的「9 月」在 11 月说出来,指的就是今年 9 月(已过去);
-                # 「12 月」在 11 月说,只可能是去年 12 月 —— 未来请说「下个月」。
                 year = now.year - 1 if mon > now.month else now.year
                 dd = min(day or now.day, _month_days(year, mon))
                 _take(m, datetime(year, mon, dd, now.hour, now.minute))
 
-    # 4) 今天/昨天/前天/大前天/明天/后天/大后天
     if when is None:
         for word, delta in _DAY_WORDS:
             idx = cleaned.find(word)
@@ -277,7 +251,6 @@ def _parse_when(text: str, now: datetime):
                 cleaned = cleaned[:idx] + " " + cleaned[idx + len(word):]
                 break
 
-    # 5) N 天前 / N 天后 / N 日之内
     if when is None:
         m = re.search(rf"(\d{{1,3}}|{_CN_NUM})\s*天\s*(前|后)", cleaned)
         if m:
@@ -285,7 +258,6 @@ def _parse_when(text: str, now: datetime):
             delta = -n if m.group(2) == "前" else n
             _take(m, now + timedelta(days=delta))
 
-    # 6) 上周/这周/下周
     if when is None:
         for word, delta in _WEEK_WORDS:
             idx = cleaned.find(word)
@@ -294,7 +266,6 @@ def _parse_when(text: str, now: datetime):
                 cleaned = cleaned[:idx] + " " + cleaned[idx + len(word):]
                 break
 
-    # 7) 光秃秃的「5 号」:没过 → 本月;已过 → 上个月(口语里 5 号说的都是已经发生的事)
     if when is None:
         m = re.search(rf"(\d{{1,2}}|{_CN_NUM})\s*[号日]", cleaned)
         if m:
@@ -309,9 +280,6 @@ def _parse_when(text: str, now: datetime):
     return (when or now), cleaned, explicit
 
 
-# ══════════════════════════════════════════════════════════
-# 金额
-# ══════════════════════════════════════════════════════════
 def _to_float(num: str) -> Optional[float]:
     try:
         return float(num.replace(",", ""))
@@ -325,14 +293,12 @@ def _extract_amount(text: str):
     优先级:符号 > 数字+币种 > 数字+量级 > 中文数字+币种/量级 > 动词后的数字 > 唯一的裸数字。
     越往后越不确定,备注里会写明,让用户知道系统在猜。
     """
-    # 1) 符号前置:$105、¥1,050、€30
     m = re.search(r"([¥￥$€£₩])\s*(\d[\d,]*(?:\.\d+)?)", text)
     if m:
         v = _to_float(m.group(2))
         if v is not None:
             return v, _SYMBOLS[m.group(1)], [m.group(0)], True, ""
 
-    # 2) 数字 + 币种(105 块 / 105 美元 / 105 rmb)
     m = re.search(rf"(\d[\d,]*(?:\.\d+)?)\s*({_UNIT_ALT})", text, re.I)
     if m:
         v = _to_float(m.group(1))
@@ -340,7 +306,6 @@ def _extract_amount(text: str):
             return v, CURRENCY_ALIASES[m.group(2).lower() if m.group(2).isascii()
                                        else m.group(2)], [m.group(0)], True, ""
 
-    # 2b) 币种前置:美元 105 / rmb 88
     m = re.search(rf"({_UNIT_ALT})\s*(\d[\d,]*(?:\.\d+)?)", text, re.I)
     if m:
         v = _to_float(m.group(2))
@@ -348,7 +313,6 @@ def _extract_amount(text: str):
             key = m.group(1).lower() if m.group(1).isascii() else m.group(1)
             return v, CURRENCY_ALIASES[key], [m.group(0)], True, ""
 
-    # 3) 数字 + 量级(1.5k / 2w / 3 万)
     m = re.search(r"(\d[\d,]*(?:\.\d+)?)\s*(千|[kK]|[wW]|万)", text)
     if m:
         v = _to_float(m.group(1))
@@ -356,7 +320,6 @@ def _extract_amount(text: str):
             scale = _SCALE.get(m.group(2).lower(), 1000)
             return v * scale, "CNY", [m.group(0)], False, "按人民币处理(只给了量级)"
 
-    # 4) 中文数字 + 币种(一百零五块 / 两千美元)
     m = re.search(rf"({_CN_NUM})\s*({_UNIT_ALT})", text, re.I)
     if m:
         v = cn_to_number(m.group(1))
@@ -364,16 +327,12 @@ def _extract_amount(text: str):
             return v, CURRENCY_ALIASES[m.group(2).lower() if m.group(2).isascii()
                                        else m.group(2)], [m.group(0)], True, ""
 
-    # 5) 中文数字整串(两千三 / 三千五 / 两万)。
-    #    注意必须**整串**交给 cn_to_number:先按 (千|万) 切会得到 "两"+"千" = 2000,
-    #    而用户说的是 2300。
     m = re.search(rf"({_CN_NUM})", text)
     if m and len(m.group(1)) >= 2:
         v = cn_to_number(m.group(1))
         if v is not None:
             return v, "CNY", [m.group(0)], False, "按人民币处理(只给了量级)"
 
-    # 6) 动词旁边的裸数字(花了 105 / 付 30)
     m = re.search(rf"(?:{'|'.join(sorted(_EXPENSE_VERBS, key=len, reverse=True))})"
                   rf"\s*(\d[\d,]*(?:\.\d+)?)", text)
     if m:
@@ -387,9 +346,6 @@ def _extract_amount(text: str):
         if v is not None:
             return v, "CNY", [m.group(0)], False, ""
 
-    # 7) 裸数字:只有一个就用它;有多个取最大(「买 2 件衣服 105」→ 105)。
-    #    口语报备省略「元」是常态,单数字不再提示 —— 每笔都挂一句
-    #    「按人民币处理」纯属噪音,反而让回执显得不可靠。
     nums = [(v, mm.group(0)) for mm in re.finditer(r"\d[\d,]*(?:\.\d+)?", text)
             if (v := _to_float(mm.group(0))) is not None]
     if len(nums) == 1:
@@ -400,9 +356,6 @@ def _extract_amount(text: str):
     return None
 
 
-# ══════════════════════════════════════════════════════════
-# 分类 / 收支方向
-# ══════════════════════════════════════════════════════════
 def _classify(text: str) -> str:
     low = text.lower()
     for cat, words in _CATEGORY_RULES:
@@ -420,9 +373,6 @@ def _direction(text: str) -> str:
     return "expense"
 
 
-# 描述清洗:剥掉金额、时间、功能动词与量词,只留下"买的是什么"。
-# 保留词先占位 —— 「打车/洗车/加油/租房」里的动词本身就是消费名,
-# 删掉会变成「车 25」这种读不懂的残句。
 _KEEP_PHRASES = ("打车", "洗车", "加油", "吃饭", "租房", "房租", "停车", "话费", "液化气")
 _STOP_WORDS = (
     "花了", "花费", "付了", "付款", "支付", "买了", "充值", "充了", "消费",
@@ -440,7 +390,6 @@ def _clean_description(text: str, spans: list) -> str:
     out = text
     for sp in spans:
         out = out.replace(sp, " ")
-    # 保护动词性名词
     for i, w in enumerate(_KEEP_PHRASES):
         out = out.replace(w, f"\x00{i}\x00")
     for w in sorted(_STOP_WORDS, key=len, reverse=True):
@@ -455,10 +404,7 @@ def _clean_description(text: str, spans: list) -> str:
 _SPLIT_PAT = re.compile(r"[，,；;\n]+|(?:然后|另外|还有|以及|再就是|接着)")
 
 
-# ══════════════════════════════════════════════════════════
-# 主入口
-# ══════════════════════════════════════════════════════════
-def parse(text: str, now: datetime = None) -> list:
+def parse(text: str, now: datetime | None = None) -> list:
     """把一段话解析成 0..N 笔钱。
 
     「今天买了一件衣服花了 105 块,还买了 45 块的大米」
@@ -482,9 +428,6 @@ def parse(text: str, now: datetime = None) -> list:
         inherited_when = p.when
         out.append(p)
 
-    # 拆段只解析出 ≤1 笔 → 换用整句再解析一次。中文口语常带逗号
-    # (「今天,我买了件衣服,花了 105 块」),拆开会让「衣服」这个分类线索掉在
-    # 没有金额的段里,整句解析才拿得到完整语境。
     if len(out) <= 1:
         whole = _parse_one(text, now, None)
         if whole is not None:
@@ -498,7 +441,7 @@ def _parse_one(seg: str, now: datetime, inherited_when: Optional[datetime]):
     if not explicit_time and inherited_when is not None:
         when = inherited_when
 
-    cleaned = _QUANT_PAT.sub(" ", cleaned)        # 「一件」「2 袋」不是金额
+    cleaned = _QUANT_PAT.sub(" ", cleaned)
     got = _extract_amount(cleaned)
     if got is None:
         return None
@@ -510,7 +453,6 @@ def _parse_one(seg: str, now: datetime, inherited_when: Optional[datetime]):
     desc = _clean_description(cleaned, spans)
     category = "income" if direction == "income" else _classify(original)
 
-    # 商户:「在星巴克买了…」
     ent = ""
     m = re.search(r"在\s*([\u4e00-\u9fa5A-Za-z0-9]{1,10}?)\s*(?:买|花|吃|订|充|消费|缴)", original)
     if m:
@@ -537,8 +479,6 @@ def _parse_one(seg: str, now: datetime, inherited_when: Optional[datetime]):
     )
 
 
-# 完成态付钱动词:「买了/花了/交了」说明钱**已经出去了**;
-# 「房租 3000 占收入多少」里的「租」不算 —— 那句在讨论额度,不是在报账。
 _SETTLED_SPEND = ("花了", "买了", "付了", "支付了", "消费了", "充值了",
                   "交了", "缴了", "扣了", "刷了", "转了", "付账")
 

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