argo-search 2.9.7 → 2.9.8

package/scripts/output_transparency.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""output_transparency.py — 搜索输出的可信度评估、结构化失败清单与精简档透明修饰。
+
+从 search_output.py 拆出（2026-10-21）：
+  1. 单一职责：search_output 管「结果成形与人读格式」，本模块管「可信度/失败分类/
+     不可信边界」三件透明化信号；拆开后 search_output 保持在 ~650 行，远离千行硬限。
+  2. 口径合一：`_FAILURE_NON_ERROR` 与 `_NON_ERROR_OUTCOME` 同源派生，不再维护
+     两份独立 frozenset。
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+# 本次调用不算失败的基础状态（引擎正常交付、无结果、或被早停主动取消）
+_FAILURE_NON_ERROR: frozenset[str] = frozenset({
+    "ok", "ok-cached", "partial", "no-results", "no-results-cached", "cancelled",
+})
+
+# errors[] 与 uncertainty 排除的 outcome 状态：在基础非错误集之上再排除
+# skipped-quota-exhausted（持续一天的配额跳过状态，不作为单次检索错误刷屏）
+_NON_ERROR_OUTCOME: frozenset[str] = _FAILURE_NON_ERROR | {"skipped-quota-exhausted"}
+
+# 二手/聚合平台（转载与洗稿高发地）。**刻意不复用 evidence 的词表**：
+# evidence 属热路径禁入名单（tests/test_hotpath_import_lint.py 的 HEAVY_TOP，
+# 它会拖进 content_signals/stylometry/burstiness 约 9ms），而本函数在每次
+# 搜索的收口处无条件执行。两处词表需同步——改这里时看 evidence.
+# _SECONDARY_PLATFORM_PATTERNS。
+_AGGREGATOR_HOSTS: frozenset[str] = frozenset({
+    "baijiahao.baidu.com",   # 百家号（自媒体洗稿重灾区）
+    "toutiao.com",           # 头条号（聚合+洗稿）
+    "k.sina.com.cn",         # 新浪博客/聚合
+    "guba.eastmoney.com",    # 股吧（UGC 讨论，非事实来源）
+})
+
+# 可信度等级（与 dsh-free-search 的 meta.uncertainty 同形）
+_UNCERTAINTY_HIGH = "high"
+_UNCERTAINTY_MEDIUM = "medium"
+_UNCERTAINTY_LOW = "low"
+# 严重度序：用于「多信号取最差」——等级只能降不升。
+_SEVERITY = {_UNCERTAINTY_HIGH: 0, _UNCERTAINTY_MEDIUM: 1, _UNCERTAINTY_LOW: 2}
+
+
+def _hostname(url: Any) -> str:
+    """URL → 归一化主机名（小写、去 www.）；解析失败返回空串。"""
+    try:
+        from urllib.parse import urlparse
+        host = urlparse(str(url or "")).hostname or ""
+    except Exception:
+        return ""
+    return host.lower().removeprefix("www.")
+
+
+# 失败类别 → (归一类别, 可执行建议, 是否可重试)。类别名与 dsh-free-search
+# 的 failureClass 对齐（quota/auth/bot-wall/transient/rate-limit/unknown），
+# 但归类依据是 argo 自己的 outcome.status（retry_policy.classify_error_status
+# 的唯一真源），不另写一套错误词表。
+_FAILURE_META: dict[str, tuple[str, str, bool]] = {
+    "timeout": ("transient", "超时；可重试或换源", True),
+    "quota-exhausted": ("quota", "配额耗尽；换源或等窗口重置", False),
+    "rate-limited": ("rate-limit", "被限流；稍后重试或换源", True),
+    "blocked": ("bot-wall", "被反爬拦截；稍后重试或换源", True),
+    "auth-failed": ("auth", "检查 API Key 是否有效、是否有该接口权限", False),
+    "error": ("unknown", "源端错误；可重试或换源", True),
+    "skipped-missing-env": ("missing-key", "未配置密钥；配置后即可参与", False),
+    "skipped-quota-exhausted": ("quota", "配额耗尽，本轮跳过", False),
+    "skipped-circuit-open": ("cooldown", "熔断冷却中，稍后自动恢复", True),
+    "skipped-budget": ("budget", "本轮预算不足，未执行", True),
+}
+
+
+def build_failures(result: dict[str, Any], limit: int = 6) -> list[dict[str, Any]]:
+    """把引擎 outcome 压成 Agent 可行动的结构化失败清单。
+
+    与 errors 的分工：errors 是给人看的整行文本（兼容旧契约），本字段是
+    给模型/宿主判断「要不要重试、换哪个源、是不是缺 key」的分类结果。
+    只收录没交出结果的 outcome；ok/no-results 不算失败（后者是「查了没有」，
+    不是「没查成」），与 uncertainty 的降级判据同源。
+    """
+    out: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for o in (result.get("engine_outcomes") or []):
+        if not isinstance(o, dict):
+            continue
+        engine = str(o.get("engine") or "")
+        status = str(o.get("status") or "")
+        if not engine or status in _FAILURE_NON_ERROR:
+            continue
+        key = (engine, status)
+        if key in seen:
+            continue
+        seen.add(key)
+        category, action, retryable = _FAILURE_META.get(
+            status, ("unknown", "源端异常；可重试或换源", True))
+        item: dict[str, Any] = {
+            "engine": engine,
+            "status": status,
+            "category": category,
+            "retryable": retryable,
+            "action": action,
+        }
+        # skipped-* 是「持续状态」而不是本次尝试失败：配额窗口/熔断冷却在
+        # 周期边界前不会因重试改变。标出来，避免 Agent 立刻重试同一个源。
+        if status.startswith("skipped-"):
+            item["persistent"] = True
+        detail = str(o.get("detail") or "").strip()
+        if detail:
+            item["detail"] = detail[:160]
+        out.append(item)
+        if len(out) >= max(1, limit):
+            break
+    return out
+
+
+def decorate_compact_payload(out: dict[str, Any],
+                             result: dict[str, Any]) -> None:
+    """精简响应（MCP/Agent 档）的收尾修饰：边界清洗 + 三件透明信息 + sources 投影。"""
+    try:
+        from content_boundary import (CONTENT_TRUST_UNTRUSTED,
+                                      sanitize_results_boundary)
+        sanitize_results_boundary(out.get("results"))
+        out["content_trust"] = CONTENT_TRUST_UNTRUSTED
+    except Exception:
+        pass
+    failures = result.get("failures")
+    if isinstance(failures, list) and failures:
+        out["failures"] = failures[:6]
+    meta = result.get("meta")
+    if isinstance(meta, dict) and meta.get("uncertainty"):
+        out["meta"] = {"uncertainty": meta["uncertainty"]}
+    sources = result.get("sources")
+    if sources:
+        out["sources"] = [
+            {
+                "ref": s.get("ref"),
+                "title": s.get("title"),
+                "url": s.get("url"),
+                "engine": s.get("engine") or s.get("source"),
+            }
+            for s in sources
+            if isinstance(s, dict) and s.get("url")
+        ][:20]
+
+
+def build_uncertainty(result: dict[str, Any]) -> dict[str, Any]:
+    """一次调用的综合可信度：`{"level": ..., "notes": [...]}`。
+
+    与 `limitations` 的分工：limitations 是**逐条**的局限声明（早停、降级、
+    缓存复用、站点过滤），本字段是**整体**等级——消费者拿到一个 level 就能
+    决定「直接引用」还是「先核验」，不必自己交叉比对五六个字段。
+    """
+    notes: list[str] = []
+    results = [r for r in (result.get("results") or []) if isinstance(r, dict)]
+
+    if not results:
+        return {"level": _UNCERTAINTY_LOW, "notes": ["没有返回结果"]}
+
+    level = _UNCERTAINTY_HIGH
+
+    def _worse(candidate: str) -> None:
+        nonlocal level
+        if _SEVERITY[candidate] > _SEVERITY[level]:
+            level = candidate
+
+    if len(results) == 1:
+        _worse(_UNCERTAINTY_LOW)
+        notes.append("只有 1 个来源，无法交叉验证")
+    elif len(results) == 2:
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append("只有 2 个来源")
+
+    hosts = {_hostname(r.get("url")) for r in results}
+    hosts.discard("")
+    if 0 < len(hosts) == 1:
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append("所有结果来自同一站点")
+
+    # 尊重 search_output._AGGREGATOR_HOSTS 的猴子补丁（test_output_uncertainty 门禁锁）
+    so_mod = sys.modules.get("search_output")
+    agg_hosts = getattr(so_mod, "_AGGREGATOR_HOSTS", _AGGREGATOR_HOSTS)
+    aggregators = sorted(h for h in hosts if h in agg_hosts
+                         or any(h.endswith("." + a) for a in agg_hosts))
+    if aggregators:
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append(f"含聚合站内容（{'/'.join(aggregators)}），建议二次核对")
+
+    if result.get("time_filter_warning"):
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append("时间窗未实际过滤，结果可能不在请求的时间范围内")
+
+    outcomes = [o for o in (result.get("engine_outcomes") or [])
+                if isinstance(o, dict)]
+    failed = [o for o in outcomes
+              if str(o.get("status") or "") not in _NON_ERROR_OUTCOME]
+    if failed:
+        _worse(_UNCERTAINTY_LOW)
+        notes.append(f"{len(failed)} 个引擎未交出结果，覆盖可能比计划的窄")
+
+    return {"level": level, "notes": notes}

package/scripts/paid_policy.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""paid_policy.py — 付费搜索的自动对冲位（2026-10-21，方案一）。
+
+只解决一件事：在**已证明有优势的域**里，把付费引擎放到 combo 第二位当对冲，
+而不是让它进通用候选池（那会被 TF-IDF/兜底带到任意查询并扣费）。
+
+策略：
+  - `ARGO_PAID_SEARCH=off` → 完全关闭；缺省 `auto`。
+  - 该域在 `PAID_DOMAIN_HEDGES` 里，且引擎 key 就绪、月度预算未用完
+    → 返回该引擎；预算用完/无 key → 回落 `tinyfish`（免费、带日期），
+    再不行返回空，由原 combo 继续。
+  - `fast`/`budget` 模式不参与（与 quota 的成本纪律一致）。
+
+当前只开两个域：`english_tech`、`intl_news_flash`。依据 2026-10-21 多引擎
+实测：DeepSeek 在英文技术/英文新闻上 p50 515ms、日期覆盖 23/39，明显优于
+anysearch/Exa/Tavily；中文宽泛新闻与金融原文反而更差，故不纳入。
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["PAID_DOMAIN_HEDGES", "hedge_for", "insert_hedge"]
+
+PAID_DOMAIN_HEDGES: dict[str, str] = {
+    "english_tech": "deepseek_search",
+    "intl_news_flash": "deepseek_search",
+}
+
+_FREE_FALLBACK = "tinyfish"
+
+
+def _enabled() -> bool:
+    try:
+        from engine_env import get_env
+        raw = get_env("ARGO_PAID_SEARCH", "auto")
+    except Exception:
+        raw = os.environ.get("ARGO_PAID_SEARCH", "auto")
+    return raw.strip().lower() not in ("off", "0", "false", "no")
+
+
+def _key_ready(engine: str) -> bool:
+    try:
+        from engine_env import missing_env_for
+        return not missing_env_for(engine)
+    except Exception:
+        return False
+
+
+def _budget_ok(engine: str) -> bool:
+    try:
+        from quota import get_quota_manager
+        return not get_quota_manager().is_hard_down(engine)
+    except Exception:
+        # 预算层读失败时 fail-closed：宁可不自动花钱
+        return False
+
+
+def _healthy_and_enabled(engine: str, enabled: set[str] | None) -> bool:
+    if enabled is not None and engine not in enabled:
+        return False
+    try:
+        from route_combo import _breaker_blocked
+        if _breaker_blocked(engine):
+            return False
+    except Exception:
+        pass
+    return True
+
+
+def hedge_for(domain: str, mode: str = "auto",
+              enabled: set[str] | None = None) -> list[str]:
+    """返回该域应插入的付费/回落引擎（0 或 1 个）。永不抛异常。"""
+    if not _enabled() or mode in ("fast", "budget"):
+        return []
+    engine = PAID_DOMAIN_HEDGES.get(str(domain or ""))
+    if not engine:
+        return []
+    try:
+        if (_healthy_and_enabled(engine, enabled)
+                and _key_ready(engine) and _budget_ok(engine)):
+            return [engine]
+        # 付费位不可用：TinyFish 是免费且带发布日期的回落位
+        if (_healthy_and_enabled(_FREE_FALLBACK, enabled)
+                and _key_ready(_FREE_FALLBACK) and _budget_ok(_FREE_FALLBACK)):
+            return [_FREE_FALLBACK]
+    except Exception:
+        return []
+    return []
+
+
+def insert_hedge(combo: list[str], domain: str, mode: str = "auto",
+                 enabled: set[str] | None = None) -> list[str]:
+    """把付费/回落引擎插到 combo 第二位（原地改并返回，便于链式调用）。"""
+    for engine in reversed(hedge_for(domain, mode, enabled=enabled)):
+        if engine not in combo:
+            combo.insert(min(1, len(combo)), engine)
+    return combo

