chore(release)： v0.1.1-alpha

##前端美化和bug修复
#### 💄 美化
- **前端美化**：对于整个前端效果进行了重新设计，现在的前端看起来会更立体。

#### 🐛 修复
- **前端演示**：修复了前端展示workflow列表的bug，但是workflow的具体条目显示由于序列化导致仍然有问题。 
- **密钥修复**：对于secret_key现在在使用默认情况时，会强制生成一个安全的密钥。

pretor/core/api/__init__.py

@@ -24,6 +24,7 @@ from pretor.api.provider import provider_router
 from pretor.api.resource import resource_router
 from pretor.api.cluster import cluster_router
 from pretor.api.agent import agent_router
+from pretor.api.workflow import workflow_router
 from pretor.utils.error import (
     DemandError, ModelNotExistError, UserError,
     UserNotExistError, UserPasswordError, ProviderError,
@@ -40,6 +41,7 @@ app.include_router(provider_router)  # 供应商路径
 app.include_router(resource_router)  # 资源路径
 app.include_router(cluster_router)  # 集群信息路径
 app.include_router(agent_router)  # agent路径
+app.include_router(workflow_router)  # workflow路径
 
 @app.exception_handler(UserNotExistError)
 async def user_not_exist_handler(request: Request, exc: UserNotExistError):

pretor/core/database/database_exception.py

@@ -19,7 +19,14 @@ from pretor.utils.error import UserNotExistError
 from pretor.utils.logger import get_logger
 logger = get_logger('database_exception')
 def database_exception(func):
+    """执行与 database exception 相关的核心业务流转操作。
+    该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+    Args:        func: 参与 database exception 逻辑运算或数据构建的上下文依赖对象。
+    Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
     async def wrapper(*args, **kwargs):
+        """执行与 wrapper 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             return await func(*args, **kwargs)
         except ValidationError as e:

pretor/core/database/module/event.py

@@ -0,0 +1,45 @@
+from sqlmodel import select
+from typing import List, Optional
+from pretor.core.database.table.event import EventRecord
+from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
+
+class EventDatabase:
+    def __init__(self, async_session_maker: async_sessionmaker[AsyncSession]):
+        self.async_session_maker = async_session_maker
+
+    async def upsert_event(self, trace_id: str, event_data_json: str) -> EventRecord:
+        async with self.async_session_maker() as session:
+            statement = select(EventRecord).where(EventRecord.trace_id == trace_id)
+            results = await session.execute(statement)
+            record = results.scalar_one_or_none()
+            if record:
+                record.event_data_json = event_data_json
+            else:
+                record = EventRecord(trace_id=trace_id, event_data_json=event_data_json)
+                session.add(record)
+            await session.commit()
+            await session.refresh(record)
+            return record
+
+    async def get_event(self, trace_id: str) -> Optional[EventRecord]:
+        async with self.async_session_maker() as session:
+            statement = select(EventRecord).where(EventRecord.trace_id == trace_id)
+            results = await session.execute(statement)
+            return results.scalar_one_or_none()
+
+    async def get_all_events(self) -> List[EventRecord]:
+        async with self.async_session_maker() as session:
+            statement = select(EventRecord)
+            results = await session.execute(statement)
+            return results.scalars().all()
+
+    async def delete_event(self, trace_id: str) -> bool:
+        async with self.async_session_maker() as session:
+            statement = select(EventRecord).where(EventRecord.trace_id == trace_id)
+            results = await session.execute(statement)
+            record = results.scalar_one_or_none()
+            if record:
+                await session.delete(record)
+                await session.commit()
+                return True
+            return False

pretor/core/database/module/individual.py

@@ -20,11 +20,16 @@ from pretor.core.database.database_exception import database_exception
 from ulid import ULID
 
 class IndividualDatabase:
+    """IndividualDatabase 核心组件类。
+    这是一个数据库操作层 (DAO/Repository) 封装类，专注于处理实体模型与关系型数据库表之间的映射。它将复杂的 SQL 查询、跨表 Join 和事务回滚逻辑进行了高级抽象，向上层服务暴露简洁的数据读写接口。    """
     def __init__(self, async_session_maker):
         self.async_session_maker = async_session_maker
 
     @database_exception
     async def add_worker_individual(self, **kwargs) -> WorkerIndividual:
+        """创建并持久化新的 worker individual 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Returns:         (WorkerIndividual): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             agent_id = str(ULID())
             individual = WorkerIndividual(agent_id=agent_id, **kwargs)
@@ -35,6 +40,10 @@ class IndividualDatabase:
 
     @database_exception
     async def get_worker_individual(self, agent_id: str) -> Optional[WorkerIndividual]:
+        """检索并获取特定的 worker individual 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:         (Optional[WorkerIndividual]): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             statement = select(WorkerIndividual).where(WorkerIndividual.agent_id == agent_id)
             results = await session.execute(statement)
@@ -42,6 +51,10 @@ class IndividualDatabase:
 
     @database_exception
     async def get_worker_individual_list(self, owner_id: str) -> List[WorkerIndividual]:
+        """检索并获取特定的 worker individual list 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        owner_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 owner 实例。
+        Returns:         (List[WorkerIndividual]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         async with self.async_session_maker() as session:
             statement = select(WorkerIndividual).where(WorkerIndividual.owner_id == owner_id)
             results = await session.execute(statement)
@@ -49,6 +62,10 @@ class IndividualDatabase:
 
     @database_exception
     async def update_worker_individual(self, agent_id: str, **kwargs) -> Optional[WorkerIndividual]:
+        """对现有的 worker individual 进行状态更新或属性覆盖。
+        基于增量变更原则，合并最新的配置或数据，并触发相关依赖组件的缓存刷新或事件通知。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:         (Optional[WorkerIndividual]): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             statement = select(WorkerIndividual).where(WorkerIndividual.agent_id == agent_id)
             results = await session.execute(statement)
@@ -65,6 +82,10 @@ class IndividualDatabase:
 
     @database_exception
     async def delete_worker_individual(self, agent_id: str) -> bool:
+        """安全地移除或注销 worker individual。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:         (bool): 一个布尔型结果标志，明确返回 True 表示该操作成功应用或条件达成，False 则表示失败或被拒绝。    """
         async with self.async_session_maker() as session:
             statement = select(WorkerIndividual).where(WorkerIndividual.agent_id == agent_id)
             results = await session.execute(statement)
@@ -77,6 +98,9 @@ class IndividualDatabase:
 
     @database_exception
     async def get_all_worker_individual(self) -> List[WorkerIndividual]:
+        """检索并获取特定的 all worker individual 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:         (List[WorkerIndividual]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         async with self.async_session_maker() as session:
             statement = select(WorkerIndividual)
             results = await session.execute(statement)

pretor/core/database/module/memory.py

@@ -1,68 +0,0 @@
-#  Copyright 2026 zhaoxi826
-#
-#  Licensed under the Apache License, Version 2.0 (the "License");
-#  you may not use this file except in compliance with the License.
-#  You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#  Unless required by applicable law or agreed to in writing, software
-#  distributed under the License is distributed on an "AS IS" BASIS,
-#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#  See the License for the specific language governing permissions and
-#  limitations under the License.
-
-from sqlmodel import SQLModel, Field, select
-from typing import Optional, List
-import json
-
-class WorkflowRecord(SQLModel, table=True):
-    id: Optional[int] = Field(default=None, primary_key=True)
-    workflow_id: str = Field(index=True)
-    workflow_data_json: str
-
-class MemoryRecord(SQLModel, table=True):
-    id: Optional[int] = Field(default=None, primary_key=True)
-    memory_text: str
-    embedding: List[float] = Field(sa_column_kwargs={"type_": "VECTOR"})  # Requires pgvector extension setup in DB
-
-class MemoryRAG:
-    def __init__(self, async_session_maker):
-        self.async_session_maker = async_session_maker
-
-    async def save_workflow(self, workflow_id: str, workflow_data: dict):
-        async with self.async_session_maker() as session:
-            record = WorkflowRecord(
-                workflow_id=workflow_id,
-                workflow_data_json=json.dumps(workflow_data)
-            )
-            session.add(record)
-            await session.commit()
-            await session.refresh(record)
-            return record
-
-    async def get_workflow(self, workflow_id: str):
-        async with self.async_session_maker() as session:
-            statement = select(WorkflowRecord).where(WorkflowRecord.workflow_id == workflow_id)
-            results = await session.execute(statement)
-            record = results.scalar_one_or_none()
-            if record:
-                return json.loads(record.workflow_data_json)
-            return None
-
-    async def add_memory(self, memory_text: str, embedding: List[float]):
-        async with self.async_session_maker() as session:
-            record = MemoryRecord(memory_text=memory_text, embedding=embedding)
-            session.add(record)
-            await session.commit()
-            await session.refresh(record)
-            return record
-
-    async def retrieve_memory(self, query_embedding: List[float], limit: int = 5):
-        # Requires pgvector specific operations; simplified retrieval simulation here
-        async with self.async_session_maker() as session:
-            # A true pgvector query would use an ORDER BY using `<->` operator
-            # e.g. statement = select(MemoryRecord).order_by(MemoryRecord.embedding.l2_distance(query_embedding)).limit(limit)
-            statement = select(MemoryRecord).limit(limit)
-            results = await session.execute(statement)
-            return results.all()

pretor/core/database/module/provider.py

@@ -19,11 +19,16 @@ from sqlmodel import select
 from pretor.core.database.database_exception import database_exception
 
 class ProviderDatabase:
+    """ProviderDatabase 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     def __init__(self, async_session_maker):
         self.async_session_maker = async_session_maker
 
     @database_exception
     async def get_provider(self) -> List[Provider]:
+        """检索并获取特定的 provider 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:         (List[Provider]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         async with self.async_session_maker() as session:
             statement = select(Provider)
             results = await session.execute(statement)
@@ -37,6 +42,9 @@ class ProviderDatabase:
 
     @database_exception
     async def add_provider(self, **kwargs) -> None:
+        """创建并持久化新的 provider 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             provider = Provider(**kwargs)
             session.add(provider)
@@ -44,6 +52,10 @@ class ProviderDatabase:
 
     @database_exception
     async def delete_provider(self, provider_id: str) -> None:
+        """安全地移除或注销 provider。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        provider_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider 实例。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             provider = await session.get(Provider, provider_id)
             if provider is not None:
@@ -52,6 +64,10 @@ class ProviderDatabase:
 
     @database_exception
     async def update_provider(self, provider_id: str, **kwargs) -> Provider:
+        """对现有的 provider 进行状态更新或属性覆盖。
+        基于增量变更原则，合并最新的配置或数据，并触发相关依赖组件的缓存刷新或事件通知。
+        Args:        provider_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             provider = await session.get(Provider, provider_id)
             if provider is not None:

pretor/core/database/module/system_node.py

@@ -18,11 +18,17 @@ from typing import List, Optional
 from pretor.core.database.database_exception import database_exception
 
 class SystemNodeDatabase:
+    """SystemNodeDatabase 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     def __init__(self, async_session_maker):
         self.async_session_maker = async_session_maker
 
     @database_exception
     async def upsert_system_node_config(self, node_name: str, provider_title: str, model_id: str, tools: Optional[List[str]] = None) -> SystemNodeConfig:
+        """执行与 upsert system node config 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        node_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        provider_title (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。        model_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 model 实例。        tools (Optional[List[str]]): 控制逻辑流向的具体字符串参数，指定了期望的 tools 内容。
+        Returns:         (SystemNodeConfig): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             statement = select(SystemNodeConfig).where(SystemNodeConfig.node_name == node_name)
             results = await session.execute(statement)
@@ -41,6 +47,9 @@ class SystemNodeDatabase:
 
     @database_exception
     async def get_all_system_node_configs(self) -> List[SystemNodeConfig]:
+        """检索并获取特定的 all system node configs 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:         (List[SystemNodeConfig]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         async with self.async_session_maker() as session:
             statement = select(SystemNodeConfig)
             results = await session.execute(statement)
@@ -48,6 +57,10 @@ class SystemNodeDatabase:
 
     @database_exception
     async def get_system_node_config(self, node_name: str) -> Optional[SystemNodeConfig]:
+        """检索并获取特定的 system node config 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        node_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:         (Optional[SystemNodeConfig]): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             statement = select(SystemNodeConfig).where(SystemNodeConfig.node_name == node_name)
             results = await session.execute(statement)

pretor/core/database/module/user.py

@@ -20,11 +20,17 @@ from pretor.core.database.table.user import UserAuthority
 from pretor.utils.access import Accessor
 
 class AuthDatabase:
+    """AuthDatabase 核心组件类。
+    这是一个数据库操作层 (DAO/Repository) 封装类，专注于处理实体模型与关系型数据库表之间的映射。它将复杂的 SQL 查询、跨表 Join 和事务回滚逻辑进行了高级抽象，向上层服务暴露简洁的数据读写接口。    """
     def __init__(self, async_session_maker):
         self.async_session_maker = async_session_maker
 
     @database_exception
     async def add_user(self, user_name: str, hashed_password: str) -> User:
+        """创建并持久化新的 user 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        hashed_password (str): 控制逻辑流向的具体字符串参数，指定了期望的 hashed password 内容。
+        Returns:         (User): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         from ulid import ULID
         async with self.async_session_maker() as session:
             # Check if any users exist
@@ -49,6 +55,10 @@ class AuthDatabase:
 
     @database_exception
     async def change_password(self, user_name, old_password, new_password) -> User:
+        """执行与 change password 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        user_name: 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        old_password: 参与 change password 逻辑运算或数据构建的上下文依赖对象。        new_password: 参与 change password 逻辑运算或数据构建的上下文依赖对象。
+        Returns:         (User): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             statement = select(User).where(User.user_name == user_name)
             results = await session.execute(statement)
@@ -65,6 +75,10 @@ class AuthDatabase:
 
     @database_exception
     async def delete_user(self, user_name: str) -> None:
+        """安全地移除或注销 user。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             statement = select(User).where(User.user_name == user_name)
             results = await session.execute(statement)
@@ -76,6 +90,10 @@ class AuthDatabase:
 
     @database_exception
     async def delete_user_by_id(self, user_id: str) -> None:
+        """安全地移除或注销 user by id。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        user_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 user 实例。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             user = await session.get(User, user_id)
             if user is None:
@@ -85,6 +103,10 @@ class AuthDatabase:
 
     @database_exception
     async def login_user(self, user_name: str) -> str:
+        """执行与 login user 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。    """
         async with self.async_session_maker() as session:
             statement = select(User).where(User.user_name == user_name)
             results = await session.execute(statement)
@@ -95,6 +117,9 @@ class AuthDatabase:
 
     @database_exception
     async def get_all_users(self) -> list[User]:
+        """检索并获取特定的 all users 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:         (list[User]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         async with self.async_session_maker() as session:
             statement = select(User)
             results = await session.execute(statement)
@@ -103,6 +128,10 @@ class AuthDatabase:
 
     @database_exception
     async def get_user_authority(self, user_id: str) -> UserAuthority:
+        """检索并获取特定的 user authority 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        user_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 user 实例。
+        Returns:         (UserAuthority): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         async with self.async_session_maker() as session:
             user = await session.get(User, user_id)
             if user is None:

pretor/core/database/postgres.py

@@ -21,12 +21,15 @@ from sqlalchemy.orm import sessionmaker
 from sqlmodel import SQLModel
 
 from pretor.core.database.module.individual import IndividualDatabase
+from pretor.core.database.module.event import EventDatabase
 from pretor.core.database.module.user import AuthDatabase
 from pretor.core.database.module.provider import ProviderDatabase
 from pretor.core.database.module.system_node import SystemNodeDatabase
 
 @ray.remote
 class PostgresDatabase:
+    """PostgresDatabase 核心组件类。
+    这是一个数据库操作层 (DAO/Repository) 封装类，专注于处理实体模型与关系型数据库表之间的映射。它将复杂的 SQL 查询、跨表 Join 和事务回滚逻辑进行了高级抽象，向上层服务暴露简洁的数据读写接口。    """
     def __init__(self):
         user = os.environ.get('POSTGRES_USER')
         password = os.environ.get('POSTGRES_PASSWORD')
@@ -40,11 +43,15 @@ class PostgresDatabase:
         self._auth_database = AuthDatabase(self.async_session_maker)
         self._provider_database = ProviderDatabase(self.async_session_maker)
         self._individual_database = IndividualDatabase(self.async_session_maker)
+        self._event_database = EventDatabase(self.async_session_maker)
         self._system_node_database = SystemNodeDatabase(self.async_session_maker)
 
         self.ready_event = asyncio.Event()
 
     async def init_db(self) -> None:
+        """完成 db 模块的启动与依赖初始化。
+        在系统引导或服务拉起阶段被调用，负责建立网络连接、分配基础内存资源及注册核心服务组件。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             async with self.async_engine.begin() as conn:
                 await conn.run_sync(SQLModel.metadata.create_all)
@@ -57,84 +64,174 @@ class PostgresDatabase:
 
     # Auth Database Methods
     async def add_user(self, user_name: str, hashed_password: str):
+        """创建并持久化新的 user 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        hashed_password (str): 控制逻辑流向的具体字符串参数，指定了期望的 hashed password 内容。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.add_user(user_name, hashed_password)
 
     async def change_password(self, user_name, old_password, new_password):
+        """执行与 change password 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        user_name: 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        old_password: 参与 change password 逻辑运算或数据构建的上下文依赖对象。        new_password: 参与 change password 逻辑运算或数据构建的上下文依赖对象。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.change_password(user_name, old_password, new_password)
 
     async def delete_user(self, user_name: str):
+        """安全地移除或注销 user。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.delete_user(user_name)
 
     async def delete_user_by_id(self, user_id: str):
+        """安全地移除或注销 user by id。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        user_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 user 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.delete_user_by_id(user_id)
 
     async def login_user(self, user_name: str):
+        """执行与 login user 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.login_user(user_name)
 
     async def get_all_users(self):
+        """检索并获取特定的 all users 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.get_all_users()
 
     async def get_user_authority(self, user_id: str):
+        """检索并获取特定的 user authority 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        user_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 user 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.get_user_authority(user_id)
 
     async def change_user_authority(self, user_id: str, new_authority):
+        """执行与 change user authority 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        user_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 user 实例。        new_authority: 参与 change user authority 逻辑运算或数据构建的上下文依赖对象。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._auth_database.change_user_authority(user_id, new_authority)
 
     # Provider Database Methods
     async def get_provider(self):
+        """检索并获取特定的 provider 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._provider_database.get_provider()
 
     async def add_provider_db(self, **kwargs):
+        """创建并持久化新的 provider db 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._provider_database.add_provider(**kwargs)
 
     async def delete_provider_db(self, provider_id: str):
+        """安全地移除或注销 provider db。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        provider_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._provider_database.delete_provider(provider_id)
 
     async def update_provider_db(self, provider_id: str, **kwargs):
+        """对现有的 provider db 进行状态更新或属性覆盖。
+        基于增量变更原则，合并最新的配置或数据，并触发相关依赖组件的缓存刷新或事件通知。
+        Args:        provider_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._provider_database.update_provider(provider_id, **kwargs)
 
     # System Node Database Methods
     async def upsert_system_node_config(self, node_name: str, provider_title: str, model_id: str, tools: list[str] = None):
+        """执行与 upsert system node config 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        node_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        provider_title (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。        model_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 model 实例。        tools (list[str]): 控制逻辑流向的具体字符串参数，指定了期望的 tools 内容。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._system_node_database.upsert_system_node_config(node_name, provider_title, model_id, tools)
 
     async def get_all_system_node_configs(self):
+        """检索并获取特定的 all system node configs 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._system_node_database.get_all_system_node_configs()
 
     # Individual Database Methods
     async def add_worker_individual(self, **kwargs):
+        """创建并持久化新的 worker individual 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._individual_database.add_worker_individual(**kwargs)
 
     async def get_worker_individual(self, agent_id: str):
+        """检索并获取特定的 worker individual 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._individual_database.get_worker_individual(agent_id)
 
     async def get_worker_individual_list(self, owner_id: str):
+        """检索并获取特定的 worker individual list 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        owner_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 owner 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._individual_database.get_worker_individual_list(owner_id)
 
     async def update_worker_individual(self, agent_id: str, **kwargs):
+        """对现有的 worker individual 进行状态更新或属性覆盖。
+        基于增量变更原则，合并最新的配置或数据，并触发相关依赖组件的缓存刷新或事件通知。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._individual_database.update_worker_individual(agent_id, **kwargs)
 
     async def delete_worker_individual(self, agent_id: str):
+        """安全地移除或注销 worker individual。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
         return await self._individual_database.delete_worker_individual(agent_id)
 
     async def get_all_worker_individual(self):
+        """检索并获取特定的 all worker individual 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.ready_event.wait()
-        return await self._individual_database.get_all_worker_individual()
+        return await self._individual_database.get_all_worker_individual()
+    # Event Database Methods
+    async def upsert_event(self, trace_id: str, event_data_json: str):
+        await self.ready_event.wait()
+        return await self._event_database.upsert_event(trace_id, event_data_json)
+
+    async def get_event(self, trace_id: str):
+        await self.ready_event.wait()
+        return await self._event_database.get_event(trace_id)
+
+    async def get_all_events(self):
+        await self.ready_event.wait()
+        return await self._event_database.get_all_events()
+
+    async def delete_event(self, trace_id: str):
+        await self.ready_event.wait()
+        return await self._event_database.delete_event(trace_id)

pretor/core/database/table/event.py

@@ -0,0 +1,5 @@
+from sqlmodel import SQLModel, Field
+
+class EventRecord(SQLModel, table=True):
+    trace_id: str = Field(primary_key=True, description="The unique trace ID of the PretorEvent")
+    event_data_json: str = Field(description="The JSON serialized PretorEvent data")

pretor/core/database/table/individual.py

@@ -18,11 +18,15 @@ from sqlalchemy import Column, JSON
 from enum import Enum
 
 class AgentType(str, Enum):
+    """AgentType 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 AgentType 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     SKILL_INDIVIDUAL = "skill_individual"
     ORDINARY_INDIVIDUAL = "ordinary_individual"
     SPECIAL_INDIVIDUAL = "special_individual"
 
 class WorkerIndividual(SQLModel, table=True):
+    """WorkerIndividual 核心组件类。
+    这是一个具体的 Worker 智能体实体类，代表着具备特定人设、领域技能或长文本处理能力的数字员工。它可以被控制器动态拉起，并在安全沙箱内执行复杂的工作流指令与多步骤推理任务。    """
     __tablename__ = "worker_individual"
     agent_id: str = Field(primary_key=True)
     agent_name: str = Field(index=True)

pretor/core/database/table/provider.py

@@ -18,6 +18,8 @@ from sqlalchemy import Column, JSON
 from typing import Optional
 
 class Provider(SQLModel, table=True):
+    """Provider 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     __tablename__ = "provider"
     provider_id: str = Field(primary_key=True)
     provider_title: str = Field(index=True)

pretor/core/database/table/system_node.py

@@ -18,6 +18,8 @@ from typing import List, Optional
 from sqlalchemy import Column, JSON
 
 class SystemNodeConfig(SQLModel, table=True):
+    """SystemNodeConfig 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     __tablename__ = "system_node_config"
     node_name: str = Field(primary_key=True)
     provider_title: str

pretor/core/database/table/user.py

@@ -16,6 +16,8 @@ from sqlmodel import SQLModel, Field
 from enum import IntEnum
 
 class UserAuthority(IntEnum):
+    """UserAuthority 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 UserAuthority 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     SUPER_ADMINISTRATOR = 100
     ADMINISTRATOR = 50
     USER = 20
@@ -23,6 +25,8 @@ class UserAuthority(IntEnum):
     GUEST = 0
 
 class User(SQLModel, table=True):
+    """User 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 User 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     __tablename__ = 'user'
     user_id: str = Field(primary_key=True)
     user_name: str = Field(index=True)

pretor/core/global_state_machine/global_state_machine.py

@@ -15,11 +15,7 @@
 import ray
 from pretor.core.global_state_machine.provider_manager import ProviderManager
 from pretor.core.global_state_machine.tool_manager import GlobalToolManager
-from typing import Dict
 from pretor.core.database.postgres import PostgresDatabase
-from pretor.api.platform.event import PretorEvent
-import asyncio
-from pretor.core.workflow.workflow import PretorWorkflow
 from pretor.core.workflow.workflow_template_manager import WorkflowManager
 from pretor.core.global_state_machine.skill_manager import GlobalSkillManager
 from pretor.core.global_state_machine.individual_manager import GlobalIndividualManager
@@ -27,10 +23,11 @@ from pretor.core.global_state_machine.individual_manager import GlobalIndividual
 
 @ray.remote
 class GlobalStateMachine:
+    """GlobalStateMachine 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 GlobalStateMachine 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     def __init__(self, postgres_database: PostgresDatabase):
         import sys
         print("GSM __init__ START", file=sys.stderr, flush=True)
-        self.event_dict: Dict[str, PretorEvent] = {}
         print("  event_dict done", file=sys.stderr, flush=True)
         self._global_provider_manager = ProviderManager(postgres_database)
         print("  provider_manager done", file=sys.stderr, flush=True)
@@ -46,10 +43,16 @@ class GlobalStateMachine:
         print("GSM __init__ DONE", file=sys.stderr, flush=True)
 
     async def init_state_machine(self):
+        """完成 state machine 模块的启动与依赖初始化。
+        在系统引导或服务拉起阶段被调用，负责建立网络连接、分配基础内存资源及注册核心服务组件。    """
         await self._global_provider_manager.init_provider_register(self.postgres_database)
         await self._global_individual_manager.init_individual_register(self.postgres_database)
 
     async def add_provider_wrap(self, provider_type, provider_title, provider_url, provider_apikey, provider_owner):
+        """创建并持久化新的 provider wrap 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        provider_type: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_type 实例。        provider_title: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。        provider_url: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_url 实例。        provider_apikey: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_apikey 实例。        provider_owner: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_owner 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return await self._global_provider_manager.add_provider(
             provider_type=provider_type,
             provider_title=provider_title,
@@ -61,21 +64,39 @@ class GlobalStateMachine:
 
     # Provider Manager Methods
     def get_provider_list(self):
+        """检索并获取特定的 provider list 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_provider_manager.get_provider_list()
 
     def get_provider(self, provider_title):
+        """检索并获取特定的 provider 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        provider_title: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_provider_manager.get_provider(provider_title)
 
     async def delete_provider(self, provider_title: str):
+        """安全地移除或注销 provider。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        provider_title (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return await self._global_provider_manager.delete_provider(provider_title, self.postgres_database)
 
     # Tool Manager Methods
     def get_tool_mapper(self):
+        """检索并获取特定的 tool mapper 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_tool_manager.tool_mapper
 
     def get_tool_list(self, agent_name: str):
         # get_tool_list didn't actually exist on tool_manager, let's implement it to return the tools
         # for a specific agent name (or scope)
+        """检索并获取特定的 tool list 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        agent_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         tools = self._global_tool_manager.tool_mapper.get(agent_name, {})
         # also include default tools
         default_tools = self._global_tool_manager.tool_mapper.get("default", {})
@@ -84,83 +105,78 @@ class GlobalStateMachine:
 
     # Workflow Template Manager Methods
     def get_all_workflow_templates(self):
+        """检索并获取特定的 all workflow templates 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_workflow_template_manager.get_all_workflow_templates()
 
     def add_workflow_template(self, template_name: str, workflow_template):
+        """创建并持久化新的 workflow template 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        template_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        workflow_template: 参与 add workflow template 逻辑运算或数据构建的上下文依赖对象。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_workflow_template_manager.add_workflow_template(template_name, workflow_template)
 
     def delete_workflow_template(self, template_name: str):
+        """安全地移除或注销 workflow template。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        template_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_workflow_template_manager.delete_workflow_template(template_name)
 
     def generate_workflow_template(self, workflow_template):
+        """执行与 generate workflow template 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        workflow_template: 参与 generate workflow template 逻辑运算或数据构建的上下文依赖对象。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_workflow_template_manager.generate_workflow_template(workflow_template)
 
     # Skill Manager Methods
     def add_skill(self, skill_name: str):
+        """创建并持久化新的 skill 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        skill_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_skill_manager.add_skill(skill_name)
 
     def get_skill_list(self):
+        """检索并获取特定的 skill list 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_skill_manager.get_skill_list()
 
     def remove_skill(self, skill_name: str):
+        """安全地移除或注销 skill。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        skill_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_skill_manager.remove_skill(skill_name)
 
     # Individual Manager Methods
     def add_individual(self, agent_id: str, config):
+        """创建并持久化新的 individual 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。        config: 驱动该模块运行的核心配置字典或 Pydantic 数据模型，定义了重试策略、超时时间及模型参数等选项。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_individual_manager.add_individual(agent_id, config)
 
     def get_individual(self, agent_id: str):
+        """检索并获取特定的 individual 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_individual_manager.get_individual(agent_id)
 
     def remove_individual(self, agent_id: str):
+        """安全地移除或注销 individual。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_individual_manager.remove_individual(agent_id)
 
     def list_individuals(self):
+        """执行与 list individuals 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self._global_individual_manager.list_individuals()
 
-    ###以下方法为event_dict方法
-    def add_event(self, event: PretorEvent) -> None:
-        event.pending_queue = asyncio.Queue()
-        event.receive_queue = asyncio.Queue()
-        self.event_dict[event.trace_id] = event
-
-    def delete_event(self, trace_id: str) -> None:
-        del self.event_dict[trace_id]
-
-    def get_event(self, trace_id: str) -> PretorEvent:
-        return self.event_dict.get(trace_id, None)
-
-    def update_attachment(self, trace_id: str, attachment: Dict[str, str]) -> None:
-        self.event_dict[trace_id].attachment = attachment
-
-    def update_workflow(self, trace_id: str, workflow: PretorWorkflow) -> None:
-        self.event_dict[trace_id].workflow = workflow
-
-    def get_workflow(self, trace_id: str) -> PretorWorkflow:
-        return self.event_dict[trace_id].workflow
-
-    def list_events(self) -> list[dict]:
-        result = []
-        for trace_id, event in self.event_dict.items():
-            workflow_title = event.workflow.title if event.workflow else None
-            workflow_status = event.workflow.status.status if event.workflow and event.workflow.status else None
-            result.append({
-                "event_id": trace_id,
-                "workflow_title": workflow_title,
-                "status": workflow_status,
-                "user_name": event.user_name,
-                "message": event.message,
-            })
-        return result
-
-    async def put_pending(self, trace_id, item) -> None:
-        await self.event_dict[trace_id].pending_queue.put(item)
-
-    async def get_pending(self, trace_id) -> str:
-        return await self.event_dict[trace_id].pending_queue.get()
-
-    async def put_received(self, trace_id, item) -> None:
-        await self.event_dict[trace_id].receive_queue.put(item)
-
-    async def get_received(self, trace_id) -> str:
-        return await self.event_dict[trace_id].receive_queue.get()

pretor/core/global_state_machine/global_workflow_manager.py

@@ -0,0 +1,187 @@
+import ray
+import asyncio
+from typing import Dict
+from pretor.api.platform.event import PretorEvent
+from pretor.core.workflow.workflow import PretorWorkflow
+from pretor.utils.ray_hook import ray_actor_hook
+from pretor.utils.logger import get_logger
+
+@ray.remote
+class GlobalWorkflowManager:
+    def __init__(self):
+        self.event_dict: Dict[str, PretorEvent] = {}
+        self.event_object_refs: Dict[str, ray.ObjectRef] = {}
+        self.postgres_database = None
+        self.logger = get_logger("GlobalWorkflowManager")
+
+    async def init_manager(self):
+        self.postgres_database = ray_actor_hook("postgres_database").postgres_database
+
+        # Load all events from database to memory
+        try:
+            records = await self.postgres_database.get_all_events.remote()
+            for record in records:
+                try:
+                    event = PretorEvent.model_validate_json(record.event_data_json)
+                    event.pending_queue = asyncio.Queue()
+                    event.receive_queue = asyncio.Queue()
+                    self.event_dict[event.trace_id] = event
+
+                    # Store in ray object store for cache
+                    event_copy = event.model_copy()
+                    event_copy.pending_queue = None
+                    event_copy.receive_queue = None
+                    self.event_object_refs[event.trace_id] = ray.put(event_copy.model_dump_json())
+
+                except Exception as e:
+                    self.logger.error(f"Failed to load event {record.trace_id}: {e}")
+            self.logger.info(f"Loaded {len(self.event_dict)} events from database")
+
+            # Trigger resumption of incomplete workflows
+            workflow_running_engine = None
+            for trace_id, event in self.event_dict.items():
+                if event.workflow and event.workflow.status.status in ["waiting_llm_working", "waiting_tool_working", "llm_working", "tool_working"]:
+                    self.logger.info(f"Resuming incomplete workflow {trace_id}")
+                    if not workflow_running_engine:
+                        try:
+                            workflow_running_engine = ray_actor_hook("workflow_running_engine").workflow_running_engine
+                        except AttributeError:
+                            self.logger.warning("workflow_running_engine not found, cannot resume workflow")
+                            break
+                    await workflow_running_engine.resume_workflow.remote(event)
+
+        except Exception as e:
+            self.logger.error(f"Failed to fetch events from database: {e}")
+
+    async def _upsert_event_to_db(self, event: PretorEvent):
+        try:
+            # Create a copy and remove non-serializable queues
+            event_copy = event.model_copy()
+            event_copy.pending_queue = None
+            event_copy.receive_queue = None
+
+            event_json = event_copy.model_dump_json()
+            # Update cache
+            self.event_object_refs[event.trace_id] = ray.put(event_json)
+
+            await self.postgres_database.upsert_event.remote(
+                event.trace_id,
+                event_json
+            )
+        except Exception as e:
+            self.logger.error(f"Failed to upsert event {event.trace_id} to database: {e}")
+
+    async def add_event(self, event: PretorEvent) -> None:
+        event.pending_queue = asyncio.Queue()
+        event.receive_queue = asyncio.Queue()
+        self.event_dict[event.trace_id] = event
+        await self._upsert_event_to_db(event)
+
+    async def delete_event(self, trace_id: str) -> None:
+        if trace_id in self.event_dict:
+            del self.event_dict[trace_id]
+        if trace_id in self.event_object_refs:
+            del self.event_object_refs[trace_id]
+        try:
+            await self.postgres_database.delete_event.remote(trace_id)
+        except Exception as e:
+            self.logger.error(f"Failed to delete event {trace_id} from database: {e}")
+
+    async def get_event(self, trace_id: str) -> PretorEvent | None:
+        # First check memory dict
+        if trace_id in self.event_dict:
+            return self.event_dict[trace_id]
+
+        # Then check Ray object store cache
+        if trace_id in self.event_object_refs:
+            try:
+                event_json = ray.get(self.event_object_refs[trace_id])
+                return PretorEvent.model_validate_json(event_json)
+            except Exception as e:
+                self.logger.warning(f"Failed to fetch event from cache for trace {trace_id}: {e}")
+
+        # Fallback to database
+        try:
+            record = await self.postgres_database.get_event.remote(trace_id)
+            if record:
+                event = PretorEvent.model_validate_json(record.event_data_json)
+
+                # Restore to memory dict with missing transient queues
+                event.pending_queue = asyncio.Queue()
+                event.receive_queue = asyncio.Queue()
+                self.event_dict[trace_id] = event
+
+                # Restore to cache
+                event_copy = event.model_copy()
+                event_copy.pending_queue = None
+                event_copy.receive_queue = None
+                self.event_object_refs[trace_id] = ray.put(event_copy.model_dump_json())
+
+                return event
+        except Exception as e:
+            self.logger.error(f"Failed to fetch event {trace_id} from database fallback: {e}")
+
+        return None
+
+    async def update_attachment(self, trace_id: str, attachment: Dict[str, str]) -> None:
+        if trace_id in self.event_dict:
+            self.event_dict[trace_id].attachment = attachment
+            await self._upsert_event_to_db(self.event_dict[trace_id])
+
+    async def update_workflow(self, trace_id: str, workflow: PretorWorkflow) -> None:
+        if trace_id in self.event_dict:
+            self.event_dict[trace_id].workflow = workflow
+            await self._upsert_event_to_db(self.event_dict[trace_id])
+
+    async def get_workflow(self, trace_id: str) -> PretorWorkflow | None:
+        event = await self.get_event(trace_id)
+        return event.workflow if event else None
+
+    async def list_events(self) -> list[dict]:
+        result = []
+
+        # Read strictly from the database to ensure we get all events,
+        # and ignore the cache to prevent frontend missing items.
+        try:
+            records = await self.postgres_database.get_all_events.remote()
+            for record in records:
+                try:
+                    event = PretorEvent.model_validate_json(record.event_data_json)
+                    workflow_title = event.workflow.title if event.workflow else None
+                    workflow_status = event.workflow.status.status if event.workflow and event.workflow.status else None
+                    result.append({
+                        "event_id": event.trace_id,
+                        "workflow_title": workflow_title,
+                        "status": workflow_status,
+                        "user_name": event.user_name,
+                        "message": event.message,
+                        "create_time": event.create_time,
+                    })
+                    # Best-effort cache population
+                    self.event_object_refs[event.trace_id] = ray.put(record.event_data_json)
+                except Exception:
+                    continue
+        except Exception as e:
+            self.logger.error(f"Failed to list_events from DB: {e}")
+
+        return result
+
+    async def put_pending(self, trace_id, item) -> None:
+        if trace_id in self.event_dict and self.event_dict[trace_id].pending_queue:
+            await self.event_dict[trace_id].pending_queue.put(item)
+
+    async def get_pending(self, trace_id) -> str:
+        if trace_id in self.event_dict and self.event_dict[trace_id].pending_queue:
+            return await self.event_dict[trace_id].pending_queue.get()
+        await asyncio.sleep(1) # Prevent CPU spinning if not found
+        return ""
+
+    async def put_received(self, trace_id, item) -> None:
+        if trace_id in self.event_dict and self.event_dict[trace_id].receive_queue:
+            await self.event_dict[trace_id].receive_queue.put(item)
+
+    async def get_received(self, trace_id) -> str:
+        if trace_id in self.event_dict and self.event_dict[trace_id].receive_queue:
+            return await self.event_dict[trace_id].receive_queue.get()
+        await asyncio.sleep(1) # Prevent CPU spinning if not found
+        return ""

pretor/core/global_state_machine/individual_manager.py

@@ -17,10 +17,16 @@ from pretor.utils.logger import get_logger
 logger = get_logger('individual_manager')
 
 class GlobalIndividualManager:
+    """GlobalIndividualManager 核心组件类。
+    这是一个管理器类，职责集中在维护整个系统内有关 GlobalIndividual 资源的全局生命周期。它提供了注册机制、状态同步以及跨组件的统一查询入口，确保系统中该类型资源的实例一致性与可控性。    """
     def __init__(self):
         self._individuals: Dict[str, Dict[str, Any]] = {}
 
     async def init_individual_register(self, postgres) -> None:
+        """完成 individual register 模块的启动与依赖初始化。
+        在系统引导或服务拉起阶段被调用，负责建立网络连接、分配基础内存资源及注册核心服务组件。
+        Args:        postgres: 参与 init individual register 逻辑运算或数据构建的上下文依赖对象。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             try:
                 individuals = await postgres.get_all_worker_individual.remote()
@@ -55,8 +61,15 @@ class GlobalIndividualManager:
         return self._individuals.get(agent_id, None)
 
     def remove_individual(self, agent_id: str) -> None:
+        """安全地移除或注销 individual。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         if agent_id in self._individuals:
             del self._individuals[agent_id]
 
     def list_individuals(self) -> Dict[str, Dict[str, Any]]:
+        """执行与 list individuals 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Returns:         (Dict[str, Dict[str, Any]]): 高度聚合的字典结构数据，将多维度的属性特征或统计指标组合后一并返回。    """
         return self._individuals

pretor/core/global_state_machine/model_provider/base_provider.py

@@ -18,10 +18,14 @@ from typing import List
 from enum import Enum
 
 class ProviderStatus(str, Enum):
+    """ProviderStatus 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     UP = "up"
     DOWN = "down"
 
 class Provider(BaseModel):
+    """Provider 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     provider_title: str
     provider_url: str
     provider_apikey: str
@@ -31,12 +35,16 @@ class Provider(BaseModel):
     provider_status: ProviderStatus = ProviderStatus.UP
 
 class ProviderArgs(BaseModel):
+    """ProviderArgs 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     provider_title: str
     provider_url: str
     provider_apikey: str
     provider_owner: str
 
 class BaseProvider(ABC):
+    """BaseProvider 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     @staticmethod
     @abstractmethod
     async def create_provider(provider_args: ProviderArgs) -> Provider:

pretor/core/global_state_machine/model_provider/claude_provider.py

@@ -1,4 +1,3 @@
-from pretor.utils.retry import retry_on_retryable_error
 #  Copyright 2026 zhaoxi826
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,13 +12,21 @@ from pretor.utils.retry import retry_on_retryable_error
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+from pretor.utils.retry import retry_on_retryable_error
+
 from pretor.core.global_state_machine.model_provider.base_provider import BaseProvider, Provider, ProviderArgs
 import httpx
 from typing import List
 
 class ClaudeProvider(BaseProvider):
+    """ClaudeProvider 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     @staticmethod
     async def create_provider(provider_args: ProviderArgs) -> Provider:
+        """创建并持久化新的 provider 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         provider_models: List[str] = await ClaudeProvider._load_models(provider_args)
         provider: Provider = ClaudeProvider._return_provider(provider_args, provider_models)
         return provider
@@ -28,6 +35,10 @@ class ClaudeProvider(BaseProvider):
     @retry_on_retryable_error()
     async def _load_models(provider_args: ProviderArgs) -> List[str]:
         # Anthropic 官方需要 version 头
+        """执行与  load models 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。
+        Returns:         (List[str]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         headers = {
             "x-api-key": provider_args.provider_apikey,
             "anthropic-version": "2023-06-01",
@@ -53,6 +64,10 @@ class ClaudeProvider(BaseProvider):
 
     @staticmethod
     def _return_provider(provider_args: ProviderArgs, provider_models: List[str]) -> Provider:
+        """执行与  return provider 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。        provider_models (List[str]): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_models 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return Provider(provider_title=provider_args.provider_title,
                         provider_apikey=provider_args.provider_apikey,
                         provider_url=provider_args.provider_url,

pretor/core/global_state_machine/model_provider/deepseek_provider.py

@@ -18,8 +18,14 @@ import httpx
 from typing import List
 
 class DeepseekProvider(BaseProvider):
+    """DeepseekProvider 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     @staticmethod
     async def create_provider(provider_args: ProviderArgs) -> Provider:
+        """创建并持久化新的 provider 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         provider_models: List[str] = await DeepseekProvider._load_models(provider_args)
         provider: Provider = DeepseekProvider._return_provider(provider_args, provider_models)
         return provider
@@ -27,6 +33,10 @@ class DeepseekProvider(BaseProvider):
     @staticmethod
     @retry_on_retryable_error()
     async def _load_models(provider_args: ProviderArgs) -> List[str]:
+        """执行与  load models 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。
+        Returns:         (List[str]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         headers = {
             "Authorization": f"Bearer {provider_args.provider_apikey}",
             "Content-Type": "application/json"
@@ -52,6 +62,10 @@ class DeepseekProvider(BaseProvider):
 
     @staticmethod
     def _return_provider(provider_args: ProviderArgs, provider_models: List[str]) -> Provider:
+        """执行与  return provider 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。        provider_models (List[str]): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_models 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return Provider(provider_title=provider_args.provider_title,
                         provider_apikey=provider_args.provider_apikey,
                         provider_url=provider_args.provider_url,

pretor/core/global_state_machine/model_provider/openai_provider.py

@@ -18,8 +18,14 @@ import httpx
 from typing import List
 
 class OpenAIProvider(BaseProvider):
+    """OpenAIProvider 核心组件类。
+    这是一个模型/服务提供商适配器类，屏蔽了外部不同供应商（如 OpenAI、Anthropic 等）的底层 API 差异。它负责标准化参数组装、网络请求发送、鉴权处理以及响应结构的反序列化。    """
     @staticmethod
     async def create_provider(provider_args: ProviderArgs) -> Provider:
+        """创建并持久化新的 provider 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         provider_models: List[str] = await OpenAIProvider._load_models(provider_args)
         provider: Provider = OpenAIProvider._return_provider(provider_args, provider_models)
         return provider
@@ -27,6 +33,10 @@ class OpenAIProvider(BaseProvider):
     @staticmethod
     @retry_on_retryable_error()
     async def _load_models(provider_args: ProviderArgs) -> List[str]:
+        """执行与  load models 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。
+        Returns:         (List[str]): 经过筛选、排序或分页处理后的实体对象列表集合。    """
         headers = {
             "Authorization": f"Bearer {provider_args.provider_apikey}",
             "Content-Type": "application/json"
@@ -52,6 +62,10 @@ class OpenAIProvider(BaseProvider):
 
     @staticmethod
     def _return_provider(provider_args: ProviderArgs, provider_models: List[str]) -> Provider:
+        """执行与  return provider 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        provider_args (ProviderArgs): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_args 实例。        provider_models (List[str]): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_models 实例。
+        Returns:         (Provider): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return Provider(provider_title=provider_args.provider_title,
                         provider_apikey=provider_args.provider_apikey,
                         provider_url=provider_args.provider_url,

pretor/core/global_state_machine/provider_manager.py

@@ -33,11 +33,19 @@ class ProviderManager:
         self.provider_register = {}
 
     async def init_provider_register(self, postgres) -> None:
+        """完成 provider register 模块的启动与依赖初始化。
+        在系统引导或服务拉起阶段被调用，负责建立网络连接、分配基础内存资源及注册核心服务组件。
+        Args:        postgres: 参与 init provider register 逻辑运算或数据构建的上下文依赖对象。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         providers = await postgres.get_provider.remote()
         for provider in providers:
             self.provider_register[provider.provider_title] = provider
 
     async def add_provider(self, provider_type, provider_title, provider_url, provider_apikey, provider_owner, postgres_database) -> None:
+        """创建并持久化新的 provider 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        provider_type: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_type 实例。        provider_title: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。        provider_url: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_url 实例。        provider_apikey: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_apikey 实例。        provider_owner: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_owner 实例。        postgres_database: 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         from pretor.core.global_state_machine.model_provider import ProviderArgs
         from pretor.utils.logger import get_logger
         logger = get_logger('provider_manager')
@@ -74,12 +82,23 @@ class ProviderManager:
             logger.warning(f"[{provider_args.provider_title}] 解析模型列表时发生错误: {e}")
 
     def get_provider_list(self):
+        """检索并获取特定的 provider list 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self.provider_register
 
     def get_provider(self, provider_title):
+        """检索并获取特定的 provider 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Args:        provider_title: 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。
+        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         return self.provider_register.get(provider_title)
 
     async def delete_provider(self, provider_title: str, postgres_database) -> None:
+        """安全地移除或注销 provider。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        provider_title (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 provider_title 实例。        postgres_database: 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         if provider_title in self.provider_register:
             provider = self.provider_register[provider_title]
             await postgres_database.delete_provider_db.remote( provider_id=provider.provider_id)

pretor/core/global_state_machine/skill_manager.py

@@ -18,6 +18,8 @@ import pathlib
 import json
 
 class GlobalSkillManager:
+    """GlobalSkillManager 核心组件类。
+    这是一个管理器类，职责集中在维护整个系统内有关 GlobalSkill 资源的全局生命周期。它提供了注册机制、状态同步以及跨组件的统一查询入口，确保系统中该类型资源的实例一致性与可控性。    """
     skill_mapper = Dict[str,Tuple[str]]
     """skill的存储表"""
 

pretor/core/global_state_machine/tool_manager.py

@@ -22,6 +22,8 @@ from pretor.utils.logger import get_logger
 logger = get_logger('tool_manager')
 
 class GlobalToolManager:
+    """GlobalToolManager 核心组件类。
+    这是一个管理器类，职责集中在维护整个系统内有关 GlobalTool 资源的全局生命周期。它提供了注册机制、状态同步以及跨组件的统一查询入口，确保系统中该类型资源的实例一致性与可控性。    """
     tool_mapper: Dict[str, Dict[str, Type[BaseToolData]]]
 
     def __init__(self):

pretor/core/individual/consciousness_node/consciousness_node.py

@@ -25,6 +25,8 @@ from pretor.adapter.model_adapter.agent_factory import AgentFactory
 
 @ray.remote
 class ConsciousnessNode:
+    """ConsciousnessNode 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     def __init__(self) -> None:
         from pretor.utils.logger import get_logger
         self.logger = get_logger('consciousness_node')
@@ -70,6 +72,10 @@ class ConsciousnessNode:
 
         @self.agent.system_prompt
         async def dynamic_prompt(ctx: RunContext[ConsciousnessNodeDeps]):
+            """执行与 dynamic prompt 相关的核心业务流转操作。
+            该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+            Args:        ctx (RunContext[ConsciousnessNodeDeps]): 参与 dynamic prompt 逻辑运算或数据构建的上下文依赖对象。
+            Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
             prompt = system_prompt + "\n\n"
             prompt += (
                 f"=== 当前任务上下文 ===\n"
@@ -87,6 +93,10 @@ class ConsciousnessNode:
             return prompt
 
     async def working(self, payload: Union[ForWorkflowEngineInput, ForWorkflowInput, ForSupervisoryInput]) -> Union[ForWorkflowEngine, ForWorkflow, ForSupervisoryNode, None]:
+        """执行与 working 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        payload (Union[ForWorkflowEngineInput, ForWorkflowInput, ForSupervisoryInput]): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
+        Returns:         (Union[ForWorkflowEngine, ForWorkflow, ForSupervisoryNode, None]): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             result = await self._run(payload)
             if isinstance(result, (ForWorkflowEngine, ForWorkflow, ForSupervisoryNode)):
@@ -139,6 +149,10 @@ class ConsciousnessNode:
         pass
 
     async def _run(self, payload: Union[ForSupervisoryInput, ForWorkflowInput, ForWorkflowEngineInput]) -> Union[ForSupervisoryNode, ForWorkflow, ForWorkflowEngine]:
+        """执行与  run 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        payload (Union[ForSupervisoryInput, ForWorkflowInput, ForWorkflowEngineInput]): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
+        Returns:         (Union[ForSupervisoryNode, ForWorkflow, ForWorkflowEngine]): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             self.agent.retries = 3
             if isinstance(payload, ForWorkflowEngineInput):

pretor/core/individual/consciousness_node/template.py

@@ -41,6 +41,8 @@ class ForSupervisoryNode(ConsciousnessNodeResponse):
 
 
 class ConsciousnessNodeDeps(DepsModel):
+    """ConsciousnessNodeDeps 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     original_command: str
     workflow_template: str | None = None
     command: str
@@ -48,20 +50,28 @@ class ConsciousnessNodeDeps(DepsModel):
 
 
 class ConsciousnessNodeInput(InputModel):
+    """ConsciousnessNodeInput 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     pass
 
 
 class ForWorkflowEngineInput(ConsciousnessNodeInput):
+    """ForWorkflowEngineInput 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 ForWorkflowEngineInput 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     workflow_template: str | None = None
     original_command: str
     available_skills: list[dict] | None = None
 
 
 class ForWorkflowInput(ConsciousnessNodeInput):
+    """ForWorkflowInput 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 ForWorkflowInput 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     workflow_step: WorkStep
     original_command: str
 
 
 class ForSupervisoryInput(ConsciousnessNodeInput):
+    """ForSupervisoryInput 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 ForSupervisoryInput 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     workflow: PretorWorkflow
     original_command: str

pretor/core/individual/control_node/control_node.py

@@ -23,6 +23,8 @@ from pretor.core.individual.control_node.template import ForWorkflow, ForWorkflo
 
 @ray.remote
 class ControlNode:
+    """ControlNode 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     def __init__(self):
         from pretor.utils.logger import get_logger
         self.logger = get_logger('control_node')
@@ -67,6 +69,10 @@ class ControlNode:
                                                 tools=callables)
         @self.agent.system_prompt
         async def dynamic_prompt(ctx: RunContext[ControlNodeDeps]):
+            """执行与 dynamic prompt 相关的核心业务流转操作。
+            该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+            Args:        ctx (RunContext[ControlNodeDeps]): 参与 dynamic prompt 逻辑运算或数据构建的上下文依赖对象。
+            Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
             prompt = system_prompt + "\n\n"
             prompt += (
                 f"=== 当前任务步骤上下文 ===\n"
@@ -77,6 +83,10 @@ class ControlNode:
             return prompt
 
     async def working(self, payload: ForWorkflowInput) -> str:
+        """执行与 working 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        payload (ForWorkflowInput): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
+        Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。    """
         try:
             result: ForWorkflow = await self._run(payload)
             return result
@@ -85,6 +95,10 @@ class ControlNode:
             return None
 
     async def _run(self, payload: ForWorkflowInput) -> ForWorkflow:
+        """执行与  run 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        payload (ForWorkflowInput): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
+        Returns:         (ForWorkflow): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             self.agent.retries = 3
             deps = ControlNodeDeps(

pretor/core/individual/control_node/template.py

@@ -23,17 +23,25 @@ class ControlNodeResponse(ResponseModel):
 
 
 class ControlNodeInput(InputModel):
+    """ControlNodeInput 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     pass
 
 
 class ControlNodeDeps(DepsModel):
+    """ControlNodeDeps 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     workflow_step: WorkStep
     # In the future, this can be dynamically populated with tools specific to the current task execution
 
 
 class ForWorkflow(ControlNodeResponse):
+    """ForWorkflow 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 ForWorkflow 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     output: str = Field(..., description="控制节点执行特定工作流步骤的结果。包含执行细节和输出数据。")
 
 
 class ForWorkflowInput(ControlNodeInput):
+    """ForWorkflowInput 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 ForWorkflowInput 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     workflow_step: WorkStep

pretor/core/individual/supervisory_node/supervisory_node.py

@@ -26,6 +26,8 @@ from pretor.utils.ray_hook import ray_actor_hook
 
 @ray.remote
 class SupervisoryNode:
+    """SupervisoryNode 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     def __init__(self) -> None:
         from pretor.utils.logger import get_logger
         self.logger = get_logger('supervisory_node')
@@ -71,6 +73,10 @@ class SupervisoryNode:
 
         @self.agent.system_prompt
         async def dynamic_prompt(ctx: RunContext[SupervisoryNodeDeps]):
+            """执行与 dynamic prompt 相关的核心业务流转操作。
+            该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+            Args:        ctx (RunContext[SupervisoryNodeDeps]): 参与 dynamic prompt 逻辑运算或数据构建的上下文依赖对象。
+            Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
             prompt = system_prompt + "\n\n"
             prompt += (
                 f"=== 当前上下文 ===\n"
@@ -111,8 +117,8 @@ class SupervisoryNode:
                 if isinstance(payload, PretorEvent):
                     payload.context["workflow_template"] = result.workflow_template
                     try:
-                        global_state_machine = ray_actor_hook("global_state_machine").global_state_machine
-                        await global_state_machine.add_event.remote(payload)
+                        global_workflow_manager = ray_actor_hook("global_workflow_manager").global_workflow_manager
+                        await global_workflow_manager.add_event.remote(payload)
                         workflow_running_engine = ray_actor_hook("workflow_running_engine").workflow_running_engine
                         await workflow_running_engine.put_event.remote(payload)
                     except Exception as e:

pretor/core/individual/supervisory_node/template.py

@@ -17,21 +17,31 @@ from pretor.utils.agent_model import ResponseModel, DepsModel
 from pydantic import BaseModel
 
 class SupervisoryNodeResponse(ResponseModel):
+    """SupervisoryNodeResponse 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     pass
 
 class ForUser(SupervisoryNodeResponse):
+    """ForUser 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 ForUser 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     context: str = Field(..., description="对用户的回复，应当使用和蔼的语气进行回复。用于直接解答简单问题或返回最终报告。")
 
 class ForConsciousnessNode(SupervisoryNodeResponse):
+    """ForConsciousnessNode 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     workflow_template: str | None = Field(default=None, description="选择的工作流模板的名称，用于处理复杂任务。若无需模板则为 None。")
     reasoning: str = Field(..., description="选择将任务移交意识节点并选用该模板的简短原因。")
 
 class TerminationMessage(BaseModel):
+    """TerminationMessage 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 TerminationMessage 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     platform: str
     user_name: str
     message: str
 
 class SupervisoryNodeDeps(DepsModel):
+    """SupervisoryNodeDeps 核心组件类。
+    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。    """
     platform: str
     user_name: str
     time: str

pretor/core/workflow/workflow.py

@@ -22,14 +22,20 @@ NodeType = Literal[
 ]
 
 class EventInfo(BaseModel):
+    """EventInfo 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 EventInfo 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     platform: str
     user_name: str
 
 class LogicGate(BaseModel):
+    """LogicGate 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 LogicGate 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     if_fail: str = Field(..., description="失败跳转目标，如 'jump_to_step_1'")
     if_pass: Literal["continue", "exit"] = Field(default="continue", description="成功后的动作")
 
 class WorkStep(BaseModel):
+    """WorkStep 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkStep 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     step: int = Field(..., gt=0, description="步骤序号，严格自增")
     name: str = Field(..., description="步骤名称")
     node: NodeType = Field(..., description="负责执行的节点类型")
@@ -46,6 +52,8 @@ class WorkStep(BaseModel):
 
 
 class WorkflowStatus(BaseModel):
+    """WorkflowStatus 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkflowStatus 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     step: int = Field(default=1, gt=0, description="当前运行到的工作流步数")
     status: Literal["waiting_llm_working", "waiting_tool_working", "llm_working", "tool_working"] = Field(
         default="waiting_llm_working",
@@ -53,6 +61,8 @@ class WorkflowStatus(BaseModel):
     )
 
 class PretorWorkflow(BaseModel):
+    """PretorWorkflow 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 PretorWorkflow 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     title: str = Field(..., description="工作流的标题")
     work_link: List[WorkStep] = Field(..., description="工作链逻辑定义")
     # ---------------- 以下为系统级管控字段，LLM 无需关心 ---------------- #
@@ -66,6 +76,9 @@ class PretorWorkflow(BaseModel):
 
     @model_validator(mode='after')
     def validate_workflow_integrity(self) -> 'PretorWorkflow':
+        """执行与 validate workflow integrity 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Returns:         ('PretorWorkflow'): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         steps = [s.step for s in self.work_link]
         expected = list(range(1, len(steps) + 1))
         if steps != expected:

pretor/core/workflow/workflow_runner.py

@@ -34,6 +34,10 @@ import pathlib
 
 
 def get_workflow_template(workflow_name: str) -> str:
+    """检索并获取特定的 workflow template 数据集合或实例对象。
+    根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+    Args:        workflow_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+    Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。    """
     workflow_template = pathlib.Path(__file__).parent.parent.parent / "workflow_template" / (workflow_name + "_workflow_template.json")
     with open(workflow_template, "r", encoding="utf-8") as workflow_template_file:
         workflow_template = workflow_template_file.read()
@@ -41,6 +45,8 @@ def get_workflow_template(workflow_name: str) -> str:
 
 
 class WorkflowEngine:
+    """WorkflowEngine 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkflowEngine 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     def __init__(self,
                  workflow: PretorWorkflow,
                  consciousness_node=None,
@@ -58,11 +64,15 @@ class WorkflowEngine:
         """控制节点"""
         self.supervisory_node = supervisory_node
         """监督节点"""
-        self._gsm = ray_actor_hook("global_state_machine").global_state_machine
+        self._gwm = ray_actor_hook("global_workflow_manager").global_workflow_manager
 
     async def _push_sse(self, msg: str) -> None:
+        """执行与  push sse 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        msg (str): 控制逻辑流向的具体字符串参数，指定了期望的 msg 内容。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
-            await self._gsm.put_pending.remote(self.workflow.trace_id, msg)
+            await self._gwm.put_pending.remote(self.workflow.trace_id, msg)
         except Exception:
             pass
 
@@ -273,6 +283,8 @@ class WorkflowEngine:
 
 @ray.remote
 class WorkflowRunningEngine:
+    """WorkflowRunningEngine 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkflowRunningEngine 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     def __init__(self, consciousness_node=None, control_node=None, supervisory_node=None):
         from pretor.utils.logger import get_logger
         self.logger = get_logger('workflow_runner')
@@ -285,6 +297,8 @@ class WorkflowRunningEngine:
 
     async def run(self):
         # Move actor hook to async start so we don't race during __init__ across cluster
+        """执行与 run 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。    """
         self.global_state_machine = ray_actor_hook("global_state_machine").global_state_machine
         self.workflow_queue = asyncio.Queue()
         self.runner_engine = {
@@ -293,8 +307,22 @@ class WorkflowRunningEngine:
         }
 
     async def put_event(self, event: PretorEvent) -> None:
+        """执行与 put event 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        event (PretorEvent): 由事件总线或工作流引擎分发过来的事件载荷，封装了触发此次调用的上下文快照与任务目标指令。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         await self.workflow_queue.put(event)
 
+    async def resume_workflow(self, event: PretorEvent) -> None:
+        """Resume an incomplete workflow that was loaded from the database."""
+        self.logger.info(f"Resuming workflow {event.trace_id}")
+        workflow_engine = WorkflowEngine(event.workflow,
+                                         self.consciousness_node,
+                                         self.control_node,
+                                         self.supervisory_node)
+        # Assuming you want to schedule it via a task
+        asyncio.create_task(workflow_engine.run())
+
     async def runner(self, i: int) -> None:
         """
             runner方法，从self.workflow_queue中不断取出任务并执行
@@ -347,7 +375,8 @@ class WorkflowRunningEngine:
                     self.logger.info(
                         f"WorkflowRunningEngine: runner_{i} 成功生成工作流 {workflow.trace_id}:{workflow.title}")
 
-                    await self.global_state_machine.update_workflow.remote(event.trace_id, workflow)
+                    global_workflow_manager = ray_actor_hook("global_workflow_manager").global_workflow_manager
+                    await global_workflow_manager.update_workflow.remote(event.trace_id, workflow)
 
                     workflow_engine = WorkflowEngine(workflow,
                                                      self.consciousness_node,

pretor/core/workflow/workflow_template_generator/workflow_template.py

@@ -16,6 +16,8 @@ from pydantic import BaseModel, model_validator
 from typing import Dict,List
 
 class WorkflowTemplateStep(BaseModel):
+    """WorkflowTemplateStep 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkflowTemplateStep 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     step: int
     node: str
     action: str
@@ -25,12 +27,17 @@ class WorkflowTemplateStep(BaseModel):
     logic_gate: Dict[str, str]
     
 class WorkflowTemplate(BaseModel):
+    """WorkflowTemplate 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkflowTemplate 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     name: str
     desc: str
     work_link: list[WorkflowTemplateStep]
 
     @model_validator(mode='after')
     def validate_steps(self) -> 'WorkflowTemplate':
+        """执行与 validate steps 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Returns:         ('WorkflowTemplate'): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         steps = [s.step for s in self.work_link]
         if len(steps) != len(set(steps)):
             raise ValueError("Step numbers in work_link must be unique")

pretor/core/workflow/workflow_template_generator/workflow_template_generator.py

@@ -16,8 +16,14 @@ from pathlib import Path
 from pretor.core.workflow.workflow_template_generator.workflow_template import WorkflowTemplate
 
 class WorkflowTemplateGenerator:
+    """WorkflowTemplateGenerator 核心组件类。
+    这是一个领域数据模型或功能封装类，承载了 WorkflowTemplateGenerator 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。    """
     @staticmethod
     def generate_workflow_template(workflow_template: WorkflowTemplate) -> WorkflowTemplate:
+        """执行与 generate workflow template 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        workflow_template (WorkflowTemplate): 参与 generate workflow template 逻辑运算或数据构建的上下文依赖对象。
+        Returns:         (WorkflowTemplate): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         output_dir = Path("pretor") / "workflow_template"
         if not output_dir.exists():
             output_dir.mkdir(parents=True)

pretor/core/workflow/workflow_template_manager.py

@@ -21,6 +21,8 @@ from pretor.utils.logger import get_logger
 logger = get_logger('workflow_template_manager')
 
 class WorkflowManager:
+    """WorkflowManager 核心组件类。
+    这是一个管理器类，职责集中在维护整个系统内有关 Workflow 资源的全局生命周期。它提供了注册机制、状态同步以及跨组件的统一查询入口，确保系统中该类型资源的实例一致性与可控性。    """
     def __init__(self):
         self.workflow_template_generator = WorkflowTemplateGenerator()
         self.workflow_templates_registry = {}
@@ -28,6 +30,9 @@ class WorkflowManager:
         self._load_workflow_template()
 
     def _load_workflow_template(self) -> None:
+        """执行与  load workflow template 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         for workflow_template_file in self.template_path.glob("*_workflow_template.json"):
             with workflow_template_file.open("r",encoding="utf-8") as f:
                 try:
@@ -39,6 +44,10 @@ class WorkflowManager:
                     logger.warning(f"{workflow_template_file}不符合workflow_template格式")
 
     def generate_workflow_template(self, workflow_template: WorkflowTemplate)  -> None:
+        """执行与 generate workflow template 相关的核心业务流转操作。
+        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
+        Args:        workflow_template (WorkflowTemplate): 参与 generate workflow template 逻辑运算或数据构建的上下文依赖对象。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         try:
             workflow_template = self.workflow_template_generator.generate_workflow_template(workflow_template=workflow_template)
             self.workflow_templates_registry[workflow_template.name] = workflow_template.desc
@@ -46,11 +55,22 @@ class WorkflowManager:
             logger.exception("Failed to generate workflow template")
 
     def add_workflow_template(self, template_name: str, workflow_template: WorkflowTemplate) -> None:
+        """创建并持久化新的 workflow template 实体。
+        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
+        Args:        template_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。        workflow_template (WorkflowTemplate): 参与 add workflow template 逻辑运算或数据构建的上下文依赖对象。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         self.generate_workflow_template(workflow_template)
 
     def get_all_workflow_templates(self) -> dict:
+        """检索并获取特定的 all workflow templates 数据集合或实例对象。
+        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
+        Returns:         (dict): 高度聚合的字典结构数据，将多维度的属性特征或统计指标组合后一并返回。    """
         return self.workflow_templates_registry
 
     def delete_workflow_template(self, template_name: str) -> None:
+        """安全地移除或注销 workflow template。
+        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
+        Args:        template_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
+        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。    """
         if template_name in self.workflow_templates_registry:
             del self.workflow_templates_registry[template_name]