CORRECTIONS.md

修正说明

已修正的内容

本文档记录了对原始设计文档的技术调整。

1. UI框架版本更新

• 修正前: PyQt6
• 修正后: PyQt5 (v5.15.9)
• 影响范围: 所有UI相关文档和代码示例

2. 日志库更换

• 修正前: loguru（第三方库）
• 修正后: logging（Python标准库）
• 改进: 减少外部依赖，使用标准库实现日志轮换（RotatingFileHandler）
• 影响范围:
  • src/logger.py 实现方式
  • 所有模块中的logger导入和使用
  • 日志配置方式

3. API调用库更新

• 修正前: httpx（手动构建请求体）
• 修正后: openai（官方OpenAI库）
• 说明: 通过OpenAI兼容接口调用Qwen，使用 AsyncOpenAI 类
• 优势:
  • 库已处理请求格式、认证、重试等逻辑
  • 代码更简洁，减少手动处理
  • 响应解析更标准化
• 影响范围: src/ai/qwen_client.py 的完整实现

4. 环境变量管理强化

• 修正前: baseurl和apikey可能硬编码或简单处理
• 修正后: 强制使用 .env 文件存储敏感信息
• 实现:
  • 项目根目录创建 .env 文件（从 .env.example 复制）
  • 应用启动时使用 python-dotenv 加载
  • 不允许hardcode API Key和URL
• 安全性: 防止敏感信息意外提交到版本控制

5. dependencies.txt 更新

PyQt5==5.15.9                    # 替代 PyQt6
openai>=1.3.0                    # 新增（官方OpenAI库）
mss==9.0.1
pyautogui==0.9.53
apscheduler==3.10.4
python-dotenv==1.0.0             # 新增（.env文件加载）
pydantic==2.5.0
Pillow>=9.0.0                     # 新增（图像处理）

已移除:

• httpx（改用openai库）
• loguru（改用logging标准库）
• PyQt6（改用PyQt5）

---

修正后的文档版本

所有以下文档已更新完毕：

文档文件	修正内容	状态
1_SYSTEM_REQUIREMENTS.md	依赖库版本	✅
2_SYSTEM_ARCHITECTURE.md	UI框架(PyQt5)、日志策略(logging)	✅
3_PROMPT_ENGINEERING.md	无修改（提示词设计不涉及技术栈）	✅
4_CODE_ARCHITECTURE.md	logger导入、QwenAPIClient实现、requirements.txt	✅
5_API_CONFIG.md	环境变量管理(.env)、日志配置、API说明	✅
0_PROJECT_OVERVIEW.md	技术栈总结	⏳ 需更新

---

关键代码变更示例

Logger 初始化

# 修正后
import logging
import logging.handlers

logger = logging.getLogger(__name__)

# 在main.py中
from src.logger import setup_logger
setup_logger(config.log_level)

API 调用

# 修正后（使用openai库）
from openai import AsyncOpenAI

client = AsyncOpenAI(
    api_key=config.api_key,
    base_url=config.base_url
)

response = await client.chat.completions.create(
    model=config.model,
    messages=messages,
    tools=functions,
    tool_choice="required" if force else "auto"
)

环境变量加载

# 修正后
from pathlib import Path
from dotenv import load_dotenv

env_path = Path(__file__).parent.parent / ".env"
load_dotenv(env_path)

api_key = os.getenv("QWEN_API_KEY")
base_url = os.getenv("QWEN_BASE_URL")

---

文件检查清单

• 1_SYSTEM_REQUIREMENTS.md - 更新依赖
• 2_SYSTEM_ARCHITECTURE.md - 更新UI和日志
• 3_PROMPT_ENGINEERING.md - 无需修改
• 4_CODE_ARCHITECTURE.md - 更新logger、API、requirements
• 5_API_CONFIG.md - 更新环境变量和日志配置
• 0_PROJECT_OVERVIEW.md - 需要后续更新（技术栈部分）

---

后续开发建议

1. 创建 .env.example 文件在项目根目录
2. 创建 .env 文件（从example复制），填入实际的API Key和URL
3. 安装依赖: pip install -r requirements.txt
4. 验证配置: 在启动前检查.env文件完整性
5. 测试日志: 运行应用时观察logs/screen_assistant.log输出

---

兼容性说明

PyQt5 vs PyQt6

• PyQt5 更稳定，生态支持更好
• PyQt5 的API基本兼容（轻微差异）
• UI代码无需大幅改动，只需确保import正确

logging vs loguru

• logging是Python标准库，零依赖
• 功能满足本项目需求（日志轮换、格式化、多处理器）
• 日志输出格式一致

openai库的优势

• 官方支持，文档齐全
• 自动处理OpenAI兼容接口（Qwen可用）
• 内置重试和超时机制
• 类型提示完善

---

验证方式

修正后的代码应满足以下检查：

# 1. 检查imports
grep -r "from loguru" src/  # 应该无输出
grep -r "PyQt6" src/        # 应该无输出
grep -r "QWEN_API_KEY =" src/ # 应该无输出（不硬编码）

# 2. 检查环境变量加载
grep -r "load_dotenv" src/main.py  # 应该有输出

# 3. 检查API调用
grep -r "AsyncOpenAI" src/ai/qwen_client.py  # 应该有输出

# 4. 检查dependencies
cat requirements.txt | grep -E "PyQt5|openai|python-dotenv"  # 应该都有

# 5. 检查日志初始化
grep -r "setup_logger" src/main.py  # 应该有输出

---

相关文件位置

• 修正的文档: /Users/qr/Desktop/sci/VisionController/docs/
• 环境变量配置: /Users/qr/Desktop/sci/VisionController/.env (待创建)
• 依赖配置: /Users/qr/Desktop/sci/VisionController/requirements.txt (待创建)