OpenClaw 开发系列:第6篇-上下文引擎 — 控制 Agent 的「视野」

api.registerContextEngine("my-custom-engine", (context) => {  // context 是引擎运行环境，提供 config、pluginConfig、logger 等  // 返回上下文引擎的实现对象  return {    // 核心方法：构建最终上下文    // 每次 Agent 推理前，OpenClaw 核心会调用此方法    async buildContext(params) {      // params 包含引擎需要的所有输入：      // - systemPrompt: 系统提示（定义 Agent 角色）      // - history: 对话历史消息数组      // - toolDefinitions: Agent 可调用的工具列表      // - memoryResults: 记忆系统检索到的相关记忆      // - skillContent: 当前激活的技能内容      // - maxTokens: 模型的上下文窗口大小限制（token 数）      // 自定义组装逻辑——决定各部分信息在上下文中的位置和优先级      const sections = [];      // 1. 系统提示（优先级最高，放在最前面）      sections.push({        role: "system",        content: params.systemPrompt,        priority: 100, // 数字越大，优先级越高      });      // 2. 记忆召回（高优先级，紧随系统提示）      if(params.memoryResults?.length) {        sections.push({          role: "system",          content: formatMemory(params.memoryResults),          priority: 80,        });      }      // 3. 技能内容（指导 Agent 行为的 Markdown）      if(params.skillContent) {        sections.push({          role: "system",          content: params.skillContent,          priority: 70,        });      }      // 4. 对话历史（按时间排序，优先级最低，最先被截断）      sections.push(        ...params.history.map(msg => ({          role: msg.role,      // "user" | "assistant" | "system"          content: msg.content,          priority: 50,          timestamp: msg.timestamp, // 用于按时间排序        }))      );      // 排序（按优先级）→ 截断（超出窗口时丢弃低优先级内容）→ 格式化      const ordered = sortAndTruncate(sections, params.maxTokens);      return ordered; // 返回最终的消息数组，传递给 Provider    },  };});

function sortAndTruncate(  sections: ContextSection[],  maxTokens: number): ContextSection[] {  // 按 priority 分组  const systemSections = sections.filter(s => s.priority >= 70);  const historySections = sections.filter(s => s.priority < 70);  // 计算系统部分占用的 token 数  const systemTokens = estimateTokens(systemSections);  // 剩余空间留给历史  const historyBudget = maxTokens - systemTokens;  // 从最新的历史开始，倒序填充  const sortedHistory = [...historySections]    .sort((a, b) => b.timestamp - a.timestamp);  const selectedHistory: ContextSection[] = [];  let usedTokens = 0;  for (const section of sortedHistory) {    const sectionTokens = estimateTokens([section]);    if (usedTokens + sectionTokens > historyBudget) break;    selectedHistory.push(section);    usedTokens += sectionTokens;  }  // 按时间正序排列  selectedHistory.sort((a, b) => a.timestamp - b.timestamp);  return [...systemSections, ...selectedHistory];}function estimateTokens(sections: ContextSection[]): number {  // 粗略估算：1 token ≈ 4 个英文字符 或 2 个中文字符  const totalChars = sections.reduce(    (sum, s) => sum + String(s.content).length, 0  );  return Math.ceil(totalChars / 3); // 保守估算}

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";export default definePluginEntry({  id: "smart-context-engine",  name: "Smart Context Engine",  version: "1.0.0",  register(api) {    api.registerContextEngine("smart-context", (context) => {      const config = api.pluginConfig as {        codingHistoryWeight?: number;        chatHistoryWeight?: number;      };      return {        async buildContext(params) {          const sections: Array<{            role: string;            content: string;            priority: number;            timestamp?: number;            tokens: number;          }> = [];          // 系统提示（最高优先级，不可截断）          if (params.systemPrompt) {            sections.push({              role: "system",              content: params.systemPrompt,              priority: 100,              tokens: estimateTokens(params.systemPrompt),            });          }          // 记忆（根据相关性动态调整优先级）          if (params.memoryResults?.length) {            for (const memory of params.memoryResults) {              const relevanceBoost = Math.round(memory.score * 10);              sections.push({                role: "system",                content: `[Memory] ${memory.content}`,                priority: 70 + relevanceBoost,                tokens: estimateTokens(memory.content),              });            }          }          // 工具定义          if (params.toolDefinitions) {            const toolDefs = JSON.stringify(params.toolDefinitions);            sections.push({              role: "system",              content: toolDefs,              priority: 90,              tokens: estimateTokens(toolDefs),            });          }          // 对话历史          if (params.history) {            for (const msg of params.history) {              const isCoding = isCodingMessage(msg.content);              const weight = isCoding                ? (config.codingHistoryWeight ?? 1.5)                : (config.chatHistoryWeight ?? 1.0);              sections.push({                role: msg.role,                content: msg.content,                priority: 50,                timestamp: msg.timestamp,                tokens: Math.ceil(estimateTokens(msg.content) * weight),              });            }          }          // 智能截断          return smartTruncate(sections, params.maxTokens);        },      };    });  },});function isCodingMessage(content: string): boolean {  const codingIndicators = [    "```", "function", "class ", "import ", "const ", "async ",    "error:", "Exception", "TODO:", "FIXME:",  ];  return codingIndicators.some(ind => content.includes(ind));}function estimateTokens(text: string): number {  return Math.ceil(text.length / 3);}function smartTruncate(  sections: Array<{ role: string; content: string; priority: number; timestamp?: number; tokens: number }>,  maxTokens: number): Array<{ role: string; content: string }> {  const fixed = sections    .filter(s => s.priority >= 90)    .sort((a, b) => b.priority - a.priority);  const flexible = sections    .filter(s => s.priority < 90)    .sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0));  const fixedTokens = fixed.reduce((sum, s) => sum + s.tokens, 0);  const budget = maxTokens - fixedTokens;  const selected: typeof flexible = [];  let used = 0;  for (const section of flexible) {    if (used + section.tokens > budget) break;    selected.push(section);    used += section.tokens;  }  // 按时间正序  selected.sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0));  return [...fixed, ...selected].map(s => ({    role: s.role,    content: s.content,  }));}