foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/finance/graph.py

@@ -18,7 +18,7 @@ from dataclasses import dataclass, field
 @dataclass
 class GraphNode:
     node_id: str
-    node_type: str                 # transaction/category/entity/account/budget
+    node_type: str
     label: str
     attrs: dict = field(default_factory=dict)
 
@@ -31,7 +31,7 @@ class GraphNode:
 class GraphEdge:
     src: str
     dst: str
-    rel: str                       # belongs_to/paid_to/charged_on/monitors
+    rel: str
     attrs: dict = field(default_factory=dict)
 
     def to_dict(self) -> dict:
@@ -45,15 +45,13 @@ class FinancialDataGraph:
     def __init__(self):
         self.nodes: dict[str, GraphNode] = {}
         self.edges: list[GraphEdge] = []
-        self._adj: dict[str, list] = defaultdict(list)        # 出边邻接
-        self._radj: dict[str, list] = defaultdict(list)       # 入边邻接
+        self._adj: dict[str, list] = defaultdict(list)
+        self._radj: dict[str, list] = defaultdict(list)
 
-    # ── 构建 ──
     def _ensure_node(self, node_id: str, node_type: str, label: str, **attrs):
         if node_id not in self.nodes:
             self.nodes[node_id] = GraphNode(node_id, node_type, label, dict(attrs))
         else:
-            # 已存在 → 累加统计类属性
             self.nodes[node_id].attrs.update(attrs)
         return self.nodes[node_id]
 
@@ -63,7 +61,7 @@ class FinancialDataGraph:
         self._adj[src].append(e)
         self._radj[dst].append(e)
 
-    def build(self, transactions: list, budgets: list = None):
+    def build(self, transactions: list, budgets: list | None = None):
         """从交易 + 预算构建图。"""
         self.nodes.clear(); self.edges.clear()
         self._adj.clear(); self._radj.clear()
@@ -73,7 +71,6 @@ class FinancialDataGraph:
             self._ensure_node(tid, "transaction", f"{t.entity} ¥{abs(t.amount):.0f}",
                               amount=t.amount, timestamp=t.timestamp,
                               is_expense=t.is_expense)
-            # 分类节点 + 边(消费统计只累加支出,收入/退款不计入'花费')
             cat_id = f"cat:{t.category}"
             cnode = self._ensure_node(cat_id, "category", t.category)
             if t.is_expense:
@@ -82,19 +79,16 @@ class FinancialDataGraph:
             else:
                 cnode.attrs["income"] = cnode.attrs.get("income", 0) + abs(t.amount)
             self._add_edge(tid, cat_id, "belongs_to")
-            # 商户节点 + 边(同样只把支出计入消费)
             ent_id = f"ent:{t.entity}"
             enode = self._ensure_node(ent_id, "entity", t.entity)
             if t.is_expense:
                 enode.attrs["total"] = enode.attrs.get("total", 0) + abs(t.amount)
                 enode.attrs["count"] = enode.attrs.get("count", 0) + 1
             self._add_edge(tid, ent_id, "paid_to")
-            # 账户节点 + 边
             acc_id = f"acc:{t.account}"
             self._ensure_node(acc_id, "account", t.account)
             self._add_edge(tid, acc_id, "charged_on")
 
