refactor(plugin): split built-in and user plugin roots (#444)

* refactor(plugin): split built-in and user plugin roots

Treat plugin.plugins as built-in packaged plugins and move user plugin discovery to the ConfigManager documents plugins directory. This avoids packaged namespace collisions while keeping plugin loading, config resolution, and extension injection working across both roots.

Made-with: Cursor

* fix(plugin): preserve legacy root semantics and skip builtin sys.path injection

Avoid re-exposing built-in plugins through top-level import roots in packaged builds, and restore the old single-root compatibility behavior for legacy callers while steering new code toward explicit multi-root settings.

Made-with: Cursor

Author: wehos

plugin/config/service.py

@@ -19,7 +19,7 @@
 
 from fastapi import HTTPException
 
-from plugin.settings import PLUGIN_CONFIG_ROOT
+from plugin.settings import PLUGIN_CONFIG_ROOTS
 
 # Schema 验证开关（可通过环境变量禁用）
 _SCHEMA_VALIDATION_ENABLED = os.getenv("NEKO_CONFIG_SCHEMA_VALIDATION", "true").lower() in ("true", "1", "yes", "on")
@@ -147,44 +147,33 @@ def get_plugin_config_path(plugin_id: str) -> Path:
             detail=f"Invalid plugin_id: '{plugin_id}'. Only alphanumeric characters, underscores, and hyphens are allowed."
         )
 
-    # 构建配置文件路径
-    config_file = PLUGIN_CONFIG_ROOT / plugin_id / "plugin.toml"
-    
-    # 解析路径并验证它在安全目录内(防止路径遍历攻击)
-    try:
-        resolved_path = config_file.resolve()
-        # Python 3.9+ 支持 is_relative_to
-        if hasattr(resolved_path, 'is_relative_to'):
-            if not resolved_path.is_relative_to(PLUGIN_CONFIG_ROOT.resolve()):
-                raise HTTPException(
-                    status_code=400,
-                    detail=f"Invalid plugin_id: '{plugin_id}'. Path traversal detected."
-                )
-        else:
-            # Python 3.8 兼容:使用 str.startswith 检查
-            root_resolved = PLUGIN_CONFIG_ROOT.resolve()
-            resolved_str = str(resolved_path)
-            root_str = str(root_resolved)
-            if not resolved_str.startswith(root_str):
-                raise HTTPException(
-                    status_code=400,
-                    detail=f"Invalid plugin_id: '{plugin_id}'. Path traversal detected."
-                )
-    except (OSError, ValueError) as e:
-        # 路径解析失败(例如包含无效字符)
-        raise HTTPException(
-            status_code=400,
-            detail=f"Invalid plugin_id: '{plugin_id}'. {str(e)}"
-        ) from e
-    
-    # 检查文件是否存在
-    if not config_file.exists():
-        raise HTTPException(
-            status_code=404,
-            detail=f"Plugin '{plugin_id}' configuration not found"
-        )
-    
-    return config_file
+    for root in PLUGIN_CONFIG_ROOTS:
+        config_file = root / plugin_id / "plugin.toml"
+
+        try:
+            resolved_path = config_file.resolve()
+            if hasattr(resolved_path, 'is_relative_to'):
+                if not resolved_path.is_relative_to(root.resolve()):
+                    continue
+            else:
+                root_resolved = root.resolve()
+                resolved_str = str(resolved_path)
+                root_str = str(root_resolved)
+                if not resolved_str.startswith(root_str):
+                    continue
+        except (OSError, ValueError) as e:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid plugin_id: '{plugin_id}'. {str(e)}"
+            ) from e
+
+        if config_file.exists():
+            return config_file
+
+    raise HTTPException(
+        status_code=404,
+        detail=f"Plugin '{plugin_id}' configuration not found"
+    )
 
 
 def load_plugin_config(plugin_id: str, *, validate: bool = True) -> Dict[str, Any]:

plugin/core/host.py

