插件化与扩展点:引导 AI 模块化插拔开发,功能解耦便于迭代

AI 写代码很快，但也很容易出现一种典型问题：

每增加一个功能，就继续往核心代码里加 if/elif。

例如：

if domain == ”legal”:    ...elif domain == ”finance”:    ...elif domain == ”medical”:    ...

功能少时没有问题，但随着类型不断增加，核心模块会越来越臃肿，每次新增功能都可能影响已有逻辑。

更合理的做法是提前定义：

Plugin：插件
Extension Point：扩展点

让 AI 遵循一个原则：

新增能力优先增加模块，而不是修改核心流程。

📌 技术名片

Plugin Architecture：插件化架构
把容易变化的功能拆成独立模块，通过统一接口接入系统。核心系统依赖接口，而不是依赖某个具体实现。

其中：

Extension Point：扩展点
是系统提前预留的功能接入口。

例如：

核心系统不需要知道每个插件内部怎么实现，只需要知道：

它们都遵守同一套接口。

💡 一个简单比喻

插件化很像电脑的 USB 接口。

电脑不需要为了鼠标、键盘、U 盘分别设计不同的主机，只需要定义统一的 USB 接口。

软件架构也是一样：

核心系统定义“怎么接”，插件决定“接进来以后怎么做”。

一、为什么 AI 特别需要扩展点？

假设知识库现在支持：

generallegal

让 AI 增加一个金融领域，它最容易写成：

if domain == ”general”:    return process_general(document)elif domain == ”legal”:    return process_legal(document)elif domain == ”finance”:    return process_finance(document)

下一次增加医学领域，再继续增加一个分支。

最终：

Core Service    ↓大量 if / elif    ↓所有领域逻辑耦合在一起

更好的思路是：

Core ↓Plugin Interface ↓Registry ↓Concrete Plugin

这符合：

Open-Closed Principle：开闭原则

简单来说就是：

对扩展开放，对修改关闭。

新增功能尽量增加新的实现，而不是反复修改已经稳定的核心代码。

二、架构规范

1. Interface → Plugin → Registry

插件化可以归纳成三个核心角色。

先规定插件必须提供什么能力：

from abc import ABC, abstractmethodclass DomainPlugin(ABC):    @abstractmethod    def parse_metadata(self, raw: dict) -> dict:        pass

这里的：

ABC（Abstract Base Class，抽象基类）

相当于插件契约。

具体插件只需要实现它：

核心系统只依赖 DomainPlugin，而不依赖某个具体领域。

系统还需要知道：

某个领域应该使用哪个插件？

可以通过：

Registry Pattern：注册表模式

实现：

class PluginRegistry:    def __init__(self):        self._plugins = {}    def register(self, name, plugin):        self._plugins[name] = plugin    def get(self, name):        return self._plugins.get(name)

于是运行时只需要：

plugin = registry.get(domain)

而不需要：

if domain == ...

插件的创建最好也不要散落在业务代码中。

2. 进一步配置化：让系统动态加载插件

如果插件未来会频繁增加，可以把具体实现配置化。

例如配置中保存：

app.plugins.legal.LegalPlugin

系统通过：

module = importlib.import_module(module_path)plugin_cls = getattr(module, class_name)

动态加载。

这样核心系统不需要写：

from app.plugins.legal import LegalPluginfrom app.plugins.finance import FinancePluginfrom app.plugins.medical import MedicalPlugin

增加一个插件可以变成：

实现 Plugin    +增加配置    ↓系统自动加载

这就是：

Plug-and-Play：即插即用。

3. 什么功能适合设计成扩展点？

不是所有代码都需要插件化。

真正适合成为扩展点的，通常是：

稳定流程中存在多个实现，而且未来还会继续变化的部分。

Agent 系统中常见的扩展点包括：

Core Runtime    │    ├── Tool Plugin    ├── Domain Plugin    ├── Retriever    ├── Reranker    ├── LLM Provider    ├── Vector Store    └── Document Processor

其中：

Retriever：检索器
Reranker：重排序器
LLM（Large Language Model，大语言模型）Provider：模型提供方
Vector Store：向量存储

都可能存在多个实现。

一个很实用的判断方法是：

如果某个地方开始出现越来越多的 if type == "A"、elif type == "B"，就应该检查这里是不是缺少一个扩展点。

但对于简单且稳定的逻辑，没有必要强行设计 Plugin、Registry、Factory，否则就会变成：

Overengineering：过度设计。

三、插件化有什么好处？

最直接的变化是：

传统方式新增功能   ↓修改 Core   ↓重新验证核心流程

变成：

插件方式新增功能   ↓实现 Plugin   ↓Register

由此带来几个实际好处：

降低耦合：领域逻辑不会全部堆进核心 Service；
降低回归风险：新增插件较少影响已有插件；
方便测试：每个插件可以独立测试；
方便替换：实现可以按配置切换；
方便 AI 开发：AI 知道新功能应该放在哪里。

最后一点尤其重要。

没有扩展点时，AI 的开发方式很容易是：

找到旧代码 ↓插入新判断 ↓修改多个 Service

有扩展点之后则变成：

找到 Extension Point ↓实现 Plugin ↓Register

插件化实际上是在给 AI 划定：

功能增长的正确方向。

四、提示词落地：明确告诉 AI 如何扩展

可以把以下规则放进：

Project Rules：项目级规则

## 插件和扩展规则1. 优先使用扩展点，而不是向核心服务添加基于类型的 if/elif 分支。2. 核心模块必须依赖于抽象，而不是具体的插件实现。3. 可扩展功能应遵循以下流程：接口→ 插件实现→ 注册表→ 运行时查找4. 不要在业务服务内部实例化具体的插件。5. 插件的发现和注册应在应用程序启动期间进行。6. 特定领域的行为必须保留在插件内部，并且不得泄露到通用服务中。7. 当实现可以独立更改时，优先使用配置驱动的注册。8. 添加插件理想情况下应该只需要：- 插件实现- 注册/配置- 插件测试9. 当不太可能出现多个实现时，不要引入插件抽象。10. 在添加基于类型的 if/elif 分支之前，检查该位置是否应该是一个扩展点。

核心目的不是要求 AI：

“多写几个 Plugin 类。”

而是要求：

稳定能力留在 Core，可变化能力进入 Extension Point。

五、正面产出：miniagent的领域插件机制

miniagent的知识库系统中，就存在一个典型扩展点：

Domain Plugin：领域插件

不同领域可以拥有自己的：

文档元数据处理；
Small-to-Big 上下文扩展；
Citation（引用）合并规则；

而通用知识库流程不需要知道具体领域细节。

1. DomainPlugin 定义插件契约

miniagent定义了：

class DomainPlugin(ABC):    @property    @abstractmethod    def processor(self) -> SmallToBigProcessor:        ...    @abstractmethod    def parse_metadata(self, raw: dict) -> dict:        ...    @property    def citation_merger(self) -> CitationMerger:        return CitationMerger()

它定义了几个领域扩展点：

DomainPlugin     │     ├── processor     ├── parse_metadata()     └── citation_merger

新的领域只需要实现这份契约，而不需要把领域判断继续塞进通用流程。

2. DomainRegistry 统一管理插件

miniagent使用：

class DomainRegistry:    def __init__(self):        self._plugins: dict[str, DomainPlugin] = {}    def register(        self,        domain: str,        plugin: DomainPlugin    ) -> None:        self._plugins[domain] = plugin    def get(self, domain: str) -> DomainPlugin:        return self._plugins.get(domain)

运行时的关系因此变成：

domain  ↓DomainRegistry  ↓DomainPlugin

而不是越来越长的 if/elif。

3. 从数据库动态加载具体实现

更进一步，miniagent在 ServiceContainer 启动时读取领域配置：

domains = await self.domain_db.get_all_domains()

然后根据配置中的：

processor_classplugin_class

动态加载：

processor_cls = import_class(    domain_orm.processor_class)processor_instance = processor_cls()plugin_cls = import_class(    domain_orm.plugin_class)plugin_instance = plugin_cls(    processor=processor_instance)

最后注册：

self.domain_registry.register(    domain=domain_orm.name,    plugin=plugin_instance)

其中动态导入的核心实现是：

def import_class(class_path: str):    module_path, class_name = class_path.rsplit(”.”, 1)    module = importlib.import_module(module_path)    return getattr(module, class_name)

因此整个插件加载过程可以概括为：

Database Configuration        ↓processor_class / plugin_class        ↓Dynamic Import        ↓Create Plugin        ↓DomainRegistry.register()        ↓Runtime Lookup

下图详细的描述了miniagent的领域插件实现机制：

这里最重要的是两个阶段：

启动阶段发现 → 创建 → 注册插件运行阶段查询 → 使用插件

插件管理和业务执行因此被分离开来。

4. 新增一个领域时会发生什么？

假设未来miniagent增加金融领域。

理想路径是：

Finance Processor        ↓Finance DomainPlugin        ↓增加 Domain 配置        ↓系统启动自动加载        ↓DomainRegistry

而不是：

修改 Retrieval Service修改 Document Service增加 finance if/elif修改核心路由

这就是插件化真正希望达到的效果：

通过增加实现扩展系统，而不是通过修改核心流程扩展系统。

总结

AI 很擅长往已有代码中继续增加逻辑，但长期迭代的软件更需要：

Stable Core    ↓Extension Point    ↓Plugin

可以把插件化原则压缩成四句话：

稳定能力 → 留在 Core变化能力 → 放进 Plugin插件管理 → 交给 Registry具体实现 → 通过配置接入

miniagent的 DomainPlugin + DomainRegistry + 动态导入 + 数据库配置就体现了这套思路：接口定义扩展边界，Registry 管理具体实现，ServiceContainer 在启动阶段动态发现和注册插件。

对于 AI 编程，最值得写进项目规则的一句话是：

新增能力时先寻找扩展点；已有扩展点，就新增实现，不要修改核心流程。

这样 AI 才不是不断往系统里“堆代码”，而是在既有架构中插入一个：

可替换、可测试、可独立迭代的模块。

开源代码

github
gitee

#AI编程