-        # 预算节点 + 监管边(预算 monitors 分类)
         for b in (budgets or []):
             bid = f"bud:{b.category}"
             self._ensure_node(bid, "budget", f"{b.category}预算",
@@ -104,8 +98,7 @@ class FinancialDataGraph:
                 self._add_edge(bid, cat_id, "monitors")
         return self
 
-    # ── 查询 ──
-    def neighbors(self, node_id: str, rel: str = None) -> list:
+    def neighbors(self, node_id: str, rel: str | None = None) -> list:
         """出边邻居(可按关系过滤)。"""
         return [self.nodes[e.dst] for e in self._adj.get(node_id, [])
                 if rel is None or e.rel == rel]
@@ -119,11 +112,10 @@ class FinancialDataGraph:
         """某分类下,按消费额排名的商户 —— 回答'这个分类的钱花在谁身上'。"""
         cat_id = f"cat:{category}"
         txns = self.transactions_of(cat_id)
-        by_entity = defaultdict(float)
+        by_entity: defaultdict[str, float] = defaultdict(float)
         for t in txns:
             if not t.attrs.get("is_expense"):
-                continue   # 只统计支出,排除收入/退款
-            # 找这笔交易付给了谁
+                continue
             for e in self._adj.get(t.node_id, []):
                 if e.rel == "paid_to":
                     by_entity[self.nodes[e.dst].label] += abs(t.attrs.get("amount", 0))
@@ -139,7 +131,6 @@ class FinancialDataGraph:
         cat = self.nodes[cat_id]
         spent = cat.attrs.get("total", 0)
         limit = self.nodes[bud_id].attrs.get("monthly_limit") if bud_id in self.nodes else None
-        # 主要贡献者(商户)
         contributors = self.top_entities_in_category(category, top=3)
         result = {
             "category": category, "found": True,
@@ -170,7 +161,7 @@ class FinancialDataGraph:
         return sorted(out, key=lambda x: -x["outflow"])
 
     def stats(self) -> dict:
-        by_type = defaultdict(int)
+        by_type: defaultdict[str, int] = defaultdict(int)
         for n in self.nodes.values():
             by_type[n.node_type] += 1
         return {"nodes": len(self.nodes), "edges": len(self.edges),

package/python/foxclaw/finance/models.py

@@ -22,21 +22,20 @@ class Transaction:
     原币金额与币种另存 `original_amount` / `currency` / `fx_rate` —— 这样「100 美元」
     不会和「100 元」在求和时混在一起,同时账本里又看得到用户当时说的原话数额。
     """
-    amount: float                       # 负数=支出,正数=收入(本位币 CNY)
-    category: str                       # 分类:subscription/food/transport/salary...
-    entity: str                         # 商户/对手方:Netflix、星巴克、公司
-    account: str                        # 账户:credit_card_1、debit、alipay
+    amount: float
+    category: str
+    entity: str
+    account: str
     timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
-    tags: list = field(default_factory=list)   # ["recurring","media"]
+    tags: list = field(default_factory=list)
     note: str = ""
     id: str = field(default_factory=lambda: f"txn_{uuid.uuid4().hex[:10]}")
-    # —— 多币种 & 自然语言记账 ——
-    currency: str = "CNY"               # 原币种
-    original_amount: Optional[float] = None   # 原币金额(正负号与 amount 一致)
-    fx_rate: float = 1.0                # 记账时原币 → 本位币的折算率
-    description: str = ""               # 报备原话里的"买的什么"
-    status: str = "settled"             # settled=已发生 planned=未来计划
-    source: str = "manual"              # manual / text / csv / bank
+    currency: str = "CNY"
+    original_amount: Optional[float] = None
+    fx_rate: float = 1.0
+    description: str = ""
+    status: str = "settled"
+    source: str = "manual"
 
     @property
     def is_expense(self) -> bool:
@@ -72,8 +71,8 @@ class Transaction:
 class Budget:
     """某分类的预算状态"""
     category: str
-    monthly_limit: float                # 月度上限
-    spent: float = 0.0                  # 本期已花(绝对值)
+    monthly_limit: float
+    spent: float = 0.0
     period: str = field(default_factory=lambda: datetime.now().strftime("%Y-%m"))
 
     @property
@@ -102,12 +101,12 @@ class FinancialEntity:
     """账户 / 商户 / 订阅"""
     name: str
     entity_type: EntityType
-    balance: Optional[float] = None     # 账户余额(仅 account)
-    recurring_amount: Optional[float] = None  # 周期金额(仅 subscription)
-    cycle: Optional[str] = None         # monthly/yearly(仅 subscription)
+    balance: Optional[float] = None
+    recurring_amount: Optional[float] = None
+    cycle: Optional[str] = None
     last_seen: str = ""
     txn_count: int = 0
-    total_amount: float = 0.0           # 累计金额
+    total_amount: float = 0.0
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -119,16 +118,13 @@ class FinancePolicyRule:
     与 Harness 的 Policy YAML 同构,但作用于资金行为。
     """
     id: str
-    condition: str                      # 人类可读条件描述
+    condition: str
     action: Literal["alert", "require_confirmation", "freeze", "veto", "suggest"]
     threshold: Optional[float] = None
-    scope: str = "global"               # global 或某 category
+    scope: str = "global"
     severity: Literal["info", "warn", "critical"] = "warn"
     source: Literal["builtin", "user", "learned"] = "builtin"
     enabled: bool = True
-    # 自校准留痕:calibrated_value = 上次校准写下的阈值(用于判断"之后有没有人手动改过";
-    # 若 threshold 已偏离它,说明是人的决定,校准就此收手)。calibrated_from = 依据说明,
-    # 让阈值可解释 —— 用户看得到"这个 800 是怎么来的",才敢信它。
     calibrated_value: Optional[float] = None
     calibrated_from: Optional[str] = None
 
@@ -144,7 +140,7 @@ class PolicyVerdict:
     severity: str
     message: str
     transaction_id: Optional[str] = None
-    requires_user_action: bool = False  # 是否需要用户确认/介入
+    requires_user_action: bool = False
 
     def to_dict(self) -> dict:
         return asdict(self)

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 = ("花了", "买了", "付了", "支付了", "消费了", "充值了",
                   "交了", "缴了", "扣了", "刷了", "转了", "付账")