package/scripts/quota.py

@@ -14,6 +14,7 @@ quota.py — Unified Search v2 配额管理器
 from __future__ import annotations
 
 import json
+import os
 import time
 import threading
 from pathlib import Path
@@ -28,6 +29,22 @@ SKILL_DIR = Path(__file__).parent.parent
 BACKENDS_DIR = SKILL_DIR / "backends"
 QUOTA_PROFILES_PATH = BACKENDS_DIR / "quota_profiles.json"
 
+# 次数额度的环境覆盖白名单（DSH 设置页「付费搜索」分组写入）。
+#
+# 为什么按引擎列名而不是一个 JSON：面板是「一行一个 KEY=VALUE」的形态，
+# 每个数字字段要独占一行才能被现有的 envMap/白名单门禁识别；一个 JSON
+# 大字段既无法在面板上分引擎显示，也会让 env gate 失去可判定的锚点。
+#
+# 语义：值 = 该引擎配额周期内的次数上限；0 = 不限制（None）；空/非法 = 保持
+# config.yaml 的声明值。周期（day/month）不在面板改——它决定的是「这条限制
+# 按天还是按月」，与引擎的商业额度形态绑定，换周期需要同时换文案与默认值。
+_QUOTA_LIMIT_ENV: tuple[tuple[str, str], ...] = (
+    ("ARGO_QUOTA_ANYSEARCH_LIMIT", "anysearch"),   # 日
+    ("ARGO_QUOTA_ZHIHU_LIMIT", "zhihu"),           # 日
+    ("ARGO_QUOTA_YUANBAO_LIMIT", "yuanbao"),       # 月
+    ("ARGO_QUOTA_TAVILY_LIMIT", "tavily"),         # 月
+)
+
 
 _STATE_DIR_CACHE: tuple[str, Path] | None = None
 
