foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/core/update_check.py

@@ -0,0 +1,149 @@
+"""可选的新版本检查(默认关)。
+
+为什么默认关:foxclaw 的定位是本地优先 —— 默认外呼会让「断网也能用」多一个
+例外,也给安全审计多一个出网点。**只有** 设置 ``FOXCLAW_UPDATE_CHECK=1`` 时才会
+访问 PyPI,其余情况 ``status()`` 里 ``enabled=False``、``update_available=False``。
+
+失败一律静默:查版本是锦上添花,不能因为它让 ``/api/system/info`` 变慢或报错。
+- 结果按 24h 缓存到 ``<FOXCLAW_DATA_DIR>/update_check.json``;
+- 查询在 daemon 线程里跑,不阻塞请求;
+- 查失败时保留上次成功的结果(只是不刷新时间),避免一次网络抖动让提示消失。
+
+只发一个 GET ``https://pypi.org/pypi/foxclaw/json``,不带任何本机信息。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+_PYPI_URL = "https://pypi.org/pypi/foxclaw/json"
+_TTL = 24 * 3600
+_TIMEOUT = 3.0
+
+_lock = threading.Lock()
+_inflight = False
+_last_error: str | None = None
+
+
+def _enabled() -> bool:
+    return os.environ.get("FOXCLAW_UPDATE_CHECK", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _current() -> str:
+    from foxclaw import __version__
+
+    return __version__
+
+
+def _data_dir() -> Path:
+    return Path(os.environ.get("FOXCLAW_DATA_DIR") or "./foxclaw_data").expanduser()
+
+
+def _cache_path() -> Path:
+    return _data_dir() / "update_check.json"
+
+
+def parse_version(value: str) -> tuple[int, ...]:
+    """``"0.1.10"`` → ``(0, 1, 10)``。只取各段的前导数字,预发布/本地后缀丢掉。
+
+    不引入 ``packaging``:这里只需要「谁更新」,自己比数字段足够,也少一个依赖。
+    """
+    parts: list[int] = []
+    for chunk in str(value or "").strip().split("."):
+        digits = ""
+        for ch in chunk:
+            if not ch.isdigit():
+                break
+            digits += ch
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts)
+
+
+def is_newer(latest: str, current: str) -> bool:
+    """latest 是否严格新于 current(逐段比,缺的段补 0)。"""
+    left, right = parse_version(latest), parse_version(current)
+    width = max(len(left), len(right))
+    return left + (0,) * (width - len(left)) > right + (0,) * (width - len(right))
+
+
+def _read_cache() -> dict[str, Any]:
+    try:
+        data = json.loads(_cache_path().read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_cache(data: dict[str, Any]) -> None:
+    try:
+        path = _cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def _fetch_latest() -> str:
+    import urllib.request
+
+    req = urllib.request.Request(
+        _PYPI_URL,
+        headers={"Accept": "application/json", "User-Agent": f"foxclaw/{_current()}"},
+    )
+    with urllib.request.urlopen(req, timeout=_TIMEOUT) as resp:  # noqa: S310 - 地址是常量 https
+        payload = json.loads(resp.read().decode("utf-8", "replace"))
+    version = ((payload or {}).get("info") or {}).get("version") or ""
+    if not version:
+        raise ValueError("PyPI 响应里没有 info.version")
+    return str(version)
+
+
+def _refresh() -> None:
+    global _inflight, _last_error
+    try:
+        latest = _fetch_latest()
+        _write_cache({"latest": latest, "checked_at": time.time(), "current": _current()})
+        _last_error = None
+    except Exception as exc:
+        _last_error = f"{type(exc).__name__}: {exc}"
+    finally:
+        with _lock:
+            _inflight = False
+
+
+def maybe_refresh() -> None:
+    """启用且缓存过期 → 后台查一次。幂等、非阻塞,可放心在每个 system/info 里调。"""
+    global _inflight
+    if not _enabled():
+        return
+    checked = _read_cache().get("checked_at")
+    if isinstance(checked, (int, float)) and time.time() - checked < _TTL:
+        return
+    with _lock:
+        if _inflight:
+            return
+        _inflight = True
+    threading.Thread(target=_refresh, name="foxclaw-update-check", daemon=True).start()
+
+
+def status() -> dict[str, Any]:
+    """给 ``/api/system/info`` 的只读快照。未启用时 latest 仍是缓存值,但不报可更新。"""
+    enabled = _enabled()
+    current = _current()
+    cache = _read_cache()
+    latest = str(cache.get("latest") or "")
+    return {
+        "enabled": enabled,
+        "current": current,
+        "latest": latest or None,
+        "update_available": bool(enabled and latest and is_newer(latest, current)),
+        "checked_at": cache.get("checked_at"),
+        "error": _last_error,
+    }

package/python/foxclaw/core/vec_recall_adapter.py

@@ -31,9 +31,8 @@ from pathlib import Path
 from types import SimpleNamespace
 
 from .shared_write import guard_shared_write
+from typing import Any
 
-# Foxclaw 的 type 白名单 → vecRecall 的 memory_type(episodic/semantic/procedural)。
-# 分错不影响读写，但影响 vecRecall 的遗忘曲线与 procedural 精确匹配。
 _FOXCLAW_TO_VR = {
     "concept": "semantic",
     "project": "semantic",
@@ -52,7 +51,6 @@ _VR_TO_FOXCLAW = {
 }
 _VALID_TYPES = set(_FOXCLAW_TO_VR)
 
-# 偏好类记忆走 topic_key（精确查询），因为"总是注入的偏好"不该做语义模糊匹配。
 _PREFERENCE_TAG = "preference"
 
 
@@ -77,7 +75,7 @@ class _HKCSharedEmbedding:
     def __init__(self, model_name: str):
         self.model_name = model_name
         self._model = None
-        self._dim = None
+        self._dim: int | None = None
 
     def _load(self):
         if self._model is None:
@@ -85,8 +83,6 @@ class _HKCSharedEmbedding:
             from hkc_search.embedding_backends import get_st_model
             model = get_st_model(self.model_name)
             if model is None:
-                # 不回退到直连 SentenceTransformer：那会绕过 HKC 的进程级共享缓存、
-                # 多加载一份模型(bge-m3 常驻约 1GB)。失败就明确报错让工厂回退 HMR。
                 raise RuntimeError(
                     f"embedding 模型不可用: {self.model_name}(HKC 共享缓存加载失败)")
             self._model = model
@@ -105,7 +101,6 @@ class _HKCSharedEmbedding:
         if self._dim is None:
             try:
                 model = self._load()
-                # ST 6.x 把 get_sentence_embedding_dimension 改名了,两个都试
                 getter = (getattr(model, "get_embedding_dimension", None)
                           or getattr(model, "get_sentence_embedding_dimension", None))
                 self._dim = (int(getter() or 0) or None) if getter else None
@@ -120,7 +115,7 @@ class VecRecallAdapter:
     backend = "vecRecall"
 
     def __init__(self, storage_path: str = "./vecrecall_data", wing: str = "foxclaw",
-                 use_chain: bool = False, embedding_model: str = None,
+                 use_chain: bool = False, embedding_model: str | None = None,
                  dedup: bool = True, embedding_backend=None, vector_backend=None):
         """`embedding_backend` / `vector_backend` 用于注入（测试传轻量实现）。
 
