快速启动指南

前置准备

1. 获取 Qwen API 密钥

从阿里云获取 Qwen API 的访问凭证：

• 访问 阿里云控制台
• 获取 QWEN_BASE_URL 和 QWEN_API_KEY

2. 环境配置

# 进入项目目录
cd /Users/qr/Desktop/sci/VisionController

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，填入你的 API 密钥和 URL
vim .env

编辑后的 .env 文件应该包含：

QWEN_BASE_URL=https://api.qwen.aliyun.com/v1
QWEN_API_KEY=your_actual_api_key_here
QWEN_MODEL=qwen3-omni

3. 创建虚拟环境并安装依赖

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt

运行应用

# 确保虚拟环境已激活
source venv/bin/activate

# 运行应用
python -m src.main

日志查看

应用运行时会生成日志文件：

# 查看实时日志
tail -f logs/screen_assistant.log

# 查看最近 100 行日志
tail -100 logs/screen_assistant.log

故障排除

问题1：ImportError: No module named 'PyQt5'

解决方案：确保虚拟环境已激活，并重新安装依赖：

pip install -r requirements.txt --force-reinstall

问题2：QWEN_API_KEY not set

解决方案：检查 .env 文件是否存在且包含有效的 API 密钥：

cat .env | grep QWEN_API_KEY

问题3：屏幕截图权限不足

解决方案（macOS）：

• 进入 系统偏好设置 > 安全性与隐私 > 屏幕录制
• 将终端或 Python 添加到允许列表

问题4：API 连接超时

解决方案：

• 检查网络连接
• 检查 QWEN_BASE_URL 是否正确
• 增加 API_TIMEOUT 环境变量值

验证安装

运行以下命令验证所有组件是否工作正常：

# 检查 Python 版本
python --version

# 检查 PyQt5 安装
python -c "from PyQt5.QtWidgets import QApplication; print('PyQt5 OK')"

# 检查 openai 库
python -c "from openai import AsyncOpenAI; print('OpenAI OK')"

# 检查配置加载
python -c "from src.config import Config; cfg = Config.from_env(); print('Config OK')"

# 检查日志系统
python -c "from src.logger import setup_logger; setup_logger('INFO'); print('Logger OK')"

开发模式

启用调试日志以查看更多的内部信息：

# 在终端中设置环境变量
export LOG_LEVEL=DEBUG
export DEBUG_MODE=true

# 然后运行应用
python -m src.main

下一步

1. 配置提示词：编辑 prompts/system_prompt.txt 来自定义助手行为
2. 实现被动监控：在 src/orchestration/control_flow.py 中完成 passive_monitor_loop() 的实现
3. 实现 Function 执行：在 src/orchestration/ 中创建 function_executor.py 来处理点击等操作
4. 完善 UI：改进 src/ui/floating_window.py 中的用户界面

文件结构速查

VisionController/
├── src/                      # 源代码
│   ├── models/              # 数据模型
│   ├── services/            # 基础服务（截屏、窗口、鼠标）
│   ├── ai/                  # AI 集成（API、提示词、解析）
│   ├── orchestration/       # 控制层（主流程、历史管理）
│   ├── ui/                  # UI 界面（PyQt5）
│   ├── utils/               # 工具和异常
│   ├── config.py            # 配置管理
│   ├── logger.py            # 日志管理
│   └── main.py              # 主入口
├── prompts/                 # 提示词文件
│   ├── system_prompt.txt
│   ├── context_template.txt
│   ├── context_active_template.txt
│   └── function_schema.json
├── logs/                    # 日志输出目录
├── .env                     # 环境变量（需创建）
├── .env.example             # 环境变量示例
├── requirements.txt         # Python 依赖
└── docs/                    # 设计文档

获取帮助

• 查看日志：logs/screen_assistant.log
• 阅读设计文档：docs/0_PROJECT_OVERVIEW.md
• 检查代码注释：所有模块都有详细的 docstring

祝你使用愉快！🎉