[RFC] 134 - Context Engine

[arvinxx]

摘要

Context Engine 是一个灵活的消息处理管道系统，专为 LobeHub 设计，用于在 AI 对话中实现更加优雅的 Context Engineering。该模块将采用模块化的处理器架构，通过可组合的管道模式，实现了上下文注入、转换、验证和优化的统一抽象。

背景

在现有的 LobeChat 实现中，聊天消息的上下文处理逻辑分散在各个层（store 与 service）中，缺乏统一的抽象和管理机制。这导致了以下核心问题：

1. 维护困难：上下文处理逻辑分散，难以统一维护和测试
2. 扩展性差：添加新的上下文处理功能需要修改多个文件
3. 职责不清：不同处理逻辑的边界模糊，难以复用

目标

基于最新的 Context Engineering 架构思考，设计并实现一个智能、可扩展的上下文处理管道系统，实现以下核心目标：

1. 统一抽象：提供基于功能分类的处理器抽象层，实现上下文处理的统一管理
2. 模块化设计：将处理逻辑按职责拆分为 Provider（提供者）和 Processor（处理器）两大类
3. 管道模式：支持处理器的顺序执行、条件执行和组合执行
4. 易于测试：提供完善的测试框架和模拟机制，支持单元测试和集成测试
5. 可配置：支持动态配置、运行时调整和插件扩展

设计

核心概念

1. 处理器分类体系

基于功能职责，处理器分为两大类：

Provider

• 职责：向消息流中添加新的上下文信息
• 特点：专注于上下文注入
• 示例：SystemRoleInjector、HistorySummaryProvider、ToolSystemRoleProvider、InboxGuideProvider

Processor

• 职责：修改、转换、清理现有消息的内容或结构
• 特点：专注于消息处理，包括转换、截断、重排、清理等
• 示例：MessageContentProcessor、PlaceholderVariablesProcessor、HistoryTruncateProcessor、ToolMessageReorder、MessageCleanupProcessor、ToolCallProcessor

2. 管道上下文（PipelineContext）

管道上下文是在整个处理管道中流动的核心数据结构：

interface PipelineContext {
  /** 不可变的输入状态 */
  readonly initialState: AgentState;

  /** 正在构建的可变消息列表 */
  messages: Message[];

  /** 处理器间通信的元数据 */
  metadata: {
    currentTokenCount?: number;
    maxTokens: number;
    model: string;
    [key: string]: any;
  };
}

3. 基础抽象类

BaseProcessor（基础处理器）

• 提供通用的处理器功能和错误处理
• 包含输入验证、输出验证、上下文克隆等通用方法
• 所有处理器都继承此基类

BaseProvider（基础提供者）

• 专门用于注入系统消息的提供者基类
• 提供上下文构建、注入判断、消息创建等通用方法
• 所有 Provider 都继承此基类

架构设计

1. 管道引擎（ContextEngine）

核心的管道执行引擎，负责协调处理器的执行：

• 支持动态添加和移除处理器
• 提供管道配置验证功能
• 支持异步处理和错误恢复
• 提供详细的执行统计和性能监控

2. 处理器实现体系

基于最新的架构设计，系统包含以下处理器：

Provider（提供者）

• SystemRoleInjector：注入智能体系统角色
• InboxGuideProvider：注入收件箱引导系统角色
• ToolSystemRoleProvider：注入工具相关系统角色
• HistorySummaryProvider：注入历史对话摘要

Processor（处理器）

• HistoryTruncateProcessor：根据配置限制历史消息数量
• InputTemplateProcessor：处理输入消息模板
• PlaceholderVariablesProcessor：处理占位符变量替换
• MessageContentProcessor：处理消息内容格式转换
• ToolCallProcessor：转换工具调用格式
• ToolMessageReorder：重新排序工具消息
• MessageCleanupProcessor：清理消息，保留必要字段

使用方式

使用流程

1. 创建管道：使用 ContextEngine 创建处理管道
2. 配置处理器：按顺序添加 Provider 和 Processor
3. 执行处理：调用 process 方法执行管道处理
4. 获取结果：返回处理后的消息数组

const pipeline = new ContextEngine({
    pipeline: [
      // 1. History truncation (MUST be first, before any message injection)
      new HistoryTruncateProcessor({ / ... / }),

      // --------- Create system role injection providers

      // 2. System role injection (agent's system role)
      new SystemRoleInjector({ / ... / }),

      // 3. Inbox guide system role injection
      new InboxGuideProvider({ / ... / }),

      // 4. Tool system role injection
      new ToolSystemRoleProvider({ / ... / }),

      // 5. History summary injection
      new HistorySummaryProvider({ / ... / }),

      // Create message processing processors

      // 6. Input template processing
      new InputTemplateProcessor({ / ... / }),

      // 7. Placeholder variables processing
      new PlaceholderVariablesProcessor({ / ... / }),

      // 8. Message content processing
      new MessageContentProcessor({ / ... / }),

      // 9. Tool call processing
      new ToolCallProcessor({ / ... / }),

      // 10. Tool message reordering
      new ToolMessageReorder(),

      // 11. Message cleanup (final step, keep only necessary fields)
      new MessageCleanupProcessor(),
    ],
  });

  const initialState: AgentState = { messages, model, provider, systemRole, tools };

  const result = await pipeline.process({
    initialState,
    maxTokens: 10_000_000,
    messages,
    model,
  });

  return result.messages;

整个流程通过 11 个处理器按顺序执行，确保上下文信息的完整性和一致性。

实施计划

• ♻️ refactor: refactor message proccesser to the Context Engine #9230