上下文引擎

插件如何通过 contextEngine 槽位接管会话上下文编排，以及它仍需委托哪些内容。这是插件架构内部指南的一部分。

上下文引擎插件¶

上下文引擎插件负责会话上下文编排，包括摄取（ingest）、组装（assembly）和压缩（compaction）。在你的插件中通过 api.registerContextEngine(id, factory) 注册它们，然后使用 plugins.slots.contextEngine 选择活动引擎。

当你的插件需要替换或扩展默认上下文管道，而不仅仅是添加记忆搜索或钩子时，请使用此功能。

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: {
      id: "lossless-claw",
      name: "Lossless Claw",
      ownsCompaction: true,
      acceptedHostParams: ["sessionKey"],
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

工厂 ctx 暴露可选的 config、agentDir 和 workspaceDir 值，用于构造时初始化。

宿主会在调用非旧版引擎的 assemble() 之前完成已注册的异步记忆提示准备。buildMemorySystemPromptAddition(...) 保持同步，并在 assemble() 处于活动状态时读取该不可变运行快照。请原样传递所提供的工具和引文上下文，以便快照不会跨越运行边界。

assemble() 可以在活动运行环境（harness）拥有持久化后端线程时返回 contextProjection。对于旧版逐轮投影，请省略该字段。当组装后的上下文应一次性注入后端线程并一直复用至 epoch 改变时，返回 { mode: "thread_bootstrap", epoch }。在引擎的语义上下文发生变化后（例如在引擎自有的压缩流程之后）更改 epoch。宿主可以在线程引导投影中保留工具调用元数据、输入形状和经过脱敏的工具结果，从而让新的后端线程无需复制包含原始机密的有效负载即可保持工具连续性。

如果你的引擎不拥有压缩算法，请保持 compact() 已实现，并显式委托：

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw