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

kilostar/api/agent.py

@@ -28,8 +28,7 @@ agent_router = APIRouter(prefix="/api/v1/agent", tags=["agent"])
 
 
 class AgentRegister(BaseModel):
-    """AgentRegister 核心组件类。
-    这是一个领域数据模型或功能封装类，承载了 AgentRegister 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。"""
+    """``POST /agent`` 入参（远程模型）：通过 provider + model_id 加载系统节点。"""
 
     provider_title: str
     model_id: str
@@ -38,8 +37,7 @@ class AgentRegister(BaseModel):
 
 
 class AgentLocalRegister(BaseModel):
-    """AgentLocalRegister 核心组件类。
-    这是一个领域数据模型或功能封装类，承载了 AgentLocalRegister 相关的内聚属性定义与状态维护。它的存在隔离了局部的业务复杂性，并对外提供了类型安全的访问接口。"""
+    """``POST /agent`` 入参（本地模型）：通过本地路径加载系统节点。"""
 
     path: str
     individual_name: str
@@ -50,10 +48,7 @@ class AgentLocalRegister(BaseModel):
 async def get_system_nodes(
     _: TokenData = Depends(RoleChecker(allowed_roles=UserAuthority.USER)),
 ):
-    """处理针对 get system nodes 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        _ (TokenData): 参与 get system nodes 逻辑运算或数据构建的上下文依赖对象。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """返回三大系统节点（regulatory/consciousness/control）当前的持久化配置。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     configs = await postgres_database.get_all_system_node_configs.remote()
     return {"system_nodes": configs}
@@ -64,10 +59,7 @@ async def load_agent(
     agent_register: Union[AgentRegister, AgentLocalRegister],
     _: TokenData = Depends(RoleChecker(allowed_roles=UserAuthority.USER)),
 ):
-    """处理针对 load agent 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        agent_register (Union[AgentRegister, AgentLocalRegister]): 参与 load agent 逻辑运算或数据构建的上下文依赖对象。        _ (TokenData): 参与 load agent 逻辑运算或数据构建的上下文依赖对象。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """加载/重载某个系统节点的 Agent：先持久化配置，再调用对应节点 Actor 的 ``create_agent``。"""
     global_state_machine = ray_actor_hook("global_state_machine").global_state_machine
     postgres_database = ray_actor_hook("postgres_database").postgres_database
 
@@ -76,7 +68,6 @@ async def load_agent(
 
     elif isinstance(agent_register, AgentRegister):
         try:
-            # Persist configuration
             await postgres_database.upsert_system_node_config.remote(
                 agent_register.individual_name,
                 agent_register.provider_title,
@@ -84,7 +75,6 @@ async def load_agent(
                 agent_register.tools,
             )
 
-            # Load agent into state machine
             match agent_register.individual_name:
                 case "regulatory_node":
                     node = ray_actor_hook("regulatory_node").regulatory_node
@@ -118,8 +108,7 @@ async def load_agent(
 
 
 class WorkerIndividualCreate(BaseModel):
-    """WorkerIndividualCreate 核心组件类。
-    这是一个具体的 Worker 智能体实体类，代表着具备特定人设、领域技能或长文本处理能力的数字员工。它可以被控制器动态拉起，并在安全沙箱内执行复杂的工作流指令与多步骤推理任务。"""
+    """``POST /worker`` 入参：创建一个 Worker Agent 所需的完整配置。"""
 
     agent_name: str
     agent_type: AgentType
@@ -134,8 +123,7 @@ class WorkerIndividualCreate(BaseModel):
 
 
 class WorkerIndividualUpdate(BaseModel):
-    """WorkerIndividualUpdate 核心组件类。
-    这是一个具体的 Worker 智能体实体类，代表着具备特定人设、领域技能或长文本处理能力的数字员工。它可以被控制器动态拉起，并在安全沙箱内执行复杂的工作流指令与多步骤推理任务。"""
+    """``PUT /worker/{agent_id}`` 入参：可选字段构成的局部更新载荷。"""
 
     agent_name: Optional[str] = None
     agent_type: Optional[AgentType] = None
@@ -154,10 +142,7 @@ async def create_worker_individual(
     worker_data: WorkerIndividualCreate,
     token_data: TokenData = Depends(RoleChecker(allowed_roles=UserAuthority.USER)),
 ):
-    """处理针对 create worker individual 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        worker_data (WorkerIndividualCreate): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。        token_data (TokenData): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """创建一个 Worker Agent，``owner_id`` 自动绑定为当前登录用户。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     data_dict = worker_data.model_dump()
     data_dict["owner_id"] = token_data.user_id
@@ -169,10 +154,7 @@ async def create_worker_individual(
 async def get_worker_individual_list(
     token_data: TokenData = Depends(Accessor.get_current_user),
 ):
-    """处理针对 get worker individual list 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        token_data (TokenData): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """列出当前登录用户名下的全部 Worker Agent。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     workers = await postgres_database.get_worker_individual_list.remote(
         owner_id=token_data.user_id
@@ -184,10 +166,7 @@ async def get_worker_individual_list(
 async def get_worker_individual(
     agent_id: str, token_data: TokenData = Depends(Accessor.get_current_user)
 ):
-    """处理针对 get worker individual 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。        token_data (TokenData): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """按 ``agent_id`` 查询 Worker Agent；非本人的 Agent 返回 403。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     worker = await postgres_database.get_worker_individual.remote(agent_id=agent_id)
     if not worker:
@@ -205,10 +184,7 @@ async def update_worker_individual(
     worker_data: WorkerIndividualUpdate,
     token_data: TokenData = Depends(Accessor.get_current_user),
 ):
-    """处理针对 update worker individual 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。        worker_data (WorkerIndividualUpdate): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。        token_data (TokenData): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """局部更新 Worker Agent 配置；同时把状态机里的旧实例移除等待懒加载。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     worker = await postgres_database.get_worker_individual.remote(agent_id=agent_id)
     if not worker:
@@ -236,10 +212,7 @@ async def update_worker_individual(
 async def reload_worker_individual(
     agent_id: str, token_data: TokenData = Depends(Accessor.get_current_user)
 ):
-    """处理针对 reload worker individual 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。        token_data (TokenData): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """强制把 Worker 从内存池中卸载，下次调用时按最新配置重新加载。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     worker = await postgres_database.get_worker_individual.remote(agent_id=agent_id)
     if not worker:
@@ -259,10 +232,7 @@ async def reload_worker_individual(
 async def delete_worker_individual(
     agent_id: str, token_data: TokenData = Depends(Accessor.get_current_user)
 ):
-    """处理针对 delete worker individual 相关的 HTTP API 请求。
-    该接口负责解析前端传入的载荷数据，调用底层核心业务逻辑进行处理，并组装标准化的 JSON 响应。
-    Args:        agent_id (str): 目标对象的唯一全局标识符 (UUID/ULID)，用于在数据库表或缓存结构中精准匹配该 agent 实例。        token_data (TokenData): 从客户端传递过来或由上游组件生成的核心业务数据体，通常需要进一步的清洗和结构化解析。
-    Returns:        : 序列化后的标准网络响应模型（如包含业务状态码、成功标志及对应的数据载荷 Data）。"""
+    """删除 Worker Agent；非本人 Agent 返回 403。"""
     postgres_database = ray_actor_hook("postgres_database").postgres_database
     worker = await postgres_database.get_worker_individual.remote(agent_id=agent_id)
     if not worker: