一个轻量级、可自托管的 CS2 饰品价格监控平台，基于 SteamDT 开放平台 API，支持 CLI 后台监控 和 Web 仪表盘 双模式。用户可通过浏览器完成所有监控操作：查看价格、管理清单、分析趋势、接收告警，无需登录，无需修改任何配置文件。
本项目采用 AI Agent 驱动开发，核心开发规范定义在
CLAUDE.md中。你可以在此基础上自由改造和扩展。
打开浏览器 http://localhost:8080 即可管理所有监控操作，无需登录：
- Dashboard 首页：终端概览大卡片 + 柱状图动画 + 核心功能快捷按钮 + 实时统计卡片
- 饰品搜索：本地 39,000+ 饰品数据库，支持中英文、无分隔符匹配（如输入
ak47匹配 AK-47），实时价格查询 - 监控清单管理：极客玻璃拟态卡片视图、Sparkline 迷你走势图、平台比价标签、饰品图片展示
- 饰品详情页：ECharts K 线图（OHLC + MA 均线 + 成交量）、平台多维度对比、历史告警关联
- 极致追踪管理：雷达强度进度条 + shimmer 动画、内存快照实时数据、卡片网格布局
- 告警历史：极客表格风格、类型标签（红涨/绿跌/琥珀量）、按天统计
- 数据分析：市场趋势分析占位页，扫描线动画（建设中）
- 系统设置：三段式纵向布局、紫色圆形开关滑块、通知渠道状态灯、主题切换
- 极客终端风格：深黑底色 + Indigo 品牌紫 (#6366f1) + 玻璃拟态，参考 Gemini 设计的 React 前端
- 深色模式：完整 light / dark 浅色主题适配
- 全局搜索：
Cmd/Ctrl + K唤起，快速跳转页面
批量巡检多个饰品，默认每 30 分钟自动采集一次价格，对比 7 天均价检测波动：
- 涨幅 ≥ 阈值% → 触发
price_surge涨价告警 - 跌幅 ≤ -阈值% → 触发
price_drop跌价告警 - 同一饰品同一方向 4 小时内只告警 1 次（冷却机制）
单品高频狙击，自定义秒级轮询，追踪指定平台的价格和在售数量变动：
- 支持
any（任何变动通知）和percent（超百分比通知）双模式 - 429 限流时自动降频（间隔翻倍，最大 1 小时），连续成功 10 次后逐步恢复
- 支持免打扰时段 (
quiet_hours) 和自定义冷却期 - 价格 & 数量同时变动时合并为一条通知
- 企业微信机器人 Webhook（P0 已完整实现）
- Telegram Bot（P1，支持代理访问，中国大陆可用）
- Server 酱（P1）
Telegram 需要代理才能在中国大陆使用。在
.env中配置TELEGRAM_PROXY=http://127.0.0.1:7890即可。
零配置本地数据库，自动记录价格历史和告警日志。v2.0 新增监控清单和极致追踪配置持久化到数据库。
cs-monitor/
├── main.py # 主程序入口（调度器 + FastAPI Web 服务）
├── config.py # 配置类（dataclass，默认值兜底）
├── requirements.txt # Python 依赖
├── .env.example # 环境变量模板
├── .gitignore
├── CLAUDE.md # AI Agent 开发工作流规范
├── architecture.md # 架构设计文档
├── PRD.md # 产品需求文档
├── task.json # 开发任务清单
├── progress.txt # 开发进度日志
├── api/
│ └── steamdt.py # SteamDT API 封装（重试、延迟、异常处理）
├── core/
│ ├── monitor.py # 普通监控：价格采集
│ ├── analyzer.py # 波动分析 + 告警检测
│ ├── scheduler.py # APScheduler 定时任务管理
│ └── extreme_tracker.py # 极致追踪：高频单品狙击
├── web/ # 🆕 FastAPI Web 层
│ ├── app.py # FastAPI 应用入口
│ ├── schemas.py # Pydantic 模型
│ ├── ws_manager.py # WebSocket 管理
│ └── routers/ # RESTful API 路由
├── frontend/ # 🆕 Vue 3 前端
│ ├── package.json
│ ├── vite.config.ts
│ └── src/
│ ├── views/ # 页面（Dashboard/Watchlist/Alerts/...）
│ ├── components/ # 组件（StatCard/PriceTable/PriceChart/...）
│ ├── stores/ # Pinia 状态管理
│ └── api/ # axios 封装
├── notify/
│ ├── base.py # 通知渠道抽象基类
│ ├── manager.py # 通知管理器（格式化 + 路由）
│ ├── wecom.py # 企业微信机器人
│ ├── telegram.py # Telegram Bot
│ └── serverchan.py # Server 酱
├── storage/
│ ├── models.py # 数据库表结构定义
│ └── database.py # SQLite 连接与 CRUD 封装
├── utils/
│ └── logger.py # loguru 日志配置
├── data/
│ └── logs/ # 日志文件输出目录
└── tests/
├── test_api.py
├── test_monitor.py
├── test_analyzer.py
├── test_extreme_tracker.py
├── test_notify.py
├── test_storage.py
└── test_web_api.py # 🆕 Web API 测试
需要 Python 3.12+ 和 Node.js 18+（用于前端开发）。
cd cs-monitor
./init.shinit.sh 会创建 .venv 虚拟环境、安装 Python 依赖，并自动安装前端 npm 依赖。
cp .env.example .env
# 编辑 .env，填写以下内容：
# - STEAMDT_API_KEY（从 https://doc.steamdt.com/ 获取）
# - 至少一种通知渠道（WECOM_WEBHOOK_URL / TELEGRAM_BOT_TOKEN / SERVERCHAN_SENDKEY）# 先构建前端（仅需执行一次，或前端代码更新后重新构建）
cd frontend && npm run build && cd ..
# 启动主程序
python main.py首次启动会立即执行一次价格采集，随后：
- 后台调度器按设定间隔运行 CLI 监控
- FastAPI Web 服务在
http://localhost:8080提供 Web 仪表盘
构建完成后，直接在浏览器打开 http://localhost:8080 即可访问 Web 仪表盘，无需额外启动前端服务器。
按 Ctrl+C 可优雅退出。
# 1. 确保 .env 已配置好
cp .env.example .env
# 编辑 .env 填写 STEAMDT_API_KEY 和通知渠道
# 2. 构建并启动
docker-compose up -d --build
# 3. 查看日志
docker-compose logs -f
# 4. 访问仪表盘
open http://localhost:8080数据持久化：docker-compose.yml 已将 ./data 目录挂载到容器，SQLite 数据库和日志不会随容器销毁而丢失。
健康检查：容器内置 healthcheck，每 30 秒检测 /api/health，连续 3 次失败自动重启。
停止服务：
docker-compose down如需修改前端代码并实时预览：
# 终端 1：启动后端
python main.py
# 终端 2：启动前端开发服务器
cd frontend
npm run dev前端开发服务器运行在 http://localhost:5173，通过 Vite 代理访问后端 API。开发完成后记得运行 npm run build 重新构建，使生产环境生效。
# Python 后端测试
python -m pytest tests/ -v
# 前端构建检查
cd frontend && npm run buildv2.0 后监控清单已迁移到数据库，可通过 Web 仪表盘 或 API 管理，无需修改配置文件。
如需查看/修改默认值，参考 config.py 中的 watchlist：
watchlist = [
{"name": "AK-47 | Redline (Field-Tested)", "threshold": 5.0},
{"name": "AWP | Asiimov (Field-Tested)", "threshold": 5.0},
]首次启动时，如果数据库中的 watchlist 表为空，系统会自动从 config.py 导入默认值。
同样已迁移到数据库。参考 config.py 中的 extreme_track_list 查看默认配置格式。
如果你想在此基础上继续开发，建议从以下几个方面入手：
- 更多通知渠道：钉钉、Discord、Bark 等
- 多用户支持：重新启用 JWT 认证为多用户模式（代码已封存，可随时恢复）
- 桌面端打包：Tauri 2.x 封装为 Windows/macOS/Linux 原生应用
- 数据归档优化：更精细的历史数据管理和清理策略
已完成的功能：套利价差提醒、K 线趋势分析、Docker 部署、数据归档、极客终端 Glass-card 玻璃拟态设计系统、本地饰品搜索（39K+）、饰品图片自动获取
| 层级 | 技术 | 说明 |
|---|---|---|
| 后端语言 | Python 3.12+ | 类型提示、dataclass |
| Web 框架 | FastAPI | 异步高性能、OpenAPI 文档 |
| HTTP 客户端 | httpx | 同步请求 + 重试机制 |
| 调度 | APScheduler | BackgroundScheduler 定时任务 |
| 数据库 | SQLite (WAL) | 零配置，支持并发读写 |
| 前端框架 | Vue 3 + Vite + TypeScript | 组件化、响应式 |
| UI 组件库 | Naive UI | 中文文档完善 |
| 图标库 | lucide-vue-next | 与 React 参考项目一致的图标系统 |
| 图表库 | ECharts 5 | K线/折线/柱状图全覆盖 |
| 状态管理 | Pinia | 轻量替代 Vuex |
| CSS | UnoCSS | 原子化 CSS |
| 日志 | loguru | 彩色控制台 + 文件日志 |
| 配置 | python-dotenv | .env 环境变量管理 |
| 测试 | pytest | 86+ 个单元测试 |
本项目由 AI Agent 按 CLAUDE.md 中的规范逐步开发完成。如果你想用同样的方式继续迭代：
- 阅读
CLAUDE.md了解工作流 - 查看
task.json了解已完成的任务（共 30 个，全部passes: true） - 在
task.json中按顺序完成下一个passes: false的任务 - 遵循"一个 task 一个 commit"的原则
MIT License - 可自由修改和商用。