refactor: 优化代码注释和文档字符串格式

backend/app/api/v1/module_application/ai/controller.py

@@ -23,7 +23,15 @@ async def chat_controller(
     query: ChatQuerySchema,
     auth: AuthSchema = Depends(AuthPermission(["app:ai:chat"]))
 ) -> StreamingResponse:
-    """智能对话接口"""
+    """
+    智能对话接口
+
+    参数:
+    - query (ChatQuerySchema): 聊天查询模型
+
+    返回:
+    - StreamingResponse: 流式响应,每次返回一个聊天响应
+    """
     user_name = auth.user.name if auth.user else "未知用户"
     logger.info(f"用户 {user_name} 发起智能对话: {query.message[:50]}...")
 
@@ -45,6 +53,15 @@ async def detail_controller(
     id: int = Path(..., description="MCP ID"),
     auth: AuthSchema = Depends(AuthPermission(["app:ai:query"]))
 ) -> JSONResponse:
+    """
+    获取 MCP 服务器详情接口
+
+    参数:
+    - id (int): MCP 服务器ID
+
+    返回:
+    - JSONResponse: 包含 MCP 服务器详情的 JSON 响应
+    """
     result_dict = await McpService.detail_service(auth=auth, id=id)
     logger.info(f"获取 MCP 服务器详情成功 {id}")
     return SuccessResponse(data=result_dict, msg="获取 MCP 服务器详情成功")
@@ -56,6 +73,17 @@ async def list_controller(
     search: McpQueryParam = Depends(),
     auth: AuthSchema = Depends(AuthPermission(["app:ai:query"]))
 ) -> JSONResponse:
+    """
+    查询 MCP 服务器列表接口
+
+    参数:
+    - page (PaginationQueryParam): 分页查询参数模型
+    - search (McpQueryParam): 查询参数模型
+    - auth (AuthSchema): 认证信息模型
+
+    返回:
+    - JSONResponse: 包含 MCP 服务器列表的 JSON 响应
+    """
     result_dict_list = await McpService.list_service(auth=auth, search=search, order_by=page.order_by)
     result_dict = await PaginationService.paginate(data_list=result_dict_list, page_no=page.page_no, page_size=page.page_size)
     logger.info(f"查询 MCP 服务器列表成功")
@@ -67,6 +95,16 @@ async def create_controller(
     data: McpCreateSchema,
     auth: AuthSchema = Depends(AuthPermission(["app:ai:create"]))
 ) -> JSONResponse:
+    """
+    创建 MCP 服务器接口
+
+    参数:
+    - data (McpCreateSchema): 创建 MCP 服务器模型
+    - auth (AuthSchema): 认证信息模型
+
+    返回:
+    - JSONResponse: 包含创建 MCP 服务器结果的 JSON 响应
+    """
     result_dict = await McpService.create_service(auth=auth, data=data)
     logger.info(f"创建 MCP 服务器成功: {result_dict}")
     return SuccessResponse(data=result_dict, msg="创建 MCP 服务器成功")
@@ -78,6 +116,17 @@ async def update_controller(
     id: int = Path(..., description="MCP ID"),
     auth: AuthSchema = Depends(AuthPermission(["app:ai:update"]))
 ) -> JSONResponse:
+    """
+    修改 MCP 服务器接口
+
+    参数:
+    - data (McpUpdateSchema): 修改 MCP 服务器模型
+    - id (int): MCP 服务器ID
+    - auth (AuthSchema): 认证信息模型
+
+    返回:
+    - JSONResponse: 包含修改 MCP 服务器结果的 JSON 响应
+    """
     result_dict = await McpService.update_service(auth=auth, id=id, data=data)
     logger.info(f"修改 MCP 服务器成功: {result_dict}")
     return SuccessResponse(data=result_dict, msg="修改 MCP 服务器成功")
@@ -88,6 +137,16 @@ async def delete_controller(
     ids: list[int] = Body(..., description="ID列表"),
     auth: AuthSchema = Depends(AuthPermission(["app:ai:delete"]))
 ) -> JSONResponse:
+    """
+    删除 MCP 服务器接口
+
+    参数:
+    - ids (list[int]): MCP 服务器ID列表
+    - auth (AuthSchema): 认证信息模型
+
+    返回:
+    - JSONResponse: 包含删除 MCP 服务器结果的 JSON 响应
+    """
     await McpService.delete_service(auth=auth, ids=ids)
     logger.info(f"删除 MCP 服务器成功: {ids}")
     return SuccessResponse(msg="删除 MCP 服务器成功")
