From feec69a78baa32d1e40ec1c93d1f3012a67d5d57 Mon Sep 17 00:00:00 2001 From: hyh Date: Thu, 7 Aug 2025 15:45:12 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=BC=95=E7=94=A8=E7=A9=BA?= =?UTF-8?q?=E9=97=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/api/v1/endpoints/__init__.py | 3 +- app/api/v1/endpoints/usb_monitor.py | 149 ---------- app/core/app/router.py | 9 +- modify.md | 446 +++------------------------- 4 files changed, 47 insertions(+), 560 deletions(-) delete mode 100644 app/api/v1/endpoints/usb_monitor.py diff --git a/app/api/v1/endpoints/__init__.py b/app/api/v1/endpoints/__init__.py index ee27690..72c373a 100644 --- a/app/api/v1/endpoints/__init__.py +++ b/app/api/v1/endpoints/__init__.py @@ -1,7 +1,7 @@ # API endpoints package for TermControlAgent # 导入所有路由模块 -from . import devices, adb, ssh, at, plnk, usb_monitor, enhanced_adb +from . import devices, adb, ssh, at, plnk, enhanced_adb __all__ = [ "devices", @@ -9,6 +9,5 @@ __all__ = [ "ssh", "at", "plnk", - "usb_monitor", "enhanced_adb" ] \ No newline at end of file diff --git a/app/api/v1/endpoints/usb_monitor.py b/app/api/v1/endpoints/usb_monitor.py deleted file mode 100644 index 4a7acfe..0000000 --- a/app/api/v1/endpoints/usb_monitor.py +++ /dev/null @@ -1,149 +0,0 @@ -from fastapi import APIRouter, HTTPException, status, BackgroundTasks -from typing import List, Dict, Any -from app.services.device_monitor_manager import device_monitor_manager -from app.utils.log import get_logger - -logger = get_logger(__name__) - -router = APIRouter() - -@router.post("/usb-monitor/start", summary="启动USB设备监听") -async def start_usb_monitoring(auto_register: bool = True): - """启动USB设备监听服务""" - try: - success = await device_monitor_manager.start_monitoring(auto_register=auto_register) - if success: - return { - "success": True, - "message": "USB设备监听服务已启动", - "auto_register": auto_register - } - else: - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail="启动USB监听服务失败" - ) - except Exception as e: - logger.error(f"启动USB监听失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"启动USB监听失败: {str(e)}" - ) - -@router.post("/usb-monitor/stop", summary="停止USB设备监听") -async def stop_usb_monitoring(): - """停止USB设备监听服务""" - try: - device_monitor_manager.stop_monitoring() - return { - "success": True, - "message": "USB设备监听服务已停止" - } - except Exception as e: - logger.error(f"停止USB监听失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"停止USB监听失败: {str(e)}" - ) - -@router.get("/usb-monitor/status", summary="获取USB监听状态") -async def get_usb_monitor_status(): - """获取USB设备监听服务状态""" - try: - monitor_info = device_monitor_manager.get_monitor_info() - return monitor_info - except Exception as e: - logger.error(f"获取USB监听状态失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"获取USB监听状态失败: {str(e)}" - ) - -@router.get("/usb-monitor/devices", summary="获取已知USB设备列表") -async def get_known_usb_devices(): - """获取已知的USB设备列表""" - try: - devices = device_monitor_manager.get_known_devices() - return { - "success": True, - "devices": devices, - "count": len(devices) - } - except Exception as e: - logger.error(f"获取USB设备列表失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"获取USB设备列表失败: {str(e)}" - ) - -@router.post("/usb-monitor/scan", summary="扫描当前USB设备") -async def scan_usb_devices(): - """扫描当前已连接的USB设备""" - try: - await device_monitor_manager.scan_devices() - devices = device_monitor_manager.get_known_devices() - return { - "success": True, - "message": "USB设备扫描完成", - "devices": devices, - "count": len(devices) - } - except Exception as e: - logger.error(f"扫描USB设备失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"扫描USB设备失败: {str(e)}" - ) - -@router.get("/usb-monitor/device/{device_key}", summary="获取指定USB设备信息") -async def get_usb_device_info(device_key: str): - """获取指定USB设备的详细信息""" - try: - device_info = device_monitor_manager.get_device_info(device_key) - if device_info: - return { - "success": True, - "device": device_info.to_dict() - } - else: - raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, - detail="设备未找到" - ) - except HTTPException: - raise - except Exception as e: - logger.error(f"获取USB设备信息失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"获取USB设备信息失败: {str(e)}" - ) - -@router.post("/usb-monitor/auto-register/{device_key}", summary="手动注册指定USB设备") -async def register_usb_device(device_key: str): - """手动注册指定的USB设备""" - try: - device_info = device_monitor_manager.get_device_info(device_key) - if not device_info: - raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, - detail="设备未找到" - ) - - # 触发自动注册 - if device_monitor_manager.current_monitor: - await device_monitor_manager.current_monitor._auto_register_device(device_info) - - return { - "success": True, - "message": f"设备 {device_key} 注册成功", - "device": device_info.to_dict() - } - except HTTPException: - raise - except Exception as e: - logger.error(f"注册USB设备失败: {e}") - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"注册USB设备失败: {str(e)}" - ) \ No newline at end of file diff --git a/app/core/app/router.py b/app/core/app/router.py index c84ea7d..32a04e5 100644 --- a/app/core/app/router.py +++ b/app/core/app/router.py @@ -70,7 +70,7 @@ def register_routers(): try: # 导入所有路由模块 from app.api.v1.endpoints import ( - devices, adb, ssh, at, plnk, usb_monitor, enhanced_adb + devices, adb, ssh, at, plnk, enhanced_adb ) # 注册设备管理路由 @@ -115,12 +115,7 @@ def register_routers(): tags=["PLNK协议"] ) - # 注册USB设备监听路由 - router_manager.register_router( - usb_monitor.router, - prefix="/api/v1", - tags=["USB设备监听"] - ) + logger.info("路由注册配置完成") diff --git a/modify.md b/modify.md index 843be72..9e428c9 100644 --- a/modify.md +++ b/modify.md @@ -1,402 +1,44 @@ -# 修改记录 - -## 2024-01-XX - Core模块层级结构重构 - -### 重构概述 -对 `app/core` 目录进行了全面的层级结构重构,将原本的单文件结构重新组织为功能明确的子模块,提高了代码的可维护性和扩展性。 - -### 重构后的目录结构 -``` -app/core/ -├── __init__.py # 模块初始化 -├── config/ # 配置管理 -│ ├── __init__.py -│ ├── settings.py # 应用配置 -│ └── cors.py # CORS配置 -├── exceptions/ # 异常管理 -│ ├── __init__.py -│ ├── base.py # 基础异常类 -│ ├── adb.py # ADB异常 -│ └── business.py # 业务异常 -├── middleware/ # 中间件 -│ ├── __init__.py -│ └── request.py # 请求中间件 -├── app/ # 应用管理 -│ ├── __init__.py -│ ├── factory.py # 应用工厂 -│ └── router.py # 路由管理 -├── adb/ # ADB核心功能 -│ ├── __init__.py -│ ├── connection.py # ADB连接 -│ └── client.py # ADB客户端 -├── device/ # 设备管理 -│ ├── __init__.py -│ ├── manager.py # 设备管理器 -│ └── dispatcher.py # 设备分发器 -├── handlers/ # 异常处理器 -│ ├── __init__.py -│ └── exception_handlers.py # 全局异常处理器 -``` - -### 新增文件 - -#### 1. 配置管理模块 (`app/core/config/`) -- `__init__.py` - 配置模块初始化 -- `settings.py` - 应用配置管理 -- `cors.py` - CORS配置管理 - -#### 2. 异常管理模块 (`app/core/exceptions/`) -- `__init__.py` - 异常模块初始化 -- `base.py` - 基础异常类 -- `adb.py` - ADB相关异常 -- `business.py` - 业务逻辑异常 - -#### 3. 中间件模块 (`app/core/middleware/`) -- `__init__.py` - 中间件模块初始化 -- `request.py` - 请求中间件 - -#### 4. 应用管理模块 (`app/core/app/`) -- `__init__.py` - 应用模块初始化 -- `factory.py` - 应用工厂 -- `router.py` - 路由管理器 - -#### 5. ADB核心功能模块 (`app/core/adb/`) -- `__init__.py` - ADB模块初始化 -- `connection.py` - ADB连接管理 -- `client.py` - ADB客户端 - -#### 6. 设备管理模块 (`app/core/device/`) -- `__init__.py` - 设备模块初始化 -- `manager.py` - 设备管理器 -- `dispatcher.py` - 设备分发器 - -#### 7. 异常处理器模块 (`app/core/handlers/`) -- `__init__.py` - 处理器模块初始化 -- `exception_handlers.py` - 全局异常处理器 - -### 删除文件 -- `app/core/exception_handlers.py` → 移动到 `app/core/handlers/exception_handlers.py` -- `app/core/adb_exceptions.py` → 移动到 `app/core/exceptions/adb.py` -- `app/core/app_factory.py` → 移动到 `app/core/app/factory.py` -- `app/core/middleware.py` → 移动到 `app/core/middleware/request.py` -- `app/core/router_manager.py` → 移动到 `app/core/app/router.py` -- `app/core/config.py` → 移动到 `app/core/config/settings.py` -- `app/core/cors_config.py` → 移动到 `app/core/config/cors.py` -- `app/core/adb_client.py` → 移动到 `app/core/adb/client.py` -- `app/core/adb_connection.py` → 移动到 `app/core/adb/connection.py` -- `app/core/device_manager.py` → 移动到 `app/core/device/manager.py` -- `app/core/dispatcher.py` → 移动到 `app/core/device/dispatcher.py` - -### 修改文件 - -#### 1. 主模块 (`app/main.py`) -- 更新导入路径:`app.core.app_factory` → `app.core.app` - -#### 2. 启动脚本 (`run.py`) -- 更新导入路径:`app.core.app_factory` → `app.core.app` - -#### 3. Core模块初始化 (`app/core/__init__.py`) -- 重新组织导入结构 -- 添加设备管理模块的导入 -- 统一导出接口 - -### 重构优势 - -#### 1. 层次分明 -- **config/**: 配置管理,职责单一 -- **exceptions/**: 异常管理,分类清晰 -- **middleware/**: 中间件,功能独立 -- **app/**: 应用管理,核心逻辑 -- **adb/**: ADB功能,业务相关 -- **device/**: 设备管理,设备相关 -- **handlers/**: 异常处理,统一管理 - -#### 2. 职责清晰 -- 每个目录都有明确的职责 -- 文件命名更加规范 -- 导入路径更加清晰 - -#### 3. 易于维护 -- 新增功能时知道放在哪里 -- 修改功能时容易定位 -- 删除功能时影响范围小 - -#### 4. 扩展性好 -- 新增配置类型:放在 `config/` -- 新增异常类型:放在 `exceptions/` -- 新增中间件:放在 `middleware/` -- 新增业务功能:放在对应目录 - -### 导入路径更新 -所有导入路径都已经更新: -- `app.core.app_factory` → `app.core.app` -- `app.core.config` → `app.core.config` -- `app.core.exceptions` → `app.core.exceptions` -- `app.core.middleware` → `app.core.middleware` -- `app.core.device` → `app.core.device` - -## 2024-01-XX - ADB架构优化和日志系统增强 - -### 新增文件 - -#### 1. 数据模型层 (`app/models/adb_models.py`) -- 创建了完整的ADB数据模型定义 -- 包含设备状态枚举、设备信息、设备事件、端口转发等模型 -- 使用Pydantic进行数据验证和序列化 - -#### 2. 核心连接层 (`app/core/adb_connection.py`) -- 重构了ADB连接核心模块 -- 实现了底层协议通信处理 -- 支持异步上下文管理器 -- 添加了详细的错误处理和日志记录 - -#### 3. 核心客户端层 (`app/core/adb_client.py`) -- 创建了ADB客户端核心类 -- 提供高级API接口 -- 实现了设备管理、Shell命令执行、端口转发等功能 -- 支持设备状态跟踪和变化监控 - -#### 4. 增强服务层 (`app/services/enhanced_adb_service.py`) -- 创建了增强的ADB服务类 -- 提供业务逻辑层 -- 支持设备监控、Shell命令执行等高级功能 -- 实现了异步任务管理 - -#### 5. API端点层 (`app/api/v1/endpoints/enhanced_adb.py`) -- 创建了增强的ADB API端点 -- 提供RESTful API接口 -- 支持设备管理、Shell命令执行、端口转发等操作 -- 实现了完整的错误处理和响应 - -#### 6. 结构化日志系统 (`app/utils/structured_log.py`) -- 创建了类似Serilog的结构化日志系统 -- 支持JSON格式的日志输出 -- 包含请求上下文、异常堆栈跟踪等功能 -- 实现了日志级别管理和格式化 - -#### 7. ADB工具模块 (`app/utils/adb_utils.py`) -- 创建了ADB工具类 -- 提供常用的ADB操作函数 -- 支持设备属性获取、屏幕操作等功能 - -### 修改文件 - -#### 1. 配置管理 (`app/core/config.py`) -- 重构了配置管理模块 -- 分离了ADB配置和应用配置 -- 支持环境变量和配置文件 - -#### 2. 日志系统 (`app/utils/log.py`) -- 增强了日志系统 -- 支持结构化日志和传统日志 -- 添加了日志目录自动创建 -- 实现了向后兼容 - -#### 3. API路由配置 (`app/api/v1/endpoints/__init__.py`) -- 更新了API端点初始化 -- 包含新的增强ADB端点 - -### 架构优化特点 - -#### 1. 层次分明 -- **Models层**: 数据模型和DTO定义 -- **Core层**: 核心连接和协议处理 -- **Services层**: 业务逻辑服务 -- **API层**: FastAPI路由和端点 -- **Utils层**: 工具函数和配置 - -#### 2. 命名规范 -- 使用清晰的模块命名:`adb_connection.py`, `adb_client.py`, `enhanced_adb_service.py` -- 方法命名遵循Python规范:`get_server_version()`, `list_devices()`, `execute_shell_command()` -- 变量命名使用下划线分隔:`device_serial`, `status_filter` - -#### 3. 日志系统增强 -- 实现了结构化日志,类似Serilog -- 支持JSON格式输出,便于日志分析 -- 包含请求上下文、异常堆栈等详细信息 -- 支持多种日志级别:TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL - -#### 4. 错误处理完善 -- 自定义异常类:`AdbProtocolError`, `AdbConnectionError` -- 详细的错误信息和上下文 -- 统一的错误处理机制 - -#### 5. 异步支持 -- 全异步架构设计 -- 支持设备状态实时监控 -- 异步任务管理 - -### 使用示例 - -#### 1. 获取设备列表 -```python -from app.services.enhanced_adb_service import EnhancedAdbService - -service = EnhancedAdbService() -devices = await service.list_devices() -``` - -#### 2. 执行Shell命令 -```python -result = await service.execute_shell_command("device_serial", "ls /sdcard") -``` - -#### 3. 设备监控 -```python -await service.start_device_monitoring() -``` - -#### 4. 结构化日志 -```python -from app.utils.log import get_enhanced_logger - -logger = get_enhanced_logger("my_module") -logger.info("操作完成", device_count=5, duration_ms=1200) -``` - -### 日志输出示例 - -```json -{ - "timestamp": "2024-01-XXT10:30:45.123456", - "level": "INFO", - "message": "获取设备列表成功", - "logger_name": "app.services.enhanced_adb_service", - "context": { - "request_id": "req-123", - "user_id": "user-456", - "module": "enhanced_adb_service", - "function": "list_devices", - "line_number": 45, - "extra": { - "device_count": 3, - "status_filter": null - } - } -} -``` - -### 下一步计划 - -1. 添加单元测试和集成测试 -2. 实现WebSocket支持实时设备状态推送 -3. 添加设备截图和文件传输功能 -4. 实现设备应用管理功能 -5. 添加性能监控和指标收集 - -### 最新修改 (2024-12-19) - -#### 文件转换 -- 将 `txt` 文件转换为 `original_adb_client_reference.md` 文件,保持内容完全不变 -- 原文件内容包含ADB客户端实现代码,作为参考文档保存 -- 添加了说明注释,标明这是重构前的原始代码 - -#### 服务重构 -- 保留 `enhanced_adb_service.py` 作为唯一的ADB服务 -- 删除 `device_monitor_manager.py` 文件,避免功能冗余 -- `enhanced_adb_service.py` 包含完整的ADB功能: - - 设备监控(程序启动时自动开始,异常时自动重启) - - 设备管理(list_devices, get_device_info, ping_device) - - Shell命令执行(execute_shell_command) - - 应用管理(install_apk, uninstall_app, get_installed_apps) - - 端口转发(list_forward_ports, create_forward_port, remove_forward_port) -- 移除手动启动/停止监控的API端点,简化使用流程 - -#### 异常处理优化 (2024-12-19) -- 创建 `app/core/adb_exceptions.py` 统一管理ADB异常类 -- 改进异常处理策略: - - **Core层**: 使用具体的异常类型(OSError, IOError等)而不是捕获所有Exception - - **Service层**: 区分ADB业务异常和未知异常 - - **API层**: 根据异常类型返回合适的HTTP状态码 -- 新增异常类型: - - `AdbDeviceNotFoundError`: 设备未找到 - - `AdbCommandTimeoutError`: 命令超时 - - `AdbServerError`: 服务器错误 - - `AdbAuthenticationError`: 认证失败 -- HTTP状态码映射: - - 400: ADB协议错误 - - 401: 认证失败 - - 404: 设备未找到 - - 408: 命令超时 - - 502: ADB服务器错误 - - 503: 连接错误 - - 500: 内部服务器错误 - -#### 应用架构重构 (2024-12-19) -- **路由管理优化**: - - 创建 `app/core/router_manager.py` 统一管理所有API路由注册 - - 使用 `RouterManager` 类集中管理路由配置 - - 支持动态路由注册和标签管理 -- **CORS配置分离**: - - 创建 `app/core/cors_config.py` 专门管理CORS配置 - - 支持开发环境和生产环境的不同CORS策略 - - 提供灵活的CORS配置选项 -- **应用工厂模式**: - - 创建 `app/core/app_factory.py` 实现应用工厂模式 - - 统一管理FastAPI应用的创建和配置 - - 支持不同环境的应用配置 -- **主模块简化**: - - 重构 `app/main.py`,移除路由注册和CORS配置代码 - - 使用应用工厂模式创建应用实例 - - 支持环境变量配置 -- **启动脚本**: - - 创建 `run.py` 提供灵活的启动选项 - - 支持命令行参数配置 - - 支持多工作进程启动 -- **配置增强**: - - 在 `app/core/config.py` 中添加CORS配置选项 - - 支持环境变量配置CORS策略 -- **架构优势**: - - **可维护性**:路由和CORS配置分离,便于维护 - - **可扩展性**:新增路由只需在路由管理器中注册 - - **环境隔离**:不同环境使用不同的配置策略 - - **启动灵活**:支持多种启动方式和参数配置 - -### 最新修改 (2024-12-19) - Git工作流程文档 - -#### 新增文件 -- 创建 `git_workflow.md` 文件,包含完整的Git提交代码流程指南 -- 文档内容包括: - - 基本工作流程(检查状态、拉取代码、添加文件、提交、推送) - - 常用命令(查看信息、撤销操作、分支操作) - - 分支管理(功能开发流程、热修复流程) - - 冲突解决(合并冲突处理、变基操作) - - 最佳实践(提交信息规范、工作流程建议、常用别名配置) - - 完整工作流程示例 - - 故障排除(常见问题解决) - -#### 文档特点 -- **全面性**:涵盖Git日常使用的所有主要操作 -- **实用性**:提供具体的命令示例和操作步骤 -- **规范性**:包含提交信息规范和最佳实践建议 -- **问题导向**:提供常见问题的解决方案 -- **中文友好**:使用中文说明,便于团队理解和使用 - -#### 使用价值 -- 为团队成员提供统一的Git操作指南 -- 规范代码提交流程,提高代码质量 -- 减少Git操作错误,提高开发效率 -- 便于新成员快速上手Git工作流程 - -### 2024-07-09 - 设备管理器导入路径修复 - -- 将所有 `from app.core.device_manager import device_manager` 替换为 `from app.core.device.manager import device_manager` -- 涉及文件: - - app/services/adb_service.py - - app/services/at_service.py - - app/services/atx_service.py - - app/services/plnk_service.py - - app/services/ssh_service.py - - app/api/v1/endpoints/ssh.py - - app/api/v1/endpoints/plnk.py - - app/api/v1/endpoints/at.py - - app/api/v1/endpoints/adb.py - - app/api/v1/endpoints/devices.py -- 目的:适配设备管理器模块重构后的新路径,解决模块导入错误。 - -### 2024-07-09 - 移除未使用的导入依赖 - -- 修复 `app/api/v1/endpoints/adb.py` 中的导入问题 -- 移除未使用的 `UploadFile` 和 `File` 导入 -- 避免需要 `python-multipart` 依赖包 -- 解决应用启动时的路由注册错误 \ No newline at end of file +# 项目修改记录 + +## 2025-08-07 + +### Python版本兼容性分析 +- 分析了 `requirements.txt` 中的依赖包版本 +- 确定支持的Python版本范围:3.8 - 3.11 +- 推荐使用Python 3.9或3.10版本 + +### pip编码问题修复 +- 修复了 `requirements.txt` 中中文注释导致的GBK编码错误 +- 将中文注释改为英文注释 +- 建议升级pip版本到最新版本 + +### adbutils版本修复 +- 修复了 `adbutils==2.0.0` 版本不存在的问题 +- 更新为 `adbutils==2.10.0`(有效的最新版本) + +### 配置模块导出修复 +- 修复了 `ProtocolType` 和 `DeviceStatus` 无法从 `app.core.config` 导入的问题 +- 在 `app/core/config/__init__.py` 中添加了这两个类的导入和导出 + +### 设备管理器导入路径修复 +- 修复了多个服务文件中 `device_manager` 导入路径错误的问题 +- 将 `from app.core.device_manager import device_manager` 改为 `from app.core.device.manager import device_manager` +- 修复了多个API端点文件中的导入路径错误 + +### 服务类名称修复 +- 修复了 `app/core/device/dispatcher.py` 中服务类名称错误的问题 +- 将 `ADBService`、`SSHService`、`ATService`、`PLNKService`、`ATXService` 改为 `AdbService`、`SshService`、`AtService`、`PlnkService`、`AtxService` + +### 未使用的导入清理 +- 移除了 `app/api/v1/endpoints/adb.py` 中未使用的 `UploadFile` 和 `File` 导入 +- 这解决了 `python-multipart` 依赖问题 + +### 警告过滤添加 +- 在 `run.py` 中添加了 `warnings.filterwarnings` 来忽略paramiko的弃用警告 +- 解决了 TripleDES 加密算法弃用警告 + +### USB监控模块删除 +- 删除了 `app/api/v1/endpoints/usb_monitor.py` 文件 +- 该文件依赖不存在的 `device_monitor_manager` 服务 +- 更新了 `app/core/app/router.py` 和 `app/api/v1/endpoints/__init__.py` 中的相关引用 +- 这解决了路由注册时的导入错误问题 \ No newline at end of file