给依靠插件id命名逃避可能的插件冲突

Author: whatevertogo

astrbot-sdk/src/astrbot_sdk/_internal/plugin_ids.py

@@ -48,6 +48,26 @@ def validate_plugin_id(plugin_id: str) -> str:
     return normalized
 
 
+def plugin_capability_prefix(plugin_id: str) -> str:
+    return f"{validate_plugin_id(plugin_id)}."
+
+
+def capability_belongs_to_plugin(capability_name: str, plugin_id: str) -> bool:
+    return str(capability_name).strip().startswith(plugin_capability_prefix(plugin_id))
+
+
+def plugin_http_route_root(plugin_id: str) -> str:
+    return f"/{validate_plugin_id(plugin_id)}"
+
+
+def http_route_belongs_to_plugin(route: str, plugin_id: str) -> bool:
+    normalized_route = str(route).strip()
+    route_root = plugin_http_route_root(plugin_id)
+    return normalized_route == route_root or normalized_route.startswith(
+        f"{route_root}/"
+    )
+
+
 def resolve_plugin_data_dir(root: Path, plugin_id: str) -> Path:
     normalized = validate_plugin_id(plugin_id)
     resolved_root = root.resolve()

astrbot-sdk/src/astrbot_sdk/clients/http.py

@@ -19,7 +19,7 @@
     # 插件声明处理 HTTP 请求的 capability
     @provide_capability(
         name="my_plugin.http_handler",
-        description="处理 /my-api 的 HTTP 请求",
+        description="处理 /my_plugin/api 的 HTTP 请求",
         input_schema={...},
         output_schema={...}
     )
