系列：ToyAgent 智能体知识库 23/26

插件机制：让能力即插即拔

一句话核心：插件是一批工具的动态载体——安装即批量注册进工具注册表，卸载即批量注销；第三方作者只需实现一个契约接口，宿主加载后模型立刻"看见"新工具，全程不需要重新编译宿主。

为什么需要

工具注册表解决了"工具怎么注册、怎么被发现"，但它默认一个前提：工具代码和宿主在同一个工程里，编译期就绑死了。这在真实生态里站不住：

迭代摩擦：每加一个能力都要重新编译、重新部署整个宿主，能力供给方（可能是另一个团队或第三方开发者）被宿主的发布节奏绑架；
无法热插拔：一个插件出问题想临时下线，只能整体回滚；
生态封闭：外部作者无法在不碰宿主源码的前提下贡献能力。

插件机制把"能力"变成运行时可安装、可卸载的包。一句话理解：插件 = 工具的 JAR 包。整个插件生态——安装、激活、运行、管理、查询五条流水线，外加 maven archetype 脚手架一键生成骨架——都建立在这句话上。

核心机制

以一个 Java 宿主的四层设计为例，每层职责单一：

层次	组件	职责
契约	`AgentPlugin` 接口 + 插件清单	onStart/onStop/tools()；清单文件声明入口类
加载	`PluginLoader`	独立 URLClassLoader 隔离加载，entrypoint 优先、SPI 兜底
生命周期	热重载器 / 运行时管理器	安装 → 激活 → 运行 → 卸载，支持热插拔
桥接	工具桥接服务	插件工具批量注册进 ToolRegistry，disposer 按 pluginId 归档

作者视角要写的东西只有一个契约接口：

// 1. 契约：插件作者唯一要实现的东西
public interface AgentPlugin {
    String id();
    String version();
    default void onStart() {}
    default void onStop() {}
    List<ToolDefinition> tools();   // 插件带来的全部工具
}

宿主侧的加载与桥接骨架：

// 2. 隔离加载：parent 指向宿主 ClassLoader，插件类只从 plugins/ 目录来
URLClassLoader cl = new URLClassLoader(
    new URL[]{ pluginDir.toUri().toURL() },
    PluginHost.class.getClassLoader());

AgentPlugin plugin = (AgentPlugin) Class
    .forName(manifest.entrypoint(), true, cl)   // 优先读清单里的入口
    .getDeclaredConstructor().newInstance();
plugin.onStart();

// 3. 工具桥接：逐个注册，返回的 disposer 按 pluginId 归档
List<AutoCloseable> disposers = new ArrayList<>();
for (ToolDefinition tool : plugin.tools()) {
    disposers.add(toolRegistry.register(tool));
}

// 4. 卸载三步回收：批量执行 disposer → plugin.onStop() → cl.close()

三个设计点值得展开：

为什么必须独立 ClassLoader？ 不只是安全隔离，更是卸载的前提：JVM 的类一旦被系统类加载器加载就无法卸载；只有插件专属的 URLClassLoader close 掉、其加载的类失去引用，整包类才能被 GC 回收，热卸载才可能实现。parent 委派给宿主则保证插件能用宿主的契约接口和公共库。
桥接层为什么要有 disposer 归档？ 注册表只认识"工具"，不认识"插件"。桥接服务把每个工具注册时拿到的注销句柄按 pluginId 打包存档，卸载时一次遍历全部回收——这就是"批量注销"的实现，避免逐个工具对账。
进程内 vs 进程外：进程内加载性能好但故障域共享（插件崩可能拖垮宿主）；进程外模式（如 JSON-RPC 桥接）让插件跑在独立进程，宿主通过协议调用，隔离更强、语言不限。成熟的插件体系通常双模式并存。

stateDiagram-v2
    [*] --> INSTALLED: 释放插件包落盘
    INSTALLED --> ACTIVE: 隔离 ClassLoader 实例化并 onStart
    ACTIVE --> REGISTERED: 桥接批量注册工具并归档 disposer
    REGISTERED --> ACTIVE: 模型每轮动态看见插件工具
    REGISTERED --> UNLOADING: 用户发起卸载
    UNLOADING --> [*]: 执行 disposer 后 onStop 再 cl.close

