修复引用空间

4 months ago · feec69a78b
4 changed files with 47 additions and 560 deletions
--- 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"
 ] 
--- a/app/api/v1/endpoints/usb_monitor.py
+++ b/app/api/v1/endpoints/usb_monitor.py
@ -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)}"
        ) 
--- 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("路由注册配置完成")
--- a/modify.md
+++ b/modify.md
@ -1,402 +1,44 @@
-# 修改记录
+# 项目修改记录
-
+
-## 2024-01-XX - Core模块层级结构重构
+## 2025-08-07
-
+
-### 重构概述
+### Python版本兼容性分析
-对 `app/core` 目录进行了全面的层级结构重构，将原本的单文件结构重新组织为功能明确的子模块，提高了代码的可维护性和扩展性。
+- 分析了 `requirements.txt` 中的依赖包版本
-
+- 确定支持的Python版本范围：3.8 - 3.11
-### 重构后的目录结构
+- 推荐使用Python 3.9或3.10版本
-```
+
-app/core/
+### pip编码问题修复
-├── __init__.py                 # 模块初始化
+- 修复了 `requirements.txt` 中中文注释导致的GBK编码错误
-├── config/                     # 配置管理
+- 将中文注释改为英文注释
-│   ├── __init__.py
+- 建议升级pip版本到最新版本
-│   ├── settings.py            # 应用配置
+
-│   └── cors.py               # CORS配置
+### adbutils版本修复
-├── exceptions/                # 异常管理
+- 修复了 `adbutils==2.0.0` 版本不存在的问题
-│   ├── __init__.py
+- 更新为 `adbutils==2.10.0`（有效的最新版本）
-│   ├── base.py               # 基础异常类
+
-│   ├── adb.py                # ADB异常
+### 配置模块导出修复
-│   └── business.py           # 业务异常
+- 修复了 `ProtocolType` 和 `DeviceStatus` 无法从 `app.core.config` 导入的问题
-├── middleware/               # 中间件
+- 在 `app/core/config/__init__.py` 中添加了这两个类的导入和导出
-│   ├── __init__.py
+
-│   └── request.py           # 请求中间件
+### 设备管理器导入路径修复
-├── app/                     # 应用管理
+- 修复了多个服务文件中 `device_manager` 导入路径错误的问题
-│   ├── __init__.py
+- 将 `from app.core.device_manager import device_manager` 改为 `from app.core.device.manager import device_manager`
-│   ├── factory.py           # 应用工厂
+- 修复了多个API端点文件中的导入路径错误
-│   └── router.py            # 路由管理
+
-├── adb/                     # ADB核心功能
+### 服务类名称修复
-│   ├── __init__.py
+- 修复了 `app/core/device/dispatcher.py` 中服务类名称错误的问题
-│   ├── connection.py        # ADB连接
+- 将 `ADBService`、`SSHService`、`ATService`、`PLNKService`、`ATXService` 改为 `AdbService`、`SshService`、`AtService`、`PlnkService`、`AtxService`
-│   └── client.py            # ADB客户端
+
-├── device/                  # 设备管理
+### 未使用的导入清理
-│   ├── __init__.py
+- 移除了 `app/api/v1/endpoints/adb.py` 中未使用的 `UploadFile` 和 `File` 导入
-│   ├── manager.py           # 设备管理器
+- 这解决了 `python-multipart` 依赖问题
-│   └── dispatcher.py        # 设备分发器
+
-├── handlers/                # 异常处理器
+### 警告过滤添加
-│   ├── __init__.py
+- 在 `run.py` 中添加了 `warnings.filterwarnings` 来忽略paramiko的弃用警告
-│   └── exception_handlers.py # 全局异常处理器
+- 解决了 TripleDES 加密算法弃用警告
-```
+
-
+### USB监控模块删除
-### 新增文件
+- 删除了 `app/api/v1/endpoints/usb_monitor.py` 文件
-
+- 该文件依赖不存在的 `device_monitor_manager` 服务
-#### 1. 配置管理模块 (`app/core/config/`)
+- 更新了 `app/core/app/router.py` 和 `app/api/v1/endpoints/__init__.py` 中的相关引用
- `__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` 依赖包
 - 解决应用启动时的路由注册错误