插件架构中服务与事件监听的扩展实践

在上一篇关于插件机制的分析中，我们已经厘清了插件底座的加载与生命周期管理模型：插件框架负责实例化、依赖解析与启动过程，而每个插件通过统一的上下文对象挂载逻辑。整个机制可以归纳为两件事：框架负责插件加载与生命周期管理，插件通过 apply(ctx) 向共享上下文挂载逻辑。

掌握这些基础之后，真正进入插件开发时，会立刻遇到两个绕不开的工程问题：

1. 如果多个插件要复用同一段逻辑，该怎么写？ 难道每个插件都复制一份吗？
2. 如何在插件中注册钩子函数，以便在特定流程中执行额外逻辑？

这两个问题恰好对应插件体系中的两条扩展线：服务（Service）与事件监听（Event/Hook）。前者负责“提供能力”，后者负责“插入行为”。本文将对这两个概念做详细拆解。

一、为什么需要“服务”：从重复代码说起

用一句话概括服务：服务是挂载在上下文 ctx 上的具名能力，例如 ctx.myService。其他插件只需通过 inject: ['myService'] 声明所需服务，即可直接使用该能力，无需 import 提供方的代码。

1.1 重复逻辑的典型场景

假设我们写了两个工具：

• 工具 A 做“总结会话”；
• 工具 B 也做“总结会话”，只是参数略有不同。

按照常规的工具编写思路，很可能写出两份几乎一样的逻辑。哪天摘要规则要改，就得改两处——这是典型的逻辑耦合与维护负担。

1.2 服务化的基本思路

使用服务的基本思路是：把逻辑本身做成一个服务，工具只做薄壳。

• 服务实现 summarize(sessionId)；
• 工具 A 和工具 B 都只负责把模型传来的参数转发给 ctx.myService.summarize(...)；
• 逻辑只有一份，工具只是入口。

1.3 工具与服务的边界

官方在设计上也明确为服务和工具划清了边界：

• 工具给模型用，是“单次执行”的入口；
• 服务给同进程的插件和工具用，可以暴露任意方法。

在核心包中通常内置了若干核心服务，其他插件都可以利用这些服务提供的方法实现各种功能。这种设计让能力沉淀在服务层，而工具层只负责协议转换与参数适配。

二、编写一个最小化服务

理解设计理念后，从代码出发看如何编写一个服务。一个最小化的服务样板如下：

// my-service.js
module.exports = {
  name: 'myService',
  apply(ctx) {
    ctx.myService = {
      summarize(sessionId) {
        // 具体实现：读取会话、生成摘要、返回结果
        return `summary of ${sessionId}`;
      }
    };
  }
};

其他插件只需声明依赖即可使用：

// another-plugin.js
module.exports = {
  name: 'anotherPlugin',
  inject: ['myService'],
  apply(ctx) {
    ctx.on('some-event', async () => {
      const result = await ctx.myService.summarize('session-1');
      // 处理 result
    });
  }
};

这里有两个关键点：

1. 服务通过 apply(ctx) 挂载：与插件挂载逻辑的方式一致，服务本质上也是插件的一种形态，只是它挂载的是能力而非行为。
2. 依赖通过 inject 声明：框架会保证在 apply 执行前，被注入的服务已经就绪。这解决了插件之间的初始化顺序问题——不需要手动管理加载次序。

2.1 服务的设计原则

在实践中有几条值得遵循的原则：

• 单一职责：一个服务聚焦一类能力，避免变成“万能工具类”。
• 接口稳定：服务一旦被多个插件依赖，其方法签名应尽量保持稳定。
• 无状态优先：尽量把状态放在会话或上下文中，服务本身保持无状态，便于测试与复用。
• 错误可预期：服务方法应明确抛出可识别的错误类型，便于调用方处理。

三、事件监听：向流程中插入行为

如果说服务解决的是“能力复用”，那么事件监听解决的是“行为插入”。它允许插件在特定流程节点执行额外逻辑，而不需要修改流程本身的代码。

3.1 事件模型的基本用法

事件监听通常通过 ctx.on(eventName, handler) 注册：