插件生命周期状态机：安装 → 激活 → 注册生效 → 卸载三步回收（批量注销工具、释放插件资源、关闭类加载器），全程不重启宿主。

举例：一次完整的安装-使用-卸载轨迹

宿主已启动，注册表里有 time_now、calc 两个内置工具：

[1] 用户：安装插件
  ① 释放插件包 dice-plugin/（含清单 + 入口类）落盘
  ② new URLClassLoader 指向该目录，反射实例化 DicePlugin
  ③ plugin.onStart() → 插件自检通过
  ④ 桥接服务收集 plugin.tools() = [roll_dice, uptime]
     逐个注册进 ToolRegistry，disposer 按 "dice-plugin" 归档
  轨迹：工具清单从 2 个变为 4 个

[2] 用户：掷一次硬币
  模型本轮重新拿到工具清单，看见 roll_dice → 发起调用 → 返回"正面"
  （宿主代码零改动，模型"自动看见"新能力——因为工具清单本来就是
   每轮从注册表动态生成的）

[3] 用户：宿主运行多久了
  模型调用 uptime → 返回进程存活时长

[4] 用户：卸载插件
  ① 桥接服务按 "dice-plugin" 批量执行 disposer → roll_dice/uptime 注销
  ② plugin.onStop() → 插件释放自身资源
  ③ cl.close() → 插件类加载器关闭，类可被 GC

[5] 用户：再掷一次硬币
  工具清单已回到 2 个，模型不认识 roll_dice；
  若模型凭记忆硬要调用 → 注册表未命中 → 返回"工具不存在"

第 5 步是个有趣的边界情况：模型上一轮还"记得"这个工具（对话历史里有调用痕迹），但注册表已经没有它了。健壮的宿主要能优雅处理这种注册表未命中——返回明确的错误信息让模型改道，而不是抛异常断流。这也提示插件卸载最好同时清理对话中残留的工具引用或至少在系统提示词里告知能力下线。

与工具注册表的分工可以用一张表收束：

维度	工具注册表	插件机制
回答的问题	工具怎么注册、怎么被发现	工具从哪来、怎么装进来、怎么卸掉
生命周期粒度	单个工具（注册/注销）	整包（安装/卸载，批量生效）
类加载	宿主同一 ClassLoader	独立 ClassLoader 隔离，卸载即关闭

教学版 vs 生产版

维度	教学版	生产版
插件包形态	解压的目录 + 清单文件	真 JAR，maven archetype 一键生成骨架
身份声明	清单 entrypoint 字段	MANIFEST + plugin.yaml，含版本/依赖/兼容宿主区间
信任	无校验，直接加载	签名验证 + 来源白名单 + 版本冲突校验
桥接	进程内批量注册	进程内 / JSON-RPC 进程外双模式
隔离	独立 ClassLoader	叠加独立进程/容器、资源限额、权限声明

面试考点

"插件机制和工具注册表是什么关系？"——注册表解决"怎么注册/发现"，插件解决"从哪来/怎么装卸"；插件是工具的批量载体，通过桥接层把整包工具注入注册表，disposer 按 pluginId 归档实现批量注销。
"Java 里插件热卸载为什么必须用独立 ClassLoader？"——系统类加载器加载的类不可卸载；插件专属 URLClassLoader close 后其类失去引用才能被 GC，这是热卸载的 JVM 层前提。
"进程内插件和进程外插件怎么选？"——进程内低延迟但共享故障域，进程外（JSON-RPC 桥）隔离强、可跨语言，代价是序列化开销与部署复杂度；按插件可信度与性能要求双模式并存。

生产化路径

插件包升级为真 JAR，配套 maven archetype 脚手架，让第三方作者十分钟出一个可安装的插件工程；
加信任链：JAR 签名验证、发布者白名单、版本与依赖冲突预检，拒绝加载不满足宿主兼容区间的包；
双模式桥接：可信高性能插件走进程内，不可信或重型插件走 JSON-RPC 进程外，配资源限额与心跳；
生命周期治理：安装/卸载全事件化（可与事件溯源篇打通），支持禁用、灰度、按租户启用；
卸载时的对话一致性：清理注册表的同时在系统提示词/工具清单层同步能力下线，优雅处理模型对已卸载工具的残留调用。