# QN-IDLE

**Repository Path**: YuYao-Gith/QN-IDLE

## Basic Information

- **Project Name**: QN-IDLE
- **Description**: 防止桌面环境自动黑屏/休眠的轻量级跨平台命令行工具（C）
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-20
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- ╔══════════════════════════════════════════════════════════════════════╗ -->
<!-- ║                    🛡️  QN-IDLE — 永不停歇的守护者                      ║ -->
<!-- ║     防止桌面环境自动黑屏/休眠的轻量级跨平台命令行工具                    ║ -->
<!-- ╚══════════════════════════════════════════════════════════════════════╝ -->

<p align="center">
  <strong>🛡️ 永不停歇的守护者 — 防止桌面环境自动黑屏/休眠的轻量级跨平台命令行工具</strong>
</p>

<p align="center">
  <a href="https://www.gnu.org/licenses/agpl-3.0.html">
    <img src="https://img.shields.io/badge/License-AGPL%20v3-blue.svg" alt="AGPLv3">
  </a>
  <a href="https://en.wikipedia.org/wiki/C17_(C_standard_revision)">
    <img src="https://img.shields.io/badge/C-17-%2300599C" alt="C17">
  </a>
  <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey" alt="Platform">
  <img src="https://img.shields.io/badge/Size-%3C100KB-success" alt="Size">
  <img src="https://img.shields.io/badge/Dependencies-None-brightgreen" alt="Dependencies">
</p>

<p align="center">
  <strong>仓库地址：</strong><a href="https://gitee.com/YuYao-Gith/QN-IDLE">https://gitee.com/YuYao-Gith/QN-IDLE</a>
</p>

---

## 📖 目录

