refactor(plugin): 重构插件系统架构，统一类型导入路径 (#296)

* refactor(plugin): 重构插件系统架构，统一类型导入路径

## 主要更改

### 新增 @esengine/plugin-types 包
- 提供打破循环依赖的最小类型定义
- 包含 ServiceToken, createServiceToken, PluginServiceRegistry, IEditorModuleBase

### engine-core 类型统一
- IPlugin<T> 泛型参数改为 T = unknown
- 所有运行时类型（IRuntimeModule, ModuleManifest, SystemContext）在此定义
- 新增 PluginServiceRegistry.ts 导出服务令牌相关类型

### editor-core 类型优化
- 重命名 IPluginLoader.ts 为 EditorModule.ts
- 新增 IEditorPlugin = IPlugin<IEditorModuleLoader> 类型别名
- 移除弃用别名 IPluginLoader, IRuntimeModuleLoader

### 编辑器插件更新
- 所有 9 个编辑器插件使用 IEditorPlugin 类型
- 统一从 editor-core 导入编辑器类型

### 服务令牌规范
- 各模块在 tokens.ts 中定义自己的服务接口和令牌
- 遵循"谁定义接口，谁导出 Token"原则

## 导入规范

| 场景 | 导入来源 |
|------|---------|
| 运行时模块 | @esengine/engine-core |
| 编辑器插件 | @esengine/editor-core |
| 服务令牌 | @esengine/engine-core |

* refactor(plugin): 完善服务令牌规范，统一运行时模块

## 更改内容

### 运行时模块优化
- particle: 使用 PluginServiceRegistry 获取依赖服务
- physics-rapier2d: 通过服务令牌注册/获取物理查询接口
- tilemap: 使用服务令牌获取物理系统依赖
- sprite: 导出服务令牌
- ui: 导出服务令牌
- behavior-tree: 使用服务令牌系统

### 资产系统增强
- IAssetManager 接口扩展
- 加载器使用服务令牌获取依赖

### 运行时核心
- GameRuntime 使用 PluginServiceRegistry
- 导出服务令牌相关类型

### 编辑器服务
- EngineService 适配新的服务令牌系统
- AssetRegistryService 优化

* fix: 修复 editor-app 和 behavior-tree-editor 中的类型引用

- editor-app/PluginLoader.ts: 使用 IPlugin 替代 IPluginLoader
- behavior-tree-editor: 使用 IEditorPlugin 替代 IPluginLoader

* fix(ui): 添加缺失的 ecs-engine-bindgen 依赖

UIRuntimeModule 使用 EngineBridgeToken，需要声明对 ecs-engine-bindgen 的依赖

* fix(type): 解决 ServiceToken 跨包类型兼容性问题

- 在 engine-core 中直接定义 ServiceToken 和 PluginServiceRegistry
  而不是从 plugin-types 重新导出，确保 tsup 生成的类型声明
  以 engine-core 作为类型来源
- 移除 RuntimeResolver.ts 中的硬编码模块 ID 检查，
  改用 module.json 中的 name 配置
- 修复 pnpm-lock.yaml 中的依赖记录

* refactor(arch): 改进架构设计，移除硬编码

- 统一类型导出：editor-core 从 engine-core 导入 IEditorModuleBase
- RuntimeResolver: 将硬编码路径改为配置常量和搜索路径列表
- 添加跨平台安装路径支持（Windows/macOS/Linux）
- 使用 ENGINE_WASM_CONFIG 配置引擎 WASM 文件信息
- IBundlePackOptions 添加 preloadBundles 配置项

* fix(particle): 添加缺失的 ecs-engine-bindgen 依赖

ParticleRuntimeModule 导入了 @esengine/ecs-engine-bindgen 的 tokens，
但 package.json 中未声明该依赖，导致 CI 构建失败。

* fix(physics-rapier2d): 移除不存在的 PhysicsSystemContext 导出

PhysicsRuntimeModule 中不存在该类型，导致 type-check 失败

packages/engine-core/src/EnginePlugin.ts

@@ -2,14 +2,43 @@
  * 插件系统核心类型定义
  * Plugin system core type definitions
  *
- * 这是插件类型的唯一定义源，editor-core 重新导出并扩展这些类型。
- * This is the single source of truth for plugin types. editor-core re-exports and extends them.
+ * 这是运行时插件类型的唯一定义源。
+ * 编辑器类型在 editor-core 中扩展这些类型。
+ *
+ * This is the single source of truth for runtime plugin types.
+ * Editor types extend these in editor-core.
+ *
+ * @see docs/architecture/plugin-system-design.md
  */
 
 import type { ComponentRegistry as ComponentRegistryType, IScene, ServiceContainer } from '@esengine/ecs-framework';
 import { TransformComponent } from './TransformComponent';
 import type { ModuleManifest } from './ModuleManifest';
 
+// 从本地模块导入服务令牌系统（确保 tsup 生成的类型以 engine-core 为源）
+// Import service token system from local module (ensures tsup generates types with engine-core as source)
+import {
+    PluginServiceRegistry,
+    createServiceToken,
+    TransformTypeToken,
+    type ServiceToken
+} from './PluginServiceRegistry';
+
+// 导出服务令牌系统 | Export service token system
+export {
+    PluginServiceRegistry,
+    createServiceToken,
+    TransformTypeToken,
+    type ServiceToken
+};
+
+// 重新导出 IEditorModuleBase（供编辑器插件使用）| Re-export for editor plugins
+export type { IEditorModuleBase } from '@esengine/plugin-types';
+
+// ============================================================================
+// 加载阶段 | Loading Phase
+// ============================================================================
+
 /**
  * 加载阶段 - 控制插件模块的加载顺序
  * Loading phase - controls the loading order of plugin modules
@@ -28,16 +57,38 @@ export type LoadingPhase =
 /**
  * 系统创建上下文
  * System creation context
+ *
+ * 包含运行时配置和插件服务注册表。
+ * Contains runtime configuration and plugin service registry.
+ *
+ * @example
+ * ```typescript
+ * // 导入需要的 Token | Import needed tokens
+ * import { Physics2DQueryToken } from '@esengine/physics-rapier2d';
+ * import { AssetManagerToken } from '@esengine/asset-system';
+ *
+ * // 注册服务 | Register service
+ * context.services.register(Physics2DQueryToken, physicsSystem);
+ *
+ * // 获取服务（可选）| Get service (optional)
+ * const physics = context.services.get(Physics2DQueryToken);
+ *
+ * // 获取服务（必需）| Get service (required)
+ * const physics = context.services.require(Physics2DQueryToken);
+ * ```
  */
 export interface SystemContext {
     /** 是否为编辑器模式 | Is editor mode */
-    isEditor: boolean;
-    /** 引擎桥接（如有） | Engine bridge (if available) */
-    engineBridge?: any;
-    /** 渲染系统（如有） | Render system (if available) */
-    renderSystem?: any;
-    /** 其他已创建的系统引用 | Other created system references */
-    [key: string]: any;
+    readonly isEditor: boolean;
+
+    /**
+     * 插件服务注册表
+     * Plugin service registry
+     *
+     * 用于跨插件共享服务。
+     * For sharing services between plugins.
+     */
+    readonly services: PluginServiceRegistry;
 }
 
 // ============================================================================
@@ -95,15 +146,41 @@ export interface IRuntimeModule {
  * Plugin interface
  *
  * 这是所有插件包导出的统一类型。
+ * 使用泛型允许编辑器模块使用更具体的类型。
+ *
  * This is the unified type that all plugin packages export.
+ * Uses generics to allow editor modules to use more specific types.
+ *
+ * @example
+ * ```typescript
+ * // 纯运行时插件 | Pure runtime plugin
+ * const MyPlugin: IPlugin = {
+ *     manifest,
+ *     runtimeModule: new MyRuntimeModule()
+ * };
+ *
+ * // 编辑器插件（在 editor-core 中定义 IEditorPlugin）
+ * // Editor plugin (IEditorPlugin defined in editor-core)
+ * const MyEditorPlugin: IEditorPlugin = {
+ *     manifest,
+ *     runtimeModule: new MyRuntimeModule(),
+ *     editorModule: new MyEditorModule()
+ * };
+ * ```
  */
-export interface IPlugin {
+export interface IPlugin<TEditorModule = unknown> {
     /** 模块清单 | Module manifest */
     readonly manifest: ModuleManifest;
     /** 运行时模块（可选） | Runtime module (optional) */
     readonly runtimeModule?: IRuntimeModule;
-    /** 编辑器模块（可选，类型为 any 以避免循环依赖） | Editor module (optional, typed as any to avoid circular deps) */
-    readonly editorModule?: any;
+    /**
+     * 编辑器模块（可选）
+     * Editor module (optional)
+     *
+     * 泛型参数允许 editor-core 使用 IEditorModuleLoader 类型。
+     * Generic parameter allows editor-core to use IEditorModuleLoader type.
+     */
+    readonly editorModule?: TEditorModule;
 }
 
 // ============================================================================

packages/engine-core/src/PluginServiceRegistry.ts

@@ -0,0 +1,147 @@
+/**
+ * 插件服务注册表
+ * Plugin Service Registry
+ *
+ * 这个文件重新定义（不是 re-export）ServiceToken 和 PluginServiceRegistry，
+ * 以确保 tsup/rollup-plugin-dts 生成的类型声明使用 engine-core 作为类型来源，
+ * 而不是追踪到 plugin-types（会导致跨包类型不兼容）。
+ *
+ * This file re-defines (not re-exports) ServiceToken and PluginServiceRegistry,
+ * to ensure tsup/rollup-plugin-dts generated type declarations use engine-core
+ * as the type source, instead of tracing back to plugin-types (which causes
+ * cross-package type incompatibility).
+ *
+ * 设计原则 | Design principles:
+ * 1. 类型安全 - 使用 ServiceToken 携带类型信息
+ * 2. 显式依赖 - 通过导入 token 明确表达依赖关系
+ * 3. 可选依赖 - get 返回 undefined，require 抛异常
+ * 4. 单一职责 - 只负责服务注册和查询，不涉及生命周期管理
+ * 5. 谁定义接口，谁导出 Token - 各模块定义自己的接口和 Token
+ * 6. 单一类型来源 - 所有包从 engine-core 导入类型，不直接使用 plugin-types
+ */
+
+// ============================================================================
+// 服务令牌 | Service Token
+// ============================================================================
+
+/**
+ * 服务令牌接口
+ * Service token interface
+ *
+ * 用于类型安全的服务注册和获取。
+ * For type-safe service registration and retrieval.
+ *
+ * 注意：__phantom 是必需属性，确保 TypeScript 在跨包类型解析时保留泛型类型信息。
+ * Note: __phantom is a required property to ensure TypeScript preserves generic
+ * type information across packages.
+ */
+export interface ServiceToken<T> {
+    readonly id: symbol;
+    readonly name: string;
+    /**
+     * Phantom type 标记（强制类型推断）
+     * Phantom type marker (enforces type inference)
+     */
+    readonly __phantom: T;
+}
+
+/**
+ * 创建服务令牌
+ * Create a service token
+ *
+ * @param name 令牌名称 | Token name
+ * @returns 服务令牌 | Service token
+ */
+export function createServiceToken<T>(name: string): ServiceToken<T> {
+    // __phantom 仅用于类型推断，运行时不需要实际值
+    // __phantom is only for type inference, no actual value needed at runtime
+    return {
+        id: Symbol(name),
+        name
+    } as ServiceToken<T>;
+}
+
+// ============================================================================
+// 插件服务注册表 | Plugin Service Registry
+// ============================================================================
+
+/**
+ * 插件服务注册表
+ * Plugin service registry
+ *
+ * 用于跨插件共享服务的类型安全注册表。
+ * Type-safe registry for sharing services between plugins.
+ */
+export class PluginServiceRegistry {
+    private _services = new Map<symbol, unknown>();
+
+    /**
+     * 注册服务
+     * Register a service
+     */
+    register<T>(token: ServiceToken<T>, service: T): void {
+        this._services.set(token.id, service);
+    }
+
+    /**
+     * 获取服务（可选）
+     * Get a service (optional)
+     */
+    get<T>(token: ServiceToken<T>): T | undefined {
+        return this._services.get(token.id) as T | undefined;
+    }
+
+    /**
+     * 获取服务（必需）
+     * Get a service (required)
+     *
+     * @throws 如果服务未注册 | If service is not registered
+     */
+    require<T>(token: ServiceToken<T>): T {
+        const service = this._services.get(token.id);
+        if (service === undefined) {
+            throw new Error(`Service not found: ${token.name}`);
+        }
+        return service as T;
+    }
+
+    /**
+     * 检查服务是否已注册
+     * Check if a service is registered
+     */
+    has<T>(token: ServiceToken<T>): boolean {
+        return this._services.has(token.id);
+    }
+
+    /**
+     * 注销服务
+     * Unregister a service
+     */
+    unregister<T>(token: ServiceToken<T>): boolean {
+        return this._services.delete(token.id);
+    }
+
+    /**
+     * 清空所有服务
+     * Clear all services
+     */
+    clear(): void {
+        this._services.clear();
+    }
+}
+
+// ============================================================================
+// engine-core 内部 Token | engine-core Internal Tokens
+// ============================================================================
+
+/**
+ * Transform 组件类型 | Transform component type
+ *
+ * 使用 any 类型以允许各模块使用自己的 ITransformComponent 接口定义。
+ * Using any type to allow modules to use their own ITransformComponent interface definition.
+ *
+ * 这是 engine-core 自己定义的 Token，因为 TransformComponent 在此模块中定义。
+ * This is a Token defined by engine-core itself, as TransformComponent is defined in this module.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const TransformTypeToken = createServiceToken<new (...args: any[]) => any>('transformType');

packages/engine-core/src/index.ts

@@ -4,11 +4,18 @@ export { HierarchyComponent } from './HierarchyComponent';
 export { HierarchySystem } from './HierarchySystem';
 export {
     EnginePlugin,
-    // 类型导出
+    // Type exports
     type LoadingPhase,
     type SystemContext,
     type IRuntimeModule,
-    type IPlugin
+    type IPlugin,
+    // Plugin service registry (defined locally in PluginServiceRegistry.ts)
+    PluginServiceRegistry,
+    createServiceToken,
+    TransformTypeToken,
+    // Types
+    type ServiceToken,
+    type IEditorModuleBase
 } from './EnginePlugin';
 
 // Module Manifest types (unified module/plugin configuration)