pkgutil.iter_modules() 默认不递归扫描子包，仅返回顶层模块名；需手动递归调用或改用 importlib.util.find_spec()、pathlib.Path.rglob() 等更可靠方式，并确保子包含 __init__.py。
pkgutil.iter_modules() 为什么找不到子包？
默认情况下 pkgutil.iter_modules() 只扫描指定路径下的**顶层模块**，不会递归进入子目录，更不会自动识别子包（即含 __init__.py 的目录）。如果你的插件放在 plugins/validator/、plugins/exporter/ 这类嵌套结构里，直接传入 plugins 路径，它只会返回 validator 和 exporter 这两个名字，但不会加载它们内部的模块——除非你手动递归调用。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 先用
pkgutil.iter_modules([path])获取一级子包名，再对每个子包路径调用pkgutil.iter_modules([subpath])； - 更稳妥的做法是改用
importlib.util.find_spec(name)或直接遍历pathlib.Path(path).rglob("*.py")，避开 pkgutil 对包结构的强依赖； - 确保每个插件目录下都有
__init__.py（哪怕为空），否则iter_modules()会跳过该目录。
如何安全导入插件模块而不污染全局命名空间？
直接用 __import__() 或 importlib.import_module() 可能触发副作用（比如执行模块顶层代码、初始化单例、连接数据库），而你可能只想检查接口或提取元数据。这时候应避免“运行式导入”。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
importlib.util.spec_from_file_location(name, filepath)+spec.loader.exec_module(module)控制导入时机； - 若只需读取插件声明（如
__plugin_name__、supports_format = ["json", "yaml"]），可用ast.parse()静态解析源码，完全绕过执行； - 为防插件崩溃主程序，建议在独立
importlib.util.module_from_spec()实例中加载，并用try/except ImportError包裹，不要复用sys.modules中已存在的同名模块。
插件注册时怎么避免重复加载或版本冲突？
pkgutil 本身不管理生命周期，同一插件被多次 iter_modules() 扫描 + 多次 import_module() 就会重复注册，尤其在热重载或配置变更后。
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 维护一个全局插件 registry 字典，键为插件唯一标识（推荐用
f"{package_name}.{module_name}"，而非仅模块名）； - 加载前先查
sys.modules是否已存在该模块，若存在且hasattr(module, "__plugin_version__")，可对比版本号决定是否 reload； - 禁止插件使用相对导入（如
from .utils import helper），因为动态加载时__package__可能为空，导致SystemError: Parent module '' not loaded。
为什么 reload() 后插件行为没变化？
Python 的 importlib.reload() 只重执行模块代码，但不会自动更新已注册的函数引用、类实例、或缓存的配置对象。比如插件定义了 class Exporter: 并在模块顶层做了 register(Exporter)，reload 后旧实例仍留在 registry 里。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 插件模块应导出纯函数或工厂函数（如
create_exporter()），而非直接注册实例； - registry 存储的是模块对象或可调用对象，不在模块顶层执行注册逻辑；
- 真正需要热重载时，先从 registry 中移除旧条目，再 reload 模块，最后重新调用其注册函数——别指望 reload 自动修复一切。
插件系统真正的复杂点不在发现和导入，而在模块边界、状态隔离与生命周期同步。pkgutil 只是入口，后面每一步都得自己兜底。
