跳至内容

成本追踪

cost-tracker.ts(323 行)是一个常被忽略但贯穿整个运行时的横切关注点。它不只是"记录花了多少钱",而是一个完整的 7 维会话级计量系统。

核心问题

AI agent 运行的每一次 API 调用、每一次工具执行、每一次代码变更都有成本。用户需要知道"这次会话花了多少钱",系统需要知道"当前还能花多少",运维需要知道"异常消耗出现在哪里"。

成本追踪不是附加功能,而是 agent 可持续运行的基础设施。

7 维计量体系

追踪维度说明
Token 计量输入 token、输出 token、缓存创建 token、缓存读取 token 分别统计
时间分解总耗时、API 调用耗时、重试排除后 API 耗时、工具执行耗时独立计算
代码变更新增行数、删除行数持续累计
多模型拆分按模型名归类用量,支持 getUsageForModel() 按模型查询
成本估算calculateUSDCost() 基于模型定价表实时估算美元成本
Web Search独立追踪 Web 搜索请求次数
状态持久化setCostStateForRestore() / resetCostState() 支持会话恢复和重置

架构设计

    flowchart LR
    subgraph Input ["事件输入"]
        API["API 调用<br/>token 计量"]
        Tool["工具执行<br/>耗时计量"]
        Code["代码变更<br/>行数累计"]
        Web["Web 搜索<br/>次数统计"]
    end

    subgraph Tracker ["cost-tracker.ts"]
        State["全局状态原子<br/>bootstrap/state.js"]
        Model["多模型分桶<br/>getUsageForModel()"]
        USD["成本估算<br/>calculateUSDCost()"]
    end

    subgraph Output ["消费端"]
        UI["状态栏显示<br/>实时费用"]
        Persist["会话持久化<br/>恢复/重置"]
        Telemetry["遥测上报<br/>logEvent()"]
    end

    API --> State
    Tool --> State
    Code --> State
    Web --> State
    State --> Model
    State --> USD
    USD --> UI
    State --> Persist
    USD --> Telemetry
  

全局状态原子

成本追踪器通过 bootstrap/state.js 中的全局状态原子实现。任何模块都可以通过 getTotalCostUSD() 等函数读取当前会话成本,而不需要传递计数器引用。这是一种典型的横切关注点全局化设计——成本信息需要在 UI 层(状态栏)、运行时层(预算检查)和遥测层(上报)同时可用。

Token 计数的两种方式

方式场景精度
规范方式从 API 响应的 usage 字段获取精确
粗略估算请求发送前预估、图片/文档估算约估

粗略估算规则:

  • 普通文本:4 字节/token
  • JSON 格式:2 字节/token(密集格式需要更保守的估算)
  • 图片/文档:保守估算 2,000 token(真实公式:width × height / 750)

多模型分桶

当一次会话中涉及多个模型(主模型 + 子代理模型 + YOLO 分类器模型)时,成本追踪器按模型名分桶统计。getUsageForModel() 支持按模型查询单独用量。

与运行时的关系

成本追踪不是孤立的记录器,而是与运行时多个子系统交互:

交互对象关系
自动压缩压缩决策考虑当前 token 消耗率
Token 预算MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200K 防止单次工具洪泛
遥测系统API 三事件模型(query/success/error)+ TTFT/TTLT 性能指标
会话恢复setCostStateForRestore() 在 resume 时恢复累计成本
状态栏实时显示当前会话美元成本

可观测性关联

成本追踪是 Claude Code 5 层遥测体系的数据源之一。每次 API 调用结束后,logEvent() 会将 token 用量、耗时和成本信息上报到遥测管线,经过 PII 过滤后分流到 Datadog 和内部数据湖。

关键指标:

  • TTFT(Time to First Token):首 token 延迟
  • TTLT(Time to Last Token):末 token 延迟
  • 缓存命中率:cacheReadTokens / totalInputTokens

对 agent 开发者的启示

模式说明
横切计量成本追踪应该像日志一样无处不在,而不是后期补加
多维分桶不要只记总 token——按模型、按时间、按变更类型分别统计
保守估算在精确数据不可用时,用保守估算兜底(JSON 2 字节/token)
会话持久化成本状态需要跨 resume 保持,否则用户看到的费用会不连续
全局可读通过全局状态原子让任何模块都能读取成本,而不是手动传参

路径证据

路径职责
src/cost-tracker.ts成本追踪器核心(323 行)
src/bootstrap/state.js全局状态原子
src/utils/modelCost.ts模型定价表
src/services/analytics/遥测管线
src/components/状态栏显示

进一步阅读

  1. 运行时流程 — 成本追踪在 queryLoop 中的位置
  2. 架构地图 — 横切关注点的系统位置
  3. 记忆系统 — 压缩与成本的关系