@@ -110,100 +110,106 @@ def _inject_extensions(
             logger.debug("[Extension] tomllib/tomli not available, skipping extension injection")
             return
 
-    # 优先使用 settings 中的 PLUGIN_CONFIG_ROOT，回退到路径推导
+    # 优先使用 settings 中的插件根目录集合，回退到路径推导
     try:
-        from plugin.settings import PLUGIN_CONFIG_ROOT
-        plugin_config_root = PLUGIN_CONFIG_ROOT
+        from plugin.settings import PLUGIN_CONFIG_ROOTS
+        plugin_config_roots = tuple(PLUGIN_CONFIG_ROOTS)
     except Exception:
-        plugin_config_root = host_config_path.parent.parent
-
-    try:
-        if not plugin_config_root.exists():
-            return
-    except Exception:
-        return
+        plugin_config_roots = (host_config_path.parent.parent,)
 
     injected_count = 0
-    for toml_path in plugin_config_root.glob("*/plugin.toml"):
+    for plugin_config_root in plugin_config_roots:
         try:
-            with toml_path.open("rb") as f:
-                conf = tomllib.load(f)
-            pdata = conf.get("plugin") or {}
+            root = plugin_config_root.resolve()
+        except Exception:
+            root = plugin_config_root
 
-            # 只处理 type=extension
-            if pdata.get("type") != "extension":
+        try:
+            if not root.exists():
                 continue
+        except Exception:
+            continue
 
-            # 检查宿主匹配
-            host_conf = pdata.get("host")
-            if not isinstance(host_conf, dict):
-                continue
-            if host_conf.get("plugin_id") != host_plugin_id:
-                continue
+        for toml_path in root.glob("*/plugin.toml"):
+            try:
+                with toml_path.open("rb") as f:
+                    conf = tomllib.load(f)
+                pdata = conf.get("plugin") or {}
 
-            # 检查 enabled
-            runtime_cfg = conf.get("plugin_runtime")
-            if isinstance(runtime_cfg, dict):
-                from plugin.utils import parse_bool_config
-                if not parse_bool_config(runtime_cfg.get("enabled"), default=True):
-                    logger.debug(
-                        "[Extension] Extension '{}' is disabled, skipping",
-                        pdata.get("id", "?"),
-                    )
+                # 只处理 type=extension
+                if pdata.get("type") != "extension":
                     continue
 
-            ext_id = pdata.get("id", "unknown")
-            ext_entry = pdata.get("entry")
-            if not ext_entry or ":" not in ext_entry:
-                logger.warning(
-                    "[Extension] Extension '{}' has invalid entry '{}', skipping",
-                    ext_id, ext_entry,
-                )
-                continue
+                # 检查宿主匹配
+                host_conf = pdata.get("host")
+                if not isinstance(host_conf, dict):
+                    continue
+                if host_conf.get("plugin_id") != host_plugin_id:
+                    continue
 
-            # 导入 Extension Router 类
-            module_path, class_name = ext_entry.split(":", 1)
-            try:
-                mod = importlib.import_module(module_path)
-                router_cls = getattr(mod, class_name)
-            except (ImportError, ModuleNotFoundError) as e:
-                logger.warning(
-                    "[Extension] Failed to import extension '{}' ({}): {}",
-                    ext_id, ext_entry, e,
-                )
-                continue
-            except AttributeError as e:
-                logger.warning(
-                    "[Extension] Class '{}' not found in module '{}' for extension '{}': {}",
-                    class_name, module_path, ext_id, e,
-                )
-                continue
+                # 检查 enabled
+                runtime_cfg = conf.get("plugin_runtime")
+                if isinstance(runtime_cfg, dict):
+                    from plugin.utils import parse_bool_config
+                    if not parse_bool_config(runtime_cfg.get("enabled"), default=True):
+                        logger.debug(
+                            "[Extension] Extension '{}' is disabled, skipping",
+                            pdata.get("id", "?"),
+                        )
+                        continue
+
+                ext_id = pdata.get("id", "unknown")
+                ext_entry = pdata.get("entry")
+                if not ext_entry or ":" not in ext_entry:
+                    logger.warning(
+                        "[Extension] Extension '{}' has invalid entry '{}', skipping",
+                        ext_id, ext_entry,
+                    )
+                    continue
 
-            # 验证是 PluginRouter 子类
-            if not (isinstance(router_cls, type) and issubclass(router_cls, PluginRouter)):
-                logger.warning(
-                    "[Extension] Extension '{}' entry class '{}' is not a PluginRouter subclass, skipping",
-                    ext_id, class_name,
-                )
-                continue
+                # 导入 Extension Router 类
+                module_path, class_name = ext_entry.split(":", 1)
+                try:
+                    mod = importlib.import_module(module_path)
+                    router_cls = getattr(mod, class_name)
+                except (ImportError, ModuleNotFoundError) as e:
+                    logger.warning(
+                        "[Extension] Failed to import extension '{}' ({}): {}",
+                        ext_id, ext_entry, e,
+                    )
+                    continue
+                except AttributeError as e:
+                    logger.warning(
+                        "[Extension] Class '{}' not found in module '{}' for extension '{}': {}",
+                        class_name, module_path, ext_id, e,
+                    )
+                    continue
 
-            # 实例化并注入
-            prefix = host_conf.get("prefix", "")
-            try:
-                router_instance = router_cls(prefix=prefix, name=ext_id)
-                instance.include_router(router_instance)
-                injected_count += 1
-                logger.info(
-                    "[Extension] Injected extension '{}' into host '{}' with prefix '{}'",
-                    ext_id, host_plugin_id, prefix,
-                )
+                # 验证是 PluginRouter 子类
+                if not (isinstance(router_cls, type) and issubclass(router_cls, PluginRouter)):
+                    logger.warning(
+                        "[Extension] Extension '{}' entry class '{}' is not a PluginRouter subclass, skipping",
+                        ext_id, class_name,
+                    )
+                    continue
+
+                # 实例化并注入
+                prefix = host_conf.get("prefix", "")
+                try:
+                    router_instance = router_cls(prefix=prefix, name=ext_id)
+                    instance.include_router(router_instance)
+                    injected_count += 1
+                    logger.info(
+                        "[Extension] Injected extension '{}' into host '{}' with prefix '{}'",
+                        ext_id, host_plugin_id, prefix,
+                    )
+                except Exception as e:
+                    logger.warning(
+                        "[Extension] Failed to inject extension '{}' into host '{}': {}",
+                        ext_id, host_plugin_id, e,
+                    )
             except Exception as e:
-                logger.warning(
-                    "[Extension] Failed to inject extension '{}' into host '{}': {}",
-                    ext_id, host_plugin_id, e,
-                )
-        except Exception as e:
-            logger.debug("[Extension] Error processing {}: {}", toml_path, e)
+                logger.debug("[Extension] Error processing {}: {}", toml_path, e)
 
     if injected_count > 0:
         logger.info(