企业官网建设流程全解析

这是 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_tokens

2.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:HashMap<TokenUsageCategory,u32>,/// 按 Category 细分的 BYOK Token 用量#[serde(default)]pubbyok_token_usage_by_category:HashMap<TokenUsageCategory,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 分类

pubtypeTokenUsageCategory=String;pubconstPRIMARY_AGENT_CATEGORY:&str="primary_agent";pubconstFULL_TERMINAL_USE_CATEGORY:&str="full_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_tokens+self.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:Option<f32>,/// 按模型细分的 Token 用量#[serde(default)]pubtoken_usage:Vec<ModelTokenUsage>,/// 工具调用审计数据#[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 it's going from false to true.ifusage_metadata.summarized&&!self.conversation_usage_metadata.was_summarized{self.conversation_usage_metadata.was_summarized=usage_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_usage=usage_metadata.context_window_usage;// 2. 更新 Creditsself.conversation_usage_metadata.credits_spent=usage_metadata.credits_spent;// 3. 双轨 Token 用量合并到 HashMapletmuttoken_usage:HashMap<_,ModelTokenUsage>=HashMap::new();for(model_id,usage)inusage_metadata.warp_token_usage{letentry=token_usage.entry(model_id.clone()).or_default();entry.warp_tokens+=usage.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{letentry=token_usage.entry(model_id.clone()).or_default();entry.byok_tokens+=usage.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_usage=token_usage.into_iter().map(|(name,mutusage)|{usage.model_id=name;usage}).collect();// 5. 更新工具调用审计self.conversation_usage_metadata.tool_usage_metadata=usage_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_summarized=usage_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 两种摘要的触发场景

5.3 Summarization 输出消息

pubenumAIAgentOutputMessageType{Summarization{text:AIOutputText,finished_duration:Option<Duration>,summarization_type:SummarizationType,/// 摘要消耗的 Token 数token_count:Option<u32>,},// ...}

摘要本身也消耗 Token（token_count），这些 Token 会计入对话的ConversationUsageMetadata。

5.4 服务端驱动的摘要

Warp 的摘要是服务端驱动的——客户端不决定何时摘要，只负责：

1. 接收服务端的summarized: true标记
2. 更新was_summarized单向门
3. 渲染 Summarization 输出消息
4. 追踪摘要消耗的 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_requests=self.has_requests_remaining();// 条件2：用户有个人赠送 Creditsletuser_bonus_credits=self.total_user_interactive_bonus_credits_remaining()>0;// 条件3：工作空间有赠送 Creditsletworkspace_bonus_credits=current_workspace.map(|w|self.total_workspace_bonus_credits_remaining(w.uid)>0).unwrap_or_default();// 条件4：工作空间启用了超量使用letworkspace_has_overages=current_workspace.is_some_and(|w|w.are_overages_remaining());// 条件5：企业版按量付费letis_payg_enabled=current_workspace.is_some_and(|w|w.billing_metadata.is_enterprise_pay_as_you_go_enabled());// 条件6：企业版自动充值letis_enterprise_auto_reload_enabled=current_workspace.is_some_and(|w|w.billing_metadata.is_enterprise_auto_reload_enabled());// 条件7（隐藏条件）：用户自带 API Keylethas_byo_api_key=UserWorkspaces::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.count+self.read_files_stats.count+self.search_codebase_stats.count+self.grep_stats.count+self.file_glob_stats.count+self.write_to_long_running_shell_command_stats.count+self.read_mcp_resource_stats.count+self.call_mcp_tool_stats.count+self.suggest_plan_stats.count+self.suggest_create_plan_stats.count+self.apply_file_diff_stats.count+self.read_shell_command_output_stats.count+self.use_computer_stats.count}}

7.2 为什么要按工具类型追踪？

• 成本分析— 不同工具消耗的 Token 不同（Computer Use 截图远比 Grep 贵）
• 行为审计— 某个 Agent 是否过度调用 MCP 工具？
• 配额控制— 未来可能按工具类型设置不同的配额
• 产品决策— 哪些工具最受欢迎？哪些工具使用率低需要改进？

八、Credits 与 Token 的关系

8.1 双重计量

Warp 有两套并行的计量系统：

Credits（Warp 虚拟货币） ├── credits_spent: 总花费 ├── credits_spent_for_last_block: 最近一次交互花费 └── 用于 Warp 商业计费 Token（LLM 计量单位） ├── 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_block=0.;}*credits_spent_for_last_block+=request_cost.value()asf32;

每次用户发起新请求时重置credits_spent_for_last_block，然后累加这次请求的所有服务端响应的 Cost。这让 UI 可以显示"这次交互花了多少 Credits"。

九、Feature Flag 与 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 │ └── 对话继续（上下文已被压缩） │ └── 其他错误 → 错误处理

十一、设计模式总结

十二、与其他 Agent 框架对比

Warp 在 Token 管理上的核心优势是精细化追踪——不是简单记录"用了多少 Token"，而是按模型、按分类、按工具类型分别追踪，并且区分 Warp 提供和用户自带的 Token。这种粒度对于企业级 Agent 的成本管理至关重要。

系列索引：

• （一）架构全景
• （二）WarpUI 框架深度解析
• （三）终端引擎深度解析
• （四）AI Agent 深度解析
• （五）基础设施深度解析
• （六）Context 管理深度解析
• （七）Token 预算策略深度解析 ← 你在这里