Merge pull request #187 from esengine/feature/complete-iscene-interface

feat(core): 完善 IScene 接口定义

.github/workflows/pr-agent.yml

@@ -1,28 +0,0 @@
-name: PR Agent
-
-on:
-  pull_request:
-    types: [opened, reopened, synchronize]
-  issue_comment:
-    types: [created, edited]
-
-permissions:
-  contents: read
-  pull-requests: write
-  issues: write
-
-jobs:
-  pr_agent:
-    runs-on: ubuntu-latest
-    name: Run PR Agent
-    if: ${{ github.event.sender.type != 'Bot' }}
-    steps:
-      - name: PR Agent Action
-        id: pragent
-        uses: Codium-ai/pr-agent@main
-        env:
-          OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          github_action_config.auto_review: "true"
-          github_action_config.auto_describe: "true"
-          github_action_config.auto_improve: "false"

.github/workflows/pr-size-labeler.yml

@@ -1,31 +0,0 @@
-name: PR Size Labeler
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened]
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  size-label:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Label PR by size
-        uses: codelytv/pr-size-labeler@v1
-        with:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          xs_label: 'size/XS'
-          xs_max_size: '10'
-          s_label: 'size/S'
-          s_max_size: '100'
-          m_label: 'size/M'
-          m_max_size: '500'
-          l_label: 'size/L'
-          l_max_size: '1000'
-          xl_label: 'size/XL'
-          message_if_xl: |
-            这个 PR 改动较大（超过 1000 行），建议拆分成多个小 PR 以便 Review。
-
-            This PR is quite large (over 1000 lines). Consider splitting it into smaller PRs for easier review.

.mergify.yml

@@ -1,178 +0,0 @@
-queue_rules:
-  - name: default
-    conditions:
-      - check-success=CI
-      - check-success=Commit Lint
-
-  # 开发依赖队列 - 只需要 Commit Lint 通过
-  - name: dev-dependencies
-    conditions:
-      - check-success=Commit Lint
-
-pull_request_rules:
-  # 自动合并 Dependabot 开发依赖分组更新（风险低，允许 CI 失败）
-  - name: 自动合并 Dependabot 开发依赖
-    conditions:
-      - author=dependabot[bot]
-      - or:
-        - title~=(?i)dev.dependencies
-        - label=dependencies
-        - body~=(?i)development.dependencies
-      - check-success=Commit Lint
-      # 排除主要版本更新
-      - -title~=(?i)major
-    actions:
-      review:
-        type: APPROVE
-        message: |
-          🤖 自动批准开发依赖更新
-
-          开发依赖更新风险较低，即使测试失败也不影响生产环境。
-          如有问题会在后续开发中发现并修复。
-      queue:
-        name: dev-dependencies
-      label:
-        add:
-          - auto-merged
-
-  # 自动合并 Dependabot 生产依赖的 patch 更新（必须 CI 通过）
-  - name: 自动合并 Dependabot 生产依赖 patch 更新
-    conditions:
-      - author=dependabot[bot]
-      - or:
-        - title~=(?i)production.dependencies
-        - and:
-          - label=dependencies
-          - -body~=(?i)development.dependencies
-      - title~=(?i)patch
-      - check-success=CI
-      - check-success=Commit Lint
-    actions:
-      review:
-        type: APPROVE
-        message: 🤖 自动批准生产依赖 patch 更新（测试通过）
-      queue:
-        name: default
-      label:
-        add:
-          - auto-merged
-
-  # 自动合并 GitHub Actions 更新（风险低）
-  - name: 自动合并 GitHub Actions 更新
-    conditions:
-      - author=dependabot[bot]
-      - label=github-actions
-      - check-success=Commit Lint
-    actions:
-      review:
-        type: APPROVE
-        message: 🤖 自动批准 GitHub Actions 更新
-      queue:
-        name: dev-dependencies
-      label:
-        add:
-          - auto-merged
-
-  # 标记需要人工审核的重要更新
-  - name: 标记需要人工审核的生产依赖更新
-    conditions:
-      - author=dependabot[bot]
-      - or:
-        - title~=(?i)production.dependencies
-        - and:
-          - label=dependencies
-          - -body~=(?i)development.dependencies
-      - or:
-        - title~=(?i)minor
-        - title~=(?i)major
-        - -check-success=CI
-    actions:
-      label:
-        add:
-          - needs-manual-review
-      comment:
-        message: |
-          ⚠️ **需要人工审核**
-
-          此更新属于以下情况之一，建议人工审核：
-          - 生产依赖的 minor/major 版本更新
-          - CI 测试未通过
-
-          Please review this update manually.
-
-  # 自动关闭超过 30 天未合并的 Dependabot PR（避免堆积）
-  - name: 关闭过期的 Dependabot PR
-    conditions:
-      - author=dependabot[bot]
-      - updated-at<30 days ago
-      - -merged
-      - -closed
-    actions:
-      close:
-        message: |
-          🤖 自动关闭此 PR
-
-          此 PR 已超过 30 天未合并。Dependabot 会在下次运行时创建新的更新。
-          如果需要此更新，请手动更新依赖或等待下次自动更新。
-
-          This PR has been open for over 30 days. Dependabot will create a new update in the next run if needed.
-
-  # 自动合并有 'automerge' 标签且测试通过的 PR
-  - name: 自动合并标记的 PR
-    conditions:
-      - label=automerge
-      - check-success=CI
-      - check-success=Commit Lint
-      - "#approved-reviews-by>=1"
-      - "#changes-requested-reviews-by=0"
-    actions:
-      queue:
-        name: default
-
-  # 自动给小 PR 添加标签（根据文件数）
-  - name: 标记小 PR 方便快速 Review
-    conditions:
-      - "#files<=3"
-    actions:
-      label:
-        add:
-          - quick-review
-
-  # 提醒大 PR 需要拆分（根据文件数）
-  - name: 提醒大 PR
-    conditions:
-      - "#files>=20"
-    actions:
-      comment:
-        message: |
-          ⚠️ 这个 PR 改动了较多文件（20+ 个），建议拆分成多个小 PR，便于 Review 和测试。
-
-          ⚠️ This PR modifies many files (20+). Consider splitting it into smaller PRs for easier review and testing.
-
-  # 自动更新过期的分支
-  - name: 自动更新过期分支
-    conditions:
-      - -draft
-      - -closed
-      - base=master
-      - "#approved-reviews-by>=1"
-    actions:
-      update: {}
-
-  # 自动添加标签
-  - name: 添加 dependencies 标签
-    conditions:
-      - author=dependabot[bot]
-    actions:
-      label:
-        add:
-          - dependencies
-
-  # 标记需要关注的 PR
-  - name: 标记需要更新的 PR
-    conditions:
-      - "#commits-behind>10"
-    actions:
-      label:
-        add:
-          - needs-rebase

packages/core/src/ECS/IScene.ts

@@ -6,7 +6,10 @@ import { ComponentStorageManager } from './Core/ComponentStorage';
 import { QuerySystem } from './Core/QuerySystem';
 import { TypeSafeEventSystem } from './Core/EventSystem';
 import type { ReferenceTracker } from './Core/ReferenceTracker';
-import type { ServiceContainer } from '../Core/ServiceContainer';
+import type { ServiceContainer, ServiceType } from '../Core/ServiceContainer';
+import type { TypedQueryBuilder } from './Core/Query/TypedQuery';
+import type { SceneSerializationOptions, SceneDeserializationOptions } from './Serialization/SceneSerializer';
+import type { IncrementalSnapshot, IncrementalSerializationOptions } from './Serialization/IncrementalSerializer';
 
 /**
  * 场景接口定义
@@ -159,6 +162,140 @@ export interface IScene {
      * 获取实体处理器
      */
     getEntityProcessor<T extends EntitySystem>(type: new (...args: any[]) => T): T | null;
+
+    /**
+     * 根据ID查找实体
+     */
+    findEntityById(id: number): Entity | null;
+
+    /**
+     * 根据名称查找实体
+     */
+    getEntityByName(name: string): Entity | null;
+
+    /**
+     * 根据标签查找实体
+     */
+    getEntitiesByTag(tag: number): Entity[];
+
+    /**
+     * 批量销毁实体
+     */
+    destroyEntities(entities: Entity[]): void;
+
+    /**
+     * 查询拥有所有指定组件的实体
+     */
+    queryAll(...componentTypes: any[]): { entities: readonly Entity[] };
+
+    /**
+     * 查询拥有任意一个指定组件的实体
+     */
+    queryAny(...componentTypes: any[]): { entities: readonly Entity[] };
+
+    /**
+     * 查询不包含指定组件的实体
+     */
+    queryNone(...componentTypes: any[]): { entities: readonly Entity[] };
+
+    /**
+     * 创建类型安全的查询构建器
+     */
+    query(): TypedQueryBuilder;
+
+    /**
+     * 通过类型获取System实例
+     */
+    getSystem<T extends EntitySystem>(systemType: ServiceType<T>): T | null;
+
+    /**
+     * 批量注册EntitySystem到场景
+     */
+    registerSystems(systemTypes: Array<ServiceType<EntitySystem>>): EntitySystem[];
+
+    /**
+     * 添加系统到场景
+     */
+    addSystem(system: EntitySystem): EntitySystem;
+
+    /**
+     * 从场景中删除系统
+     */
+    removeSystem(system: EntitySystem): void;
+
+    /**
+     * 获取场景统计信息
+     */
+    getStats(): {
+        entityCount: number;
+        processorCount: number;
+        componentStorageStats: Map<string, any>;
+    };
+
+    /**
+     * 获取场景的调试信息
+     */
+    getDebugInfo(): {
+        name: string;
+        entityCount: number;
+        processorCount: number;
+        isRunning: boolean;
+        entities: Array<{
+            name: string;
+            id: number;
+            componentCount: number;
+            componentTypes: string[];
+        }>;
+        processors: Array<{
+            name: string;
+            updateOrder: number;
+            entityCount: number;
+        }>;
+        componentStats: Map<string, any>;
+    };
+
+    /**
+     * 序列化场景
+     */
+    serialize(options?: SceneSerializationOptions): string | Uint8Array;
+
+    /**
+     * 反序列化场景
+     */
+    deserialize(saveData: string | Uint8Array, options?: SceneDeserializationOptions): void;
+
+    /**
+     * 创建增量序列化的基础快照
+     */
+    createIncrementalSnapshot(options?: IncrementalSerializationOptions): void;
+
+    /**
+     * 增量序列化场景
+     */
+    serializeIncremental(options?: IncrementalSerializationOptions): IncrementalSnapshot;
+
+    /**
+     * 应用增量变更到场景
+     */
+    applyIncremental(
+        incremental: IncrementalSnapshot | string | Uint8Array,
+        componentRegistry?: Map<string, any>
+    ): void;
+
+    /**
+     * 更新增量快照基准
+     */
+    updateIncrementalSnapshot(options?: IncrementalSerializationOptions): void;
+
+    /**
+     * 清除增量快照
+     */
+    clearIncrementalSnapshot(): void;
+
+    /**
+     * 检查是否有增量快照
+     */
+    hasIncrementalSnapshot(): boolean;
 }
 
 /**