foxclaw 0.1.0 → 0.1.3

package/python/tests/test_finance_ledger.py

@@ -0,0 +1,245 @@
+"""自然语言记账 —— 用户随口报备的一句花费,要能自己识别、记账、汇总。
+
+这是财务应用第一线的功能,输入是「今天买了一件衣服花了 105 块」这种大白话。
+测试固定四件事:
+  1. 金额/币种/时间/分类识别对(含中文数字、美元/美金/块/块钱);
+  2. 过去/今天 → 已发生,明天/下个月 → 计划支出,且计划不污染"本月已花";
+  3. 一段话多笔要拆开,时间可继承;
+  4. 记账本汇总(按天/按分类/按币种)与汇率折算正确。
+"""
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.finance import FinanceRuntime
+from foxclaw.finance.nlparse import (cn_to_number, has_expense_signal,
+                                         has_payment_verb, parse)
+from foxclaw.agents.impl.finance import _should_autorecord
+from foxclaw.agents.impl.supervisor import SupervisorAgent
+
+NOW = datetime(2026, 11, 7, 20, 0)
+
+
+def _rt(tmp_path):
+    return FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"),
+                          data_path=str(tmp_path / "finance_data.json"))
+
+
+def _one(text, now=NOW):
+    ps = parse(text, now=now)
+    assert len(ps) == 1, f"{text!r} 解析出 {len(ps)} 笔"
+    return ps[0]
+
+
+def test_今天买衣服105块():
+    p = _one("今天买了一件衣服花了105块")
+    assert (p.amount, p.currency, p.direction) == (105.0, "CNY", "expense")
+    assert p.when.date() == NOW.date() and not p.planned
+    assert p.category == "clothing"
+    assert p.entity == "衣服"
+
+
+def test_明天买大米45():
+    p = _one("明天买一袋大米花了45")
+    assert p.amount == 45.0 and p.planned
+    assert p.when.date() == datetime(2026, 11, 8).date()
+    assert p.category == "food"
+
+
+def test_后天洗车100():
+    p = _one("后天花了100洗车")
+    assert p.amount == 100.0 and p.planned
+    assert p.category == "transport"
+    assert p.when.date() == datetime(2026, 11, 9).date()
+
+
+def test_货币单位识别():
+    assert _one("花了105块").currency == "CNY"
+    assert _one("花了105块钱").currency == "CNY"
+    assert _one("花了105元").currency == "CNY"
+    assert _one("花了105人民币").currency == "CNY"
+    assert _one("花了105rmb").currency == "CNY"
+    assert _one("花了105美元").currency == "USD"
+    assert _one("花了105美金").currency == "USD"
+    assert _one("花了$105").currency == "USD"
+    assert _one("花了105港币").currency == "HKD"
+    assert _one("花了105欧元").currency == "EUR"
+
+
+def test_符号与前置币种():
+    assert _one("¥105").currency == "CNY"
+    assert _one("美元105").currency == "USD"
+
+
+def test_量级后缀():
+    assert _one("买了个包1.5k").amount == 1500.0
+    assert _one("买了个手机2万").amount == 20000.0
+
+
+def test_中文数字():
+    assert cn_to_number("一百零五") == 105
+    assert cn_to_number("两千三") == 2300
+    assert cn_to_number("三千五") == 3500
+    assert cn_to_number("十五") == 15
+    assert cn_to_number("十万") == 100000
+    assert _one("买了一百零五块的衣服").amount == 105.0
+    assert _one("两千三买了个手机").amount == 2300.0
+
+
+def test_过去时间词():
+    assert _one("昨天买了个杯子30").when.date() == datetime(2026, 11, 6).date()
+    assert _one("前天买了个杯子30").when.date() == datetime(2026, 11, 5).date()
+    assert _one("大前天买了个杯子30").when.date() == datetime(2026, 11, 4).date()
+    assert _one("3天前买了个杯子30").when.date() == datetime(2026, 11, 4).date()
+
+
+def test_未来时间词():
+    assert _one("大后天买了个杯子30").when.date() == datetime(2026, 11, 10).date()
+    assert _one("3天后买了个杯子30").when.date() == datetime(2026, 11, 10).date()
+    assert _one("下个月5号交房租3000").when.date() == datetime(2026, 12, 5).date()
+    assert _one("下个月5号交房租3000").planned
+
+
+def test_上个月与上月():
+    p = _one("上个月花了2000")
+    assert p.when.strftime("%Y-%m") == "2026-10" and not p.planned
+    assert _one("上月5号买衣服300").when.date() == datetime(2026, 10, 5).date()
+
+
+def test_几月与几号():
+    assert _one("9月买衣服105").when.strftime("%Y-%m") == "2026-09"
+    assert _one("5号买衣服105", now=datetime(2026, 11, 7)).when.strftime("%Y-%m") == "2026-11"
+    assert _one("28号买衣服105", now=datetime(2026, 11, 7)).when.strftime("%Y-%m") == "2026-10"
+
+
+def test_时间词不会被当成金额():
+    p = _one("上个月5号买了双鞋300")
+    assert p.amount == 300.0
+    assert p.when.date() == datetime(2026, 10, 5).date()
+
+
+def test_一句话多笔拆分():
+    ps = parse("今天买衣服105，还买了大米45", now=NOW)
+    assert [p.amount for p in ps] == [105.0, 45.0]
+    assert {p.category for p in ps} == {"clothing", "food"}
+
+
+def test_时间可继承():
+    ps = parse("今天买衣服105，洗车100", now=NOW)
+    assert len(ps) == 2
+    assert all(p.when.date() == NOW.date() for p in ps)
+
+
+def test_单笔带逗号不拆坏():
+    p = _one("今天，我买了一件衣服，花了105块")
+    assert p.amount == 105.0 and p.category == "clothing"
+
+
+def test_收入方向():
+    p = _one("工资发了12000")
+    assert p.direction == "income" and p.amount == 12000.0
+    assert p.category == "income"
+
+
+def test_无金额不解析():
+    assert parse("今天几号", now=NOW) == []
+    assert parse("本月预算怎么分配", now=NOW) == []
+    assert parse("今天买了几件衣服", now=NOW) == []
+
+
+def test_花费信号闸门():
+    assert has_expense_signal("今天买了一件衣服花了105块")
+    assert has_expense_signal("洗车100")
+    assert not has_expense_signal("今天几号")
+    assert not has_expense_signal("3个月计划")
+    assert has_payment_verb("我买了105块的衣服")
+    assert not has_payment_verb("衣服预算800")
+
+
+def test_预算句不自动记账():
+    assert not _should_autorecord("衣服预算800")
+    assert not _should_autorecord("给我定个800的餐饮预算")
+    assert _should_autorecord("今天买了一件衣服花了105块")
+    assert _should_autorecord("洗车100")
+
+
+def test_主管把花费报备路由给财务():
+    assert SupervisorAgent._is_expense_report("今天买了一件衣服花了105块")
+    assert SupervisorAgent._is_expense_report("后天花了100洗车")
+    assert not SupervisorAgent._is_expense_report("帮我总结这篇文档")
+    assert not SupervisorAgent._is_expense_report("今天几号")
+
+
+def test_记账回执与账本(tmp_path):
+    rt = _rt(tmp_path)
+    rec = rt.record_text("今天买了一件衣服花了105块")
+    assert len(rec["recorded"]) == 1
+    assert "已记账 1 笔" in rec["ack"] and "105.00" in rec["ack"]
+
+    led = rt.ledger("2026-11")
+    assert led["count"] == 1 and led["expense"] == 105.0
+    assert led["by_category"][0]["category"] == "clothing"
+    assert led["planned"]["count"] == 0
+
+
+def test_计划支出不进本月已花(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("今天买了一件衣服花了105块")
+    rt.record_text("明天买一袋大米花了45")
+
+    led = rt.ledger()
+    assert led["expense"] == 105.0
+    assert led["planned"]["count"] == 1
+    assert led["planned"]["expense"] == 45.0
+    assert rt.analyze()["transaction_count"] == 1
+
+
+def test_多币种折成本位币(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("花了100美元")
+    led = rt.ledger()
+    assert led["expense"] == 720.0
+    usd = [c for c in led["by_currency"] if c["currency"] == "USD"][0]
+    assert usd["original_total"] == -100.0 and usd["base_total"] == -720.0
+    assert rt.transactions[0].amount_original == -100.0
+    assert rt.transactions[0].fx_rate == 7.2
+
+
+def test_汇率可改(tmp_path):
+    rt = _rt(tmp_path)
+    rt.fx.set_rate("USD", 7.0)
+    rt.record_text("花了100美金")
+    assert rt.ledger()["expense"] == 700.0
+    assert _rt(tmp_path).fx.rate("USD") == 7.0
+
+
+def test_按天与分类汇总(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("今天买了一件衣服花了105块")
+    rt.record_text("今天在星巴克花了32块钱")
+    led = rt.ledger()
+    assert led["count"] == 2
+    day = led["by_day"][0]
+    assert day["count"] == 2 and day["expense"] == -137.0
+    cats = {c["category"]: c["total"] for c in led["by_category"]}
+    assert cats["clothing"] == 105.0 and cats["food"] == 32.0
+
+
+def test_记账后账本可持久化(tmp_path):
+    rt = _rt(tmp_path)
+    rt.record_text("今天买了一件衣服花了105块")
+    rt.record_text("上个月5号买了双鞋300")
+    again = _rt(tmp_path)
+    assert len(again.transactions) == 2
+    assert again.ledger("2026-10")["expense"] == 300.0
+    assert again.ledger("2026-11")["expense"] == 105.0
+
+
+def test_未配置汇率按1比1并提示(tmp_path):
+    rt = _rt(tmp_path)
+    rt.fx.rates.pop("JPY", None)
+    rec = rt.record_text("花了100日元")
+    assert any("汇率" in w for w in rec["recorded"][0]["warnings"])
+    assert rt.ledger()["expense"] == 100.0

package/python/tests/test_finance_persist.py

@@ -0,0 +1,174 @@
+"""财务内核持久化 — 重启不丢账、坏文件不阻断启动、批量导入不逐笔写盘。
+
+背景:交易/预算/余额原先只在内存,后端一重启就清零,财务分析永远是"0 笔交易"。
+这里固定住三件事:
+  1. 写进去的状态能被**新实例**读回来(真正的重启等价);
+  2. 文件损坏 / 单条记录坏 / 落盘失败时,一律降级并把错误暴露出来,不抛、不阻断启动;
+  3. 批量导入只做一次磁盘 IO。
+"""
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from foxclaw.finance import FinanceRuntime, Transaction
+
+CSV = str(Path(__file__).parent.parent / "examples" / "sample_transactions.csv")
+
+
+def _rt(tmp_path, data_name="finance_data.json"):
+    """临时目录里的 runtime:policy 与数据都写在 tmp_path,不污染工作区。"""
+    return FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"),
+                          data_path=str(tmp_path / data_name))
+
+
+def test_落盘点默认与policy同目录(tmp_path):
+    rt = FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"))
+    assert rt._data_path == tmp_path / "finance_data.json"
+
+
+def test_交易预算余额重启后可恢复(tmp_path):
+    rt = _rt(tmp_path)
+    rt.add_transaction(Transaction(amount=-88.5, category="food",
+                                   entity="星巴克", account="debit",
+                                   tags=["recurring"], note="早餐"))
+    rt.add_transaction(Transaction(amount=12000, category="salary",
+                                   entity="公司", account="debit"))
+    rt.set_budget("food", 400)
+    rt.set_balance("debit", 11800)
+
+    assert rt.save() is True
+    assert (tmp_path / "finance_data.json").exists()
+
+    rt2 = _rt(tmp_path)
+    assert len(rt2.transactions) == 2
+    assert rt2.transactions[0].amount == -88.5
+    assert rt2.transactions[0].entity == "星巴克"
+    assert rt2.transactions[0].note == "早餐"
+    assert rt2.transactions[0].tags == ["recurring"]
+    assert rt2.transactions[1].amount == 12000
+    assert len(rt2.budgets) == 1 and rt2.budgets[0].monthly_limit == 400
+    assert rt2.account_balances == {"debit": 11800}
+    assert rt2.entities["星巴克"].txn_count == 1
+    assert rt2.entities["星巴克"].entity_type == "subscription"
+    assert rt2.entities["公司"].total_amount == 12000
+
+
+def test_写入即落盘下次实例自动加载(tmp_path):
+    rt = _rt(tmp_path)
+    rt.add_transaction(Transaction(amount=-20, category="transport",
+                                   entity="地铁", account="debit"))
+    rt.set_balance("debit", 100)
+
+    loaded = _rt(tmp_path)
+    assert loaded.load()
+    assert len(loaded.transactions) == 1
+    assert loaded.status()["persist"]["load_error"] == ""
+
+
+def test_文件格式合法且带版本(tmp_path):
+    rt = _rt(tmp_path)
+    rt.add_transaction(Transaction(amount=-1, category="misc",
+                                   entity="x", account="debit"))
+    data = json.loads((tmp_path / "finance_data.json").read_text(encoding="utf-8"))
+    assert data["version"] == 1
+    assert data["saved_at"]
+    assert len(data["transactions"]) == 1
+
+
+def test_损坏文件不阻断启动且可自愈(tmp_path):
+    p = tmp_path / "finance_data.json"
+    p.write_text("{ 这不是 json ", encoding="utf-8")
+
+    rt = _rt(tmp_path)
+    assert rt.transactions == [] and rt.budgets == []
+    assert rt.load_error
+
+    rt.add_transaction(Transaction(amount=-5, category="misc",
+                                   entity="y", account="debit"))
+    assert rt.save() is True
+    assert rt.load_error == ""
+    assert len(_rt(tmp_path).transactions) == 1
+
+
+def test_顶层非对象也降级(tmp_path):
+    (tmp_path / "finance_data.json").write_text("[1, 2, 3]", encoding="utf-8")
+    rt = _rt(tmp_path)
+    assert rt.transactions == []
+    assert "JSON 对象" in rt.load_error
+
+
+def test_单条坏记录只跳过自己不废掉整份(tmp_path):
+    (tmp_path / "finance_data.json").write_text(json.dumps({
+        "version": 1,
+        "transactions": [
+            {"amount": -10, "category": "food", "entity": "a", "account": "debit"},
+            {"category": "food"},
+            "not-a-dict",
+            {"amount": -20, "category": "food", "entity": "b", "account": "debit"},
+        ],
+        "budgets": [{"category": "food", "monthly_limit": 300}],
+        "account_balances": {"debit": "not-a-number", "cash": 50},
+    }, ensure_ascii=False), encoding="utf-8")
+
+    rt = _rt(tmp_path)
+    assert [t.entity for t in rt.transactions] == ["a", "b"]
+    assert len(rt.budgets) == 1
+    assert rt.account_balances == {"cash": 50.0}
+
+
+def test_实体段缺失时按交易重建(tmp_path):
+    (tmp_path / "finance_data.json").write_text(json.dumps({
+        "transactions": [
+            {"amount": -30, "category": "subscription", "entity": "Netflix",
+             "account": "card", "tags": ["recurring"]},
+            {"amount": -10, "category": "food", "entity": "Netflix", "account": "card"},
+        ],
+    }, ensure_ascii=False), encoding="utf-8")
+
+    rt = _rt(tmp_path)
+    assert rt.entities["Netflix"].txn_count == 2
+    assert rt.entities["Netflix"].total_amount == -40
+    assert rt.entities["Netflix"].entity_type == "subscription"
+
+
+def test_批量导入只写一次盘(tmp_path, monkeypatch):
+    rt = _rt(tmp_path)
+    calls = []
+    orig = rt.save
+
+    def _counting_save():
+        calls.append(1)
+        return orig()
+
+    monkeypatch.setattr(rt, "save", _counting_save)
+    n = rt.import_csv(CSV)
+    assert n > 0
+    assert len(calls) == 1, f"导入 {n} 笔应只落盘 1 次,实为 {len(calls)} 次"
+    assert len(_rt(tmp_path).transactions) == n
+
+
+def test_落盘失败只回报不抛异常(tmp_path):
+    blocker = tmp_path / "blocker"
+    blocker.write_text("我是个文件,不是目录", encoding="utf-8")
+    rt = FinanceRuntime(policy_path=str(tmp_path / "finance_policy.yaml"),
+                        data_path=str(blocker / "finance_data.json"))
+    assert rt.save() is False
+    assert rt.save_error
+    rt.add_transaction(Transaction(amount=-1, category="misc",
+                                   entity="z", account="debit"))
+    assert len(rt.transactions) == 1
+    assert rt.status()["persist"]["save_error"]
+
+
+def test_分析使用持久化后的数据(tmp_path):
+    rt = _rt(tmp_path)
+    rt.set_budget("food", 100)
+    rt.add_transaction(Transaction(amount=-150, category="food",
+                                   entity="餐厅", account="debit"))
+
+    report = _rt(tmp_path).analyze(period="2026-11")
+    assert report["transaction_count"] == 1
+    food = [b for b in report["budget_status"] if b["category"] == "food"]
+    assert food and food[0]["is_over"] is True

package/python/tests/test_gateway.py

@@ -0,0 +1,125 @@
+"""统一 API 网关:per-client 令牌桶 + 配额 + 空闲淘汰 + 429/Retry-After + 启用哲学。
+全离线(TestClient)。网关默认关,本测试显式 FOXCLAW_GATEWAY=1 + 低额度触发限流。"""
+import os, sys, tempfile
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+import pytest
+
+def test_gateway():
+    if "foxclaw.api" in sys.modules:
+        pytest.skip("需独立进程运行(模块级单例已固化),请用 tests/run_all.py")
+    os.environ["FOXCLAW_SKIP_DOTENV"] = "1"
+    os.environ["FOXCLAW_GATEWAY"] = "1"
+    os.environ["FOXCLAW_GATEWAY_RATE"] = "5"
+    os.environ["FOXCLAW_GATEWAY_QUOTA"] = "1000"
+    os.environ["FOXCLAW_MAX_BODY_MB"] = "1"
+    os.environ.pop("FOXCLAW_API_KEY", None)
+    os.environ["HKC_EMBEDDING"] = "stub"
+    os.environ["FOXCLAW_SHADOW_ROUNDS"] = "6"
+    os.environ["FOXCLAW_DATA_DIR"] = tempfile.mkdtemp(prefix="foxclaw_gw_")
+
+    print("=" * 60); print("统一 API 网关验证"); print("=" * 60)
+
+    from foxclaw.core.gateway import Gateway
+
+    g = Gateway(rate_per_min=3, quota_per_hour=100000)
+    allowed = [g.check("a")[0] for _ in range(5)]
+    assert allowed[:3] == [True, True, True] and allowed[3] is False, allowed
+    ok, retry, reason = g.check("a")
+    assert not ok and reason == "rate" and retry >= 1, (ok, retry, reason)
+    print("[1] 令牌桶突发限流(3 放行→限流,带 retry)OK")
+
+    assert g.check("b")[0] is True, "客户端之间不隔离"
+    print("[2] per-client 隔离 OK")
+
+    g2 = Gateway(rate_per_min=100000, quota_per_hour=4)
+    cnt = sum(1 for _ in range(6) if g2.check("z")[0])
+    assert cnt == 4, cnt
+    ok, retry, reason = g2.check("z")
+    assert not ok and reason == "quota" and retry >= 1, (ok, retry, reason)
+    print("[3] 每小时配额封顶(reason=quota)OK")
+
+    g3 = Gateway(rate_per_min=100, quota_per_hour=100000, max_clients=64)
+    for i in range(500):
+        g3.check(f"c{i}")
+    assert g3.stats()["tracked_clients"] <= 64, g3.stats()
+    print(f"[4] 空闲淘汰(500 client → 追踪 {g3.stats()['tracked_clients']}≤64,防内存 DoS)OK")
+
+    from fastapi.testclient import TestClient
+    from foxclaw.api import app, _gateway_on
+
+    with TestClient(app) as c:
+        s = c.get("/api/gateway/stats").json()
+        assert s["enabled"] is True and s["rate_per_min"] == 5, s
+        print(f"[5] /api/gateway/stats(enabled={s['enabled']}, rate={s['rate_per_min']}/min)OK")
+
+        codes = [c.get("/api/status").status_code for _ in range(12)]
+        assert 200 in codes and 429 in codes, codes
+        r429 = None
+        for _ in range(15):
+            r = c.get("/api/status")
+            if r.status_code == 429:
+                r429 = r; break
+        assert r429 is not None, "未触发 429"
+        assert r429.headers.get("Retry-After") and r429.json().get("retry_after", 0) >= 1, (r429.headers, r429.text)
+        print("[6] 突发超限 → 429 + Retry-After 头 OK")
+
+        assert c.get("/health").status_code == 200, "探针被网关误限"
+        print("[7] 探针 /health 豁免网关 OK")
+
+        big = c.post("/api/knowledge/ingest", json={"text": "x" * (1200 * 1024)})
+        assert big.status_code == 413, (big.status_code, big.text[:120])
+        print("[8] 超大请求体 → 413(读 body 前拦截)OK")
+
+        import asyncio
+        from starlette.requests import Request as _Req
+        from foxclaw.api.middleware import (
+            _gateway_mw, _PayloadTooLarge, _wrap_body_limit)
+
+        pending = [b"x" * 10, b"y" * 10, b"z" * 10]
+
+        async def _recv():
+            if pending:
+                return {"type": "http.request", "body": pending.pop(0),
+                        "more_body": bool(pending)}
+            return {"type": "http.disconnect"}
+
+        req = _Req({"type": "http", "method": "POST", "path": "/api/x",
+                    "scheme": "http", "server": ("test", 80),
+                    "headers": [], "query_string": b""}, _recv)
+        _wrap_body_limit(req, 15)
+
+        async def _drain():
+            for _ in range(3):
+                await req.receive()
+
+        try:
+            asyncio.run(_drain())
+        except _PayloadTooLarge:
+            pass
+        else:
+            raise AssertionError("chunked 超限未被流上计数拦住")
+
+        async def _boom(_req):
+            raise _PayloadTooLarge(999)
+
+        req2 = _Req({"type": "http", "method": "POST", "path": "/api/x",
+                     "scheme": "http", "server": ("test", 80),
+                     "headers": [], "query_string": b""})
+        resp = asyncio.run(_gateway_mw(req2, _boom))
+        assert resp.status_code == 413, resp.status_code
+        print("[8b] chunked 超限 → 流上计数拦截并转 413 OK")
+
+    os.environ.pop("FOXCLAW_GATEWAY", None); os.environ.pop("FOXCLAW_API_KEY", None)
+    assert _gateway_on() is False, "本地默认应关"
+    os.environ["FOXCLAW_API_KEY"] = "x"
+    assert _gateway_on() is True, "配鉴权应自动开"
+    os.environ["FOXCLAW_GATEWAY"] = "0"
+    assert _gateway_on() is False, "FOXCLAW_GATEWAY=0 应强制关"
+    os.environ.pop("FOXCLAW_GATEWAY", None); os.environ.pop("FOXCLAW_API_KEY", None)
+    print("[9] 启用哲学(默认关 / 配 key 自动开 / =0 强制关)OK")
+
+    print("\n统一 API 网关验证全部通过")
+
+if __name__ == "__main__":
+    test_gateway()