@@ -28,7 +28,7 @@ async def handle_http_request(request_id: str, payload: dict, cancel_token):
 
     # 注册路由 → capability 映射
     await ctx.http.register_api(
-        route="/my-api",
+        route="/my_plugin/api",
         methods=["GET", "POST"],
         handler_capability="my_plugin.http_handler",
         description="我的 API"
@@ -99,15 +99,15 @@ async def register_api(
         """注册 Web API 端点。
 
         Args:
-            route: API 路由路径（如 "/my-api"）
+            route: API 路由路径（必须使用 "/{plugin_id}" 或 "/{plugin_id}/..."）
             handler_capability: 处理此路由的 capability 名称
             handler: 使用 @provide_capability 标记的方法引用
             methods: HTTP 方法列表，默认 ["GET"]
             description: API 描述
 
         示例:
             await ctx.http.register_api(
-                route="/my-api",
+                route="/my_plugin/api",
                 handler_capability="my_plugin.http_handler",
                 methods=["GET", "POST"],
                 description="我的 API"
@@ -137,7 +137,7 @@ async def unregister_api(
             methods: HTTP 方法列表，None 表示所有方法
 
         示例:
-            await ctx.http.unregister_api("/my-api")
+            await ctx.http.unregister_api("/my_plugin/api")
         """
         if methods is None:
             methods = []

astrbot-sdk/src/astrbot_sdk/decorators.py

@@ -1079,7 +1079,7 @@ def provide_capability(
     支持使用 JSON Schema 或 pydantic 模型定义输入输出。
 
     Args:
-        name: capability 名称（不能使用保留命名空间）
+        name: capability 名称（不能使用保留命名空间，且运行时必须以当前 plugin_id 为前缀）
         description: 能力描述
         input_schema: 输入 JSON Schema
         output_schema: 输出 JSON Schema

astrbot-sdk/src/astrbot_sdk/runtime/_capability_router_builtins/capabilities/http.py

@@ -3,6 +3,12 @@
 import re
 from typing import Any
 
+from ...._internal.plugin_ids import (
+    capability_belongs_to_plugin,
+    http_route_belongs_to_plugin,
+    plugin_capability_prefix,
+    plugin_http_route_root,
+)
 from ....errors import AstrBotError
 from ..bridge_base import CapabilityRouterBridgeBase
 
@@ -32,6 +38,31 @@ def _validate_route(route: str, capability_name: str) -> None:
         )
 
 
+def _validate_plugin_route_namespace(route: str, plugin_id: str) -> None:
+    if http_route_belongs_to_plugin(route, plugin_id):
+        return
+    route_root = plugin_http_route_root(plugin_id)
+    raise AstrBotError.invalid_input(
+        "http.register_api 要求 route 使用当前插件的公开命名空间前缀："
+        f" route={route!r}, plugin_id={plugin_id!r}, expected={route_root!r} "
+        f"或 {route_root + '/...'}"
+    )
+
+
+def _validate_handler_capability_namespace(
+    handler_capability: str,
+    plugin_id: str,
+) -> None:
+    if capability_belongs_to_plugin(handler_capability, plugin_id):
+        return
+    expected_prefix = plugin_capability_prefix(plugin_id)
+    raise AstrBotError.invalid_input(
+        "http.register_api 要求 handler_capability 属于当前插件："
+        f" capability={handler_capability!r}, plugin_id={plugin_id!r}, "
+        f"expected_prefix={expected_prefix!r}"
+    )
+
+
 class HttpCapabilityMixin(CapabilityRouterBridgeBase):
     async def _http_register_api(
         self, _request_id: str, payload: dict[str, Any], _token
@@ -51,6 +82,8 @@ async def _http_register_api(
             )
         _validate_route(route, "http.register_api")
         plugin_name = self._require_caller_plugin_id("http.register_api")
+        _validate_plugin_route_namespace(route, plugin_name)
+        _validate_handler_capability_namespace(handler_capability, plugin_name)
         methods = sorted({method.upper() for method in methods_payload if method})
         entry: dict[str, Any] = {
             "route": route,

astrbot-sdk/src/astrbot_sdk/runtime/environment_groups.py

@@ -3,7 +3,7 @@
 这个模块负责“多个插件，共享较少数量 Python 环境”的策略。核心约束是：
 
 - 插件仍然独立发现、独立加载
-- Worker 进程仍然保持一插件一进程
+- Worker 运行时既可以是一插件一进程，也可以由 GroupWorkerRuntime 在同一进程承载多个插件
 - 只有在依赖兼容时才共享 Python 环境
 
 整体流程如下：

astrbot-sdk/src/astrbot_sdk/runtime/loader.py

@@ -70,7 +70,11 @@
 
 from .._internal.command_model import resolve_command_model_param
 from .._internal.injected_params import is_framework_injected_parameter
-from .._internal.plugin_ids import validate_plugin_id
+from .._internal.plugin_ids import (
+    capability_belongs_to_plugin,
+    plugin_capability_prefix,
+    validate_plugin_id,
+)
 from .._internal.typing_utils import unwrap_optional
 from ..decorators import (
     ConversationMeta,
@@ -223,6 +227,37 @@ def _iter_discoverable_names(instance: Any) -> list[str]:
     return [*handler_names, *extra_names]
 
 
+def _validate_loaded_capability_namespace(
+    plugin: PluginSpec,
+    *,
+    resolved_component: _ResolvedComponent,
+    attribute_name: str,
+    capability_name: str,
+) -> None:
+    if capability_belongs_to_plugin(capability_name, plugin.name):
+        return
+    expected_prefix = plugin_capability_prefix(plugin.name)
+    raise ValueError(
+        f"{_component_context(plugin, class_path=resolved_component.class_path, index=resolved_component.index)} "
+        f"方法 {attribute_name!r} 导出的 capability {capability_name!r} 必须使用当前插件名前缀 "
+        f"{expected_prefix!r}，例如 {expected_prefix}<action>"
+    )
+
+
+def _register_loaded_capability_name(
+    seen_capability_sources: dict[str, str],
+    *,
+    capability_name: str,
+    source_ref: str,
+) -> None:
+    existing_source = seen_capability_sources.get(capability_name)
+    if existing_source is not None:
+        raise ValueError(
+            f"capability {capability_name!r} 重复定义：{existing_source} 与 {source_ref}"
+        )
+    seen_capability_sources[capability_name] = source_ref
+
+
 def _is_injected_parameter(annotation: Any, parameter_name: str) -> bool:
     return is_framework_injected_parameter(parameter_name, annotation)
 
@@ -890,6 +925,7 @@ def load_plugin(plugin: PluginSpec) -> LoadedPlugin:
     llm_tools: list[LoadedLLMTool] = []
     agents: list[LoadedAgent] = []
     seen_agents: set[str] = set()
+    seen_capability_sources: dict[str, str] = {}
 
     for resolved_component in _plugin_component_classes(plugin):
         component_cls = resolved_component.cls
@@ -930,6 +966,18 @@ def load_plugin(plugin: PluginSpec) -> LoadedPlugin:
                 continue
             if capability is not None:
                 bound, meta = capability
+                capability_name = meta.descriptor.name
+                _validate_loaded_capability_namespace(
+                    plugin,
+                    resolved_component=resolved_component,
+                    attribute_name=name,
+                    capability_name=capability_name,
+                )
+                _register_loaded_capability_name(
+                    seen_capability_sources,
+                    capability_name=capability_name,
+                    source_ref=f"{resolved_component.class_path}.{name}",
+                )
                 capabilities.append(
                     LoadedCapability(
                         descriptor=meta.descriptor.model_copy(deep=True),

astrbot-sdk/src/astrbot_sdk/runtime/supervisor.py

@@ -8,14 +8,14 @@
         |
         +-- WorkerSession (插件 A) -- StdioTransport -- PluginWorkerRuntime (子进程)
         |
-        +-- WorkerSession (插件 B) -- StdioTransport -- PluginWorkerRuntime (子进程)
+        +-- WorkerSession (插件 B, 插件 C) -- StdioTransport -- GroupWorkerRuntime (子进程)
         |
-        +-- WorkerSession (插件 C) -- StdioTransport -- PluginWorkerRuntime (子进程)
+        +-- WorkerSession (插件 D) -- StdioTransport -- PluginWorkerRuntime (子进程)
 
 核心类：
     SupervisorRuntime: 监管者运行时
         - 发现并加载所有插件
-        - 为每个插件启动 Worker 进程
+        - 为单个插件或兼容插件组启动 Worker 进程
         - 聚合所有 handler 并向 Core 注册
         - 路由 Core 的调用请求到对应 Worker
         - 处理 Worker 进程崩溃和重连
@@ -45,6 +45,10 @@
 
 from loguru import logger
 
+from .._internal.plugin_ids import (
+    capability_belongs_to_plugin,
+    plugin_capability_prefix,
+)
 from ..errors import AstrBotError
 from ..protocol.descriptors import CapabilityDescriptor
 from ..protocol.messages import EventMessage, InitializeOutput, PeerInfo
@@ -533,60 +537,25 @@ def _register_plugin_capability(
         session: WorkerSession,
         plugin_name: str,
     ) -> None:
-        """注册插件 capability，处理命名冲突。
-
-        当 capability 名称冲突时：
-        - 如果是保留命名空间（handler/system/internal），跳过并警告
-        - 否则，使用插件名作为前缀重新命名，例如：
-          - 插件 'my_plugin' 注册 'demo.echo' 冲突
-          - 自动重命名为 'my_plugin.demo.echo'
-        """
+        """注册插件 capability。"""
         capability_name = descriptor.name
-
-        if not self.capability_router.contains(capability_name):
-            # 无冲突，直接注册
-            self._do_register_capability(
-                descriptor, session, capability_name, plugin_name
-            )
-            return
-
-        # 检查是否在保留命名空间内
-        if capability_name.startswith(("handler.", "system.", "internal.")):
-            logger.warning(
-                "Capability '{}' 在保留命名空间内，跳过插件 '{}' 的注册。"
-                "保留命名空间不允许插件覆盖。",
-                capability_name,
-                plugin_name,
+        if not capability_belongs_to_plugin(capability_name, plugin_name):
+            expected_prefix = plugin_capability_prefix(plugin_name)
+            raise ValueError(
+                "插件导出的 capability 必须使用 plugin_id 作为公开命名空间前缀："
+                f" plugin={plugin_name!r}, capability={capability_name!r}, "
+                f"expected_prefix={expected_prefix!r}"
             )
-            return
-
-        # 尝试添加插件前缀解决冲突
-        prefixed_name = f"{plugin_name}.{capability_name}"
-        if self.capability_router.contains(prefixed_name):
-            logger.warning(
-                "Capability '{}' 和 '{}.{}' 均已存在，"
-                "跳过插件 '{}' 的注册。请考虑使用更唯一的命名。",
-                capability_name,
-                plugin_name,
-                capability_name,
-                plugin_name,
+        # Worker 侧 loader 已经做过命名空间校验；这里若还能撞名，说明协议数据
+        # 与本地路由状态不一致，继续静默改名只会掩盖问题。
+        if self.capability_router.contains(capability_name):
+            existing_plugin = self._capability_sources.get(capability_name, "<unknown>")
+            raise RuntimeError(
+                "duplicate capability registration detected after worker load validation: "
+                f"{capability_name!r} already registered by {existing_plugin!r}, "
+                f"cannot register again for {plugin_name!r}"
             )
-            return
-
-        # 使用前缀名称注册
-        prefixed_descriptor = descriptor.model_copy(deep=True)
-        prefixed_descriptor.name = prefixed_name
-        logger.info(
-            "Capability '{}' 与已注册能力冲突，自动重命名为 '{}' (插件: {})。",
-            capability_name,
-            prefixed_name,
-            plugin_name,
-        )
-        self._do_register_capability(
-            prefixed_descriptor, session, prefixed_name, plugin_name
-        )
-        # 记录原始名称到前缀名称的映射，便于调试
-        self._capability_sources[f"_original:{prefixed_name}"] = capability_name
+        self._do_register_capability(descriptor, session, capability_name, plugin_name)
 
     def _do_register_capability(
         self,

astrbot-sdk/src/astrbot_sdk/templates/project_notes/AGENTS.md

@@ -7,5 +7,6 @@
 - Validate the generated plugin with `astrbot-sdk validate --plugin-dir .` before packaging or sharing it.
 - Run `python -m pytest tests/test_plugin.py -v` after changing plugin behavior so the sample harness contract stays honest.
 - `astrbot-sdk build --plugin-dir .` should create the release zip without development-only files such as `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.agents/`, or `.opencode/`.
+- Exported capabilities should use `<plugin_id>.<action>`, and HTTP routes should use `/{plugin_id}` or `/{plugin_id}/...` so the plugin stays collision-safe inside `GroupWorkerRuntime`.
 
-- 除非有充分理由，插件的直接依赖应声明已验证的最低兼容版本。若已知存在不兼容的大版本或问题版本，应同时补充上界或排除约束
+- 除非有充分理由，插件的直接依赖应声明已验证的最低兼容版本。若已知存在不兼容的大版本或问题版本，应同时补充上界或排除约束

astrbot-sdk/src/astrbot_sdk/templates/project_notes/CLAUDE.md

@@ -1,4 +1,4 @@
-# AGENTS.md
+# CLAUDE.md
 
 ## AstrBot Plugin Notes
 
@@ -7,5 +7,6 @@
 - Validate the generated plugin with `astrbot-sdk validate --plugin-dir .` before packaging or sharing it.
 - Run `python -m pytest tests/test_plugin.py -v` after changing plugin behavior so the sample harness contract stays honest.
 - `astrbot-sdk build --plugin-dir .` should create the release zip without development-only files such as `AGENTS.md`, `CLAUDE.md`, `.claude/`, `.agents/`, or `.opencode/`.
+- Exported capabilities should use `<plugin_id>.<action>`, and HTTP routes should use `/{plugin_id}` or `/{plugin_id}/...` so the plugin stays collision-safe inside `GroupWorkerRuntime`.
 
-- 除非有充分理由，插件的直接依赖应声明已验证的最低兼容版本。若已知存在不兼容的大版本或问题版本，应同时补充上界或排除约束
+- 除非有充分理由，插件的直接依赖应声明已验证的最低兼容版本。若已知存在不兼容的大版本或问题版本，应同时补充上界或排除约束