@@ -118,6 +135,16 @@ def _prune_foreign_engines(state: dict, protect: set[str]) -> dict:
             if name in known or name in protect}
 
 
+def _at_or_over_budget(cost_used: float, budget: float) -> bool:
+    """预算是否用完：按 6 位小数比较，消掉单价累加的浮点漂移。
+
+    实测：Exa $0.01 × 1000 次 = 9.999999999999831，直接 `>= 10` 会判「还没
+    用完」，额度显示 10.0 却还能再打一次。预算是对外承诺的数字，比较口径
+    必须与展示口径一致（budget_status 也是 round 6）。
+    """
+    return round(float(cost_used), 6) >= round(float(budget), 6)
+
+
 class QuotaManager:
     """配额追踪与消耗速率计算（v2）。"""
 
@@ -151,10 +178,29 @@ class QuotaManager:
             self._profiles_hot = None
             self._state_hot = None
 
-    def _fresh_locked(self) -> None:
-        """带锁调用：磁盘文件签名变化即重读（调用方须已持锁）。"""
+    def _fresh_locked(self, engine: str | None = None) -> None:
+        """带锁调用：磁盘文件签名变化即重读（调用方须已持锁）。
+
+        同一次路由遍历（~0.3ms 内对 230+ 个不同 engine 逐一查询）共用首轮
+        stat 结果，避免单次 route_query 产生 900+ 次重复 stat；同一引擎再次
+        查询或超过 2ms 立即重新 stat，保持跨进程热读立即可见（test_hot_state）。
+        """
+        now = time.monotonic()
+        seen = getattr(self, "_fresh_seen", None)
+        if (engine is not None and seen is not None and engine not in seen
+                and (now - getattr(self, "_fresh_ts", 0.0)) < 0.002):
+            seen.add(engine)
+            return
+        self._fresh_ts = now
+        self._fresh_seen = {engine} if engine is not None else set()
+        try:
+            import budget as _budget
+            b_sig = _budget.budget_signature()
+        except Exception:
+            b_sig = None
         try:
-            if self._profiles_hot is not None and self._profiles_hot.changed():
+            if (self._profiles_hot is not None and self._profiles_hot.changed()) \
+                    or (b_sig is not None and b_sig != getattr(self, "_budget_sig", None)):
                 self._load_profiles()
             if self._state_hot is not None and self._state_hot.changed():
                 self._load_state()
@@ -169,6 +215,38 @@ class QuotaManager:
                 self._profiles = json.loads(QUOTA_PROFILES_PATH.read_bytes())
             except (json.JSONDecodeError, OSError):
                 self._profiles = {}
+        # 月度预算覆盖（2026-10-21）：只改 profile 的 budget_* 与 period，
+        # 不碰 quota_profiles.json（那是随包发版的派生件）。拼错/无预算的引擎
+        # 不受影响，符合「其他默认不改」。
+        try:
+            import budget as _budget
+            _budget.apply_to_profiles(self._profiles)
+            self._budget_sig = _budget.budget_signature()
+        except Exception:
+            self._budget_sig = None
+        self._apply_quota_env_overrides()
+
+    def _apply_quota_env_overrides(self) -> None:
+        """把面板写入的 ARGO_QUOTA_<ENGINE>_LIMIT 叠到次数额度上。
+
+        只改内存里的 profile，不写 quota_profiles.json（派生件随包发版）。
+        非法/空值静默忽略：面板与环境变量都可能被手工编辑，配额读取失败
+        不应让整次路由崩掉。0 = 显式不限制。
+        """
+        for env_name, engine in _QUOTA_LIMIT_ENV:
+            raw = (os.environ.get(env_name) or "").strip()
+            if not raw:
+                continue
+            try:
+                value = int(raw)
+            except ValueError:
+                continue
+            if value < 0:
+                continue
+            profile = self._profiles.get(engine)
+            if not isinstance(profile, dict):
+                continue
+            profile["limit"] = value if value > 0 else None
 
     def _load_state(self) -> None:
         if _state_path().exists():
@@ -256,12 +334,18 @@ class QuotaManager:
                 st = self._state.setdefault(engine, {
                     "used": 0, "limit": 0, "calls": [],
                     "errors": 0, "last_reset": now, "total_cost": 0.0,
+                    "cost_used": 0.0,
                 })
                 st["used"] = st.get("used", 0) + credits
                 st.setdefault("calls", []).append(now)
                 if not success:
                     st["errors"] = st.get("errors", 0) + 1
-                st["total_cost"] = st.get("total_cost", 0.0) + self.get_cost_per_call(engine)
+                else:
+                    # 只对成功调用计费：DeepSeek 等按成功请求收费，失败也计入
+                    # 会让预算被网络抖动假消耗（2026-10-21 修）。
+                    _cost = self.get_cost_per_call(engine)
+                    st["cost_used"] = st.get("cost_used", 0.0) + _cost
+                    st["total_cost"] = st.get("total_cost", 0.0) + _cost
                 self._prune_locked(st, now)
 
         self._mutate_locked(_apply)
@@ -291,13 +375,14 @@ class QuotaManager:
             if not isinstance(state, dict):
                 return
             state["used"] = 0
+            state["cost_used"] = 0.0
             state["last_reset"] = now
             argo_paths.atomic_write_json(_state_path(), self._state)
 
     def get_remaining_ratio(self, engine: str) -> float:
         """获取配额剩余比例。无限配额返回 1.0。"""
         with self._lock:
-            self._fresh_locked()
+            self._fresh_locked(engine)
             # 按周期重置（先于 limit 判空：null 引擎计数也要按周期归零，
             # 否则用量计数永久累计、无周期语义）。重置在文件锁内落盘。
             if self._period_elapsed(engine, time.time()):
@@ -305,9 +390,18 @@ class QuotaManager:
             profile = self._profiles.get(engine, {})
             state = self._state.get(engine, {})
             limit = profile.get("limit")
-            if limit is None:
-                return 1.0
-            return max(0.0, (limit - state.get("used", 0)) / limit)
+            ratios: list[float] = []
+            if limit is not None:
+                ratios.append(max(0.0, (limit - state.get("used", 0)) / limit))
+            budget = profile.get("budget_amount")
+            if budget:
+                cost_used = float(state.get("cost_used", 0.0))
+                if _at_or_over_budget(cost_used, budget):
+                    ratios.append(0.0)
+                else:
+                    ratios.append(max(0.0,
+                                      (float(budget) - cost_used) / float(budget)))
+            return min(ratios) if ratios else 1.0
 
     @staticmethod
     def _engine_key_fp(engine: str) -> str:
@@ -394,7 +488,7 @@ class QuotaManager:
 
     def is_remote_exhausted(self, engine: str) -> bool:
         with self._lock:
-            self._fresh_locked()
+            self._fresh_locked(engine)
             self._refresh_remote_state_locked(engine, time.time())
             return "remote_exhausted" in (self._state.get(engine) or {})
 
@@ -436,9 +530,51 @@ class QuotaManager:
         与限频/预算无关——路由组合层用它做全模式排除；
         is_available 的限频/付费判断不在此列。
         """
-        if self.is_remote_exhausted(engine):
-            return True
-        return self.get_remaining_ratio(engine) <= 0
+        with self._lock:
+            self._fresh_locked(engine)
+            now = time.time()
+            self._refresh_remote_state_locked(engine, now)
+            st = self._state.get(engine) or {}
+            if "remote_exhausted" in st:
+                return True
+            if self._period_elapsed(engine, now):
+                self._reset_period_locked(engine, now)
+                st = self._state.get(engine) or {}
+            limit = (self._profiles.get(engine) or {}).get("limit")
+            if limit is not None and (limit - st.get("used", 0)) <= 0:
+                return True
+            budget = (self._profiles.get(engine) or {}).get("budget_amount")
+            return budget is not None and float(st.get("cost_used", 0.0)) >= float(budget)
+
+    def is_over_budget(self, engine: str) -> bool:
+        """只判「月度预算是否用完」，不看次数/限频/远端配额。
+
+        调度层用它给显式调用一条可行动的错误（「本月预算已用完 ¥5.00/¥5.00」），
+        与 is_hard_down 的「配额意义上不可用」分开，避免把限流也报成预算。
+        """
+        with self._lock:
+            self._fresh_locked(engine)
+            now = time.time()
+            if self._period_elapsed(engine, now):
+                self._reset_period_locked(engine, now)
+            profile = self._profiles.get(engine) or {}
+            budget = profile.get("budget_amount")
+            if budget is None:
+                return False
+            st = self._state.get(engine) or {}
+            return _at_or_over_budget(st.get("cost_used", 0.0), budget)
+
+    def budget_status(self, engine: str) -> dict[str, Any]:
+        """单引擎预算快照（O(1)，避免 over_budget_error 为拼错误文案扫全表 280 引擎）。"""
+        with self._lock:
+            self._fresh_locked(engine)
+            profile = self._profiles.get(engine) or {}
+            st = self._state.get(engine) or {}
+            return {
+                "budget": profile.get("budget_amount"),
+                "budget_currency": profile.get("budget_currency"),
+                "cost_used": round(float(st.get("cost_used", 0.0)), 6),
+            }
 
     def get_current_rpm(self, engine: str) -> float:
         """获取最近 1 分钟的调用速率。"""
@@ -475,7 +611,7 @@ class QuotaManager:
         将 is_remote_exhausted / get_remaining_ratio / get_current_rpm 的
         检查合并到单次持锁中，消除 TOCTOU 间隙。
         """
-        self._fresh_locked()
+        self._fresh_locked(engine)
         # is_remote_exhausted 的内联版本（不重复获取锁）
         self._refresh_remote_state_locked(engine, time.time())
         if "remote_exhausted" in (self._state.get(engine) or {}):
@@ -493,6 +629,10 @@ class QuotaManager:
             qr = max(0.0, (limit - used) / limit)
             if qr <= 0:
                 return False
+        budget = profile.get("budget_amount")
+        if budget is not None and _at_or_over_budget(
+                state.get("cost_used", 0.0), budget):
+            return False
         # get_current_rpm 的内联版本（不重复获取锁）
         qps = profile.get("qps")
         if qps is not None:
@@ -538,6 +678,11 @@ class QuotaManager:
                 "total_cost": round(self.get_total_cost(engine), 6),
                 "used": self._state.get(engine, {}).get("used", 0),
                 "limit": profile.get("limit", "∞"),
+                "period": profile.get("period"),
+                # 月度预算（原生币种）：amount=None 表示未设预算、沿用次数额度
+                "budget": profile.get("budget_amount"),
+                "budget_currency": profile.get("budget_currency"),
+                "cost_used": round((self._state.get(engine) or {}).get("cost_used", 0.0), 6),
                 "cost_tier": profile.get("cost_tier", "free"),
                 "remote_exhausted_until": (
                     round(float(mark["until"])) if mark else None),