「Regnexe 实战系列」第 5 篇共 10 篇对应仓库ExampleReadme05PluginPackagingTest。上一篇04. Plugin 注解打包一切。一个真实的团队矛盾做平台型项目的同学应该都遇到过这种争论“工具应该写死在代码里编译期就能查出问题。”“不对运维要能随时加减插件不能每次都重新编译发版。”这两种诉求都对只是适用场景不一样。Regnexe 这套 harness 没有强行二选一而是把插件怎么打包和插件怎么加载拆成了独立的维度四种方式并存按场景挑。方式一代码直打包——PluginDescriptor才是底层真相前几篇用的withTool/withSkill/withSubAgent/Plugin最终都会落到同一个东西上一个装着若干CapabilityDescriptor的PluginDescriptor。如果你想完全手动控制PluginDescriptor.builder()直接开放了这条路PluginDescriptortripPluginPluginDescriptor.builder().pluginId(trip-plugin).version(1.0).name(Trip Plugin).description(Bundles a tool, a skill, and a sub-agent for trip planning).tool(weatherTool)// - trip-plugin.get_weather.skillConfig(travelAdvisor)// - trip-plugin.travel_advisor.subAgentConfig(expenseEstimator)// - trip-plugin.expense_estimator.build();regnexeAgentBuilder.withPlugin(tripPlugin)...一个PluginDescriptor三种能力类型id 自动按pluginId . name拼好不用再一个个手写CapabilityDescriptor。这是最硬核的方式——适合能力定义来自数据库、配置中心需要在运行时动态拼装的场景。⚠️ 踩坑提醒三种能力共用一个pluginId时Skill 的allowedTools必须写完整能力 id——这里是trip-plugin.get_weather不是裸的get_weather。这个坑在上一篇也提过因为太容易踩这里再敲一次警钟。方式二包扫描——让插件自己长出来如果插件类已经按Plugin/AgentSkill/AgentSubAgent写好了根本不需要一个个new出来注册直接扫包regnexeAgentBuilder.withScanPackages(com.example.plugins)...DefaultPluginManager会在指定包下找出所有带这三种注解的类自动实例化、自动注册。适合插件数量较多、希望加一个类就自动生效的场景——前提是类得有 public 无参构造器。方式三文件系统目录——运维真正想要的那种回到开头那个争论运维要的不重新发版就能加减插件Regnexe 用纯文件目录解决/opt/regnexe-plugins/ weather-plugin/ plugin.yaml ← 元数据 tools/ get_weather.sh ← 脚本工具 get_weather.yaml ← 配套说明 skills/ advisor/SKILL.md ← Skill subagents/ planner/AGENT.md ← Sub-AgentregnexeAgentBuilder.withDirectory(/opt/regnexe-plugins)...加一个插件文件夹、删一个插件文件夹应用都不用重启重新发布——这是纯代码方案永远做不到的灵活度。实测验证三种方式都能跑通仓库里的测试不是只讲道理每种方式都有真实验证。比如包扫描DefaultPluginManagermgrnewDefaultPluginManager();mgr.scanPackages(org.salt.regnexe.agent.core.example.testplugins);SimpleMarketplacemarketplacenewSimpleMarketplace();marketplace.load(mgr);CapabilityDescriptorcapmarketplace.resolveDescriptor(test-weather-plugin.get_weather);Assert.assertNotNull(cap);// 扫描成功能力已注册文件系统目录加载也是同理——临时建一个目录、写好plugin.yaml和脚本文件addDirectory(...)之后直接能resolveDescriptor拿到对应能力整个流程全自动。四种方式怎么选方式适合场景withTool/withSkill/withSubAgent临时脚本、PoC、动态生成的简单能力Plugin 嵌套注解业务模块固定、需要打包管理和版本控制PluginDescriptor.builder()能力定义来自 DB/配置中心运行时动态拼装包扫描withScanPackages插件类已写好希望自动发现注册文件系统目录withDirectory运维要随时增删插件不接受重新发版它们不是互斥关系一个应用里完全可以同时用——核心业务工具用Plugin写死运营临时配置的能力走目录加载。 上一篇04. Plugin 注解打包一切 下一篇06. Marketplace 换成数据库只需要实现一个接口 项目地址https://github.com/flower-trees/regnexe-agent
插件加载方式选不对，团队迟早要吵起来：代码 / 注解 / 包扫描 / 目录怎么选
「Regnexe 实战系列」第 5 篇共 10 篇对应仓库ExampleReadme05PluginPackagingTest。上一篇04. Plugin 注解打包一切。一个真实的团队矛盾做平台型项目的同学应该都遇到过这种争论“工具应该写死在代码里编译期就能查出问题。”“不对运维要能随时加减插件不能每次都重新编译发版。”这两种诉求都对只是适用场景不一样。Regnexe 这套 harness 没有强行二选一而是把插件怎么打包和插件怎么加载拆成了独立的维度四种方式并存按场景挑。方式一代码直打包——PluginDescriptor才是底层真相前几篇用的withTool/withSkill/withSubAgent/Plugin最终都会落到同一个东西上一个装着若干CapabilityDescriptor的PluginDescriptor。如果你想完全手动控制PluginDescriptor.builder()直接开放了这条路PluginDescriptortripPluginPluginDescriptor.builder().pluginId(trip-plugin).version(1.0).name(Trip Plugin).description(Bundles a tool, a skill, and a sub-agent for trip planning).tool(weatherTool)// - trip-plugin.get_weather.skillConfig(travelAdvisor)// - trip-plugin.travel_advisor.subAgentConfig(expenseEstimator)// - trip-plugin.expense_estimator.build();regnexeAgentBuilder.withPlugin(tripPlugin)...一个PluginDescriptor三种能力类型id 自动按pluginId . name拼好不用再一个个手写CapabilityDescriptor。这是最硬核的方式——适合能力定义来自数据库、配置中心需要在运行时动态拼装的场景。⚠️ 踩坑提醒三种能力共用一个pluginId时Skill 的allowedTools必须写完整能力 id——这里是trip-plugin.get_weather不是裸的get_weather。这个坑在上一篇也提过因为太容易踩这里再敲一次警钟。方式二包扫描——让插件自己长出来如果插件类已经按Plugin/AgentSkill/AgentSubAgent写好了根本不需要一个个new出来注册直接扫包regnexeAgentBuilder.withScanPackages(com.example.plugins)...DefaultPluginManager会在指定包下找出所有带这三种注解的类自动实例化、自动注册。适合插件数量较多、希望加一个类就自动生效的场景——前提是类得有 public 无参构造器。方式三文件系统目录——运维真正想要的那种回到开头那个争论运维要的不重新发版就能加减插件Regnexe 用纯文件目录解决/opt/regnexe-plugins/ weather-plugin/ plugin.yaml ← 元数据 tools/ get_weather.sh ← 脚本工具 get_weather.yaml ← 配套说明 skills/ advisor/SKILL.md ← Skill subagents/ planner/AGENT.md ← Sub-AgentregnexeAgentBuilder.withDirectory(/opt/regnexe-plugins)...加一个插件文件夹、删一个插件文件夹应用都不用重启重新发布——这是纯代码方案永远做不到的灵活度。实测验证三种方式都能跑通仓库里的测试不是只讲道理每种方式都有真实验证。比如包扫描DefaultPluginManagermgrnewDefaultPluginManager();mgr.scanPackages(org.salt.regnexe.agent.core.example.testplugins);SimpleMarketplacemarketplacenewSimpleMarketplace();marketplace.load(mgr);CapabilityDescriptorcapmarketplace.resolveDescriptor(test-weather-plugin.get_weather);Assert.assertNotNull(cap);// 扫描成功能力已注册文件系统目录加载也是同理——临时建一个目录、写好plugin.yaml和脚本文件addDirectory(...)之后直接能resolveDescriptor拿到对应能力整个流程全自动。四种方式怎么选方式适合场景withTool/withSkill/withSubAgent临时脚本、PoC、动态生成的简单能力Plugin 嵌套注解业务模块固定、需要打包管理和版本控制PluginDescriptor.builder()能力定义来自 DB/配置中心运行时动态拼装包扫描withScanPackages插件类已写好希望自动发现注册文件系统目录withDirectory运维要随时增删插件不接受重新发版它们不是互斥关系一个应用里完全可以同时用——核心业务工具用Plugin写死运营临时配置的能力走目录加载。 上一篇04. Plugin 注解打包一切 下一篇06. Marketplace 换成数据库只需要实现一个接口 项目地址https://github.com/flower-trees/regnexe-agent
