# dingtalk_lesson_checkin

**Repository Path**: hackcat_admin/dingtalk_lesson_checkin

## Basic Information

- **Project Name**: dingtalk_lesson_checkin
- **Description**: 很多在线学习/培训平台会在播放视频时不定时弹出签到按钮，出现时间短、位置随机， 稍不留神就错过。本工具通过屏幕图像识别自动检测并点击这类按钮，让你无需时刻盯着屏幕抢点。

它不依赖网页结构——不解析 DOM、不注入脚本，纯粹通过屏幕像素识别， 所以无论是浏览器、桌面客户端还是全屏播放都能用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🎯 Signin Clicker · 视频自动签到助手

**看视频时那个亮黄色的"签到"按钮总是不定时跳出、一闪而过？**
**本工具盯着屏幕，一出现就自动帮你点掉。**

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platform-Windows-lightgrey.svg)](https://github.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![opencv](https://img.shields.io/badge/OpenCV-4.x-red.svg)](https://opencv.org/)

</div>

---

## 📖 简介

很多在线学习/培训平台会在播放视频时**不定时弹出签到按钮**，出现时间短、位置随机，
稍不留神就错过。本工具通过**屏幕图像识别**自动检测并点击这类按钮，让你无需时刻盯着屏幕抢点。

它**不依赖网页结构**——不解析 DOM、不注入脚本，纯粹通过屏幕像素识别，
所以无论是浏览器、桌面客户端还是全屏播放都能用。

> ⚠️ **免责声明**：本项目仅供个人自动化与无障碍辅助的**学习交流**使用。
> 使用前请确认并遵守你所使用平台的相关条款。作者不对因使用本工具产生的任何后果负责。

---

## ✨ 特性

| 特性 | 说明 |
|------|------|
| 🎨 **颜色过滤** | HSV 色彩空间提取亮黄像素，排除非黄干扰（图标、文字、皮肤） |
| ⭕ **霍夫圆检测** | 只认圆形，排除横幅、方块、线条等非圆干扰 |
| 📊 **填充率验证** | 环形采样圆内黄色占比，确认是实心圆，排除空心环/残缺圆 |
| 🔁 **状态无关** | 匹配的是不变的黄色圆底，按钮文字颜色/倒计时数字怎么变都不影响识别 |
| ⚡ **高速** | 连通域分块优化，霍夫圆只跑局部，全屏约 **23 次/秒** |
| 🖥️ **平台无关** | 不依赖网页结构，浏览器 / 桌面 App / 全屏通用 |
| 🔧 **可诊断** | F6 一键保存截图 + 分阶段分析，定位"为什么没检出" |

**三重把关 = 极低误检率**：只有"亮黄色的实心圆形"才会被点击。

---

## 📦 依赖

| 依赖 | 用途 | 说明 |
|------|------|------|
| `numpy` | 数组运算 | Anaconda 自带 |
| `opencv-python` | 颜色转换 + 霍夫圆检测 | **需安装** |
| `mss` | 高速抓屏 | 已装；缺失时自动退回 PIL |
| `Pillow` | 备选抓屏 | Anaconda 自带 |

安装依赖：

```bash
pip install opencv-python mss numpy Pillow
```

---

## 🚀 快速上手

### 方式一：双击启动（推荐，零配置）

1. 双击 **`启动签到助手.bat`**
   （它会自动定位 Anaconda/系统 Python，并检查/安装依赖）
2. 让黄色"签到"按钮出现在屏幕上
3. 按 **`F7`** 校准，看到下面输出说明识别成功：
   ```
   [校准] 检测到黄色圆形按钮 @(839,219)  半径=61px
   ```
4. 按 **`F8`** 开启自动点击，安心看视频
5. 看完按 **`F9`** 退出

### 方式二：命令行启动

```bash
python signin_clicker.py
```

---

## 🎮 快捷键

快捷键是**全局**的，焦点在别的窗口也能响应。

| 按键 | 作用 |
|------|------|
| `F6` | **诊断**：保存截图 + 分阶段分析，定位为什么没检出 |
| `F7` | **校准**：扫一次屏幕，报告检测结果（**不点击**） |
| `F8` | **启动 / 暂停**自动点击 |
| `F9` | **退出** |

---

## 🔧 调参

检测原理决定了误检率极低（必须是亮黄圆形才算数）。多数情况无需调参。
若需要，所有参数均可命令行传入：

```bash
python signin_clicker.py --fill-ratio 0.4 --circle-min-r 25
```

| 参数 | 默认 | 说明 |
|------|------|------|
| `--h-lo` / `--h-hi` | 15 / 40 | 黄色色相范围（HSV 的 H，OpenCV 8bit 口径，0-180） |
| `--s-min` | 80 | 饱和度下限 |
| `--v-min` | 180 | 亮度下限。按钮偏暗就调低 |
| `--min-pixels` | 2000 | 黄色像素总数下限（全局预筛） |
| `--circle-min-r` | 30 | 圆最小半径(px) |
| `--circle-max-r` | 120 | 圆最大半径(px) |
| `--fill-ratio` | 0.45 | 圆内黄色填充率下限（0~1）。误报多调高，漏检调低 |
| `--cooldown` | 1200 | 每次点击后冷却毫秒，避免重复点 |
| `--min-move` | 60 | 新检测点离上次多远才算"新按钮"（绕过冷却） |
| `--scan-delay` | 90 | 扫描间隔(ms)。越小越灵敏越占 CPU |
| `--restore` | 关 | 点完把鼠标还原原位 |
| `--region X Y W H` | 整屏 | 只扫这块矩形，**提速且防误报** |

### 常见调整场景

**按钮抓不到**（F7 报"未检测到"）：
```bash
python signin_clicker.py --v-min 150 --fill-ratio 0.35 --circle-min-r 20
```

**按钮一闪太快抓不住**：扫描已很快（~44ms），可进一步缩小区域：
```bash
python signin_clicker.py --region 200 100 1200 800
```

---

## 🔬 工作原理

```
┌─────────────┐   ┌──────────────┐   ┌──────────────────┐   ┌──────────────┐   ┌───────────┐
│  抓屏 (mss)  │──▶│ HSV 颜色过滤 │──▶│ 连通域分块(只留大块)│──▶│ 局部霍夫圆检测 │──▶│ 填充率验证 │
│   ~16ms     │   │   inRange    │   │ connectedComponents│   │ HoughCircles │   │  环形采样  │
└─────────────┘   └──────────────┘   └──────────────────┘   └──────────────┘   └─────┬─────┘
                                                                                        │
                                                                                  ┌─────▼─────┐
                                                                                  │ 点击中心+冷却│
                                                                                  └───────────┘
```

**关键设计**：

1. **为什么用霍夫圆而非纯颜色？**
   纯颜色识别会把桌面上任何黄色的东西（文件夹图标、托盘、皮肤）都误判为按钮。
   霍夫圆要求"形状是圆"，误检率骤降。

2. **为什么匹配圆底而非整个按钮？**
   签到按钮的文字颜色（正常态深褐 / 选中态蓝）和倒计时数字会变化，
   而亮黄圆底是**不变量**。匹配不变量 = 适应所有状态。

3. **为什么先做连通域分块？**
   霍夫圆很慢。先用连通域找出集中的黄色团块，只在团块局部跑霍夫圆，
   不必扫全屏 → 从 200ms+ 降到 ~44ms。

4. **填充率环形采样（0.15~0.6r）为什么避开中心？**
   按钮中心有文字/数字，那里不是黄色。用环形采样（避开中心）能真实反映圆盘的填充情况。

---

## 🐛 排查

| 问题 | 解决 |
|------|------|
| 黑窗口一闪就没 | 杀毒软件拦截，加白名单；或在文件管理器手动跑 `.bat` |
| `No module named cv2` | `pip install opencv-python` |
| 点击没反应 | 以管理员身份运行；确认视频窗口没被遮挡 |
| 坐标偏移 | 已启用高 DPI 感知；仍有偏移则把系统缩放调到 100% 测试 |
| **按钮在却抓不到** | 按 **`F6`** 诊断！它会保存截图 + 分析各阶段，把输出贴到 issue |

### 🩺 F6 诊断模式

当按钮明明在却识别不到时，**按 `F6`**。它会：

- 保存当前截图到 `diagnose_shot.png`（黄色像素被标红，可肉眼确认按钮位置）
- 报告：黄色像素总数、连通块数量与大小、每个候选团块的霍夫圆结果和填充率
- 针对性地给出调参建议（如"黄色像素太散，试 --circle-min-r 15"）

---

## 📁 项目结构

```
signin-clicker/
├── signin_clicker.py      # 核心脚本：颜色+霍夫圆检测 + 抓屏 + 点击 + 快捷键
├── 启动签到助手.bat        # 双击启动，自动定位 Python + 检查依赖
├── README.md              # 本文档
├── LICENSE                # MIT
└── .gitignore
```

---

## ❓ FAQ

**Q: 支持非黄色的按钮吗？**
A: 当前针对亮黄圆形按钮调参。改 `--h-lo/--h-hi` 可适配其他色相（如橙色、红色），
但需确保目标是个圆形。方形按钮需要换用模板匹配方案。

**Q: 会影响我正常使用电脑吗？**
A: 不会。它只在检测到目标按钮时瞬间点击其中心，其余时间只读屏幕不操作鼠标。
加 `--restore` 可让点击后鼠标归位，几乎无感。

**Q: 性能占用如何？**
A: 全屏扫描约 44ms/帧（~23次/秒），CPU 占用很低。用 `--region` 缩小范围可进一步降低。

**Q: 只支持 Windows 吗？**
A: 目前是。点击和快捷键用了 Windows API（ctypes）。macOS/Linux 需替换为对应平台 API。

---

## 🤝 贡献

欢迎提 Issue 和 PR！尤其欢迎：
- 适配其他平台（macOS/Linux）
- 适配其他按钮类型（方形、其他颜色）
- 性能优化

---

## 📄 许可证

[MIT License](./LICENSE) © 2026 hackcat