Warp源码深度解析（七）：Token预算策略——双轨计费、上下文溢出与摘要压缩

这是 Warp 源码深度解析系列的第七篇。Token 是 AI Agent 运行的燃料——用完了对话就死了。本文深入 Warp 的双轨 Token 计费warp_tokens vs byok_tokens、ConversationUsageMetadata 追踪、上下文窗口溢出处理、SummarizationType 摘要压缩、RequestUsageModel 6条件可用性检查以及 ToolUsageMetadata 工具调用审计完整还原 Token 从产生到消耗到审计的全生命周期。一、Token 预算问题的本质AI Agent 的 Token 预算管理面临三重挑战┌──────────────────────────────────────────────────────────────┐ │ 挑战1计费复杂性 │ │ Warp 提供的 Token 用户自带 Key 的 Token │ │ → 两套独立的计费和追踪系统 │ ├──────────────────────────────────────────────────────────────┤ │ 挑战2上下文溢出 │ │ 对话越长上下文越大最终超出模型窗口限制 │ │ → 需要优雅降级而非直接崩溃 │ ├──────────────────────────────────────────────────────────────┤ │ 挑战3多模型混用 │ │ 一次对话可能经过多个模型主模型 快速模型 嵌入模型 │ │ → 需要按模型追踪 Token 用量 │ └──────────────────────────────────────────────────────────────┘Warp 的解法是一个三层架构追踪层ConversationUsageMetadata→ 决策层RequestUsageModel→ 降级层Summarization Error Handling。二、双轨 Token 计费——warp_tokens vs byok_tokens2.1 为什么需要双轨Warp 的商业模式有两种 Token 来源warp_tokens— Warp 提供的 Token包含在订阅中有配额限制byok_tokens— Bring Your Own Key用户自带 API Key无配额限制// crates/persistence/src/model.rs:1069pubstructModelTokenUsage{pubmodel_id:String,/// Warp 提供的 Token 用量/// 向后兼容旧数据用 total_tokens 字段通过 alias 映射#[serde(default, alias total_tokens)]pubwarp_tokens:u32,/// 用户自带 Key 的 Token 用量#[serde(default)]pubbyok_tokens:u32,/// 按 Category 细分的 Warp Token 用量#[serde(default)]pubwarp_token_usage_by_category:HashMapTokenUsageCategory,u32,/// 按 Category 细分的 BYOK Token 用量#[serde(default)]pubbyok_token_usage_by_category:HashMapTokenUsageCategory,u32,}2.2 向后兼容的 alias 设计注意#[serde(default, alias total_tokens)]——旧版本持久化的数据用total_tokens字段名新版本改为warp_tokens。通过 serde alias 实现零停机迁移// 旧数据{ model_id: gpt-4, total_tokens: 1500 }// 新数据{ model_id: gpt-4, warp_tokens: 1500, byok_tokens: 0 }// 两种格式都能正确反序列化2.3 Token Category 分类pubtypeTokenUsageCategoryString;pubconstPRIMARY_AGENT_CATEGORY:strprimary_agent;pubconstFULL_TERMINAL_USE_CATEGORY:strfull_terminal_use;当前只有两个分类但用String类型而非枚举是为了服务端可以动态添加新分类而无需客户端发版。这是一种前向兼容设计。2.4 双轨数据的合并输出implModelTokenUsage{pubfnto_proto_warp_usage(self)-Option(String,ModelTokenUsage){self.to_proto_usage(self.warp_tokens,self.warp_token_usage_by_category)}pubfnto_proto_byok_usage(self)-Option(String,ModelTokenUsage){self.to_proto_usage(self.byok_tokens,self.byok_token_usage_by_category)}pubfnto_proto_combined(self)-ModelTokenUsage{// warp_tokens byok_tokens 合并ModelTokenUsage{model_id:self.model_id.clone(),total_tokens:self.warp_tokensself.byok_tokens,...}}}三种输出模式各有用途warp_usage— Warp 计费系统用byok_usage— 用户查看自己的 Key 消耗combined— 展示总用量三、ConversationUsageMetadata——对话级 Token 追踪3.1 核心结构// crates/persistence/src/model.rs:1297pubstructConversationUsageMetadata{/// 对话是否已被摘要压缩pubwas_summarized:bool,/// 上下文窗口使用比例0.0~1.0由服务端报告pubcontext_window_usage:f32,/// 总花费的 Creditspubcredits_spent:f32,/// 最近一个 Block一次 Agent 交互的 Creditspubcredits_spent_for_last_block:Optionf32,/// 按模型细分的 Token 用量#[serde(default)]pubtoken_usage:VecModelTokenUsage,/// 工具调用审计数据#[serde(default)]pubtool_usage_metadata:ToolUsageMetadata,}3.2 context_window_usage——服务端的油表context_window_usage是一个 0.0~1.0 的浮点数由服务端在每次响应中报告不是客户端计算的。这是一个重要的设计决策客户端无法准确知道上下文占用了多少 Token因为 1. 不同模型的 Token 计算方式不同 2. 系统提示词的长度客户端不知道 3. 工具定义的长度客户端不知道 4. 服务端可能插入额外上下文 → 让服务端报告是最准确的3.3 was_summarized——单向门// app/src/ai/agent/conversation.rs:1611// A conversation can never go from summarized to un-summarized,// so we only update the summarized flag if its going from false to true.ifusage_metadata.summarized!self.conversation_usage_metadata.was_summarized{self.conversation_usage_metadata.was_summarizedusage_metadata.summarized;}was_summarized是一个单向门——只能从false变为true永远不能回退。这反映了一个事实一旦对话被摘要压缩原始上下文已经丢失恢复是不可能的。3.4 Token 用量更新流程// app/src/ai/agent/conversation.rs:1568ifletSome(usage_metadata)usage_metadata{// 1. 更新上下文窗口使用量self.conversation_usage_metadata.context_window_usageusage_metadata.context_window_usage;// 2. 更新 Creditsself.conversation_usage_metadata.credits_spentusage_metadata.credits_spent;// 3. 双轨 Token 用量合并到 HashMapletmuttoken_usage:HashMap_,ModelTokenUsageHashMap::new();for(model_id,usage)inusage_metadata.warp_token_usage{letentrytoken_usage.entry(model_id.clone()).or_default();entry.warp_tokensusage.total_tokens;for(category,tokens)inusage.token_usage_by_category{*entry.warp_token_usage_by_category.entry(category).or_default()tokens;}}for(model_id,usage)inusage_metadata.byok_token_usage{letentrytoken_usage.entry(model_id.clone()).or_default();entry.byok_tokensusage.total_tokens;for(category,tokens)inusage.token_usage_by_category{*entry.byok_token_usage_by_category.entry(category).or_default()tokens;}}// 4. 转换为 Vec 持久化self.conversation_usage_metadata.token_usagetoken_usage.into_iter().map(|(name,mutusage)|{usage.model_idname;usage}).collect();// 5. 更新工具调用审计self.conversation_usage_metadata.tool_usage_metadatausage_metadata.tool_usage_metadata.as_ref().map(Into::into).unwrap_or_default();// 6. 单向门was_summarizedifusage_metadata.summarized!self.conversation_usage_metadata.was_summarized{self.conversation_usage_metadata.was_summarizedusage_metadata.summarized;}}四、上下文窗口溢出处理4.1 溢出错误映射当 LLM 服务端返回 Token 超限错误时Warp 统一处理为ContextWindowExceeded// ContextWindowExceeded 和 MaxTokenLimit 都映射到同一个用户可见错误ContextWindowExceeded|MaxTokenLimit{RenderableAIError::ContextWindowExceeded}4.2 对话状态转换对话进行中 (Active) │ ├── 服务端返回 ContextWindowExceeded │ ▼ 对话失败 (Failed) │ ├── 用户看到上下文窗口已超出 └── 建议开启新对话关键设计Warp 不会自动截断对话内容或强制摘要。上下文溢出直接导致对话失败用户需要主动处理。这是一个显式优于隐式的设计决策——自动摘要可能让用户丢失重要上下文而不自知。4.3 SummarizationCancellationConfirmation当用户尝试取消正在进行的摘要操作时Warp 会弹出确认对话框// FeatureFlag: SummarizationCancellationConfirmation// 确认你确定要取消摘要吗这可能导致对话无法继续。这也说明摘要是不可逆操作——取消意味着对话可能无法恢复。五、SummarizationType——两种摘要模式5.1 枚举定义// app/src/ai/agent/mod.rs:1621pubenumSummarizationType{/// 对话摘要——压缩整个对话历史ConversationSummary,/// 工具调用结果摘要——压缩长工具输出ToolCallResultSummary,}5.2 两种摘要的触发场景类型触发场景目的ConversationSummary上下文窗口即将溢出压缩对话历史释放 Token 空间ToolCallResultSummary工具输出过长如 cat 大文件压缩单次工具调用结果释放 Token 空间5.3 Summarization 输出消息pubenumAIAgentOutputMessageType{Summarization{text:AIOutputText,finished_duration:OptionDuration,summarization_type:SummarizationType,/// 摘要消耗的 Token 数token_count:Optionu32,},// ...}摘要本身也消耗 Tokentoken_count这些 Token 会计入对话的ConversationUsageMetadata。5.4 服务端驱动的摘要Warp 的摘要是服务端驱动的——客户端不决定何时摘要只负责接收服务端的summarized: true标记更新was_summarized单向门渲染 Summarization 输出消息追踪摘要消耗的 Token这种设计简化了客户端逻辑但也意味着客户端无法主动触发摘要。5.5 SummarizationViaMessageReplacement Flag// FeatureFlag: SummarizationViaMessageReplacement// 用消息替换方式实现摘要而非删除原始消息传统摘要实现可能直接删除旧消息。SummarizationViaMessageReplacement用替换方式——保留消息 ID更新消息内容。这让 UI 可以显示此消息已被摘要的状态而不是突然消失。六、RequestUsageModel——6 条件可用性检查6.1 has_any_ai_remaining()这是 AI 可用性的终极检查——6 个条件只要满足一个就可以继续使用// app/src/ai/request_usage_model.rs:381pubfnhas_any_ai_remaining(self,ctx:AppContext)-bool{// 条件1基础套餐还有请求额度lethas_base_plan_ai_requestsself.has_requests_remaining();// 条件2用户有个人赠送 Creditsletuser_bonus_creditsself.total_user_interactive_bonus_credits_remaining()0;// 条件3工作空间有赠送 Creditsletworkspace_bonus_creditscurrent_workspace.map(|w|self.total_workspace_bonus_credits_remaining(w.uid)0).unwrap_or_default();// 条件4工作空间启用了超量使用letworkspace_has_overagescurrent_workspace.is_some_and(|w|w.are_overages_remaining());// 条件5企业版按量付费letis_payg_enabledcurrent_workspace.is_some_and(|w|w.billing_metadata.is_enterprise_pay_as_you_go_enabled());// 条件6企业版自动充值letis_enterprise_auto_reload_enabledcurrent_workspace.is_some_and(|w|w.billing_metadata.is_enterprise_auto_reload_enabled());// 条件7隐藏条件用户自带 API Keylethas_byo_api_keyUserWorkspaces::as_ref(ctx).is_byo_api_key_enabled()ApiKeyManager::as_ref(ctx).keys().has_any_key();has_base_plan_ai_requests||(user_bonus_credits||workspace_bonus_credits)||workspace_has_overages||is_payg_enabled||is_enterprise_auto_reload_enabled||has_byo_api_key}6.2 7 层降级策略用户发送请求 │ ├── 1. 基础套餐有额度 → 直接使用 │ ├── 2. 个人赠送 Credits → 消耗赠送额度 │ ├── 3. 工作空间赠送 Credits → 消耗团队额度 │ ├── 4. 超量使用Overages→ 按量计费 │ ├── 5. 企业按量付费PAYG→ 企业计费 │ ├── 6. 企业自动充值 → 自动充值后使用 │ └── 7. BYOK → 用户自带 Key不受限制BYOK 是终极降级——只要你自己的 API Key 还有额度Warp 的配额限制不影响你。6.3 默认配额免费用户 - 150 请求/月 - 3 个代码库索引 - 5000 文件/仓库七、ToolUsageMetadata——工具调用审计7.1 完整审计结构// crates/persistence/src/model.rs:1204pubstructToolUsageMetadata{pubrun_command_stats:RunCommandStats,// 执行命令pubread_files_stats:ToolCallStats,// 读取文件pubsearch_codebase_stats:ToolCallStats,// 搜索代码库pubgrep_stats:ToolCallStats,// Grep 搜索pubfile_glob_stats:ToolCallStats,// 文件匹配pubapply_file_diff_stats:ApplyFileDiffStats,// 应用文件 Diffpubwrite_to_long_running_shell_command_stats:ToolCallStats,// 写入长运行命令pubread_mcp_resource_stats:ToolCallStats,// 读取 MCP 资源pubcall_mcp_tool_stats:ToolCallStats,// 调用 MCP 工具pubsuggest_plan_stats:ToolCallStats,// 建议计划pubsuggest_create_plan_stats:ToolCallStats,// 建议创建计划pubread_shell_command_output_stats:ToolCallStats,// 读取命令输出pubuse_computer_stats:ToolCallStats,// Computer Use}13 种工具调用每一种都有独立的统计。total_tool_calls()方法汇总所有工具调用次数implToolUsageMetadata{pubfntotal_tool_calls(self)-i32{self.run_command_stats.countself.read_files_stats.countself.search_codebase_stats.countself.grep_stats.countself.file_glob_stats.countself.write_to_long_running_shell_command_stats.countself.read_mcp_resource_stats.countself.call_mcp_tool_stats.countself.suggest_plan_stats.countself.suggest_create_plan_stats.countself.apply_file_diff_stats.countself.read_shell_command_output_stats.countself.use_computer_stats.count}}7.2 为什么要按工具类型追踪成本分析— 不同工具消耗的 Token 不同Computer Use 截图远比 Grep 贵行为审计— 某个 Agent 是否过度调用 MCP 工具配额控制— 未来可能按工具类型设置不同的配额产品决策— 哪些工具最受欢迎哪些工具使用率低需要改进八、Credits 与 Token 的关系8.1 双重计量Warp 有两套并行的计量系统CreditsWarp 虚拟货币 ├── credits_spent: 总花费 ├── credits_spent_for_last_block: 最近一次交互花费 └── 用于 Warp 商业计费 TokenLLM 计量单位 ├── warp_tokens: Warp 提供的 Token ├── byok_tokens: 用户自带 Key 的 Token └── 用于 LLM 层面追踪Credits 是面向用户的计费单位Token 是面向技术的追踪单位。一次请求的 Credits 和 Token 不一定是简单的线性关系——Warp 可能在 Token 成本上加价也可能对不同模型使用不同的 Credit 汇率。8.2 credits_spent_for_last_block 的重置ifwas_user_initiated_request{*credits_spent_for_last_block0.;}*credits_spent_for_last_blockrequest_cost.value()asf32;每次用户发起新请求时重置credits_spent_for_last_block然后累加这次请求的所有服务端响应的 Cost。这让 UI 可以显示这次交互花了多少 Credits。九、Feature Flag 与 Token 策略的关联Flag对 Token 策略的影响FullSourceCodeEmbedding代码库上下文消耗更多 TokenCrossRepoContext跨仓库上下文进一步增加 Token 消耗ContextWindowUsageV2上下文窗口使用量的 v2 计算方式SummarizationViaMessageReplacement摘要替换方式影响 Token 计数RetryTruncatedCodeResponses截断重试消耗额外 TokenSummarizationCancellationConfirmation摘要取消确认的 UIAgentViewBlockContext自动附加 Block 增加上下文 Token最关键的权衡AgentViewBlockContext增强了 Agent 的感知能力自动附加终端输出但也增加了 Token 消耗。Warp 用 Feature Flag 让用户/团队自己决定是否承担这个额外成本。十、Token 生命周期完整流程1. 用户发起请求 │ ▼ 2. has_any_ai_remaining() 检查 6 条件 │ ├── 不通过 → 显示配额不足 │ └── 通过 ↓ │ 3. 组装上下文AIAgentContext × 9 │ ▼ 4. 发送到 LLM Server │ ├── 正常响应 → 更新 ConversationUsageMetadata │ ├── context_window_usage 更新 │ ├── credits_spent 累加 │ ├── token_usage 按模型按分类累加 │ └── tool_usage_metadata 按工具累加 │ ├── ContextWindowExceeded → 对话失败 │ ├── 需要摘要 → 服务端返回 summarized: true │ ├── was_summarized 设为 true单向门 │ ├── Summarization 消耗额外 Token │ └── 对话继续上下文已被压缩 │ └── 其他错误 → 错误处理十一、设计模式总结模式实现价值双轨计费warp_tokens byok_tokens商业灵活性和用户自主性服务端油表context_window_usage 由服务端报告准确性优于客户端估算单向门was_summarized 只能 false→true防止错误的恢复操作7 层降级has_any_ai_remaining() 6 条件 BYOK配额耗尽时的优雅降级按工具审计13 种 ToolUsageMetadata精细化成本分析Feature Flag 权衡AgentViewBlockContext 增强但增加 Token用户自主选择成本/能力平衡向后兼容serde aliastotal_tokens→warp_tokens零停机数据迁移前向兼容TokenUsageCategory String 而非枚举服务端可动态添加分类十二、与其他 Agent 框架对比特性WarpClaude CodeCursorGitHub Copilot计费模式双轨warp BYOK单轨订阅单轨订阅单轨订阅Token 追踪粒度模型 × 分类 × 工具按对话按月按月上下文使用量服务端报告 f32客户端估算客户端估算不透明溢出处理对话失败 摘要自动摘要自动截断自动截断摘要类型对话 工具调用双类型对话无无工具调用审计13 种独立统计无无无配额降级7 层2 层2 层2 层BYOK原生支持支持部分不支持Warp 在 Token 管理上的核心优势是精细化追踪——不是简单记录用了多少 Token而是按模型、按分类、按工具类型分别追踪并且区分 Warp 提供和用户自带的 Token。这种粒度对于企业级 Agent 的成本管理至关重要。系列索引一架构全景二WarpUI 框架深度解析三终端引擎深度解析四AI Agent 深度解析五基础设施深度解析六Context 管理深度解析七Token 预算策略深度解析 ← 你在这里