@@ -97,7 +156,8 @@ async def delete_controller(
 async def websocket_chat_controller(
     websocket: WebSocket,
 ):
-    """WebSocket聊天接口
+    """
+    WebSocket聊天接口
 
     ws://127.0.0.1:8001/api/v1/ai/mcp/ws/chat
     """

backend/app/api/v1/module_application/ai/crud.py

@@ -12,30 +12,85 @@ class McpCRUD(CRUDBase[McpModel, McpCreateSchema, McpUpdateSchema]):
     """MCP 服务器数据层"""
 
     def __init__(self, auth: AuthSchema) -> None:
-        """初始化CRUD"""
+        """
+        初始化CRUD
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        """
         self.auth = auth
         super().__init__(model=McpModel, auth=auth)
 
     async def get_by_id_crud(self, id: int) -> Optional[McpModel]:
-        """详情"""
+        """
+        获取MCP服务器详情
+
+        参数:
+        - id (int): MCP服务器ID
+
+        返回:
+        - Optional[McpModel]: MCP服务器模型实例（如果存在）
+        """
         return await self.get(id=id)
 
     async def get_by_name_crud(self, name: str) -> Optional[McpModel]:
-        """通过名称获取MCP服务器"""
+        """
+        通过名称获取MCP服务器
+
+        参数:
+        - name (str): MCP服务器名称
+
+        返回:
+        - Optional[McpModel]: MCP服务器模型实例（如果存在）
+        """
         return await self.get(name=name)
 
     async def get_list_crud(self, search: Optional[Dict] = None, order_by: Optional[List[Dict[str, str]]] = None) -> Sequence[McpModel]:
-        """列表查询"""
+        """
+        列表查询MCP服务器
+
+        参数:
+        - search (Optional[Dict]): 查询参数字典
+        - order_by (Optional[List[Dict[str, str]]]): 排序参数列表
+
+        返回:
+        - Sequence[McpModel]: MCP服务器模型实例序列
+        """
         return await self.list(search=search or {}, order_by=order_by or [{'id': 'asc'}])
 
     async def create_crud(self, data: McpCreateSchema) -> Optional[McpModel]:
-        """创建"""
+        """
+        创建MCP服务器
+
+        参数:
+        - data (McpCreateSchema): 创建MCP服务器模型
+
+        返回:
+        - Optional[McpModel]: 创建的MCP服务器模型实例（如果成功）
+        """
         return await self.create(data=data)
 
     async def update_crud(self, id: int, data: McpUpdateSchema) -> Optional[McpModel]:
-        """更新"""
+        """
+        更新MCP服务器
+
+        参数:
+        - id (int): MCP服务器ID
+        - data (McpUpdateSchema): 更新MCP服务器模型
+
+        返回:
+        - Optional[McpModel]: 更新的MCP服务器模型实例（如果成功）
+        """
         return await self.update(id=id, data=data)
 
     async def delete_crud(self, ids: List[int]) -> None:
-        """批量删除"""
+        """
+        批量删除MCP服务器
+
+        参数:
+        - ids (List[int]): MCP服务器ID列表
+
+        返回:
+        - None
+        """
         return await self.delete(ids=ids)

backend/app/api/v1/module_application/ai/service.py

@@ -15,23 +15,51 @@ class McpService:
 
     @classmethod
     async def detail_service(cls, auth: AuthSchema, id: int) -> Dict[str, Any]:
-        """详情"""
+        """
+        获取MCP服务器详情
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - id (int): MCP服务器ID
+
+        返回:
+        - Dict[str, Any]: MCP服务器详情字典
+        """
         obj = await McpCRUD(auth).get_by_id_crud(id=id)
         if not obj:
             raise CustomException(msg='MCP 服务器不存在')
         return McpOutSchema.model_validate(obj).model_dump()
 
     @classmethod
     async def list_service(cls, auth: AuthSchema, search: Optional[McpQueryParam] = None, order_by: Optional[List[Dict[str, str]]] = None) -> List[Dict[str, Any]]:
-        """列表查询"""
+        """
+        列表查询MCP服务器
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - search (Optional[McpQueryParam]): 查询参数模型
+        - order_by (Optional[List[Dict[str, str]]]): 排序参数列表
+
+        返回:
+        - List[Dict[str, Any]]: MCP服务器详情字典列表
+        """
         if order_by:
             order_by = eval(str(order_by))
         obj_list = await McpCRUD(auth).get_list_crud(search=search.__dict__ if search else {}, order_by=order_by)
         return [McpOutSchema.model_validate(obj).model_dump() for obj in obj_list]
 
     @classmethod
     async def create_service(cls, auth: AuthSchema, data: McpCreateSchema) -> Dict[str, Any]:
-        """创建"""
+        """
+        创建MCP服务器
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - data (McpCreateSchema): 创建MCP服务器模型
+
+        返回:
+        - Dict[str, Any]: 创建的MCP服务器详情字典
+        """
         obj = await McpCRUD(auth).get_by_name_crud(name=data.name)
         if obj:
             raise CustomException(msg='创建失败，MCP 服务器已存在')
@@ -40,7 +68,17 @@ async def create_service(cls, auth: AuthSchema, data: McpCreateSchema) -> Dict[s
 
     @classmethod
     async def update_service(cls, auth: AuthSchema, id: int, data: McpUpdateSchema) -> Dict[str, Any]:
-        """更新"""
+        """
+        更新MCP服务器
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - id (int): MCP服务器ID
+        - data (McpUpdateSchema): 更新MCP服务器模型
+
+        返回:
+        - Dict[str, Any]: 更新的MCP服务器详情字典
+        """
         obj = await McpCRUD(auth).get_by_id_crud(id=id)
         if not obj:
             raise CustomException(msg='更新失败，该数据不存在')
@@ -52,7 +90,16 @@ async def update_service(cls, auth: AuthSchema, id: int, data: McpUpdateSchema)
 
     @classmethod
     async def delete_service(cls, auth: AuthSchema, ids: List[int]) -> None:
-        """删除"""
+        """
+        批量删除MCP服务器
+
+        参数:
+        - auth (AuthSchema): 认证信息模型
+        - ids (List[int]): MCP服务器ID列表
+
+        返回:
+        - None
+        """
         if len(ids) < 1:
             raise CustomException(msg='删除失败，删除对象不能为空')
         for id in ids:
@@ -63,7 +110,15 @@ async def delete_service(cls, auth: AuthSchema, ids: List[int]) -> None:
 
     @classmethod
     async def chat_query(cls, query: ChatQuerySchema):
-        """处理聊天查询"""
+        """
+        处理聊天查询
+
+        参数:
+        - query (ChatQuerySchema): 聊天查询模型
+
+        返回:
+        - AsyncGenerator[str, None]: 异步生成器,每次返回一个聊天响应
+        """
         # 创建MCP客户端实例
         mcp_client = AIClient()
         try: