foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/core/web_search.py

@@ -0,0 +1,218 @@
+"""
+联网搜索工具 —— 给 Agent 提供实时信息检索能力。
+
+DeepSeek/OpenAI 等基础 API 不自带联网,本模块对接百度 AI 搜索
+(千帆 ai_search,底层百度搜索 + ERNIE),国内访问稳定、每日有免费额度。
+百度 AI 搜索是"搜索+生成"一体接口:输入问题,它联网检索后直接产出
+带引用的实时答案,本模块取其答案作为"联网上下文"注入回 Agent 的模型。
+
+配置(在 .env):
+    BAIDU_SEARCH_KEY=bce-v3/ALTAK-xxx/xxx      # 千帆 AppBuilder API Key
+    BAIDU_SEARCH_MODEL=ernie-4.5-turbo-32k     # 可选,默认 ernie-3.5-8k
+    BAIDU_SEARCH_BASE=https://qianfan.baidubce.com/v2/ai_search  # 可选
+
+降级策略:未配 key / 网络不通 / 失败 → 返回空,不影响主流程,
+Agent 如实告知"暂未查到",不编造。
+"""
+from __future__ import annotations
+import os
+import re
+import json
+import urllib.request
+import urllib.error
+from . import settings
+
+
+TOPIC_TRIGGERS = [
+    "版本", "几个版本", "第几", "价格", "多少钱", "汇率", "股价", "新闻",
+    "发布", "上线", "更新到", "迭代", "排行", "排名", "天气",
+    "模型", "型号", "出了没", "发布没", "更新没", "新版",
+    "latest", "news", "version", "price", "models",
+]
+TIME_WORDS = [
+    "最新", "现在", "目前", "今天", "今日", "昨天", "本周", "本月", "今年",
+    "最近", "当前", "today", "current", "now",
+]
+PERSONAL_MARKERS = [
+    "支出", "收入", "预算", "交易", "账单", "花了", "消费", "记账", "结余", "余额",
+    "行程", "日程", "出行", "复习", "知识点", "学习计划", "记忆",
+]
+
+SEARCH_TRIGGERS = TOPIC_TRIGGERS
+
+_CJK_TRIGGERS = [k for k in SEARCH_TRIGGERS if not k.isascii()]
+_ASCII_TRIGGERS = [k.lower() for k in SEARCH_TRIGGERS if k.isascii()]
+_ASCII_RE = (
+    re.compile(r"\b(" + "|".join(re.escape(k) for k in _ASCII_TRIGGERS) + r")\b")
+    if _ASCII_TRIGGERS else None
+)
+
+
+def is_personal_query(query: str) -> bool:
+    """问的是不是**用户自己的数据**(账本/行程/学习/记忆)。
+
+    单一真源:凡是"要不要把这个问题发到外部"的判断都用它 —— 联网增强(needs_search)、
+    技能路由的外部技能闸,都必须走这里。教训:这条保护原先只写在 needs_search 里,
+    结果技能派发默认开启后,「查一下最新的本月支出」照样把私人财务问题发去外部搜索
+    —— 同一个 bug 从没设防的旁路回来了。**保护必须放在共同咽喉,不能各写一份。**
+    """
+    if not query:
+        return False
+    return any(m in query.lower() for m in PERSONAL_MARKERS)
+
+
+def needs_search(query: str) -> bool:
+    """是否值得为这个问题联网。宁可漏搜也不要错搜:
+    错搜的代价是每次 ~22s + 付费调用(且答案本来就在本地);漏搜只是少一点时效信息。"""
+    if not query:
+        return False
+    q = query.lower()
+    if is_personal_query(q):
+        return False
+    if re.search(r"你[^,。?!]{0,8}模型", q):
+        return False
+    if any(k in q for k in _CJK_TRIGGERS):
+        return True
+    return bool(_ASCII_RE and _ASCII_RE.search(q))
+
+
+def _key() -> str:
+    return os.environ.get("BAIDU_SEARCH_KEY", "").strip()
+
+
+def _model() -> str:
+    return os.environ.get("BAIDU_SEARCH_MODEL", "ernie-3.5-8k").strip()
+
+
+def _base() -> str:
+    return os.environ.get(
+        "BAIDU_SEARCH_BASE", "https://qianfan.baidubce.com/v2/ai_search"
+    ).rstrip("/")
+
+
+def _timeout() -> int:
+    """读取超时(秒)。深度搜索较慢,默认 45s;可经 BAIDU_SEARCH_TIMEOUT 调。"""
+    return max(5, int(settings.get_safe("BAIDU_SEARCH_TIMEOUT")))
+
+
+def _deep() -> bool:
+    """是否开启深度搜索(更全但更慢)。默认开;BAIDU_SEARCH_DEEP=0 关掉换速度。"""
+    return os.environ.get("BAIDU_SEARCH_DEEP", "1").strip() not in ("0", "false", "False", "")
+
+
+def search_answer(query: str) -> dict:
+    """调用百度 AI 搜索,返回 {answer, references}。
+    answer=联网生成的实时答案文本;references=参考资料列表。失败返回空 dict。"""
+    key = _key()
+    if not key:
+        return {}
+    from .tracing import span as _span
+    with _span("web.search"):
+        return _search_answer_inner(query, key)
+
+
+def _search_answer_inner(query: str, key: str) -> dict:
+    try:
+        payload = json.dumps({
+            "messages": [{"role": "user", "content": query}],
+            "stream": False,
+            "model": _model(),
+            "enable_deep_search": _deep(),
+            "enable_corner_markers": False,
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            f"{_base()}/chat/completions",
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {key}",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=_timeout()) as resp:
+            data = json.loads(resp.read().decode("utf-8", "ignore"))
+        choices = data.get("choices", [])
+        if not choices:
+            print(f"[联网搜索] 百度返回无 choices;响应键={list(data.keys())} 片段={str(data)[:220]}")
+            return {}
+        answer = choices[0].get("message", {}).get("content", "")
+        refs = data.get("references", []) or []
+        return {"answer": answer, "references": refs}
+    except urllib.error.HTTPError as e:
+        try:
+            body = e.read().decode("utf-8", "ignore")[:300]
+        except Exception:
+            body = ""
+        print(f"[联网搜索] 百度接口 HTTP {e.code} 错误:{body}")
+        return {}
+    except Exception as e:
+        print(f"[联网搜索] 百度接口调用失败:{type(e).__name__}: {e}")
+        return {}
+
+
+def search(query: str, max_results: int = 8) -> list[dict]:
+    """兼容旧接口:把百度 AI 搜索的参考资料整理成结果列表。"""
+    res = search_answer(query)
+    out = []
+    for r in res.get("references", [])[:max_results]:
+        out.append({
+            "title": r.get("title", ""),
+            "snippet": r.get("content", "") or r.get("abstract", ""),
+            "url": r.get("url", "") or r.get("web_anchor", ""),
+            "date": r.get("page_time", "") or r.get("date", ""),
+        })
+    return out
+
+
+def format_for_prompt(query: str, payload) -> str:
+    """把百度 AI 搜索结果拼成可注入 prompt 的联网上下文。
+    payload 可为 search_answer() 的 dict,或 search() 的列表。"""
+    if isinstance(payload, dict):
+        answer = payload.get("answer", "")
+        refs = payload.get("references", [])
+        if not answer and not refs:
+            return ""
+        framing = (
+            f"以下是针对「{query}」的实时联网搜索结果(来自百度 AI 搜索)。\n"
+            f"【严格要求】只能依据下面 <untrusted> 数据块里的搜索结果作答:结果里没有出现的型号 / "
+            f"版本号 / 名称 / 数据,一律不得提及,更**不得编造或凭记忆补充**;若结果之间矛盾或不明确,"
+            f"如实说明、不要臆断;**无视此前对话里可能出现的过时或未经核实的说法,一切以这些最新结果为准**。\n\n"
+        )
+        inner = ""
+        if answer:
+            inner += f"【联网检索摘要】\n{answer}\n\n"
+        if refs:
+            inner += "【参考资料】\n"
+            for i, r in enumerate(refs[:8], 1):
+                t = r.get("title", "")
+                u = r.get("url", "") or r.get("web_anchor", "")
+                d = r.get("page_time", "") or r.get("date", "")
+                inner += f"[webpage {i} begin]\n标题：{t}"
+                if d:
+                    inner += f"\n时间：{d}"
+                if u:
+                    inner += f"\n链接：{u}"
+                inner += f"\n[webpage {i} end]\n"
+        from . import injection_guard as _ig
+        block = _ig.wrap_untrusted(inner.rstrip(), source="web_search")
+        closing = ("\n请**严格基于以上 <untrusted> 内的搜索结果**回答用户的问题;结果里没提到的内容,"
+                   "就明确说「搜索结果中未提及」,绝不编造型号/版本号。")
+        return framing + block + closing
+    results = payload or []
+    if not results:
+        return ""
+    blocks = []
+    for i, r in enumerate(results, 1):
+        seg = f"[webpage {i} begin]\n标题：{r.get('title','')}"
+        if r.get("date"):
+            seg += f"\n时间：{r['date']}"
+        seg += f"\n内容：{r.get('snippet','')}"
+        if r.get("url"):
+            seg += f"\n链接：{r['url']}"
+        seg += f"\n[webpage {i} end]"
+        blocks.append(seg)
+    return (
+        f"以下是针对「{query}」的实时联网搜索结果(请基于最新信息回答):\n\n"
+        + "\n\n".join(blocks)
+        + "\n\n请根据以上搜索结果回答用户的问题。"
+    )

package/python/foxclaw/finance/__init__.py

@@ -0,0 +1,15 @@
+"""Foxclaw — Finance: 财务 Agent 的资金行为操作系统内核"""
+from .models import (
+    Transaction, Budget, FinancialEntity,
+    FinancePolicyRule, PolicyVerdict,
+)
+from .reasoning import FinanceReasoning
+from .policy import FinancePolicyEngine, DEFAULT_RULES
+from .runtime import FinanceRuntime
+
+__all__ = [
+    "Transaction", "Budget", "FinancialEntity",
+    "FinancePolicyRule", "PolicyVerdict",
+    "FinanceReasoning", "FinancePolicyEngine", "DEFAULT_RULES",
+    "FinanceRuntime",
+]

package/python/foxclaw/finance/evidence.py

@@ -0,0 +1,149 @@
+"""
+Foxclaw 财务子系统 — 结构化证据链 (Evidence Chain)
+
+借鉴 2026 年前沿金融 AI 的"可解释性铁律":一个只给原始分数(如 0.87)
+而无人类可读证据链的决策,被认为比没有 AI 更糟,因为无法被审计员复核。
+
+每个财务风险决策输出结构化的:
+  风险分数 + 风险因子(每个带证据和权重)+ 缓解因素 + 决策理由 + 建议动作 + 置信度
+
+这与 Foxclaw 的 ThoughtChain 审计链天然契合 —— 证据链可直接沉淀为审计节点。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class RiskFactor:
+    """单个风险因子:是什么、证据、权重。"""
+    factor: str
+    evidence: str
+    weight: float
+
+    def to_dict(self) -> dict:
+        return {"factor": self.factor, "evidence": self.evidence,
+                "weight": round(self.weight, 3)}
+
+
+@dataclass
+class EvidenceChain:
+    """结构化决策证据链 —— 财务决策的可审计输出。"""
+    decision_type: str
+    risk_score: float = 0.0
+    risk_factors: list = field(default_factory=list)
+    mitigating_factors: list = field(default_factory=list)
+    rationale: str = ""
+    recommended_action: str = ""
+    confidence: float = 0.0
+    additional_checks: list = field(default_factory=list)
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat(timespec="seconds"))
+
+    def add_factor(self, factor: str, evidence: str, weight: float):
+        self.risk_factors.append(RiskFactor(factor, evidence, weight))
+        return self
+
+    def compute_risk(self) -> float:
+        """综合风险:饱和式聚合(避免多个小因子简单累加成假高危)。
+
+        取最大单因子权重为基准 + 其余因子的衰减贡献,再减缓解,裁剪 [0,1]。
+        这样"1个严重"比"3个轻微"风险更高,符合直觉。
+        """
+        if not self.risk_factors:
+            self.risk_score = 0.0
+            return 0.0
+        weights = sorted((f.weight for f in self.risk_factors), reverse=True)
+        score = weights[0]
+        for w in weights[1:]:
+            score += w * (1 - score) * 0.5
+        mitigation = min(0.2, 0.1 * len(self.mitigating_factors))
+        self.risk_score = max(0.0, min(1.0, round(score - mitigation, 3)))
+        return self.risk_score
+
+    def level(self) -> str:
+        """风险等级(供人快速判断)。"""
+        s = self.risk_score
+        return "high" if s >= 0.7 else "medium" if s >= 0.4 else "low"
+
+    def to_dict(self) -> dict:
+        return {
+            "decision_type": self.decision_type,
+            "risk_score": self.risk_score,
+            "risk_level": self.level(),
+            "risk_factors": [f.to_dict() for f in self.risk_factors],
+            "mitigating_factors": list(self.mitigating_factors),
+            "rationale": self.rationale,
+            "recommended_action": self.recommended_action,
+            "confidence": round(self.confidence, 3),
+            "additional_checks": list(self.additional_checks),
+            "created_at": self.created_at,
+        }
+
+    def to_thought_note(self) -> str:
+        """压缩成一句可塞进 ThoughtChain 的审计摘要。"""
+        factors = "; ".join(f"{f.factor}({f.weight})" for f in self.risk_factors[:3])
+        return (f"[财务决策·{self.decision_type}] 风险={self.risk_score}({self.level()}) "
+                f"| 因子: {factors} | 建议: {self.recommended_action}")
+
+
+class FinanceExplainer:
+    """把财务原始判断转成结构化证据链。"""
+
+    @staticmethod
+    def explain_budget_risk(budget_status: list) -> EvidenceChain:
+        """预算风险 → 证据链。budget_status 为 budget_status() 的输出。"""
+        ec = EvidenceChain(decision_type="budget_risk", confidence=0.9)
+        over_budgets = []
+        near_budgets = []
+        for b in budget_status:
+            ratio = b.get("usage_ratio", 0)
+            cat = b.get("category", "?")
+            if ratio >= 1.0:
+                over = b.get("spent", 0) - b.get("monthly_limit", 0)
+                w = min(0.8, 0.45 + (ratio - 1.0) * 0.35)
+                ec.add_factor("超预算", f"{cat} 已用 {ratio*100:.0f}%,超支 ¥{over:.0f}",
+                              weight=w)
+                over_budgets.append(cat)
+            elif ratio >= 0.8:
+                ec.add_factor("接近预算上限",
+                              f"{cat} 已用 {ratio*100:.0f}%,接近上限", weight=0.25)
+                near_budgets.append(cat)
+        healthy = [b.get("category") for b in budget_status
+                   if b.get("usage_ratio", 0) < 0.8]
+        if healthy:
+            ec.mitigating_factors.append(f"{len(healthy)} 个分类预算健康")
+        ec.compute_risk()
+        if over_budgets:
+            ec.rationale = f"{','.join(over_budgets)} 已超预算,需立即关注"
+            ec.recommended_action = f"削减 {over_budgets[0]} 支出或调整预算"
+            ec.additional_checks.append("检查是否有可取消的重复订阅")
+        elif near_budgets:
+            ec.rationale = f"{','.join(near_budgets)} 接近上限,建议放缓"
+            ec.recommended_action = "本月剩余时间控制相关分类支出"
+        else:
+            ec.rationale = "所有预算分类处于健康水平"
+            ec.recommended_action = "保持当前消费节奏"
+        return ec
+
+    @staticmethod
+    def explain_anomalies(anomalies: list) -> EvidenceChain:
+        """异常消费 → 证据链。anomalies 为 detect_anomalies() 的输出。"""
+        ec = EvidenceChain(decision_type="anomaly", confidence=0.85)
+        for a in anomalies[:5]:
+            z = a.get("z_score", 0)
+            w = min(0.6, 0.15 + z * 0.05)
+            ec.add_factor("异常大额支出",
+                          f"{a.get('entity','?')} ¥{abs(a.get('amount',0)):.0f}"
+                          f"({a.get('category','?')},偏离度 z={z})", weight=w)
+        ec.compute_risk()
+        if anomalies:
+            ec.rationale = f"检测到 {len(anomalies)} 笔异常支出,偏离历史模式"
+            ec.recommended_action = "核对这些交易是否本人操作,排查盗刷/误记"
+            ec.additional_checks.append("与银行流水对账确认")
+            if len(anomalies) >= 3:
+                ec.additional_checks.append("考虑是否近期消费习惯发生变化")
+        else:
+            ec.rationale = "未发现异常支出,消费模式稳定"
+            ec.recommended_action = "无需处理"
+            ec.confidence = 0.9
+        return ec

package/python/foxclaw/finance/fx.py

@@ -0,0 +1,98 @@
+"""本位币折算 —— 多币种记账的汇率表。
+
+为什么需要它:用户会说「花了 105 块」也会说「花了 100 美元」。如果两者都写进
+`Transaction.amount` 再求和,100 美元会被当成 100 元 —— 预算、风控、现金流预测
+会一起错,而且错得看不出来。所以账本统一用**本位币(CNY)记账**,原币金额与币种
+另存,汇总时两种都能看。
+
+汇率是**静态参考价,不联网**:宁可给一个用户能改的明确数字,也不假装实时行情。
+用户可在 `finance_fx.json` 或 `/api/finance/fx` 里改成自己的记账汇率(比如当天
+刷卡的实际结算价,那才是真实成本)。
+"""
+
+import json
+from pathlib import Path
+
+BASE_CURRENCY = "CNY"
+
+DEFAULT_RATES = {
+    "CNY": 1.0,
+    "USD": 7.2,
+    "HKD": 0.92,
+    "EUR": 7.8,
+    "JPY": 0.048,
+    "GBP": 9.1,
+    "KRW": 0.0052,
+    "SGD": 5.3,
+    "AUD": 4.7,
+    "CAD": 5.2,
+}
+
+
+class FxTable:
+    """币种 → 本位币折算率,带落盘(原子写)。"""
+
+    def __init__(self, path: str | None = None):
+        self.path = Path(path) if path else None
+        self.rates = dict(DEFAULT_RATES)
+        self.note = "static"
+        self._load()
+
+    def _load(self):
+        if not self.path or not self.path.exists():
+            return
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            rates = data.get("rates") if isinstance(data, dict) else None
+            if isinstance(rates, dict):
+                for k, v in rates.items():
+                    try:
+                        self.rates[str(k).upper()] = float(v)
+                    except (TypeError, ValueError):
+                        continue
+                if data.get("note"):
+                    self.note = data["note"]
+        except Exception:
+            pass
+
+    def save(self) -> bool:
+        if not self.path:
+            return False
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self.path.with_suffix(".tmp")
+            tmp.write_text(json.dumps({"base": BASE_CURRENCY, "note": self.note,
+                                       "rates": self.rates},
+                                      ensure_ascii=False, indent=1), encoding="utf-8")
+            tmp.replace(self.path)
+            return True
+        except Exception:
+            return False
+
+    def rate(self, currency: str) -> float:
+        """取折算率。未知币种返回 1.0,由调用方标注「按 1:1 暂记」。"""
+        if not currency:
+            return 1.0
+        return float(self.rates.get(str(currency).upper(), 1.0))
+
+    def known(self, currency: str) -> bool:
+        return str(currency or "").upper() in self.rates
+
+    def to_base(self, amount: float, currency: str = BASE_CURRENCY) -> tuple:
+        """原币 → (本位币金额, 折算率)。"""
+        r = self.rate(currency)
+        return round(float(amount) * r, 2), r
+
+    def set_rate(self, currency: str, rate: float) -> dict:
+        cur = str(currency or "").upper().strip()
+        if not cur or rate is None or float(rate) <= 0:
+            raise ValueError("币种与汇率都必须有效(汇率 > 0)")
+        self.rates[cur] = round(float(rate), 6)
+        self.note = "user"
+        self.save()
+        return self.snapshot()
+
+    def snapshot(self) -> dict:
+        return {"base": BASE_CURRENCY, "note": self.note,
+                "rates": dict(sorted(self.rates.items())),
+                "path": str(self.path) if self.path else None}

package/python/foxclaw/finance/graph.py

@@ -0,0 +1,179 @@
+"""
+Foxclaw 财务子系统 — 财务数据图 (Financial Data Graph)
+
+借鉴 2026 年企业级财务 Agent 的核心设计:不把推理建在孤立记录上,而是先把
+财务数据连接、归一化成一张可审计的关系图,让推理基于"关系"而非"孤立记录"。
+
+适配 Foxclaw 个人/Agent 级:把交易、分类、商户、账户、预算关联成图,支持
+关系型查询(这笔超支由谁造成、关联哪些交易、影响哪个账户),与 HMR 关系图呼应。
+
+节点类型:transaction / category / entity(商户) / account / budget
+边:交易→分类、交易→商户、交易→账户、预算→分类(预算监管该分类)
+"""
+from __future__ import annotations
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+
+@dataclass
+class GraphNode:
+    node_id: str
+    node_type: str
+    label: str
+    attrs: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {"id": self.node_id, "type": self.node_type,
+                "label": self.label, "attrs": self.attrs}
+
+
+@dataclass
+class GraphEdge:
+    src: str
+    dst: str
+    rel: str
+    attrs: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {"src": self.src, "dst": self.dst, "rel": self.rel,
+                "attrs": self.attrs}
+
+
+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)
+
+    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]
+
+    def _add_edge(self, src: str, dst: str, rel: str, **attrs):
+        e = GraphEdge(src, dst, rel, dict(attrs))
+        self.edges.append(e)
+        self._adj[src].append(e)
+        self._radj[dst].append(e)
+
+    def build(self, transactions: list, budgets: list | None = None):
+        """从交易 + 预算构建图。"""
+        self.nodes.clear(); self.edges.clear()
+        self._adj.clear(); self._radj.clear()
+
+        for t in transactions:
+            tid = f"txn:{t.id}"
+            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:
+                cnode.attrs["total"] = cnode.attrs.get("total", 0) + abs(t.amount)
+                cnode.attrs["count"] = cnode.attrs.get("count", 0) + 1
+            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")
+
+        for b in (budgets or []):
+            bid = f"bud:{b.category}"
+            self._ensure_node(bid, "budget", f"{b.category}预算",
+                              monthly_limit=b.monthly_limit, spent=b.spent)
+            cat_id = f"cat:{b.category}"
+            if cat_id in self.nodes:
+                self._add_edge(bid, cat_id, "monitors")
+        return self
+
+    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]
+
+    def transactions_of(self, node_id: str) -> list:
+        """某节点(分类/商户/账户)关联的所有交易。"""
+        return [self.nodes[e.src] for e in self._radj.get(node_id, [])
+                if self.nodes[e.src].node_type == "transaction"]
+
+    def top_entities_in_category(self, category: str, top: int = 3) -> list:
+        """某分类下,按消费额排名的商户 —— 回答'这个分类的钱花在谁身上'。"""
+        cat_id = f"cat:{category}"
+        txns = self.transactions_of(cat_id)
+        by_entity: defaultdict[str, float] = defaultdict(float)
+        for t in txns:
+            if not t.attrs.get("is_expense"):
+                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))
+        ranked = sorted(by_entity.items(), key=lambda x: -x[1])[:top]
+        return [{"entity": name, "amount": round(amt, 2)} for name, amt in ranked]
+
+    def trace_overspend(self, category: str) -> dict:
+        """追溯某分类超支的成因 —— 图的核心价值:回答'谁造成了超支'。"""
+        cat_id = f"cat:{category}"
+        bud_id = f"bud:{category}"
+        if cat_id not in self.nodes:
+            return {"category": category, "found": False}
+        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,
+            "total_spent": round(spent, 2),
+            "budget_limit": limit,
+            "is_over": (limit is not None and spent > limit),
+            "top_contributors": contributors,
+            "transaction_count": cat.attrs.get("count", 0),
+        }
+        if contributors:
+            top = contributors[0]
+            result["primary_driver"] = (
+                f"{top['entity']} 贡献了 ¥{top['amount']:.0f}"
+                f"({top['amount']/spent*100:.0f}%)" if spent else top["entity"])
+        return result
+
+    def account_exposure(self) -> list:
+        """各账户的支出敞口 —— 回答'钱主要从哪个账户流出'。"""
+        out = []
+        for nid, node in self.nodes.items():
+            if node.node_type != "account":
+                continue
+            txns = self.transactions_of(nid)
+            total = sum(abs(t.attrs.get("amount", 0)) for t in txns
+                        if t.attrs.get("is_expense"))
+            out.append({"account": node.label, "outflow": round(total, 2),
+                        "transaction_count": len(txns)})
+        return sorted(out, key=lambda x: -x["outflow"])
+
+    def stats(self) -> dict:
+        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),
+                "by_type": dict(by_type)}
+
+    def to_dict(self, max_nodes: int = 200) -> dict:
+        """导出图(供前端可视化或调试)。"""
+        nodes = list(self.nodes.values())[:max_nodes]
+        node_ids = {n.node_id for n in nodes}
+        return {
+            "nodes": [n.to_dict() for n in nodes],
+            "edges": [e.to_dict() for e in self.edges
+                      if e.src in node_ids and e.dst in node_ids],
+            "stats": self.stats(),
+        }