- [🎯 简介](#-简介)
- [✨ 特性](#-特性)
- [🚀 快速开始](#-快速开始)
- [💻 平台支持](#-平台支持)
- [📦 安装指南](#-安装指南)
  - [Linux](#-linux)
  - [macOS](#-macos)
  - [Windows](#-windows)
- [⚙️ 使用方法](#-使用方法)
- [🔧 命令行选项](#-命令行选项)
- [🏗️ 从源码构建](#-从源码构建)
- [🤝 贡献指南](#-贡献指南)
- [📜 许可证](#-许可证)
- [👤 作者](#-作者)

---

## 🎯 简介

```text
╔══════════════════════════════════════════════════════════════════╗
║ 还在为这些问题烦恼吗？                                           ║
║  • 看电影时屏幕自动变暗？                                        ║
║  • 演示 PPT 时突然黑屏？                                         ║
║  • 长时间编译时系统自动休眠？                                    ║
║  • SSH 会话因桌面空闲而中断？                                    ║
║  • 游戏挂机时屏幕保护弹出？                                      ║
║                                                                  ║
║  QN-IDLE 让你彻底告别这些烦恼！                                  ║
║  支持 Windows / macOS / Linux 三大平台                           ║
╚══════════════════════════════════════════════════════════════════╝
```

**QN-IDLE** 是一个跨平台的命令行工具，通过定期调用系统原生 API 或模拟轻微用户活动，防止系统进入空闲状态、自动黑屏、息屏或挂起。

---

## ✨ 特性

| 特性 | 说明 |
|------|------|
| 🌍 **跨平台** | 支持 Windows、macOS、Linux |
| 🚀 **极轻量** | 纯 C17 编写，零外部依赖，二进制 < 100KB |
| 💪 **低资源** | 内存占用 < 1MB，CPU 使用率 < 0.1% |
| 🎯 **原生 API** | 使用各平台原生接口，非 hack 方式 |
| 🔄 **多重策略** | 自动检测 + 自动回退，任何环境都能工作 |
| 👻 **守护进程** | 支持后台静默运行（Unix） |
| 📊 **实时统计** | 可选详细输出，实时监控抑制效果 |
| 🛡️ **安全可靠** | AGPLv3 开源，编译安全加固 |

---

## 🚀 快速开始

### Linux / macOS

```bash
# 克隆仓库
git clone https://gitee.com/YuYao-Gith/QN-IDLE.git
cd QN-IDLE

# 编译并安装
make && sudo make install

# 运行（60 秒间隔）
qidle -i 60
```

### Windows

```cmd
:: 使用 MinGW-w64 编译
make build

:: 或手动编译
gcc -std=c17 -O3 -o qidle.exe qn-idle.c -luser32 -lkernel32 -lpowrprof

:: 运行
qidle.exe -i 60
```

---

## 💻 平台支持

| 平台 | 版本要求 | 抑制方式 | 状态 |
|------|----------|----------|------|
| Windows | Windows 7+ | SetThreadExecutionState + SendInput | ✅ 完美 |
| macOS | macOS 10.12+ | IOPMAssertionCreate + caffeinate | ✅ 完美 |
| Linux (X11) | 任意发行版 | xdg-screensaver + xdotool + xset | ✅ 完美 |
| Linux (Wayland) | 任意发行版 | D-Bus + systemd-inhibit + ydotool | ✅ 完美 |

### Windows

- 使用原生 `SetThreadExecutionState` API，无需管理员权限
- 支持防止系统休眠 + 显示器关闭
- 兼容 Windows 7/8/10/11

### macOS

- 使用 IOKit 电源管理断言
- 不影响系统正常休眠策略（合盖仍会休眠）
- 支持 `caffeinate` 作为备选方案

### Linux

- 自动检测 X11/Wayland 环境，缓存并优先使用上次成功的策略
- 多种抑制策略自动回退
- 支持 systemd 用户服务集成

---

## 📦 安装指南

### Linux

#### 从源码安装

```bash
git clone https://gitee.com/YuYao-Gith/QN-IDLE.git
cd QN-IDLE
make
sudo make install
```

#### systemd 用户服务（推荐）

```bash
mkdir -p ~/.config/systemd/user/
cat > ~/.config/systemd/user/qidle.service << 'EOF'
[Unit]
Description=QN-IDLE - Prevent System Idle
After=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/qidle -i 55
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=graphical-session.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qidle.service
```

### macOS

```bash
# 编译安装
make && sudo make install

# 或指定安装路径
sudo make install PREFIX=/usr/local
```

#### 设置为开机启动（LaunchAgent）

```bash
cat > ~/Library/LaunchAgents/com.qnidle.qidle.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.qnidle.qidle</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/qidle</string>
        <string>-i</string>
        <string>60</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qnidle.qidle.plist
```

### Windows

#### 手动安装

```cmd
:: 编译
gcc -std=c17 -O3 -o qidle.exe qn-idle.c -luser32 -lkernel32 -lpowrprof

:: 复制到系统目录（需要管理员权限）
copy qidle.exe C:\Windows\System32\
```

#### 设置为开机启动

创建计划任务或放入启动文件夹：

```cmd
:: 创建计划任务（管理员权限）
schtasks /create /tn "QN-IDLE" /tr "C:\Windows\System32\qidle.exe -i 60" /sc onlogon /rl highest
```

---

## ⚙️ 使用方法

### 基本用法

```bash
# 默认 60 秒间隔
qidle

# 自定义间隔 30 秒
qidle -i 30

# 详细输出模式
qidle -v

# 后台运行（Linux/macOS）
qidle -d

# 检测当前平台
qidle --detect
```

### 典型场景

```bash
# 看电影（2 小时不黑屏）
qidle -i 120 &

# 演示模式（前台，实时查看状态）
qidle -v -i 30

# 游戏挂机（Windows）
qidle.exe -i 300

# 编译大项目（防止休眠）
qidle -d -i 60
```

---

## 🔧 命令行选项

| 选项 | 说明 |
|------|------|
| `-i, --interval <秒>` | 设置抑制间隔（默认 60，范围 1-3600） |
| `-v, --verbose` | 详细输出模式 |
| `-d, --daemon` | 守护进程模式（仅 Unix） |
| `--detect` | 检测当前平台信息 |
| `-V, --version` | 显示版本信息 |
| `-h, --help` | 显示帮助信息 |

---

## 🏗️ 从源码构建

### 依赖

- 编译器：GCC ≥ 9.0 / Clang ≥ 10.0（Windows 可用 MinGW-w64）
- 构建工具：GNU Make（或手动编译）
- 无外部库依赖

### 构建命令

```bash
# 当前平台编译
make build

# 安装到系统
make install

# 调试版本（ASan/UBSan）
make debug

# 全平台发布构建（需要交叉编译工具链）
make release

# 交叉编译 Windows 版本
make cross-win

# 交叉编译 macOS 版本
make cross-mac

# 静态分析
make analyze

# 清理
make clean

# 查看帮助
make help
```

### 手动编译

```bash
# Linux/macOS
gcc -std=c17 -O3 -o qidle qn-idle.c

# Windows (MinGW)
gcc -std=c17 -O3 -o qidle.exe qn-idle.c -luser32 -lkernel32 -lpowrprof

# Windows (MSVC)
cl /std:c17 /O2 qn-idle.c /Fe:qidle.exe user32.lib kernel32.lib powrprof.lib
```

---

## 🤝 贡献指南

```text
╔══════════════════════════════════════════════════════════════════╗
║  我们欢迎各种形式的贡献！                                        ║
║  🐛 Bug 报告     📝 文档改进     💡 功能建议                    ║
║  🔧 代码提交     🌍 翻译        🎨 艺术设计                     ║
╚══════════════════════════════════════════════════════════════════╝
```

### 贡献流程

1. Fork 本仓库（https://gitee.com/YuYao-Gith/QN-IDLE）
2. 创建特性分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m '添加某某特性'`
4. 推送分支：`git push origin feature/amazing-feature`
5. 发起 Pull Request

### 代码规范

- 遵循 C17 标准
- 通过所有平台编译测试（`-Wall -Wextra -Wpedantic` 零警告）
- 新功能需包含文档更新
- 提交信息清晰明了

---

## 📜 许可证

本项目采用 [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl-3.0.html) 许可证。

- 完整文本：[LICENSE](LICENSE)
- 许可证官网：https://www.gnu.org/licenses/agpl-3.0.html

> **重要提示**：AGPLv3 要求如果你修改了本软件并在网络上提供服务，你必须公开修改后的源代码。

---

## 👤 作者

- **作者**：YuYao-Gith
- **邮箱**：asdf2502@126.com
- **仓库**：https://gitee.com/YuYao-Gith/QN-IDLE
- **Issues**：https://gitee.com/YuYao-Gith/QN-IDLE/issues

---

## 🙏 致谢

- Windows API 团队 — 提供了优秀的电源管理接口
- Apple IOKit 团队 — macOS 电源管理框架
- X11/Wayland 社区 — Linux 显示服务器生态
- FreeDesktop.org — D-Bus 规范
- 所有贡献者 — 让这个项目变得更好

---

## ⭐ 支持项目

如果这个项目对你有帮助，请：

- 给项目一个 Star ⭐
- 分享给需要的朋友
- 提交 Issue 或 PR 帮助改进

---

<p align="center">
  <strong>🌟 QN-IDLE — 永不停歇的守护者</strong><br/>
  <sub>Made with ❤️ by <a href="mailto:asdf2502@126.com">YuYao</a> | Licensed under <a href="https://www.gnu.org/licenses/agpl-3.0.html">AGPLv3</a></sub><br/>
  <sub>仓库地址: <a href="https://gitee.com/YuYao-Gith/QN-IDLE">https://gitee.com/YuYao-Gith/QN-IDLE</a></sub>
</p>