Lesson 02 — 成本预算：轨迹级的钱包

L00 基线 · 故障⑤预算炸弹：
  总 token：70714（mock 估算）
  结局：💸 overspent（烧穿预算无刹车）

# cost_budget.py
def extract_usage(llm_response):
    """优先取 usage_metadata，取不到按字符/4 估算。"""
    usage = getattr(llm_response, "usage_metadata", None)
    if isinstance(usage, dict) and usage:
        return {
            "input_tokens": usage.get("input_tokens", 0),
            "output_tokens": usage.get("output_tokens", 0),
            "total_tokens": usage.get("total_tokens", ...),
            "estimated": False,   # ← 真实计量
        }
    # 降级：字符估算，诚实标注
    est = max(1, len(str(content)) // 4)
    return {"total_tokens": est, "estimated": True}  # ← 估算

# state.py
token_usage: Annotated[int, add_int]   # ← 复用 L01 的 add_int reducer
cost_mode: str                          # normal / frugal / over_budget

                    token 累计
                        │
    ┌───────────────────┼───────────────────┐
    │     normal        │    frugal         │  over_budget
    │  （未到 80%）      │  （80%~100%）      │  （≥100%）
    │                   │                   │
    │  正常跑            │  节俭模式          │  诚实收尾
    │                   │  剩余子题降级       │  （复用 L01 路径）
    │                   │  flash            │  带部分结果退出
    └───────────────────┴───────────────────┘
     0           80% × budget       100% × budget

# nodes.py（reviewer 开头）
from .step_budget import should_truncate          # L01：步数预算
from .cost_budget import should_truncate_for_cost # L02：成本预算

truncate, reason = should_truncate(state)          # 步数/循环
if not truncate:
    truncate, cost_reason = should_truncate_for_cost(state)  # 成本
    if truncate:
        reason = cost_reason
if truncate:
    return {"review_decision": "pass", "truncated": True, ...}  # 同一条诚实收尾路径

# cost_budget.py
@dataclass
class NodeCostTracker:
    by_node: dict[str, dict]  # {node: {total_tokens, calls, estimated}}

    def report(self):
        """按 token 降序列出每个节点的消耗（吞金兽在前）。"""
        ...

预算炸弹场景（裸奔）：
  researcher        11748 token   99.5%   ← 吞金兽（吃超长搜索结果）
  writer               30 token    0.3%
  summarize            20 token    0.2%
  split                 5 token    0.0%

💸 before：裸奔（预算炸弹）
   总 token：11803  ← 烧穿
   researcher 99.5%  ← 吞金兽

✅ after：开预算（预算炸弹）
   总 token：7837  ← 硬预算刹车（诚实收尾）
   researcher 99.9%

✅ 对照：开预算（正常）
   总 token：70  ← 成本可控，治理零税

cd portfolio-projects/research-assistant
python ../../agent-ops-lessons/02_cost_budget/code.py

cd portfolio-projects/research-assistant

# 1. 全部测试绿（139 + 17 = 156）
python -m pytest -q
# 预期：156 passed

# 2. 开关关时行为 = 现状
python -m pytest tests/test_graph.py tests/test_nodes.py tests/test_step_budget.py -q
# 预期：全绿

# 3. 开成本预算后硬预算触发
python -c "
from research_assistant import config
config.settings.__dict__['enable_cost_budget'] = True
config.settings.__dict__['max_budget_tokens'] = 100
from research_assistant.cost_budget import should_truncate_for_cost
print(should_truncate_for_cost({'token_usage': 150}))
"
# 预期：(True, '成本预算超限（150/100 token）')