virid-core 0.1.0__tar.gz

virid_core-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+# --- 依赖与包管理器 ---
+.venv/
+uv.lock
+__pycache__/

virid_core-0.1.0/PKG-INFO

@@ -0,0 +1,4 @@
+Metadata-Version: 2.4
+Name: virid-core
+Version: 0.1.0
+Requires-Python: >=3.10

virid_core-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "virid-core"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/virid"] # 告诉 Hatch 顶层是个命名空间
+layout = "src"           # 核心：使用标准的 src 布局逻辑
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

virid_core-0.1.0/src/virid/core/__init__.py

@@ -0,0 +1,18 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from .app import ViridApp,ViridPlugin
+from .core import *
+from .decorators import *
+from .util import toggle_utils
+
+
+def create_virid(
+    enable_logging: bool = True,
+) -> ViridApp:
+    from .app import virid_app
+
+    toggle_utils(enable_logging)
+    return virid_app

virid_core-0.1.0/src/virid/core/app.py

@@ -0,0 +1,145 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+
+from __future__ import annotations
+from .core import Engine
+from .container import Container
+from typing import Type, Callable, TypeVar, overload, Any, Protocol
+from .core.message import BaseMessage, EventMessage, SingleMessage
+from .core.interface import TickHook, ExecuteHook, Middleware
+from .core.io import MessageWriter
+
+T = TypeVar("T")
+F = TypeVar("F", bound=EventMessage, contravariant=True)
+H = TypeVar("H", bound=SingleMessage, contravariant=True)
+O = TypeVar("O", contravariant=True)
+
+installed_plugins = set()
+
+
+class ViridPlugin(Protocol[O]):
+    name: str
+
+    def install(self, app: ViridApp, options: O) -> None: ...
+
+
+class ViridApp:
+    def __init__(self):
+        self.engine = Engine()
+        self.container = Container()
+        self.activate: list[Callable] = [lambda x: x]
+
+    def on_activate(self, activate: Callable, front: bool = False) -> None:
+        if front:
+            self.activate.insert(0, activate)
+        else:
+            self.activate.append(activate)
+
+    def get(self, identifier: Type[T]) -> T:
+        return self.container.get(identifier, self.activate)
+
+    def bind(self, identifier, singleton=True):
+        self.container.bind(identifier, singleton)
+
+    def tick(self):
+        self.engine.tick()
+
+    def register(
+        self, message_class: Type[BaseMessage], system_fn: Callable, priority: int = 0
+    ):
+        self.engine.register(message_class, system_fn, priority)
+
+    def on_before_tick(self, hook: TickHook, front: bool = False):
+        self.engine.on_before_tick(hook, front)
+
+    def on_after_tick(self, hook: TickHook, front: bool = False):
+        self.engine.on_after_tick(hook, front)
+
+    @overload
+    def on_before_execute(
+        self,
+        message_type: Type[F],
+        hook: ExecuteHook[F],
+        front: bool = False,
+    ) -> None: ...
+
+    @overload
+    def on_before_execute(
+        self,
+        message_type: Type[H],
+        hook: ExecuteHook[list[H]],
+        front: bool = False,
+    ) -> None: ...
+
+    @overload
+    def on_before_execute(
+        self,
+        message_type: Type[BaseMessage],
+        hook: ExecuteHook[list[SingleMessage] | EventMessage],
+        front: bool = False,
+    ) -> None: ...
+
+    def on_before_execute(
+        self, message_type: Any, hook: Any, front: bool = False
+    ) -> None:
+        self.engine.on_before_execute(message_type, hook, front)
+
+    @overload
+    def on_after_execute(
+        self,
+        message_type: Type[F],
+        hook: ExecuteHook[F],
+        front: bool = False,
+    ) -> None: ...
+
+    @overload
+    def on_after_execute(
+        self,
+        message_type: Type[H],
+        hook: ExecuteHook[list[H]],
+        front: bool = False,
+    ) -> None: ...
+
+    @overload
+    def on_after_execute(
+        self,
+        message_type: Type[BaseMessage],
+        hook: ExecuteHook[list[SingleMessage] | EventMessage],
+        front: bool = False,
+    ) -> None: ...
+
+    def on_after_execute(
+        self, message_type: Any, hook: Any, front: bool = False
+    ) -> None:
+        self.engine.on_after_execute(message_type, hook, front)
+
+    def use_middleware(self, middleware: Middleware):
+        self.engine.use_middleware(middleware)
+
+    def use(self, plugin: ViridPlugin[O], options: O) -> ViridApp:
+        if plugin.name in installed_plugins:
+            MessageWriter.warn(
+                f"[Virid Plugin] Duplicate Installation: Plugin {plugin.name} has already been installed."
+            )
+            return self
+
+        try:
+            plugin.install(self, options)
+            installed_plugins.add(plugin.name)
+        except Exception as e:
+            MessageWriter.error(
+                e, f"[Virid Container] Activation Hook Failed: {plugin.name}"
+            )
+
+        return self
+
+
+virid_app = ViridApp()
+
+
+from .util import register_base_handlers
+
+register_base_handlers(virid_app)

virid_core-0.1.0/src/virid/core/container.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from typing import Type, TypeVar, Callable, Any, Optional
+from .core.io import MessageWriter
+
+T = TypeVar("T")
+
+
+class Container:
+    def __init__(self):
+        self._bindings: dict[Type[Any], tuple[Type[Any], bool]] = {}
+        self._singletons: dict[Type[Any], Any] = {}
+
+    def bind(self, identifier: Type[T], singleton: bool = False) -> None:
+        """
+        注册绑定。
+        - to: 映射到的目标类。如果不传，默认绑定到自身（toSelf）
+        - singleton: 是否为单例。默认为 False (transient)
+        """
+        if getattr(identifier, "__virid_component__", False) is True or getattr(identifier, "__virid_controller__", False) is True:  # type: ignore
+            self._bindings[identifier] = (identifier, singleton)
+
+        else:
+            MessageWriter.error(
+                TypeError(
+                    f"[Virid Container] Invalid Component: The Class {identifier.__name__} whit not @Component decorator."
+                )
+            )
+
+    def get(self, identifier: Type[T], on_activate: list[Callable]) -> T:
+        """获取实例，执行激活流水线"""
+        if identifier not in self._bindings:
+            raise RuntimeError(
+                f"[Virid Container] Unbound: No binding found for {identifier.__name__}"
+            )
+
+        target_ctor, is_singleton = self._bindings[identifier]
+
+        # 如果是单例
+        if is_singleton:
+            if identifier not in self._singletons:
+                self._singletons[identifier] = self.activate(target_ctor(), on_activate)
+            return self._singletons[identifier]
+
+        # 如果是多例
+        return self.activate(target_ctor(), on_activate)
+
+    def activate(self, component: Any, on_activate: list[Callable]):
+        result = component
+        for hook in on_activate:
+            result = hook(result)
+
+        return result

virid_core-0.1.0/src/virid/core/core/__init__.py

@@ -0,0 +1,10 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from .io import *
+from .engine import *
+from .message import *
+from .registry import *
+from .interface import *

virid_core-0.1.0/src/virid/core/core/dispatcher.py

@@ -0,0 +1,281 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+
+import time
+from typing import Callable, Type
+from .interface import (
+    SystemTask,
+    TickHook,
+    ExecuteHook,
+    TickHookContext,
+    ExecuteHookContext,
+)
+from .io import MessageWriter
+from .message import BaseMessage, SingleMessage, EventMessage
+from .stage import Stage
+
+
+class ExecutionTask:
+
+    def __init__(
+        self,
+        system_fn: Callable,
+        message: EventMessage | list[SingleMessage],
+        priority: int,
+        hook_context: ExecuteHookContext,
+    ):
+        self.message = message
+        self.system_fn = system_fn
+        self.priority = priority
+        self.hook_context = hook_context
+
+    def trigger_hook(
+        self,
+        hooks: list[
+            tuple[
+                type[BaseMessage],
+                ExecuteHook,
+            ]
+        ],
+        success: bool,
+    ):
+        # 根据是不是数组来取self.message的第一个
+        message = self.message[0] if isinstance(self.message, list) else self.message
+        try:
+            for hook in hooks:
+                if isinstance(message, hook[0]):
+                    hook[1](self.message, self.hook_context, success)
+        except Exception as e:
+            MessageWriter.error(e, f"[Virid Hook] System Execute Hook Error.\n")
+
+    def execute(
+        self,
+        before_execute_hooks: list[
+            tuple[
+                type[BaseMessage],
+                ExecuteHook,
+            ]
+        ],
+        after_execute_hooks: list[
+            tuple[
+                type[BaseMessage],
+                ExecuteHook,
+            ]
+        ],
+    ):
+        success = True
+        self.trigger_hook(before_execute_hooks, success)
+        try:
+            self.system_fn(self.message)
+        except Exception as e:
+            success = False
+            self.trigger_hook(after_execute_hooks, success)
+            # 重新丢出错误
+            raise e
+
+        self.trigger_hook(after_execute_hooks, success)
+
+
+class Dispatcher:
+    def __init__(self):
+        self.stage = Stage()
+        self.event_queue: list[EventMessage] = []
+        self.dirty_signal_types: dict[Type[SingleMessage], None] = {}
+
+        self.is_running = False
+        self.internal_depth = 0
+        self.tick_counter = 0
+
+        # 两个tick hook
+        self.before_tick_hooks: list[TickHook] = []
+        self.after_tick_hooks: list[TickHook] = []
+        self.tick_payload = {}
+
+        # 两个execute hook
+        self.before_execute_hooks: list[
+            tuple[
+                type[BaseMessage],
+                ExecuteHook,
+            ]
+        ] = []
+        self.after_execute_hooks: list[
+            tuple[
+                type[BaseMessage],
+                ExecuteHook,
+            ]
+        ] = []
+
+    def add_before_tick_hook(self, hook: TickHook, front: bool = False):
+        if front:
+            self.before_tick_hooks.insert(0, hook)
+        else:
+            self.before_tick_hooks.append(hook)
+
+    def add_after_tick_hook(self, hook: TickHook, front: bool = False):
+        if front:
+            self.after_tick_hooks.insert(0, hook)
+        else:
+            self.after_tick_hooks.append(hook)
+
+    def add_before_execute_hook(
+        self, message_type: Type[BaseMessage], hook: ExecuteHook, front: bool = False
+    ):
+        if front:
+            self.before_execute_hooks.insert(0, (message_type, hook))
+        else:
+            self.before_execute_hooks.append((message_type, hook))
+
+    def add_after_execute_hook(
+        self, message_type: Type[BaseMessage], hook: ExecuteHook, front: bool = False
+    ):
+        if front:
+            self.after_execute_hooks.insert(0, (message_type, hook))
+        else:
+            self.after_execute_hooks.append((message_type, hook))
+
+    def mark_dirty(self, message: BaseMessage):
+        self.stage.push(message)
+        # 根据消息类型放进不同的池子里
+        if isinstance(message, SingleMessage):
+            self.dirty_signal_types[type(message)] = None
+        elif isinstance(message, EventMessage):
+            self.event_queue.append(message)
+
+    def tick(self, system_task_map: dict[Type[BaseMessage], list[SystemTask]]):
+
+        if self.is_running or (
+            len(self.dirty_signal_types) == 0 and len(self.event_queue) == 0
+        ):
+            return
+
+        if self.internal_depth == 0:
+            self.tick_payload = {}
+            self.execute_hooks(self.before_tick_hooks)
+
+        if self.internal_depth > 100:
+            self.internal_depth = 0
+            self.dirty_signal_types.clear()
+            self.event_queue.clear()
+            self.stage.reset()
+            MessageWriter.error(
+                RuntimeError(
+                    "[Virid Dispatcher] Internal depth exceeded 100. Possible infinite loop detected. 💥."
+                ),
+            )
+            return
+
+        self.is_running = True
+        self.internal_depth += 1
+
+        # 正式开始任务
+        signal_snapshot = set()
+        event_snapshot = list()
+
+        try:
+            signal_snapshot, event_snapshot = self.prepare_snapshot()
+            tasks = self.collect_tasks(
+                event_snapshot,
+                signal_snapshot,
+                system_task_map,
+            )
+            self.execute_tasks(tasks)
+
+        except Exception as e:
+            MessageWriter.error(e)
+
+        finally:
+            self.clear()
+            self.is_running = False
+            if len(self.dirty_signal_types) > 0 or len(self.event_queue) > 0:
+                self.tick(system_task_map)
+            else:
+                self.internal_depth = 0
+                self.execute_hooks(self.after_tick_hooks)
+                self.tick_counter += 1
+
+    def collect_tasks(
+        self,
+        event_snapshot: list[EventMessage],
+        signal_snapshot: list[Type[SingleMessage]],
+        system_task_map: dict[Type[BaseMessage], list[SystemTask]],
+    ):
+        tasks: list[ExecutionTask] = []
+        # 处理Event消息
+        for msg in event_snapshot:
+            for system_task in system_task_map.get(type(msg), []):
+                tasks.append(
+                    ExecutionTask(
+                        system_task.system_fn,
+                        msg,
+                        system_task.priority,
+                        ExecuteHookContext(
+                            tick=self.tick_counter,
+                            context=system_task.system_fn.system_context,  # type: ignore
+                            payload={},
+                        ),
+                    )
+                )
+
+        # 处理Signal消息
+        for msg_cls in signal_snapshot:
+            for system_task in system_task_map.get(msg_cls, []):
+                tasks.append(
+                    ExecutionTask(
+                        system_task.system_fn,
+                        self.stage.peek_signal(msg_cls),
+                        system_task.priority,
+                        ExecuteHookContext(
+                            tick=self.tick_counter,
+                            context=system_task.system_fn.system_context,  # type: ignore
+                            payload={},
+                        ),
+                    )
+                )
+
+        return tasks
+
+    def execute_tasks(
+        self,
+        tasks: list[ExecutionTask],
+    ):
+        # 按照优先级排序
+        tasks.sort(key=lambda task: task.priority, reverse=True)
+
+        for task in tasks:
+            try:
+                task.execute(self.before_execute_hooks, self.after_execute_hooks)
+            except Exception as e:
+                MessageWriter.error(
+                    e,
+                    f"[virid Dispatcher]: System Error. \n"
+                    + f"SystemLocation: {task.system_fn.__name__} \n"
+                    + f"MessageName: {type(task.message).__name__} \n"
+                    + f"MessageData: {task.message} \n",
+                )
+
+    def prepare_snapshot(self) -> tuple[list[type[SingleMessage]], list[EventMessage]]:
+        self.stage.flip()
+        signal_snapshot = list(self.dirty_signal_types.keys())
+        event_snapshot = self.event_queue[:]
+        self.dirty_signal_types.clear()
+        self.event_queue.clear()
+        return signal_snapshot, event_snapshot
+
+    def clear(
+        self,
+    ):
+        self.stage.clear_signal()
+        self.stage.clear_event()
+
+    def execute_hooks(self, tick_hooks: list[TickHook]):
+        hooks_context = TickHookContext(
+            tick=self.tick_counter, time=time.time(), payload=self.tick_payload
+        )
+        try:
+            for hook in tick_hooks:
+                hook(hooks_context)
+        except Exception as e:
+            MessageWriter.error(e, f"[Virid Dispatcher]: Tick Hook Error.\n")

virid_core-0.1.0/src/virid/core/core/engine.py

@@ -0,0 +1,83 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from typing import Callable, Type
+from .message import BaseMessage
+from .io import MessageWriter, activate_publisher
+from .registry import Registry
+from .dispatcher import Dispatcher
+from .interface import TickHook, ExecuteHook, Middleware
+
+
+class Engine:
+    def __init__(self):
+        self.registry = Registry()
+        self.dispatcher = Dispatcher()
+        self.middlewares: list[Middleware] = []
+        activate_publisher(self)
+
+    def use_middleware(self, middleware: Middleware):
+        self.middlewares.append(middleware)
+
+    def dispatch(self, message: BaseMessage):
+        """将消息放入缓冲区，等待调度器处理。"""
+
+        # 检查消息类型
+        if not isinstance(message, BaseMessage):
+            MessageWriter.error(
+                TypeError(
+                    f"[Virid Dispatch] TypeError: Only instances of BaseMessage can be dispatched, got: {type(message).__name__}"
+                )
+            )
+
+        def final_action() -> None:
+            # 检查是否有对应的处理函数
+            message_class = type(message)
+            if message_class not in self.registry.system_task_map:
+                MessageWriter.warn(
+                    f"[Virid Dispatch] No System Found: No system function is registered for message: {message_class.__name__}"
+                )
+
+            self.dispatcher.mark_dirty(message)
+
+        self.pipeline(message, final_action)
+
+    def tick(self):
+        """调度器调用，处理缓冲区中的消息。"""
+        self.dispatcher.tick(self.registry.system_task_map)
+
+    def register(
+        self,
+        message_class: Type[BaseMessage],
+        system_fn: Callable,
+        priority: int = 0,
+    ):
+        """注册System并返回一个无参的卸载函数。"""
+        return self.registry.register(message_class, system_fn, priority)
+
+    def pipeline(self, message: BaseMessage, final_action: Callable[[], None]):
+        def next_step(idx):
+            if idx < len(self.middlewares):
+                self.middlewares[idx](message, lambda: next_step(idx + 1))
+            else:
+                final_action()
+
+        next_step(0)
+
+    def on_before_tick(self, hook: TickHook, front: bool = False):
+        self.dispatcher.add_before_tick_hook(hook, front)
+
+    def on_after_tick(self, hook: TickHook, front: bool = False):
+        self.dispatcher.add_after_tick_hook(hook, front)
+
+    def on_before_execute(
+        self, message_type: Type[BaseMessage], hook: ExecuteHook, front: bool = False
+    ):
+        self.dispatcher.add_before_execute_hook(message_type, hook, front)
+
+    def on_after_execute(
+        self, message_type: Type[BaseMessage], hook: ExecuteHook, front: bool = False
+    ):
+        self.dispatcher.add_after_execute_hook(message_type, hook, front)

virid_core-0.1.0/src/virid/core/core/interface.py

@@ -0,0 +1,59 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from dataclasses import dataclass
+from typing import Any, Callable, TypeVar
+from .message import BaseMessage
+T = TypeVar("T")
+
+@dataclass
+class SystemContext:
+    """
+    系统上下文，包含系统执行时的相关信息
+    """
+
+    params: list[Any]
+    message_type: type[BaseMessage]
+    method_name: str
+    original_method: Callable
+
+
+@dataclass
+class SystemTask:
+    """
+    系统任务，包含系统函数和相关信息
+    """
+
+    system_fn: Callable
+    priority: int
+
+
+@dataclass
+class TickHookContext:
+    """
+    TickHook 上下文，包含 tickHook 的相关信息
+    """
+
+    tick: int
+    time: float
+    payload: dict[str, Any]
+
+
+@dataclass
+class ExecuteHookContext:
+    """
+    ExecuteHook 上下文，包含 executeHook 的相关信息
+    """
+
+    tick: int
+    context: SystemContext
+    payload: dict[str, Any]
+
+
+ExecuteHook = Callable[[T, ExecuteHookContext, bool], None]
+
+TickHook = Callable[[TickHookContext], None]
+
+Middleware = Callable[[BaseMessage, Callable[[], None]], None]

virid_core-0.1.0/src/virid/core/core/io.py

@@ -0,0 +1,62 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from typing import Type, TypeVar, Any
+from .message import BaseMessage, ErrorMessage, WarnMessage, InfoMessage
+
+T = TypeVar("T", bound=BaseMessage)
+
+
+publisher: Any = None
+
+
+def activate_publisher(dispatcher_instance: Any):
+    """供Dispatcher初始化时调用，延迟初始化"""
+    global publisher
+    publisher = dispatcher_instance
+
+
+def publish(message: BaseMessage) -> None:
+    if publisher is None:
+        raise RuntimeError(
+            "[Virid MessageWriter] RuntimeError: No active dispatcher found. Please ensure that a dispatcher is activated before dispatching messages."
+        )
+    publisher.dispatch(message)
+
+
+class MessageWriter:
+    """
+    消息写入器。
+    """
+
+    @staticmethod
+    def write(target: Type[T] | T, *args, **kwargs) -> None:
+        """
+        核心写入入口
+        """
+        if isinstance(target, type) and issubclass(target, BaseMessage):
+            # 动态实例化，完美透传所有位置参数与关键字参数
+            instance = target(*args, **kwargs)
+        elif isinstance(target, BaseMessage):
+            instance = target
+        else:
+            raise TypeError(
+                f"[Virid MessageWriter] TypeError: Only BaseMessage subclasses or instances are allowed to be written, got: {type(target).__name__}"
+            )
+
+        # 统一收拢到惰性分发代理
+        publish(instance)
+
+    @staticmethod
+    def error(error: Exception, context: str = "") -> None:
+        MessageWriter.write(ErrorMessage(error=error, context=context))
+
+    @staticmethod
+    def warn(context: str) -> None:
+        MessageWriter.write(WarnMessage(context=context))
+
+    @staticmethod
+    def info(context: str) -> None:
+        MessageWriter.write(InfoMessage(context=context))

virid_core-0.1.0/src/virid/core/core/message.py

@@ -0,0 +1,46 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from dataclasses import dataclass
+from typing import TypeVar, Callable, ParamSpec
+
+# 定义参数规格变量和类型变量
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@dataclass
+class BaseMessage:
+    @classmethod
+    def send(cls: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> None:
+        # 这里的 cls 实际上就是构造函数本身
+        instance = cls(*args, **kwargs)
+        from .io import MessageWriter
+
+        MessageWriter.write(instance)  # type: ignore
+
+
+@dataclass
+class SingleMessage(BaseMessage): ...
+
+
+@dataclass
+class EventMessage(BaseMessage): ...
+
+
+@dataclass
+class InfoMessage(EventMessage):
+    context: str
+
+
+@dataclass
+class WarnMessage(EventMessage):
+    context: str
+
+
+@dataclass
+class ErrorMessage(EventMessage):
+    error: Exception
+    context: str = ""

virid_core-0.1.0/src/virid/core/core/registry.py

@@ -0,0 +1,63 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from typing import Type, Callable
+from .message import BaseMessage
+from .io import MessageWriter
+from .interface import SystemTask
+
+
+class Registry:
+    def __init__(self):
+        self.system_task_map: dict[Type[BaseMessage], list[SystemTask]] = {}
+
+    def register(
+        self,
+        message_class: Type[BaseMessage],
+        system_fn: Callable,
+        priority: int = 0,
+    ) -> Callable[[], None]:
+        """
+        注册系统函数并返回一个无参的卸载函数。
+        """
+        # 初始化消息桶
+        if message_class not in self.system_task_map:
+            self.system_task_map[message_class] = []
+
+        systems = self.system_task_map[message_class]
+
+        # 检查重复注册
+        if system_fn in systems:
+            func_name = getattr(system_fn, "__name__", "Anonymous")
+            MessageWriter.warn(
+                f"[virid Warn] System function is already registered for this message type!\n"
+                f"Message Class: {message_class.__name__}\n"
+                f"Function Name: {func_name}\n"
+            )
+            return lambda: None
+
+        # 追加注册到桶中
+        systems.append(SystemTask(system_fn=system_fn, priority=priority))
+
+        # 返回一个闭包卸载函数
+        def unregister() -> None:
+            current_systems = self.system_task_map.get(message_class)
+            if current_systems is not None:
+                # 寻找匹配的系统索引（对标 JS 的 findIndex）
+                index = next(
+                    (
+                        i
+                        for i, s in enumerate(current_systems)
+                        if s.system_fn == system_fn
+                    ),
+                    -1,
+                )
+                if index != -1:
+                    current_systems.pop(index)
+                    # 如果这个消息类型没有任何系统监听了，彻底删除 key，保持内存干净
+                    if len(current_systems) == 0:
+                        del self.system_task_map[message_class]
+
+        return unregister

virid_core-0.1.0/src/virid/core/core/stage.py

@@ -0,0 +1,75 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from typing import Type
+from .message import BaseMessage, SingleMessage, EventMessage
+from .io import MessageWriter
+
+
+class Stage:
+    def __init__(self):
+        # SingleMessage缓冲池
+        self._signal_active: dict[Type[SingleMessage], list[SingleMessage]] = {}
+        self._signal_staging: dict[Type[SingleMessage], list[SingleMessage]] = {}
+
+        # EventMessage缓冲池
+        self._event_active: list[EventMessage] = []
+        self._event_staging: list[EventMessage] = []
+
+    def push(self, event: BaseMessage):
+        """根据消息继承范式，物理隔离分流"""
+        if isinstance(event, SingleMessage):
+            msg_cls = type(event)
+            if msg_cls not in self._signal_staging:
+                self._signal_staging[msg_cls] = []
+            self._signal_staging[msg_cls].append(event)
+
+        elif isinstance(event, EventMessage):
+            self._event_staging.append(event)
+
+        else:
+            MessageWriter.error(
+                TypeError(
+                    f"[Virid Buffer] TypeError: Message {type(event).__name__} must inherit from SingleMessage or EventMessage"
+                )
+            )
+
+    def flip(self):
+        """
+        翻转双缓冲区：
+        """
+        # 物理隔离：Active 指向当前轮的快照，Staging 重置为全新容器
+        self._signal_active = self._signal_staging
+        self._signal_staging = {}
+
+        self._event_active = self._event_staging
+        self._event_staging = []
+
+    def peek_signal(self, msg_cls: Type[SingleMessage]) -> list[SingleMessage]:
+        """
+        获取指定消息类型的缓冲池中的消息
+        """
+        return self._signal_active.get(msg_cls, [])
+
+    def clear_signal(self) -> None:
+        """
+        清空指定消息类型的缓冲池
+        """
+        self._signal_active.clear()
+
+    def clear_event(self) -> None:
+        """
+        清空事件消息缓冲池
+        """
+        self._event_active.clear()
+
+    def reset(self):
+        """
+        重置整个缓冲区，清空所有消息
+        """
+        self._signal_active = {}
+        self._signal_staging = {}
+        self._event_active = []
+        self._event_staging = []

virid_core-0.1.0/src/virid/core/decorators/__init__.py

@@ -0,0 +1,6 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+from .decorator import *

virid_core-0.1.0/src/virid/core/decorators/decorator.py

@@ -0,0 +1,208 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+import inspect
+from functools import wraps
+from typing import Any, Callable, Type, Optional, get_origin, get_args
+
+from ..core.interface import SystemContext
+from ..core.message import BaseMessage, EventMessage, SingleMessage
+from ..core.io import MessageWriter
+from ..app import virid_app
+
+
+def handle_result(res: Any) -> None:
+    """统一处理返回值，支持链式反应，平铺列表投递"""
+    if res is None:
+        return
+    # 如果返回的是列表/元组，平铺处理
+    messages = res if isinstance(res, (list, tuple)) else [res]
+
+    for m in messages:
+        if isinstance(m, BaseMessage):
+            MessageWriter.write(m)
+        else:
+            MessageWriter.warn(
+                f"[virid HandleResult] Invalid Return Type: Expected BaseMessage or List[BaseMessage], got {type(m).__name__}. Ignored."
+            )
+
+
+def system(
+    message_type: Optional[Type[BaseMessage]] = None,
+    priority: int = 0,
+    singleton: bool = True,
+):
+    """
+    系统装饰器
+    :param message_type: 监听的消息类型 (可选，如果不传会自动从参数的类型注解推断)
+    :param priority: 优先级，数值越大越早执行
+    :param singleton: 是否为单例模式。True 传入单条消息；False 传入整个消息列表
+    """
+
+    # 提前校验 decorator 参数
+    if message_type is not None and not (
+        isinstance(message_type, type) and issubclass(message_type, BaseMessage)
+    ):
+        raise TypeError(
+            f"[Virid System] TypeError: @System requires a subclass of BaseMessage, got: {message_type}"
+        )
+
+    def decorator(func: Callable) -> Callable:
+        sig = inspect.signature(func)
+        params = list(sig.parameters.values())
+
+        if not params:
+            raise ValueError(
+                f"[Virid System] Parameter Loss: '{func.__name__}' must have at least one parameter for receiving messages!"
+            )
+
+        # 支持泛型解包的参数解析器
+        msg_param_name = None
+        inferred_msg_type = None
+
+        for param in params:
+            annotation = param.annotation
+            if not annotation or annotation == inspect.Parameter.empty:
+                continue
+
+            target_type = None
+            origin = get_origin(annotation)
+
+            # 如果是泛型列表（如 list[DecreaseMessage] 或 List[DecreaseMessage]）
+            if origin is list:
+                args = get_args(annotation)
+                if (
+                    args
+                    and isinstance(args[0], type)
+                    and issubclass(args[0], BaseMessage)
+                ):
+                    target_type = args[0]  # 提取出里面的 DecreaseMessage 真实类型
+
+            # 普通类型
+            elif isinstance(annotation, type) and issubclass(annotation, BaseMessage):
+                target_type = annotation
+
+            # 如果找到了消息参数
+            if target_type is not None:
+                if msg_param_name is not None:
+                    raise ValueError(
+                        f"[Virid System] Multiple Messages: '{func.__name__}' cannot have multiple BaseMessage parameters."
+                    )
+                msg_param_name = param.name
+                inferred_msg_type = target_type
+
+        # 确定最终的消息类型 (装饰器明确指定优先 > 参数类型推断)
+        final_message_type = message_type or inferred_msg_type
+
+        if final_message_type is None:
+            raise ValueError(
+                f"[Virid System] Parameter Loss: Cannot infer message type for '{func.__name__}'. "
+                f"Declare via @System(MyMessage) or type hint (e.g., def my_system(msg: MyMessage):)."
+            )
+
+        # 运行时警告：类型冲突
+        if (
+            message_type
+            and inferred_msg_type
+            and not issubclass(inferred_msg_type, message_type)
+        ):
+            MessageWriter.warn(
+                f"[virid System] Type Mismatch in '{func.__name__}': Decorator expects {message_type.__name__}, "
+                f"but parameter expects {inferred_msg_type.__name__}."
+            )
+
+        # 闭包缓存变量
+        is_initialized = False
+        cached_components: list[Any] = [None] * len(params)
+
+        # 根据 singleton 开关，精准重组参数负载
+        def build_args(message: Any) -> list:
+            """构建函数入参：将消息实体和可能存在的依赖注入按顺序排好"""
+            nonlocal is_initialized, cached_components
+
+            is_incoming_list = isinstance(message, list)
+
+            # 加工最终要塞给函数对应的参数负载
+            if singleton:
+                # 单例模式：函数只想要单条消息
+                true_message = message[-1] if is_incoming_list else message
+
+                # 运行时类型校验
+                if not isinstance(true_message, final_message_type):
+                    raise TypeError(
+                        f"[virid System] Type Mismatch: Expected {final_message_type.__name__}, but received {type(true_message).__name__}"
+                    )
+                payload = true_message
+            else:
+                # 批处理模式：函数想要一个消息列表
+                true_messages_list = message if is_incoming_list else [message]
+
+                # 运行时对列表内的元素进行类型校验
+                if true_messages_list and not isinstance(
+                    true_messages_list[0], final_message_type
+                ):
+                    raise TypeError(
+                        f"[virid System] Type Mismatch: Expected elements of {final_message_type.__name__}, but received {type(true_messages_list[0]).__name__}"
+                    )
+                payload = true_messages_list
+
+            # 首次命中去容器捞取并缓存所有 Component 单例
+            if not is_initialized:
+                for idx, param in enumerate(params):
+                    if param.name != msg_param_name:
+                        # 只有在第一次运行时，才去全局容器里捞
+                        inject_instance = virid_app.get(param.annotation)
+                        if inject_instance is None:
+                            raise RuntimeError(
+                                f"[virid System] Unknown Inject Data Types: '{param.name}' ({param.annotation.__name__}) "
+                                f"is not registered in the container for '{func.__name__}'!"
+                            )
+                        cached_components[idx] = inject_instance
+                # 标记初始化完成
+                is_initialized = True
+
+            # 高频重组参数
+            call_args = []
+            for idx, param in enumerate(params):
+                if param.name == msg_param_name:
+                    call_args.append(payload)
+                else:
+                    # 直接从闭包里的数组中拿
+                    call_args.append(cached_components[idx])
+
+            return call_args
+
+        # 包装函数 (同步)
+        @wraps(func)
+        def wrapped_system(message: EventMessage | list[SingleMessage]):
+            # 动态组装参数
+            call_args = build_args(message)
+            result = func(*call_args)
+            # 解析并处理返回值（支持链式反应）
+            handle_result(result)
+            return result
+
+        # 给包装后的函数挂载上下文信息
+        wrapped_system.system_context: SystemContext = {  # type: ignore
+            "params": [p.annotation for p in params],
+            "message_type": final_message_type,
+            "method_name": func.__name__,
+            "original_method": func,
+        }
+
+        # 自动向全局调度中心登记
+        virid_app.register(final_message_type, wrapped_system, priority)
+
+        return wrapped_system
+
+    return decorator
+
+
+def component():
+    def bind_component(cls):
+        cls.__virid_component__ = True
+        return cls
+
+    return bind_component

virid_core-0.1.0/src/virid/core/util.py

@@ -0,0 +1,111 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+
+from .core.message import ErrorMessage, InfoMessage, WarnMessage
+from .core.interface import SystemContext
+from logging import getLogger
+import logging
+
+switch = True
+
+
+def toggle_utils(val: bool) -> None:
+    global switch
+    switch = val
+
+
+class ViridFormatter(logging.Formatter):
+    # 颜色与样式转义码
+    RESET = "\x1b[0m"
+    BOLD = "\x1b[1m"
+    RED = "\x1b[31m"
+    GREEN = "\x1b[32m"
+    YELLOW = "\x1b[33m"
+    MAGENTA = "\x1b[35m"
+    CYAN = "\x1b[36m"
+    GRAY = "\x1b[90m"
+
+    def format(self, record):
+        if record.levelno == logging.INFO:
+            header = f"{self.GREEN}{self.BOLD} ✔ [Virid Info] {self.RESET}"
+            record.msg = (
+                f"{header}{self.GRAY}Global Info Caught:{self.RESET}\n"
+                f"  {self.GREEN}Details:{self.RESET} {record.msg}"
+            )
+        elif record.levelno == logging.WARNING:
+            header = f"{self.YELLOW}{self.BOLD} ⚠ [Virid Warn] {self.RESET}"
+            context = f"{self.CYAN}{record.msg}{self.RESET}"
+            record.msg = (
+                f"{header}{self.GRAY}Global Warn Caught:{self.RESET}\n"
+                f"  {self.YELLOW}Context:{self.RESET} {context}"
+            )
+        elif record.levelno == logging.ERROR:
+            header = f"{self.RED}{self.BOLD} ✖ [Virid Error] {self.RESET}"
+
+            if "context" in getattr(record, "msg_type", ""):
+                record.msg = f"  {self.RED}Context:{self.RESET} {self.MAGENTA}{record.msg}{self.RESET}"
+            else:
+                record.msg = (
+                    f"{header}{self.GRAY}Global Error Caught:{self.RESET}\n"
+                    f"  {self.RED}Details:{self.RESET} {record.msg}"
+                )
+
+        return super().format(record)
+
+
+logging.basicConfig(level=logging.INFO)
+handler = logging.root.handlers[0]
+handler.setFormatter(ViridFormatter("%(message)s"))
+logger = getLogger(__name__)
+
+
+def error(message: ErrorMessage) -> None:
+    if switch is False:
+        return
+    logger.error(message.error, extra={"msg_type": "error"})
+    logger.error(message.context, extra={"msg_type": "context"})
+
+
+error.system_context: SystemContext = {  # type: ignore
+    "params": [ErrorMessage],
+    "message_type": ErrorMessage,
+    "method_name": error.__name__,
+    "original_method": error,
+}
+
+
+def info(message: InfoMessage) -> None:
+    if switch is False:
+        return
+    logger.info(message.context)
+
+
+info.system_context: SystemContext = {  # type: ignore
+    "params": [InfoMessage],
+    "message_type": InfoMessage,
+    "method_name": info.__name__,
+    "original_method": info,
+}
+
+
+def warn(message: WarnMessage) -> None:
+    if switch is False:
+        return
+    logger.warning(message.context)
+
+
+warn.system_context: SystemContext = {  # type: ignore
+    "params": [WarnMessage],
+    "message_type": WarnMessage,
+    "method_name": warn.__name__,
+    "original_method": warn,
+}
+
+
+def register_base_handlers(virid) -> None:
+    virid.register(ErrorMessage, error)
+    virid.register(InfoMessage, info)
+    virid.register(WarnMessage, warn)

virid_core-0.1.0/tests/core/throughput.py

@@ -0,0 +1,75 @@
+"""
+Copyright (c) 2026-present Ailrid.
+Licensed under the Apache License, Version 2.0.
+Project: Virid
+"""
+
+import time
+from dataclasses import dataclass
+from virid.core import (
+    component,
+    EventMessage,
+    system,
+    create_virid,
+)
+
+virid = create_virid()
+
+
+@component()
+@dataclass
+class BenchCounter:
+    value: int = 0
+
+
+virid.bind(BenchCounter)
+
+class BenchMessage(EventMessage): ...
+
+
+# 用来在外部验证系统确实执行了正确次数的全局计数器
+actual_run_count = 0
+
+
+@system(message_type=BenchMessage)
+def benchmark(counter: BenchCounter) -> None:
+    global actual_run_count
+    counter.value += 1
+    actual_run_count += 1
+
+
+if __name__ == "__main__":
+    # 压测规模：跑 200,000 次完整的 [Send -> Tick -> DI -> Execute] 大循环
+    TOTAL_ITERATIONS = 200_000
+
+    print("=" * 60)
+    print(" 开始 Virid 框架全链路集成压测 (Full Loop Benchmark)...")
+    print(f" 压测规模: {TOTAL_ITERATIONS:,} 次 完整框架调度闭环")
+    print("=" * 60)
+
+    # 预热第一帧
+    BenchMessage.send()
+    virid.tick()
+
+    # 重置计数器，开始正式全链路计时
+    actual_run_count = 0
+    start_time = time.perf_counter()
+
+    # 核心吞吐量高频循环
+    for _ in range(TOTAL_ITERATIONS):
+        BenchMessage.send()
+        virid.tick()
+
+    end_time = time.perf_counter()
+
+    # 性能结果统计
+    elapsed_time = end_time - start_time
+    throughput = TOTAL_ITERATIONS / elapsed_time
+
+    print(f"【压测结果】")
+    print(f" 完整跑完耗时 : {elapsed_time:.4f} 秒")
+    print(f" 框架全链路吞吐: {throughput:,.2f} 次全循环/秒 (Ticks/sec)")
+    print("-" * 60)
+    print(f"【确定性状态校验】")
+    print(f" 系统实际触发次数: {actual_run_count:,} 次 (预期: {TOTAL_ITERATIONS:,})")
+    print("=" * 60)