Hermes Agent 源码解析

第 14 讲：预算控制与限流——IterationBudget、Credits Tracker、Rate Guard 与费用估算管线

基于 Hermes Agent v0.16.0 源码 · 2026-06-27

一、为什么预算控制是 Agent 系统的生命线

前十三讲我们覆盖了 Hermes 从核心架构到认证系统的全链路。这一讲聚焦一个看似低调却决定性的子系统：预算控制与限流。

在一个 AI Agent 系统中，一次对话可能触发数十次 API 调用。如果没有预算控制，一个陷入死循环的 Agent 可以在几分钟内消耗掉数百美元。Hermes 的预算体系不是简单的计数器——它是多层防御架构，从迭代次数到费用估算，从限流熔断到工具循环检测，形成了完整的成本控制闭环。

二、IterationBudget：线程安全的迭代预算计数器

iteration_budget.py 仅 62 行代码，却是 Hermes 预算体系的第一道防线。每个 AIAgent 实例（父 Agent 或子 Agent）持有一个独立的 IterationBudget 对象，通过 consume/refund 模式控制迭代次数。

class IterationBudget:
    def __init__(self, max_total: int):
        self.max_total = max_total
        self._used = 0
        self._lock = threading.Lock()

    def consume(self) -> bool:
        """Try to consume one iteration. Returns True if allowed."""
        with self._lock:
            if self._used >= self.max_total:
                return False
            self._used += 1
            return True

    def refund(self) -> None:
        """Give back one iteration (e.g. for execute_code turns)."""
        with self._lock:
            if self._used > 0:
                self._used -= 1

关键设计细节：

🔹 线程安全：所有状态变更通过 threading.Lock 保护，Gateway 多会话并发场景下不会数据竞争

🔹 Refund 机制：execute_code（程序化工具调用）的迭代通过 refund() 返还——程序化调用不消耗模型推理预算，因为它们不经过 LLM 决策

🔹 父子独立预算：父 Agent 默认 max_iterations=90，子 Agent 默认 delegation.max_iterations=50，各自独立计数

在 conversation_loop.py 中，预算检查是主循环的退出条件之一：

while (api_call_count < agent.max_iterations
       and agent.iteration_budget.remaining > 0)
       or agent._budget_grace_call:
    ...
    if agent._budget_grace_call:
        agent._budget_grace_call = False
    elif not agent.iteration_budget.consume():
        _turn_exit_reason = "budget_exhausted"
        agent._safe_print(
            f"\u26a0\ufe0f Iteration budget exhausted "
            f"({used}/{max_total} used)")
        break

Grace call 机制是精妙的设计：当预算耗尽时，Agent 获得一次额外调用机会——这允许模型在最后一次响应中完成未竟的工具调用或给出总结，而不是粗暴截断。

三、Credits Tracker：Nous 积分状态机

credits_tracker.py 是 Hermes 对 Nous Portal 积分系统的深度集成。它不是简单的余额展示——而是一个完整的积分状态机，包含解析、策略评估、通知发射三个层次。

1. 积分头解析管线

Nous Portal 在每个 API 响应中注入 x-nous-credits-* 系列头字段。CreditsTracker 的解析器实现了严格验证：

解析器使用 钱安全的 int 解析：int() 直接转换，绝不使用 int(float(...))——后者在超过 2^53 时会静默损坏大金额值。任何字段解析失败都会导致整个解析返回 None（fail-hard-on-bad-input）。

2. 积分策略引擎

evaluate_credits_notices() 是一个纯函数，接收积分状态和锁存器，返回需要显示和清除的通知列表。核心策略包含四个条件分支：

3. 智能抑制逻辑

🔹 Free tier 抑制：当使用免费模型时（:free 后缀），depleted 通知被抑制——免费用户没有积分可消耗，显示错误横幅只会造成恐慌

🔹 充值余额抑制：当账户有充值余额（purchased_micros > 0）时，usage gauge 被完全抑制——显示"90% 已用"对用户毫无意义，因为充值余额仍在