@@ -133,9 +128,6 @@ class VecRecallAdapter:
         self.wing = wing
         self.storage_path = str(storage_path)
         self.version = self._resolve_version()
-        # vecRecall 本体没有任何锁（只有 REST server 层有 RLock），而它用的是
-        # check_same_thread=False 的单条 sqlite 连接 + 内存 dict 索引。并行子 Agent
-        # 同时 add/search 属于未定义行为，和 HMR 是同一类坑 —— 这里沿用同一套串行化。
         self._lock = threading.RLock()
 
         self._emb = embedding_backend or _HKCSharedEmbedding(
@@ -152,7 +144,6 @@ class VecRecallAdapter:
             **extra,
         )
 
-    # ── 构造辅助 ──────────────────────────────────────────
     @staticmethod
     def _resolve_version() -> str:
         try:
@@ -162,7 +153,7 @@ class VecRecallAdapter:
             return "unknown"
 
     @staticmethod
-    def _resolve_model(embedding_model: str = None) -> str:
+    def _resolve_model(embedding_model: str | None = None) -> str:
         """与 HMRAdapter 同一条解析链，保证两套后端用同一个模型（分数与维度可比）。"""
         return (embedding_model
                 or os.environ.get("EMBEDDING_MODEL")
@@ -188,14 +179,13 @@ class VecRecallAdapter:
         except Exception:
             return
         dims = {int(r[0]) for r in rows}
-        want = getattr(self._emb, "dim", None)   # 轻量后端无 dim 属性时跳过
+        want = getattr(self._emb, "dim", None)
         if dims and want and dims != {int(want)}:
             raise RuntimeError(
                 f"已有向量维度 {sorted(dims)} 与当前嵌入维度 {want} 不一致。"
                 f"换 embedding 模型必须重建索引：删除 {self.storage_path} 后重启"
             )
 
-    # ── 摄入 ──────────────────────────────────────────────
     _AUTO_TITLE = re.compile(r"^[A-Za-z_]+\s+\d{1,2}:\d{2}$")
 
     @staticmethod
@@ -214,8 +204,8 @@ class VecRecallAdapter:
         s = re.split(r"[。！？!?\n\r]", s, 1)[0].strip()
         return " ".join(s.split())[:80]
 
-    def ingest(self, content: str, type: str = "concept", agent_id: str = None,
-               title: str = None, tags: list = None, shared: bool = False, **kwargs):
+    def ingest(self, content: str, type: str = "concept", agent_id: str | None = None,
+               title: str | None = None, tags: list | None = None, shared: bool = False, **kwargs):
         """统一摄入。签名与 `HMRAdapter.ingest` 一致。
 
         隔离承载：`agent_id` → owner，`shared=True` → visibility="shared"。
@@ -231,8 +221,6 @@ class VecRecallAdapter:
         if not title:
             title = self._derive_title(content) or ""
 
-        # 【P0-3】共享层写入闸门：必须在落库之前判定，语义与 HMR 路径完全一致，
-        # 否则同一个策略在两个后端上表现不同。
         if shared:
             guard_shared_write(self, agent_id, content, mtype, meta_tags)
 
@@ -240,8 +228,6 @@ class VecRecallAdapter:
         if "confidence" in kwargs:
             metadata["confidence"] = kwargs["confidence"]
 
-        # execution 是审计证据：被遗忘曲线衰减或被去重合并，就无法再证明"当时确实
-        # 这么做了"。vecRecall 的 immutable 同时免于衰减与去重，正好对上这个语义。
         retention = "immutable" if mtype == "execution" else "decay"
         topic_key = kwargs.get("topic_key") or (
             _PREFERENCE_TAG if _PREFERENCE_TAG in meta_tags else "")
@@ -260,8 +246,7 @@ class VecRecallAdapter:
                 topic_key=topic_key,
             )
 
-    # ── 召回 ──────────────────────────────────────────────
-    def _visible(self, mem, agent_id: str, include_shared: bool) -> bool:
+    def _visible(self, mem, agent_id: str | None, include_shared: bool) -> bool:
         """可见性判定，与 vecRecall `_visible_to` 规则保持同源。
 
         - shared 记忆：仅当 include_shared 时可见
@@ -276,7 +261,7 @@ class VecRecallAdapter:
             return include_shared
         return owner == agent_id or not owner
 
-    def recall(self, query: str = "", agent_id: str = None, top_k: int = 5,
+    def recall(self, query: str = "", agent_id: str | None = None, top_k: int = 5,
                include_shared: bool = True, **kwargs):
         """统一召回，返回 list[dict]。
 
@@ -300,9 +285,6 @@ class VecRecallAdapter:
                 results = list(getattr(bundle, "l2_topic_context", []) or []) + \
                           list(getattr(bundle, "l3_deep_results", []) or [])
                 if not results and (query or "").strip():
-                    # L2 有 0.55 阈值：命中偏弱时整层为空。HMR 的 recall 是无条件
-                    # 返回 top_k，为不改变上层"总能拿到几条"的预期，退化到全量语义
-                    # 检索，再在下面用 _visible 补上隔离（search 本身不隔离）。
                     results = list(self._vr.search(query, n=fetch_k) or [])
         except Exception:
             return []
@@ -384,8 +366,7 @@ class VecRecallAdapter:
             row["_ts"] = getattr(m, "timestamp", "") or ""
             rows.append(row)
 
-        rows.sort(key=lambda x: str(x.get("_ts")), reverse=True)   # 新近优先
-        # 同一偏好反复表达会存成多条，去重保留最新，否则会挤满 limit
+        rows.sort(key=lambda x: str(x.get("_ts")), reverse=True)
         deduped, seen_c = [], set()
         for x in rows:
             if x["content"] in seen_c:
@@ -401,7 +382,6 @@ class VecRecallAdapter:
             except Exception:
                 return False
 
-    # ── 展示 ──────────────────────────────────────────────
     def recent(self, limit: int = 20) -> list:
         """最近的记忆条目（新→旧），供前端右栏"记忆信息条"。"""
         rows = []
@@ -435,11 +415,6 @@ class VecRecallAdapter:
             })
         return rows
 
-    # ── HMR 专有接口的占位 ────────────────────────────────
-    # vecRecall 没有"会话工作区 / 运行时快照"这两个概念。留占位而不是让调用方
-    # AttributeError：上层有统一的"后端接口"假设，缺方法会炸在一个与被调用能力
-    # 无关的地方。agents/base.py 取到 workspace 后并不读其字段（active_goal 的
-    # 写入已移除），所以空壳没有实际成本。
     def get_workspace(self, agent_id: str):
         return SimpleNamespace(agent_id=agent_id, active_goal="", status="idle",
                                push_task=lambda _t: None)
@@ -453,14 +428,13 @@ class VecRecallAdapter:
     def restore_runtime_state(self):
         return None
 
-    # ── 状态 ──────────────────────────────────────────────
     def get_system_status(self):
         return {"backend": self.backend, "version": self.version, "wing": self.wing}
 
     def stats(self) -> dict:
         """记忆统计：前端记忆中心展示真实数字。字段与 HMRAdapter.stats 一致。"""
         total = shared_count = relations = 0
-        by_agent = {}
+        by_agent: dict[str, Any] = {}
         embedding = type(self._emb).__name__
         try:
             with self._lock:

package/python/foxclaw/core/verify.py

@@ -25,17 +25,15 @@ from dataclasses import dataclass, field
 from urllib.parse import urlparse
 
 from . import failure_policy as _policy
+from typing import Callable
 
 VERIFIED = "verified"
 UNVERIFIED = "unverified"
 FAILED = "failed"
 
-#: 每条工具结果最多挂几条证据(再多就成了噪声,用户不会看)
 MAX_EVIDENCE = 8
 
 _URL_RE = re.compile(r"https?://[^\s<>\"'）)\]}]+")
-#: 只保留"真实存在"的路径 —— 正则从文本里认出来的路径九成是误报(URL 片段、示例路径),
-#: 只有能在磁盘上 stat 到的才算证据。这不是限制,是"证据"二字的含义。
 _WIN_PATH_RE = re.compile(r"[A-Za-z]:[\\/][^\s\"'<>|*?，。；]+")
 _POSIX_PATH_RE = re.compile(r"(?<![\w:])/(?:[\w.\-]+/)+[\w.\-]+")
 
@@ -44,10 +42,10 @@ _POSIX_PATH_RE = re.compile(r"(?<![\w:])/(?:[\w.\-]+/)+[\w.\-]+")
 class Evidence:
     """一条可核对的凭据:一个链接、一个真实存在的文件、或一次工具的原始命中。"""
 
-    kind: str                     # url / file
-    ref: str                      # 链接或绝对路径
-    label: str                    # 展示名(域名 / 文件名)
-    source: str                   # 哪个工具产出的
+    kind: str
+    ref: str
+    label: str
+    source: str
     at: float = field(default_factory=time.time)
 
     def to_dict(self) -> dict:
@@ -121,14 +119,10 @@ def extract_evidence(source: str, text: str, limit: int = MAX_EVIDENCE) -> list[
     return out
 
 
-#: 工具专属的后置条件检查。返回 (是否通过, 不通过的原因)。
-#: 没登记的工具走通用规则(见 verify),不会被当成"已验证"。
-_CHECKERS: dict[str, "callable"] = {
-    # 联网搜索:结论必须能指回来源,否则就是"模型自己写的" —— 标未核验而不是验证通过
+_CHECKERS: dict[str, Callable[..., tuple[bool, str]]] = {
     "web_search": lambda args, text: (
         (True, "") if _URL_RE.search(text or "")
         else (False, "搜索结果没有可核对的来源链接")),
-    # 个人记忆:召回为空是合法结果(确实没记过),非空即有凭据
     "recall_memory": lambda args, text: (
         (True, "") if (text or "").strip().startswith("【召回的相关记忆】")
         else (False, "未返回记忆条目")),
@@ -157,9 +151,7 @@ def verify(name: str, args: dict | None, text: str,
 
     read_only = bool((capability or {}).get("read_only"))
     if read_only:
-        # 只读 + 有返回 = 这一步确实发生过(内容是否可信由污点/证据层管)
         return Verification(VERIFIED, evidence=ev)
-    # 有副作用但没登记后置条件:不能证明效果已发生 → 未核验(不许声称完成)
     return Verification(UNVERIFIED, reason="该工具未声明可观察的后置条件", evidence=ev)
 
 

package/python/foxclaw/core/web_search.py

@@ -23,40 +23,23 @@ 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          # 对外保持同名(旧引用不破)
+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 = (
@@ -85,16 +68,12 @@ def needs_search(query: str) -> bool:
         return False
     q = query.lower()
     if is_personal_query(q):
-        return False                      # 问的是自己的数据 → 答案在本地内核,绝不联网
-    # 自我模型/身份问题(你是什么模型 / 你现在是哪个模型 …)→ 由 ModelRouter 运行时注入本地即答,不联网。
-    # 否则会因含"模型"触发词白跑一次 ~20s 百度搜索。"你"与"模型"相邻(≤8字)才算自问;
-    # "你帮我查 X 的模型"(相距远)仍走搜索。
+        return False
     if re.search(r"你[^,。?!]{0,8}模型", q):
         return False
     if any(k in q for k in _CJK_TRIGGERS):
-        return True                       # 外部世界话题 → 联网
+        return True
     return bool(_ASCII_RE and _ASCII_RE.search(q))
-    # 注:只含时间词(今天/本月/最近…)而无话题 → 不触发(见上方 TIME_WORDS 说明)
 
 
 def _key() -> str:
@@ -139,7 +118,7 @@ def _search_answer_inner(query: str, key: str) -> dict:
             "stream": False,
             "model": _model(),
             "enable_deep_search": _deep(),
-            "enable_corner_markers": False,   # 不要答案里的 ^[1]^ 角标(参考资料已单列)
+            "enable_corner_markers": False,
         }).encode("utf-8")
         req = urllib.request.Request(
             f"{_base()}/chat/completions",
@@ -193,7 +172,6 @@ def format_for_prompt(query: str, payload) -> str:
         refs = payload.get("references", [])
         if not answer and not refs:
             return ""
-        # 我方的作答指令(可信,放在 <untrusted> 之外);检索到的外部内容(不可信,放在 <untrusted> 之内)。
         framing = (
             f"以下是针对「{query}」的实时联网搜索结果(来自百度 AI 搜索)。\n"
             f"【严格要求】只能依据下面 <untrusted> 数据块里的搜索结果作答:结果里没有出现的型号 / "
@@ -215,13 +193,11 @@ def format_for_prompt(query: str, payload) -> str:
                 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 ""

package/python/foxclaw/finance/evidence.py

@@ -17,9 +17,9 @@ from datetime import datetime
 @dataclass
 class RiskFactor:
     """单个风险因子:是什么、证据、权重。"""
-    factor: str                  # 风险因子名(如"超预算")
-    evidence: str                # 人类可读证据(如"餐饮已用 120%,超 ¥240")
-    weight: float                # 权重 0-1(对总风险的贡献)
+    factor: str
+    evidence: str
+    weight: float
 
     def to_dict(self) -> dict:
         return {"factor": self.factor, "evidence": self.evidence,
@@ -29,14 +29,14 @@ class RiskFactor:
 @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)  # 还需补充的检查
+    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):
@@ -53,10 +53,10 @@ class EvidenceChain:
             self.risk_score = 0.0
             return 0.0
         weights = sorted((f.weight for f in self.risk_factors), reverse=True)
-        score = weights[0]                          # 最大因子为主
+        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
+            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
 
@@ -100,7 +100,6 @@ class FinanceExplainer:
             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)
@@ -109,13 +108,11 @@ class FinanceExplainer:
                 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]} 支出或调整预算"
@@ -134,7 +131,6 @@ class FinanceExplainer:
         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}"

package/python/foxclaw/finance/fx.py

@@ -15,7 +15,6 @@ from pathlib import Path
 
 BASE_CURRENCY = "CNY"
 
-# 参考价(1 单位外币 = 多少 CNY)。宁可粗,但要能改。
 DEFAULT_RATES = {
     "CNY": 1.0,
     "USD": 7.2,
@@ -33,7 +32,7 @@ DEFAULT_RATES = {
 class FxTable:
     """币种 → 本位币折算率,带落盘(原子写)。"""
 
-    def __init__(self, path: str = None):
+    def __init__(self, path: str | None = None):
         self.path = Path(path) if path else None
         self.rates = dict(DEFAULT_RATES)
         self.note = "static"
@@ -54,7 +53,6 @@ class FxTable:
                 if data.get("note"):
                     self.note = data["note"]
         except Exception:
-            # 汇率表坏了不能拖垮记账:退回出厂参考价,下次保存时自动覆盖
             pass
 
     def save(self) -> bool: