feat(frontend):优化前端页面设计

kilostar/core/postgres_database/database_exception.py

@@ -22,15 +22,9 @@ logger = get_logger("database_exception")
 
 
 def database_exception(func):
-    """执行与 database exception 相关的核心业务流转操作。
-    该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-    Args:        func: 参与 database exception 逻辑运算或数据构建的上下文依赖对象。
-    Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+    """异步装饰器：把 SQLAlchemy / Pydantic / 业务异常归类记日志后再抛出。"""
 
     async def wrapper(*args, **kwargs):
-        """执行与 wrapper 相关的核心业务流转操作。
-        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
         try:
             return await func(*args, **kwargs)
         except ValidationError as e:

kilostar/core/postgres_database/module/individual.py

@@ -32,8 +32,7 @@ _AGENT_TYPE_MODEL_MAP = {
 
 
 class IndividualDatabase:
-    """IndividualDatabase 核心组件类。
-    这是一个数据库操作层 (DAO/Repository) 封装类，专注于处理实体模型与关系型数据库表之间的映射。它将复杂的 SQL 查询、跨表 Join 和事务回滚逻辑进行了高级抽象，向上层服务暴露简洁的数据读写接口。"""
+    """Individual 表族（Base/Specialist/Ordinary/Special）的 DAO，按 agent_type 选择具体子表。"""
 
     def __init__(self, async_session_maker):
         self.async_session_maker = async_session_maker
@@ -44,8 +43,7 @@ class IndividualDatabase:
 
     @database_exception
     async def add_worker_individual(self, **kwargs):
-        """创建并持久化新的 worker individual 实体。
-        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。"""
+        """新建一个 Worker Individual：自动生成 ULID，按 ``agent_type`` 选择对应子表写入。"""
         async with self.async_session_maker() as session:
             agent_id = str(ULID())
             agent_type = kwargs.get("agent_type", "base")
@@ -58,7 +56,7 @@ class IndividualDatabase:
 
     @database_exception
     async def get_worker_individual(self, agent_id: str):
-        """检索并获取特定的 worker individual 数据集合或实例对象。"""
+        """按 agent_id 取单个 Individual；不存在返回 None。"""
         async with self.async_session_maker() as session:
             statement = select(BaseIndividualModel).where(
                 BaseIndividualModel.agent_id == agent_id
@@ -68,7 +66,7 @@ class IndividualDatabase:
 
     @database_exception
     async def get_worker_individual_list(self, owner_id: str):
-        """检索并获取特定的 worker individual list 数据集合或实例对象。"""
+        """读取某用户名下的所有 Individual。"""
         async with self.async_session_maker() as session:
             statement = select(BaseIndividualModel).where(
                 BaseIndividualModel.owner_id == owner_id
@@ -78,7 +76,7 @@ class IndividualDatabase:
 
     @database_exception
     async def update_worker_individual(self, agent_id: str, **kwargs):
-        """对现有的 worker individual 进行状态更新或属性覆盖。"""
+        """部分更新 Individual：只覆盖 kwargs 中非 None 的字段；找不到返回 None。"""
         async with self.async_session_maker() as session:
             statement = select(BaseIndividualModel).where(
                 BaseIndividualModel.agent_id == agent_id
@@ -97,7 +95,7 @@ class IndividualDatabase:
 
     @database_exception
     async def delete_worker_individual(self, agent_id: str) -> bool:
-        """安全地移除或注销 worker individual。"""
+        """删除 Individual；不存在返回 False，删除成功返回 True。"""
         async with self.async_session_maker() as session:
             statement = select(BaseIndividualModel).where(
                 BaseIndividualModel.agent_id == agent_id
@@ -112,7 +110,7 @@ class IndividualDatabase:
 
     @database_exception
     async def get_all_worker_individual(self):
-        """检索并获取特定的 all worker individual 数据集合或实例对象。"""
+        """返回数据库中全部 Individual。"""
         async with self.async_session_maker() as session:
             statement = select(BaseIndividualModel)
             results = await session.execute(statement)

kilostar/core/postgres_database/module/provider.py

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

kilostar/core/postgres_database/module/system_node.py

@@ -19,8 +19,7 @@ from kilostar.core.postgres_database.database_exception import database_exceptio
 
 
 class SystemNodeDatabase:
-    """SystemNodeDatabase 核心组件类。
-    这是一个系统执行节点类，作为多智能体架构中的独立处理单元。它能够接收工作流上下文，根据内置的大模型策略进行意图理解和自主决策，从而驱动特定阶段的任务闭环。"""
+    """SystemNodeConfig 表的 DAO：管理 control/consciousness/regulatory 等系统节点的模型配置。"""
 
     def __init__(self, async_session_maker):
         self.async_session_maker = async_session_maker
@@ -33,10 +32,7 @@ class SystemNodeDatabase:
         model_id: str,
         tools: Optional[List[str]] = None,
     ) -> SystemNodeConfigModel:
-        """执行与 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:         (SystemNodeConfigModel): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按 node_name 插入或更新一个系统节点的模型配置（Provider + 模型 ID + 工具列表）。"""
         async with self.async_session_maker() as session:
             statement = select(SystemNodeConfigModel).where(
                 SystemNodeConfigModel.node_name == node_name
@@ -62,9 +58,7 @@ class SystemNodeDatabase:
 
     @database_exception
     async def get_all_system_node_configs(self) -> List[SystemNodeConfigModel]:
-        """检索并获取特定的 all system node configs 数据集合或实例对象。
-        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
-        Returns:         (List[SystemNodeConfigModel]): 经过筛选、排序或分页处理后的实体对象列表集合。"""
+        """返回所有系统节点的模型配置列表。"""
         async with self.async_session_maker() as session:
             statement = select(SystemNodeConfigModel)
             results = await session.execute(statement)
@@ -74,10 +68,7 @@ class SystemNodeDatabase:
     async def get_system_node_config(
         self, node_name: str
     ) -> Optional[SystemNodeConfigModel]:
-        """检索并获取特定的 system node config 数据集合或实例对象。
-        根据提供的查询条件或上下文凭证，从数据库、缓存或第三方服务中读取对应的资源状态。
-        Args:        node_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
-        Returns:         (Optional[SystemNodeConfigModel]): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按 node_name 取出单个系统节点的模型配置；不存在返回 None。"""
         async with self.async_session_maker() as session:
             statement = select(SystemNodeConfigModel).where(
                 SystemNodeConfigModel.node_name == node_name

kilostar/core/postgres_database/module/user.py

@@ -21,18 +21,14 @@ from kilostar.utils.access import Accessor
 
 
 class AuthDatabase:
-    """AuthDatabase 核心组件类。
-    这是一个数据库操作层 (DAO/Repository) 封装类，专注于处理实体模型与关系型数据库表之间的映射。它将复杂的 SQL 查询、跨表 Join 和事务回滚逻辑进行了高级抽象，向上层服务暴露简洁的数据读写接口。"""
+    """User 表的 DAO：注册、登录、改密、删除以及权限读写。"""
 
     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): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """新建一名用户；若当前库中尚无任何用户，第一名将被自动赋予 SUPER_ADMINISTRATOR 权限。"""
         from ulid import ULID
 
         async with self.async_session_maker() as session:
@@ -58,10 +54,7 @@ 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): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """校验旧密码后将其替换为新密码；旧密码不匹配抛 UserPasswordError。"""
         async with self.async_session_maker() as session:
             statement = select(User).where(User.user_name == user_name)
             results = await session.execute(statement)
@@ -78,10 +71,7 @@ class AuthDatabase:
 
     @database_exception
     async def delete_user(self, user_name: str) -> None:
-        """安全地移除或注销 user。
-        执行物理删除或逻辑删除操作，并妥善清理相关的关联数据及占用资源。
-        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
-        Returns:         (None): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按用户名删除一名用户，不存在则抛 UserNotExistError。"""
         async with self.async_session_maker() as session:
             statement = select(User).where(User.user_name == user_name)
             results = await session.execute(statement)
@@ -93,10 +83,7 @@ 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): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按用户 ID 删除一名用户，不存在则抛 UserNotExistError。"""
         async with self.async_session_maker() as session:
             user = await session.get(User, user_id)
             if user is None:
@@ -106,10 +93,7 @@ class AuthDatabase:
 
     @database_exception
     async def login_user(self, user_name: str) -> str:
-        """执行与 login user 相关的核心业务流转操作。
-        该方法封装了具体的算法策略或状态控制逻辑，确保操作能够在事务上下文中被原子且一致地执行。
-        Args:        user_name (str): 赋予该实体的人类可读名称或标题字符串，主要用于前端 UI 展示、日志记录或模糊检索。
-        Returns:         (str): 处理流程所输出的具体字符串产物，可能是新生成的 ID 序列、格式化好的文本片段或 LLM 推理的回答内容。"""
+        """按用户名查出 User 记录返回给上层；上层再做密码校验并签发 token。"""
         async with self.async_session_maker() as session:
             statement = select(User).where(User.user_name == user_name)
             results = await session.execute(statement)
@@ -120,9 +104,7 @@ 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)
@@ -131,10 +113,7 @@ 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): 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """返回指定用户的 UserAuthority 枚举；不存在抛 UserNotExistError。"""
         async with self.async_session_maker() as session:
             user = await session.get(User, user_id)
             if user is None:

kilostar/core/postgres_database/postgres.py

@@ -49,8 +49,12 @@ from .module.chat_history import ChatHistoryDatabase
 
 @ray.remote
 class PostgresDatabase:
-    """PostgresDatabase 核心组件类。
-    这是一个数据库操作层 (DAO/Repository) 封装类，专注于处理实体模型与关系型数据库表之间的映射。它将复杂的 SQL 查询、跨表 Join 和事务回滚逻辑进行了高级抽象，向上层服务暴露简洁的数据读写接口。"""
+    """以 Ray Actor 形式暴露的统一数据库门面。
+
+    内部组合了 Auth / Provider / Individual / SystemNode / Workflow / ChatHistory
+    六个子库，所有方法在调用前都会等待 ``ready_event``，确保 ``init_db`` 完成后
+    再放行业务请求。
+    """
 
     def __init__(self):
         user = os.environ.get("POSTGRES_USER")
@@ -76,6 +80,7 @@ class PostgresDatabase:
         self.ready_event = asyncio.Event()
 
     async def init_db(self) -> None:
+        """根据 metadata 创建（或校验）所有 ORM 表，并置位 ready_event。"""
         try:
             async with self.async_engine.begin() as conn:
                 await conn.run_sync(BaseDataModel.metadata.create_all)
@@ -88,98 +93,65 @@ 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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按用户 ID 删除一名用户。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按用户名查询用户记录，用于上层做密码校验与签发 token。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """返回全部已登记的模型 Provider。"""
         await self.ready_event.wait()
         return await self._provider_database.get_provider()
 
     async def add_provider_db(self, **kwargs):
-        """创建并持久化新的 provider db 实体。
-        接收构建参数，执行必要的数据校验与默认值填充后，将新记录安全地写入底层存储或系统注册表中。
-        Returns:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """新增一个模型 Provider 记录。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """删除指定 ID 的模型 Provider 记录。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """部分更新指定 Provider 的字段。"""
         await self.ready_event.wait()
         return await self._provider_database.update_provider(provider_id, **kwargs)
 
@@ -191,68 +163,47 @@ class PostgresDatabase:
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """插入或更新某个系统节点（如 control/consciousness/regulatory）的模型配置。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """登记一个新的 Worker Individual 配置。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """按 agent_id 读取单个 Worker Individual 配置。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """读取某用户名下的所有 Worker Individual 配置。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """部分更新指定 Worker Individual 的字段。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """删除指定的 Worker Individual。"""
         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:        : 经由当前业务模型加工处理后所输出的具体数据实例或领域模型对象。"""
+        """返回全部 Worker Individual 配置。"""
         await self.ready_event.wait()
         return await self._individual_database.get_all_worker_individual()
 
@@ -260,46 +211,56 @@ class PostgresDatabase:
     async def create_workflow(
         self, trace_id: str, user_id: str, title: str, command: str
     ):
+        """新建一个工作流记录。"""
         await self.ready_event.wait()
         return await self._workflow_database.create_workflow(
             trace_id, user_id, title, command
         )
 
     async def get_workflow(self, trace_id: str):
+        """按 trace_id 读取工作流记录。"""
         await self.ready_event.wait()
         return await self._workflow_database.get_workflow(trace_id)
 
     async def update_workflow_status(self, trace_id: str, status: str):
+        """更新工作流的状态字段。"""
         await self.ready_event.wait()
         return await self._workflow_database.update_workflow_status(trace_id, status)
 
     async def list_workflows(self, user_id: str):
+        """返回某用户名下的全部工作流。"""
         await self.ready_event.wait()
         return await self._workflow_database.list_workflows(user_id)
 
     async def upsert_workflow_context(self, trace_id: str, **kwargs):
+        """插入或更新工作流的运行期上下文快照。"""
         await self.ready_event.wait()
         return await self._workflow_database.upsert_workflow_context(trace_id, **kwargs)
 
     async def get_workflow_context(self, trace_id: str):
+        """读取指定工作流的上下文快照。"""
         await self.ready_event.wait()
         return await self._workflow_database.get_workflow_context(trace_id)
 
     # Chat History Database Methods
     async def create_chat_session(self, user_id: str, title: str = "新对话"):
+        """新建一个聊天会话。"""
         await self.ready_event.wait()
         return await self._chat_history_database.create_chat_session(user_id, title)
 
     async def list_chat_sessions(self, user_id: str):
+        """返回某用户名下的全部聊天会话。"""
         await self.ready_event.wait()
         return await self._chat_history_database.list_chat_sessions(user_id)
 
     async def add_chat_message(self, chat_id: str, message: str, message_owner: str):
+        """向某个聊天会话追加一条消息。"""
         await self.ready_event.wait()
         return await self._chat_history_database.add_chat_message(
             chat_id, message, message_owner
         )
 
     async def list_chat_messages(self, chat_id: str):
+        """返回某个聊天会话的全部消息。"""
         await self.ready_event.wait()
         return await self._chat_history_database.list_chat_messages(chat_id)