foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/core/web_search.py

@@ -0,0 +1,242 @@
+"""
+联网搜索工具 —— 给 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
+
+
+# 触发联网搜索的关键词:问到实时/时效性信息时才搜
+# ── 是否需要联网:话题信号(强) vs 时间词(弱) vs 个人数据(否决)──────────────
+# 教训:曾把纯时间词(今天/本月/最近…)也当触发,结果「分析一下本月支出」这类**问自己账本**
+# 的任务被误判为需要联网 → 白跑一次 ~22s 的付费深度搜索。而 Foxclaw 的领域(个人财务/
+# 行程/学习)天生满是时间词,这不是个别误判,是**一整类合法任务**在白交时间和钱。
+# 现在:时间词单独**不足以**触发;必须出现"外部世界话题";且个人数据一律否决。
+# (与既有的 now⊂knowledge / current⊂concurrent 词边界修复同源:都是过度触发。)
+
+# 强触发:出现即说明要的是外部实时信息
+TOPIC_TRIGGERS = [
+    "版本", "几个版本", "第几", "价格", "多少钱", "汇率", "股价", "新闻",
+    "发布", "上线", "更新到", "迭代", "排行", "排名", "天气",
+    # 问"某产品/技术的模型/型号/出没出/更没更"——都是外部时效信息,过去漏搜→编造。
+    # 只留明确指向外部产品的词;"有哪些/可用/支持"太宽(会误伤"我有哪些任务"),不加。
+    "模型", "型号", "出了没", "发布没", "更新没", "新版",
+    "latest", "news", "version", "price", "models",
+]
+# 弱信号:纯时间词。单独出现不触发(个人数据问题天生带这些词)
+TIME_WORDS = [
+    "最新", "现在", "目前", "今天", "今日", "昨天", "本周", "本月", "今年",
+    "最近", "当前", "today", "current", "now",
+]
+# 否决:问的是用户自己的账/行程/学习/记忆 —— 这些答案在本地领域内核里,不在网上。
+# 注意别放"我的"这类过宽的词:「我的股票现在多少钱」是真需要联网的。
+PERSONAL_MARKERS = [
+    "支出", "收入", "预算", "交易", "账单", "花了", "消费", "记账", "结余", "余额",
+    "行程", "日程", "出行", "复习", "知识点", "学习计划", "记忆",
+]
+
+SEARCH_TRIGGERS = TOPIC_TRIGGERS          # 对外保持同名(旧引用不破)
+
+# 中文触发词按「子串」匹配(中文无词边界);英文触发词按「词边界」匹配,
+# 否则短词会误命中常见词:"now"⊂"knowledge"、"current"⊂"concurrent"、
+# "now"⊂"known" —— 在这个满口 knowledge 的项目里会频繁无谓地打百度。
+_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                      # 问的是自己的数据 → 答案在本地内核,绝不联网
+    # 自我模型/身份问题(你是什么模型 / 你现在是哪个模型 …)→ 由 ModelRouter 运行时注入本地即答,不联网。
+    # 否则会因含"模型"触发词白跑一次 ~20s 百度搜索。"你"与"模型"相邻(≤8字)才算自问;
+    # "你帮我查 X 的模型"(相距远)仍走搜索。
+    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))
+    # 注:只含时间词(今天/本月/最近…)而无话题 → 不触发(见上方 TIME_WORDS 说明)
+
+
+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,   # 不要答案里的 ^[1]^ 角标(参考资料已单列)
+        }).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 ""
+        # 我方的作答指令(可信,放在 <untrusted> 之外);检索到的外部内容(不可信,放在 <untrusted> 之内)。
+        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"
+        # 隔离外部内容:搜索结果是外部不可控数据,包裹进 <untrusted> 防间接注入(见 injection_guard)。
+        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,153 @@
+"""
+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                # 人类可读证据(如"餐饮已用 120%,超 ¥240")
+    weight: float                # 权重 0-1(对总风险的贡献)
+
+    def to_dict(self) -> dict:
+        return {"factor": self.factor, "evidence": self.evidence,
+                "weight": round(self.weight, 3)}
+
+
+@dataclass
+class EvidenceChain:
+    """结构化决策证据链 —— 财务决策的可审计输出。"""
+    decision_type: str                                  # 决策类型(如 budget_risk / anomaly)
+    risk_score: float = 0.0                             # 综合风险分 0-1
+    risk_factors: list = field(default_factory=list)    # [RiskFactor]
+    mitigating_factors: list = field(default_factory=list)  # 缓解因素(降低风险的)
+    rationale: str = ""                                 # 决策理由(人类可读)
+    recommended_action: str = ""                        # 建议动作
+    confidence: float = 0.0                             # 置信度 0-1
+    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          # 其余因子衰减叠加(饱和,不会超过1)
+        mitigation = min(0.2, 0.1 * len(self.mitigating_factors))  # 缓解最多减0.2
+        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)
+                # 权重随超支程度递增:超10%→0.5,超50%→0.65,超100%+→0.8(上限)
+                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)
+            # z 分数越高,权重越大(裁剪到 0.6)
+            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,100 @@
+"""本位币折算 —— 多币种记账的汇率表。
+
+为什么需要它:用户会说「花了 105 块」也会说「花了 100 美元」。如果两者都写进
+`Transaction.amount` 再求和,100 美元会被当成 100 元 —— 预算、风控、现金流预测
+会一起错,而且错得看不出来。所以账本统一用**本位币(CNY)记账**,原币金额与币种
+另存,汇总时两种都能看。
+
+汇率是**静态参考价,不联网**:宁可给一个用户能改的明确数字,也不假装实时行情。
+用户可在 `finance_fx.json` 或 `/api/finance/fx` 里改成自己的记账汇率(比如当天
+刷卡的实际结算价,那才是真实成本)。
+"""
+
+import json
+from pathlib import Path
+
+BASE_CURRENCY = "CNY"
+
+# 参考价(1 单位外币 = 多少 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):
+        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}