module.exports = {
  name: 'my-listener',
  apply(ctx) {
    ctx.on('tool:before-call', async (payload) => {
      // 在工具调用前执行额外逻辑
      console.log('about to call tool:', payload.toolName);
    });
    ctx.on('tool:after-call', async (payload) => {
      // 在工具调用后执行额外逻辑
      console.log('tool call finished:', payload.result);
    });
  }
};

与服务的区别在于：

• 服务是“被调用”的：调用方主动发起；
• 事件是“被触发”的：由框架或某个流程节点在合适时机发出。

3.2 钩子的执行顺序与优先级

当多个插件监听同一事件时，执行顺序就成为关键问题。常见的处理方式包括：

• 注册顺序：按插件加载顺序依次执行；
• 优先级字段：允许在注册时指定优先级，数值越小越先执行；
• 串行与并行：部分事件适合串行（如参数修改），部分适合并行（如日志记录）。

一个带优先级的注册示例：

ctx.on('message:received', handler, { priority: 10 });

3.3 事件的典型应用场景

• 审计与日志：记录每次工具调用的入参与出参；
• 权限校验：在工具执行前检查调用方是否有权限；
• 结果后处理：对模型输出做格式化、脱敏或补充；
• 指标采集：统计调用次数、耗时、失败率；
• 动态干预：根据上下文条件决定是否短路某个流程。

四、服务与事件的协同：一个完整示例

下面通过一个综合示例，展示服务与事件如何协同工作。

// summarize-service.js
module.exports = {
  name: 'summarizeService',
  apply(ctx) {
    ctx.summarizeService = {
      async summarize(sessionId, options = {}) {
        const session = await ctx.sessionStore.get(sessionId);
        const text = session.messages.map(m => m.content).join('\n');
        return await ctx.modelClient.complete({
          prompt: `请总结以下内容：\n${text}`,
          maxTokens: options.maxTokens || 256
        });
      }
    };
  }
};

// summarize-tool.js
module.exports = {
  name: 'summarizeTool',
  inject: ['summarizeService'],
  apply(ctx) {
    ctx.registerTool({
      name: 'summarize',
      description: '总结指定会话',
      parameters: {
        sessionId: { type: 'string', required: true }
      },
      async execute(params) {
        return await ctx.summarizeService.summarize(params.sessionId);
      }
    });
  }
};

// audit-listener.js
module.exports = {
  name: 'auditListener',
  inject: ['summarizeService'],
  apply(ctx) {
    ctx.on('tool:before-call', async ({ toolName, params }) => {
      if (toolName === 'summarize') {
        console.log('summarize called with', params.sessionId);
      }
    });
    ctx.on('tool:after-call', async ({ toolName, result, error }) => {
      if (toolName === 'summarize') {
        console.log('summarize finished, error:', error);
      }
    });
  }
};

在这个示例中：

• summarizeService 提供核心能力；
• summarizeTool 作为薄壳，把模型参数转发给服务；
• auditListener 通过事件监听在调用前后插入审计逻辑。

三者解耦，各自独立演化。

五、常见陷阱与最佳实践

5.1 依赖循环

如果服务 A 注入服务 B，服务 B 又注入服务 A，就会形成循环依赖。解决办法是：

• 抽出公共逻辑到第三个服务；
• 或使用事件机制替代直接依赖。

5.2 事件顺序不确定

不要依赖未定义的执行顺序。如果逻辑有先后要求，应显式指定优先级，或合并到同一个监听器中。

5.3 服务方法过重

服务方法应保持轻量，避免在一次调用中做过多事情。重逻辑应拆分到更细粒度的服务中，由调用方组合。

5.4 忘记错误处理

事件监听器中的异常如果未被捕获，可能导致整个流程中断。建议在监听器内部做好 try/catch，并根据场景决定是否向上抛出。

六、小结

插件体系的两条扩展线各有分工：

• 服务：负责“提供能力”，解决逻辑复用问题，让工具只做薄壳；
• 事件监听：负责“插入行为”，让插件能在不修改流程代码的前提下参与执行。

掌握这两条线之后，插件开发就从“写一个个孤立的功能”升级为“构建一个可组合、可扩展的能力网络”。下一步，可以进一步探索服务的懒加载、事件的拦截与改写、以及跨插件的状态共享等进阶话题。