🔹 Escalating 通知：usage gauge 使用升级机制（50% → 75% → 90%），同一时刻只显示最高达到的档位，恢复时自动降级

4. Cold-start 种子机制

在 conversation_loop.py 中，seed_credits_at_session_start() 在会话开始时从 /api/oauth/account 获取积分状态。TUI/桌面端在会话打开时种子，CLI 在第一轮对话时种子——fail-open 设计确保种子失败不影响对话。

四、Nous Rate Guard：跨会话限流熔断器

nous_rate_guard.py 解决了 Hermes 最棘手的限流问题：重试放大效应。

问题场景：Nous Portal 返回 429 → Hermes SDK 重试 3 次 × Hermes 应用层重试 3 次 = 最多 9 次 API 调用，每次调用都消耗 RPH（Requests Per Hour）配额。如果每个 Hermes 会话（CLI、Gateway、Cron）都独立重试，限流会指数级恶化。

解决方案：跨会话熔断器

Rate Guard 将限流状态写入共享文件 ~/.hermes/rate_limits/nous.json，所有会话在发起请求前检查该文件。文件内容通过原子写入（tempfile + rename）保证一致性：

state = {
    "reset_at": reset_at,       # 绝对时间戳
    "recorded_at": now,         # 记录时间
    "reset_seconds": reset_at - now  # 剩余秒数
}

# Atomic write: write to temp file + rename
fd, tmp_path = tempfile.mkstemp(dir=state_dir, suffix=".tmp")
with os.fdopen(fd, "w") as f:
    json.dump(state, f)
atomic_replace(tmp_path, path)

1. Reset 时间解析优先级

Rate Guard 从三个来源提取 reset 时间，优先级递减：

1. x-ratelimit-reset-requests-1h — 每小时 RPH 窗口（最有价值）

2. x-ratelimit-reset-requests — 每分钟 RPM 窗口

3. retry-after — 通用 HTTP 头

🔹 所有来源均不可用时，回退到 300 秒（5 分钟）默认冷却

2. 真伪限流鉴别

Nous Portal 背后有多个上游提供商（DeepSeek、Kimi、MiMo 等）。一个 429 可能意味着：

(a) 调用者自己的 RPM/RPH/TPM 桶耗尽 — 真正的限流

(b) 上游提供商对特定模型容量不足 — 瞬时问题，几秒后恢复

如果误判 (b) 为 (a)，熔断器会阻塞所有 Nous 请求数分钟，即使调用者的账户完全健康。Rate Guard 通过两个信号鉴别：

def is_genuine_nous_rate_limit(
    *, headers, last_known_state
) -> bool:
    # Signal 1: current 429 response headers
    state = _parse_buckets_from_headers(headers)
    if _has_exhausted_bucket(state):
        return True
    # Signal 2: last-known-good state from previous
    # successful response
    if last_known_state is not None
       and _has_exhausted_bucket_in_object(last_known_state):
        return True
    return False  # treat as transient, no breaker trip

判断标准：任何桶 remaining == 0 且 reset 窗口 >= 60 秒。短于 60 秒的 reset 窗口被视为瞬态抖动（上游抖动、二级节流），不值得触发跨会话熔断器。

五、Usage Pricing：费用估算管线

usage_pricing.py（908 行）实现了完整的费用估算管线，覆盖 40+ 模型的价格数据。这是 Hermes 的计费路由解析器——不仅计算费用，还决定如何计算费用。

1. 计费路由解析

resolve_billing_route() 根据 provider + model + base_url 确定计费模式：

2. 官方文档快照定价

对于 Anthropic、OpenAI、Google、DeepSeek、Bedrock 等提供商，Hermes 维护了本地定价快照（_OFFICIAL_DOCS_PRICING 字典）。每个 PricingEntry 包含：

@dataclass(frozen=True)
class PricingEntry:
    input_cost_per_million: Optional[Decimal] = None
    output_cost_per_million: Optional[Decimal] = None
    cache_read_cost_per_million: Optional[Decimal] = None
    cache_write_cost_per_million: Optional[Decimal] = None
    request_cost: Optional[Decimal] = None
    source: CostSource = "none"
    source_url: Optional[str] = None
    pricing_version: Optional[str] = None

注意所有金额使用 Decimal 而非 float——避免浮点精度问题。价格以每百万 token 为单位存储，计算时除以 1000000。

3. 用量标准化

normalize_usage() 处理三种不同的 API 用量格式：

Anthropic：input_tokens/output_tokens/cache_read_input_tokens/cache_creation_input_tokens

Codex Responses：input_tokens 包含缓存 token，input_tokens_details.cached_tokens 分离它们

OpenAI Chat Completions：prompt_tokens 包含缓存 token，prompt_tokens_details.cached_tokens 分离它们

标准化后输出 CanonicalUsage 数据类，统一为 input_tokens、output_tokens、cache_read_tokens、cache_write_tokens、reasoning_tokens 五个桶。

4. 费用估算结果

estimate_usage_cost() 返回 CostResult，包含四个状态：

actual：精确费用（来自 provider API）

estimated：估算费用（来自本地快照或 models API）

included：订阅包含（Codex 等）

unknown：无价格数据

六、错误分类：计费耗尽 vs 瞬时限流

error_classifier.py 中的错误分类器是预算控制的关键环节。它必须准确区分计费耗尽（需要切换 provider 或充值）和瞬时限流（等待即可恢复）。

计费耗尽模式（_BILLING_PATTERNS）：

_BILLING_PATTERNS = [
    "insufficient credits",
    "insufficient_quota",
    "insufficient balance",
    "credit balance",
    "credits exhausted",
    "no usable credits",
    "top up your credits",
    "payment required",
    "billing hard limit",
    "exceeded your current quota",
    "account is deactivated",
    "plan does not include",
    "out of funds",
    "run out of funds",
]

模糊模式（_USAGE_LIMIT_PATTERNS）需要二次判断：

🔹 匹配 _USAGE_LIMIT_PATTERNS（如 "usage limit"、"quota"）

🔹 同时匹配 _USAGE_LIMIT_TRANSIENT_SIGNALS（如 "try again"、"retry"）→ 判定为瞬时限流

🔹 否则 → 判定为计费耗尽

分类结果驱动不同的恢复策略：

七、工具循环护栏：防止 Agent 空转

即使预算计数器正常工作，Agent 仍可能陷入工具调用死循环——反复执行同一个失败的工具，消耗迭代预算却不产生进展。Hermes 的 tool_loop_guardrails 提供了两层防护：

软警告层（默认开启）：

🔹 exact_failure：同一工具完全相同的失败出现 2 次 → 追加引导信息

🔹 same_tool_failure：同一工具不同参数的失败出现 3 次 → 追加引导信息

🔹 idempotent_no_progress：幂等工具连续 2 次无进展 → 追加引导信息

硬停止层（默认关闭，Cron/自主会话推荐开启）：

🔹 exact_failure：5 次 → 电路熔断，终止 Agent

🔹 same_tool_failure：8 次 → 电路熔断

🔹 idempotent_no_progress：5 次 → 电路熔断

护栏状态在每轮对话开始时通过 agent._tool_guardrails.reset_for_turn() 重置，确保计数按对话轮次而非全局累计。

八、配置项一览

九、总结：四层预算防御体系

Hermes 的预算控制不是单一机制，而是四道防线组成的完整体系：

这个体系的核心设计哲学是：预算控制不是事后补救，而是内建在 Agent 运行循环中的第一公民。从 IterationBudget 的 consume/refund 到 CreditsTracker 的 escalating notices，从 RateGuard 的跨会话协调到错误分类器的 billing/rate_limit 鉴别，每一层都针对一个具体的失控场景提供了精确的防护。

下一讲（第 15 讲）System Prompt 怎么动态构建、Prompt Caching 如何节省 token 成本。