ai-shopping-monitor 1.2.1
AI-powered shopping monitor and auto-purchase agent
License: MIT
Requires Python: >=3.8
Keywords: ai, shopping, monitor, automation, deepseek

# AI Agent 显卡监控系统

基于 DeepSeek API 的智能显卡监控抢购系统，使用大语言模型理解页面内容，提供更准确的产品识别和更强的鲁棒性。

## 🌟 核心特性

### 智能识别
✅ **语义理解** - AI 能理解"RTX 5090 显卡"与"包含 RTX 5090 的整机"的区别  
✅ **鲁棒性强** - 不依赖固定的 CSS 选择器，页面改版后仍能工作  
✅ **准确率高** - 通过自然语言理解提高产品识别和库存判断的准确率  
✅ **易维护** - 通过 prompt 调整行为，无需修改代码逻辑

### 自动化功能
✅ **自动监控** - 持续监控 Best Buy 页面，及时发现库存变化  
✅ **智能决策** - 基于价格、库存、产品类型自动做出购买决策  
✅ **自动购买** - 发现符合条件的产品自动加入购物车并结账  
✅ **邮件通知** - 购买成功后立即发送邮件通知

### 可靠性保障
✅ **错误恢复** - 自动重试、降级策略、Chrome 自动重启  
✅ **详细日志** - 完整的操作日志，便于调试和优化  
✅ **配置灵活** - 支持 JSON/YAML 配置，命令行参数覆盖  
✅ **优雅关闭** - Ctrl+C 优雅停止，清理资源

## 📚 文档导航

### 快速入门
- **[快速开始](#快速开始)** - 5分钟上手指南
- **[系统要求](#系统要求)** - 运行环境和依赖
- **[项目结构](#项目结构)** - 代码组织和文件说明

### 配置指南
- **[配置说明](config/README.md)** - 配置文件详细说明
- **[API 密钥获取指南](docs/API_KEY_GUIDE.md)** - 如何获取 DeepSeek API 密钥
- **[命令行使用](#命令行使用)** - 命令行参数和选项

### 使用文档
- **[完整使用指南](docs/USAGE_GUIDE.md)** - 详细的使用说明和示例
- **[运行示例](#运行示例)** - 系统运行输出示例
- **[停止监控](#停止监控)** - 如何优雅停止系统

### 技术文档
- **[系统架构](#系统架构)** - 架构设计和组件说明
- **[降级策略](docs/fallback_strategy_guide.md)** - API 失败时的降级策略
- **[监控控制器](docs/monitor_controller_guide.md)** - 监控控制器工作原理
- **[通知服务](docs/notification_service_guide.md)** - 邮件通知配置和使用

### 问题解决
- **[常见问题](#常见问题)** - FAQ 和快速解答
- **[故障排除指南](docs/TROUBLESHOOTING.md)** - 详细的问题诊断和解决方案
- **[开发和测试](#开发和测试)** - 测试和调试工具

### 其他资源
- **[安全建议](#安全建议)** - 密钥保护和安全实践
- **[性能优化建议](#性能优化建议)** - 提升系统性能
- **[许可证](#许可证)** - 开源许可信息

## 传统版本

如果你想使用传统的基于规则匹配的版本（不需要 API 密钥），请查看以下文件：
- `auto_buy_monitor_fast.py` - 超快速监控脚本（推荐）
- `auto_buy_monitor.py` - 标准双产品监控脚本
- `monitor_5090_with_price.py` - RTX 5090 单产品监控脚本

## 系统要求

- **Python 3.8+** - 推荐使用 Python 3.10 或更高版本
- **Chrome 浏览器** - 需要支持远程调试
- **DeepSeek API 密钥** - 用于 AI 页面分析
- **QQ 邮箱** - 用于通知（可选）

## 项目结构

```
.
├── main.py                 # 主入口文件
├── src/                    # 源代码目录
│   ├── ai_agent_engine.py  # AI Agent 引擎
│   ├── browser_driver.py   # 浏览器驱动
│   ├── config_loader.py    # 配置加载器
│   ├── config_models.py    # 配置数据模型
│   ├── config_validator.py # 配置验证器
│   ├── config_applicator.py # 配置应用器
│   ├── decision_engine.py  # 决策引擎
│   ├── logger.py           # 日志系统
│   ├── monitor_controller.py # 监控控制器
│   ├── notification_service.py # 通知服务
│   ├── page_context.py     # 页面上下文
│   └── price_extractor.py  # 价格提取器
├── tests/                  # 测试目录
│   ├── test_ai_agent_engine.py
│   ├── test_browser_driver.py
│   ├── test_config.py
│   ├── test_decision_engine.py
│   ├── test_integration_checkpoint.py
│   ├── test_logger.py
│   ├── test_monitor_controller.py
│   ├── test_notification_service.py
│   ├── test_page_context.py
│   └── test_price_extractor.py
├── config/                 # 配置文件目录
│   ├── config.json         # 主配置文件
│   ├── example_config.json # 示例配置文件
│   └── README.md           # 配置说明文档
├── docs/                   # 文档目录
│   ├── USAGE_GUIDE.md      # 使用指南
│   ├── fallback_strategy_guide.md # 降级策略说明
│   ├── monitor_controller_guide.md # 监控控制器说明
│   └── notification_service_guide.md # 通知服务说明
├── examples/               # 示例代码
│   ├── browser_driver_demo.py
│   ├── fallback_demo.py
│   ├── monitor_controller_demo.py
│   └── notification_demo.py
├── logs/                   # 日志目录
├── requirements.txt        # Python 依赖
├── START_AI_MONITOR.bat    # Windows 启动脚本
└── start_my_chrome_debug.bat # Chrome 调试模式启动脚本
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

主要依赖包括：
- `selenium` - 浏览器自动化
- `openai` - DeepSeek API 客户端
- `pyyaml` - YAML 配置支持（可选）

### 2. 获取 DeepSeek API 密钥

1. 访问 [DeepSeek 官网](https://platform.deepseek.com/)
2. 注册账号并登录
3. 在 API Keys 页面创建新的 API 密钥
4. 保存密钥（只显示一次）

### 3. 创建配置文件

```bash
python main.py --create-config config/config.json
```

### 4. 编辑配置文件

编辑 `config/config.json`，填入以下信息：

```json
{
  "api_config": {
    "api_key": "YOUR_DEEPSEEK_API_KEY_HERE"
  },
  "email_config": {
    "sender_email": "your_email@qq.com",
    "sender_password": "your_authorization_code",
    "receiver_email": "receiver@example.com"
  },
  "targets": [
    {
      "name": "RTX 5090",
      "max_price": 2650.0
    }
  ]
}
```

**必须修改的配置项：**
1. `api_config.api_key` - 填入你的 DeepSeek API 密钥
2. `email_config.sender_email` - 填入你的 QQ 邮箱
3. `email_config.sender_password` - 填入 QQ 邮箱授权码（不是密码）
4. `email_config.receiver_email` - 填入接收通知的邮箱

### 5. 启动 Chrome 调试模式

**Windows:**
```bash
start_my_chrome_debug.bat
```

**手动启动:**
```bash
chrome.exe --remote-debugging-port=9222 --user-data-dir="C:\chrome_debug_profile"
```

**macOS:**
```bash
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="~/chrome_debug_profile"
```

**Linux:**
```bash
google-chrome --remote-debugging-port=9222 --user-data-dir="~/chrome_debug_profile"
```

**重要提示：**
- Chrome 启动后，手动登录 Best Buy 账号
- 确保已添加支付方式和收货地址
- 保持 Chrome 窗口打开

### 6. 启动监控系统

**使用批处理脚本（Windows，推荐）:**
```bash
START_AI_MONITOR.bat
```

**或使用命令行:**
```bash
python main.py
```

**使用指定配置文件:**
```bash
python main.py -c config/my_config.json
```

**启用 DEBUG 日志:**
```bash
python main.py --log-level DEBUG
```

## 命令行使用

### 基本命令

```bash
# 使用默认配置启动
python main.py

# 使用指定配置文件
python main.py -c config/my_config.json

# 创建示例配置文件
python main.py --create-config config/new_config.json

# 设置日志级别
python main.py --log-level DEBUG

# 查看版本信息
python main.py --version

# 查看帮助信息
python main.py --help
```

### 高级选项

```bash
# 禁用控制台日志输出
python main.py --no-console

# 指定日志文件路径
python main.py --log-file logs/custom.log

# 跳过配置验证（不推荐）
python main.py --no-validate
```

## 运行示例

```
╔═══════════════════════════════════════════════════════════════════════════╗
║                                                                           ║
║              AI Agent 显卡监控系统 v1.0.0                                  ║
║                                                                           ║
║              基于 DeepSeek API 的智能监控抢购系统                          ║
║                                                                           ║
╚═══════════════════════════════════════════════════════════════════════════╝

系统信息:
  Python 版本: 3.12.7
  工作目录: D:\ai-agent-monitor

加载配置文件: config/config.json
✓ 配置加载成功

检查运行前提条件...
  Chrome 调试端口: 9222
✓ 前提条件检查通过

初始化监控系统...
✓ 监控系统初始化完成

===============================================================================
监控配置:
  检查间隔: 30 秒
  监控目标: 2 个
    1. RTX 5090 - 最高价格: $2650.00
    2. RTX 5080 - 最高价格: $1500.00

按 Ctrl+C 停止监控
===============================================================================

[2026-02-05 10:30:00] 开始第 1 次检查
[2026-02-05 10:30:00] 检查目标: RTX 5090
[2026-02-05 10:30:05] 找到 3 个符合条件的产品
[2026-02-05 10:30:05] 处理产品: NVIDIA GeForce RTX 5090 Founders Edition
[2026-02-05 10:30:05] 价格: $1999.99
[2026-02-05 10:30:05] 决策引擎批准购买，发送通知...
[2026-02-05 10:30:10] 开始执行购买流程
[2026-02-05 10:30:15] 成功加入购物车
[2026-02-05 10:30:20] 成功到达结账页面
[2026-02-05 10:30:20] 购买流程完成！请在浏览器中完成支付流程

等待 30 秒后进行下一次检查...
```

## 停止监控

按 `Ctrl+C` 优雅停止监控系统。系统会：
1. 停止监控循环
2. 关闭浏览器连接
3. 记录统计信息
4. 清理资源

```
收到中断信号，正在停止监控...

===============================================================================
停止监控系统
===============================================================================
总检查次数: 42
找到产品数: 15
购买尝试次数: 3
===============================================================================
监控系统已停止
===============================================================================
```

## 常见问题

### Q: 如何获取 DeepSeek API 密钥？

A: 
1. 访问 [DeepSeek 官网](https://platform.deepseek.com/)
2. 注册账号并登录
3. 在 API Keys 页面创建新的 API 密钥
4. 保存密钥（只显示一次）

### Q: 如何获取 QQ 邮箱授权码？

A: 
1. 登录 QQ 邮箱网页版
2. 设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
3. 开启 SMTP 服务
4. 生成授权码（不是 QQ 密码）

### Q: 为什么提示 "无法连接到浏览器"？

A: 
1. 确保 Chrome 已启动并使用 `--remote-debugging-port=9222` 参数
2. 检查端口 9222 是否被占用
3. 尝试修改配置文件中的 `debug_port` 为其他端口

### Q: API 调用失败怎么办？

A: 系统会自动：
1. 重试最多 3 次（指数退避）
2. 如果仍然失败，切换到降级模式（基于规则的产品识别）
3. 记录详细错误日志

详见 [降级策略指南](docs/fallback_strategy_guide.md)

### Q: 如何查看详细日志？

A: 使用 DEBUG 日志级别：
```bash
python main.py --log-level DEBUG
```

### Q: 如何禁用邮件通知？

A: 在配置文件中设置：
```json
"email_config": {
  "enabled": false
}
```

### Q: 可以同时监控多个产品吗？

A: 可以，在配置文件的 `targets` 数组中添加多个监控目标：
```json
"targets": [
  {
    "name": "RTX 5090",
    "max_price": 2650.0
  },
  {
    "name": "RTX 5080",
    "max_price": 1500.0
  }
]
```

### Q: 如何调整 AI 分析的准确性？

A: 可以调整以下参数：
- `api_config.temperature` - 降低温度（如 0.1）提高确定性
- `api_config.model_name` - 使用更强大的模型
- 修改 `src/ai_agent_engine.py` 中的 prompt 模板

### Q: 系统如何区分显卡和整机？

A: AI Agent 通过语义理解识别产品类型，会自动排除：
- 包含显卡的整机（Gaming PC, Desktop, Laptop）
- 显卡配件（支架、线缆、转接头、散热器）
- 礼品卡、保修服务

### Q: 如何测试系统是否正常工作？

A: 运行示例脚本：
```bash
# 测试浏览器连接
python examples/browser_driver_demo.py

# 测试通知服务
python examples/notification_demo.py

# 测试监控控制器
python examples/monitor_controller_demo.py

# 测试降级策略
python examples/fallback_demo.py
```

## 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                     Monitor Controller                       │
│  (监控循环、调度、配置管理)                                    │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Browser    │   │  AI Agent    │   │ Notification │
│   Driver     │   │   Engine     │   │   Service    │
└──────────────┘   └──────────────┘   └──────────────┘
        │                   │
        │                   │
        ▼                   ▼
┌──────────────┐   ┌──────────────┐
│ Page Context │   │  DeepSeek    │
│  Extractor   │   │     API      │
└──────────────┘   └──────────────┘
```

### 核心组件

1. **Monitor Controller** - 主控制器，负责监控循环、任务调度、配置加载
2. **Browser Driver** - Selenium 浏览器驱动，负责页面导航和操作
3. **Page Context Extractor** - 提取页面上下文（HTML、文本、截图）
4. **AI Agent Engine** - 调用 DeepSeek API 进行页面分析和决策
5. **Decision Engine** - 基于 AI 分析结果做出购买决策
6. **Price Extractor** - 从文本中提取价格信息
7. **Notification Service** - 发送邮件通知

详细架构说明请查看 [设计文档](.kiro/specs/ai-agent-monitor/design.md)

## 开发和测试

### 运行测试

```bash
# 运行所有测试
pytest tests/

# 运行单元测试
pytest tests/test_ai_agent_engine.py
pytest tests/test_browser_driver.py
pytest tests/test_decision_engine.py

# 运行集成测试
pytest tests/test_integration_checkpoint.py
pytest tests/test_full_integration.py

# 生成覆盖率报告
pytest --cov=src --cov-report=html
```

### 代码结构

所有源代码都包含详细的文档字符串和注释：
- 模块级文档字符串说明模块用途
- 类文档字符串说明类的职责
- 方法文档字符串说明参数、返回值和行为
- 关键代码段包含行内注释

### 贡献指南

如果你想为项目做出贡献，请：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 安全建议

1. **保护 API 密钥** - 不要将配置文件提交到版本控制系统
2. **使用环境变量** - 可以通过环境变量传递敏感信息
3. **定期更新密钥** - 定期轮换 API 密钥和邮箱授权码
4. **监控异常活动** - 注意 API 调用量和邮件发送量
5. **使用 .gitignore** - 确保 `config/config.json` 在 `.gitignore` 中

## 性能优化建议

1. **调整检查间隔** - 根据网络状况和 API 配额调整 `check_interval`
2. **使用降级策略** - 在 API 配额不足时，系统会自动切换到规则匹配
3. **优化 prompt** - 根据实际情况调整 prompt 模板，提高识别准确率
4. **监控 API 使用量** - 定期检查 DeepSeek API 使用情况
5. **启用日志轮转** - 避免日志文件过大

## 许可证

MIT License

Copyright (c) 2026 AI Agent Monitor

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## 致谢

- [DeepSeek](https://www.deepseek.com/) - 提供强大的 AI API
- [Selenium](https://www.selenium.dev/) - 浏览器自动化框架
- [OpenAI Python SDK](https://github.com/openai/openai-python) - API 客户端库

## 免责声明

本工具仅供学习和研究使用。使用本工具进行自动化购买可能违反 Best Buy 的服务条款。请遵守相关法律法规和网站规则，风险自负。

作者不对使用本工具造成的任何后果负责，包括但不限于：
- 账号被封禁
- 订单被取消
- 财务损失
- 其他任何直接或间接损失

使用本工具即表示你已阅读并同意上述免责声明。

---

**祝你抢购成功！🎉**

如有问题或建议，请查看 [完整使用指南](docs/USAGE_GUIDE.md) 或提交 Issue。