Warp源码深度解析（六）：AI Agent的Context管理——从9种上下文到流水线组装

这是 Warp 源码深度解析系列的第六篇。Context 管理是 AI Agent 的感知系统——决定了 Agent 能看到什么、知道什么。本文深入 Warp 的 9 种 AIAgentContext、BlocklistAIContextModel 状态机、input_context_for_request 流水线组装、项目规则扫描和代码库索引上下文完整还原从用户输入到 LLM 请求的上下文构建全链路。一、为什么 Context 管理是 Agent 的命脉LLM 的上下文窗口是有限的。一个 Agent 的智商很大程度上取决于你能往这个窗口里塞什么、怎么塞、塞多少。用户提问这个 bug 怎么修 ┌──────────────────────────────────────────────────────────┐ │ 低级 Agent只看到用户的问题 │ │ → 回答请提供更多上下文 │ ├──────────────────────────────────────────────────────────┤ │ 中级 Agent看到问题 当前目录 最近几条命令 │ │ → 回答猜测性建议经常猜错 │ ├──────────────────────────────────────────────────────────┤ │ 高级 Agent看到问题 目录 Git分支 项目规则 │ │ 代码索引 执行环境 终端输出 选中文本 附件图片 │ │ → 回答精准定位直接给 patch │ └──────────────────────────────────────────────────────────┘Warp 选择了第三条路——9 种上下文源 流水线组装 Feature Flag 动态门控。二、9 种 AIAgentContext——Agent 的感知维度2.1 完整枚举// app/src/ai/agent/mod.rs:1966pubenumAIAgentContext{// ── 环境类始终包含──Directory{pwd:OptionString,home_dir:OptionString,are_file_symbols_indexed:bool,},Git{head:String,branch:OptionString,},ExecutionEnvironment(WarpAiExecutionContext),// OS、Shell类型和版本CurrentTime{current_time:DateTimeLocal},ProjectRules{root_path:String,active_rules:VecFileContext,additional_rule_paths:VecString,},// ── 代码库类Feature Flag 门控──Codebase{path:String,name:String,},Skills{skills:VecSkillDescriptor,},// ── 用户选择类仅用户查询时包含──SelectedText(String),Image(ImageContext),File(FileContext),Block(BoxBlockContext),}2.2 分类解读分类上下文何时注入控制方式环境类Directory, Git, ProjectRules每次请求无条件包含执行类ExecutionEnvironment, CurrentTime每次请求无条件包含代码类Codebase每次请求FullSourceCodeEmbeddingCrossRepoContext双 Flag 门控技能类Skills每次请求ListSkillsFlag 门控用户类Block, SelectedText, Image, File仅用户查询is_user_query参数控制这种分层设计的关键洞察环境上下文是免费的Token 开销小代码上下文是昂贵的需要索引和嵌入用户上下文是有歧义的需要互斥处理。三、BlocklistAIContextModel——上下文状态机3.1 核心结构// app/src/ai/blocklist/context_model.rs:110pubstructBlocklistAIContextModel{terminal_model:ArcFairMutexTerminalModel,directory_context:DirectoryContext,// 用户手动选择的 Block 上下文pending_context_block_ids:HashSetBlockId,// 用户选中的文本上下文pending_context_selected_text:OptionString,// 附件图片 文件pending_attachments:VecPendingAttachment,// Diff hunk 附件pending_inline_diff_hunk_attachments:HashMapString,AIAgentAttachment,// 查询状态新对话 vs 继续现有对话pending_query_state:PendingQueryState,// Agent View 中自动附加的用户命令 Blockauto_attached_agent_view_user_block_ids:VecBlockId,// 队列模式Agent 响应中排队下一条 promptqueue_next_prompt_enabled:bool,}3.2 关键不变量Block 与 SelectedText 互斥在 Warp 的设计中用户不能同时选择 Block 上下文和选中文本。这不是实现限制而是产品决策选 Block “看这段命令和输出”选文本 “看这几行代码”两种上下文语义不同同时存在会让 LLM 困惑。代码中通过set_pending_context_block_ids和set_pending_context_selected_text的调用时序保证互斥。3.3 自动附加的 Block 上下文当AgentViewBlockContextFlag 启用时用户在 Agent View 中执行的命令会自动附加为上下文// 监听 Block 完成事件ModelEvent::BlockCompleted(BlockCompletedEvent{block_type:BlockType::User(user_block_completed),block_id,..}){ifFeatureFlag::AgentViewBlockContext.is_enabled()me.agent_view_controller.as_ref(ctx).is_fullscreen()!user_block_completed.was_part_of_agent_interaction{// 用户执行的命令非 Agent 交互产生的自动附加me.auto_attached_agent_view_user_block_ids.push(block_id.clone());}}这意味着在 Agent 全屏模式下你执行的每一条命令Agent 都能看到。这是一种隐式上下文注入——用户不需要手动 -引用。四、pending_context()——上下文组装的第一层BlocklistAIContextModel::pending_context()是上下文组装的第一层负责将状态转化为VecAIAgentContextpending_context(app, is_user_query) │ ├── 始终包含 │ ├── Directory { pwd, home_dir, are_file_symbols_indexed } │ ├── Git { head, branch } 如果有 git 信息 │ └── ProjectRules { root_path, active_rules } 如果有规则文件 │ └── if is_user_query ├── pending_context_block_ids → Block 上下文 ├── auto_attached_agent_view_user_block_ids → 自动附加 Block ├── pending_context_selected_text → SelectedText └── pending_attachments 中的 Image → Image 上下文4.1 ProjectRules 的注入项目规则扫描是pending_context的重要环节。Warp 通过ProjectContextModel扫描当前目录树上的规则文件letproject_rulesifletSome(pwd)pwd.clone().and_then(|path|{PathBuf::from_str(path).ok().and_then(|s|s.canonicalize().ok())}){ProjectContextModel::as_ref(app).find_applicable_rules(pwd)}else{None};4.2 目录是否被索引的标记are_file_symbols_indexed告诉 Agent 当前目录是否有代码索引可用letis_pwd_indexedUserWorkspaces::as_ref(app).is_codebase_context_enabled(app)pwd.as_ref().is_some_and(|pwd|{RepoOutlines::as_ref(app).is_directory_indexed(Path::new(pwd))});这个标记让服务端知道是否应该尝试代码搜索。五、input_context_for_request()——流水线的最终组装input_context_for_request()是上下文流水线的最后一公里在pending_context()基础上追加请求级上下文// app/src/ai/blocklist/controller/input_context.rs:51pub(super)fninput_context_for_request(is_user_query:bool,context_model:BlocklistAIContextModel,active_session:ActiveSession,conversation_id:OptionAIConversationId,additional_context:VecAIAgentContext,app:AppContext,)-Arc[AIAgentContext]{// 第一层pending_context()letmutcontextcontext_model.pending_context(app,is_user_query);// 第二层请求级上下文context.push(AIAgentContext::CurrentTime{current_time:Local::now()});ifletSome(env)active_session.ai_execution_environment(app){context.push(AIAgentContext::ExecutionEnvironment(env));}// 第三层Feature Flag 门控的上下文ifFeatureFlag::FullSourceCodeEmbedding.is_enabled()FeatureFlag::CrossRepoContext.is_enabled(){for(codebase_path,status)inCodebaseIndexManager::as_ref(app).get_codebase_index_statuses(app){ifstatus.has_synced_version(){context.push(AIAgentContext::Codebase{name,path});}}}ifFeatureFlag::ListSkills.is_enabled(){letskillslist_skills_if_changed(active_session.current_working_directory().map(Path::new),conversation_id,app,);ifletSome(skills)skills{context.push(AIAgentContext::Skills{skills});}}// 第四层额外上下文如 Agent 间通信context.extend(additional_context);context.into()}5.1 完整流水线可视化用户按 Enter 提交查询 │ ▼ BlocklistAIContextModel.pending_context() │ ├── Directory { pwd, home_dir, are_file_symbols_indexed } ├── Git { head, branch } ├── ProjectRules { root_path, active_rules } ├── Block × N用户选择 自动附加 ├── SelectedText └── Image × N │ ▼ input_context_for_request() │ ├── CurrentTime ├── ExecutionEnvironmentOS, Shell版本 ├── Codebase × N需 FullSourceCodeEmbedding CrossRepoContext ├── Skills需 ListSkills └── additional_contextAgent间通信等 │ ▼ Arc[AIAgentContext] ← 最终上下文集合 │ ▼ AIAgentInput::UserQuery { context, ... } │ ▼ 发送到 LLM Server六、上下文引用解析——parse_context_attachments用户可以在查询文本中用特殊语法引用上下文6.1 三种引用模式lazy_static!{// block:block_id → 引用终端 BlockpubstaticrefBLOCK_CONTEXT_ATTACHMENT_REGEX:RegexRegex::new(rblock:([^])).unwrap();// workflow:id / notebook:id / plan:id / rule:id → Warp Drive 对象pubstaticrefDRIVE_OBJECT_ATTACHMENT_REGEX:RegexRegex::new(r(workflow|notebook|plan|rule):([^])).unwrap();// change:filename:line_start-line_end → Diff HunkpubstaticrefDIFF_HUNK_ATTACHMENT_REGEX:RegexRegex::new(rchange:([^])).unwrap();}6.2 跨终端 Block 搜索当用户用block:ID引用 Block 时Warp 会搜索所有 TerminalModel不只当前终端fnfind_block_attachment_in_all_terminals(block_id:BlockId,ctx:AppContext,)-OptionAIAgentAttachment{forwindow_idinctx.window_ids(){ifletSome(terminal_views)ctx.views_of_type::TerminalView(window_id){forterminal_view_handleinterminal_views{letterminal_viewterminal_view_handle.as_ref(ctx);letterminal_modelterminal_view.model.lock();letblock_listterminal_model.block_list();ifletSome(block)block_list.block_with_id(block_id){returnSome(AIAgentAttachment::Block(BlockContext{...}));}}}}None}这意味着你可以在终端 A 的 Agent 对话中引用终端 B 的命令输出。对于多终端工作流这是杀手级特性。6.3 Warp Drive 对象附件plan:ID引用特别有趣——它优先从AIDocumentModel本地编辑器获取内容再 fallback 到CloudModel云端同步版本letcontentAIDocumentModel::as_ref(ctx).get_document_content(ai_doc_id,ctx).or_else(||{CloudModel::as_ref(ctx).get_all_active_notebooks().find(|nb|nb.model().ai_document_id.as_ref()Some(ai_doc_id)).map(|nb|nb.model().data.clone())});这保证了未保存的编辑也能作为上下文注入——Agent 看到的永远是最新版本。七、ProjectContextModel——项目规则扫描7.1 规则文件扫描// crates/ai/src/project_context/model.rsconstRULES_FILE_PATTERN:[str][WARP.md,AGENTS.md];constMAX_SCAN_DEPTH:usize3;constMAX_FILES_TO_SCAN:usize5000;Warp 扫描当前目录向上遍历的 WARP.md 和 AGENTS.md 文件最多深入 3 层、最多扫描 5000 个文件。7.2 优先级规则WARP.md 优先于 AGENTS.md同一目录中 WARP.md 先被匹配从当前目录向上查找最靠近的规则文件优先这和 Claude Code 的 CLAUDE.md、Cursor 的 .cursorrules 是同一思路但 Warp 支持两个文件名且做了目录树遍历。八、代码库索引上下文——双路系统Warp 的代码库上下文有两条路径由 Feature Flag 控制┌─────────────────────────────┐ │ 用户查询到达服务端 │ └──────────┬──────────────────┘ │ ┌────────────────┴────────────────┐ │ │ FullSourceCodeEmbedding Outline-Based CrossRepoContext (传统路径) │ │ ┌─────────▼──────────┐ ┌────────▼────────┐ │ CodebaseIndexManager│ │ RepoOutlines │ │ (本地 Merkle Tree │ │ (服务端 API) │ │ 向量嵌入) │ │ │ └─────────┬──────────┘ └────────┬────────┘ │ │ retrieve_relevant_files() server API search │ │ get_relevant_fragments() │ │ │ build_and_rerank_fragments() │ │ │ process_fragments() │ │ │ └────────────┬────────────────────┘ │ 相关代码片段注入上下文8.1 全文嵌入路径constRETRIEVE_FRAGMENT_CONTEXT_LENGTH:usize0;// 不附加上下文行constREINDEX_INTERVAL:DurationDuration::from_secs(20*60);// 20分钟重索引关键设计决策RETRIEVE_FRAGMENT_CONTEXT_LENGTH 0——片段不附带上下文行。这意味着每个代码片段是独立的不会因为包含周围的噪音代码而浪费 Token。8.2 Merkle Tree 增量同步文件变更检测 → Merkle Tree Hash 比较 │ ├── Hash 一致 → 跳过 └── Hash 不同 → 重新嵌入该文件增量同步间隔 60 分钟全量重索引间隔 20 分钟。这种全量 增量双节奏设计兼顾了完整性和性能。九、Feature Flag 门控的上下文路径上下文相关的 Feature Flag 构成了一个精细的控制系统Flag控制的上下文默认渠道FullSourceCodeEmbedding本地代码库向量索引DOGFOODCrossRepoContext跨仓库代码上下文DOGFOODListSkillsSkills 列表注入DOGFOODImageAsContext图片作为上下文-FileRetrievalTools文件检索工具-AgentViewBlockContextAgent View 自动附加 BlockDOGFOODReloadStaleConversationFiles重新加载过时文件-SummarizationViaMessageReplacement摘要替换方式DOGFOODContextWindowUsageV2上下文窗口使用量 v2-双 Flag 门控是最值得学习的模式// 必须两个 Flag 同时开启才注入 Codebase 上下文ifFeatureFlag::FullSourceCodeEmbedding.is_enabled()FeatureFlag::CrossRepoContext.is_enabled(){// 注入 Codebase 上下文}为什么不是单个 Flag因为FullSourceCodeEmbedding控制索引的构建CrossRepoContext控制索引的使用。你可以构建索引但不跨仓库使用也可以允许跨仓库但索引还没建好。这种能力 Flag × 行为 Flag的组合是很好的实践。十、上下文重置策略10.1 什么时候重置ModelEvent::BlockCompleted(BlockCompletedEvent{block_type:BlockType::User(user_block_completed),block_id,..}){// 如果不是 AgentViewBlockContext 模式// 且用户执行的命令不是 Agent 交互的一部分// 则重置上下文if!FeatureFlag::AgentViewBlockContext.is_enabled()!user_block_completed.was_part_of_agent_interaction{me.reset_context_to_default(ctx);}}10.2 两种模式对比模式重置时机行为传统模式用户命令完成后立即清空 pending contextAgentViewBlockContext不自动重置用户命令自动附加持续累积传统模式下每次用户执行命令后上下文都会被清空——这避免了过时上下文污染但也丢失了连续对话的上下文连贯性。AgentViewBlockContext 模式通过自动附加解决了这个矛盾。十一、设计模式总结模式实现价值分层组装pending_context() → input_context_for_request()环境上下文和用户上下文解耦各自演进互斥不变量Block vs SelectedText避免语义冲突的上下文注入Feature Flag 门控双 Flag 组合能力 × 行为渐进式发布索引构建和使用解耦隐式上下文注入AgentViewBlockContext 自动附加用户无需手动 体验更自然跨终端引用block:ID搜索所有 TerminalModel多终端工作流的上下文共享最新内容优先AIDocumentModel → CloudModel fallback未保存的编辑也能注入上下文零上下文片段RETRIEVE_FRAGMENT_CONTEXT_LENGTH 0代码片段不带噪音精确匹配十二、与其他 Agent 框架对比特性WarpClaude CodeCursorGitHub Copilot上下文种类9 种枚举隐式文件终端文件选择文件选择终端输出作为上下文Block 自动附加终端日志读取无无图片上下文ImageAsContextFlag支持截图无项目规则WARP.md/AGENTS.md 双文件CLAUDE.md.cursorrules无代码索引Merkle Tree 向量嵌入本地索引本地索引服务端索引跨仓库上下文CrossRepoContextFlag多项目Workspace无引用语法block:IDplan:IDfilefile无Feature Flag 门控9 个上下文相关 Flag无无无Warp 的独特价值在于上下文是显式建模的——9 种枚举类型、Feature Flag 门控、互斥不变量而不是简单地把所有东西塞进 prompt。这种工程化的上下文管理使得 Warp 的 Agent 可以在 Token 预算有限的情况下精准选择最有价值的上下文。系列索引一架构全景二WarpUI 框架深度解析三终端引擎深度解析四AI Agent 深度解析五基础设施深度解析六Context 管理深度解析 ← 你在这里七Token 预算策略深度解析