# pyahk

**Repository Path**: itjee/pyahk

## Basic Information

- **Project Name**: pyahk
- **Description**: 游戏辅助, 自用
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-27
- **Last Updated**: 2026-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 📚 项目文档

本项目采用模块化文档结构，详细内容请参考wiki目录：

| 模块 | 内容概述 | 目标用户 |
|------|----------|----------|
| [01-项目概述与快速入门](WIKI/01-项目概述与快速入门.md) | 项目介绍、安装配置、基础使用 | 所有用户 |
| [02-架构与核心概念](WIKI/02-架构与核心概念.md) | 系统架构、事件总线、调度器、输入系统 | 开发者 |
| [03-功能模块与API](WIKI/03-功能模块与API.md) | 功能模块详解与常用API索引 | 高级用户/开发者 |
| [04-配置与条件系统](WIKI/04-配置与条件系统.md) | 配置管理、条件逻辑、热重载机制 | 配置人员 |
| [05-图像捕获与性能](WIKI/05-图像捕获与性能.md) | DXGI捕获、模板匹配、性能优化 | 技术人员 |
| [06-调试、部署与故障排查](WIKI/06-调试、部署与故障排查.md) | 调试工具、部署运维、故障排查合订本 | 开发者/运维 |

## 项目入口

pyahk提供两种使用方式：

1. **GUI版本** (`main.py`)：完整的图形用户界面，支持所有功能模块的可视化配置和控制
2. **命令行版本** (`main_special.py`)：轻量级版本，专注于特定游戏场景的自动化任务

## 核心功能特性

pyahk 基于现代化技术架构，提供以下核心功能：

### 🚀 **性能优化技术**
- **零拷贝屏幕捕获**: 基于DXGI的C++实现，毫秒级响应速度
- **HSV模板匹配**: 0.3ms检测速度，比OCR快82-803倍，100%成功率
- **智能暂停/恢复**: 优先级按键期间节省70-90% CPU资源
- **事件驱动架构**: 中央事件总线，完全解耦设计
- **统一调度器**: 单线程调度，亚毫秒级定时精度

### 🎮 **游戏自动化功能**
- **优先级按键系统**: 基于Windows Hook的选择性拦截；特殊按键保持原生响应，管理按键程序接管；智能暂停/恢复，节省70-90%CPU资源
- **智能药剂管理**: 
  - 矩形检测（推荐）: 0.3ms，100%成功率，96%误差<5%
  - 圆形检测: ~5ms，适合球形资源条
  - OCR识别: 25-241ms，三种引擎可选
- **高级技能系统**: HSV冷却检测，多触发模式，按键序列支持
- **装备词缀洗练**: PaddleOCR识别，实时OSD反馈
- **自动寻路探索**: A*算法，随机地图探索

### 🔧 **开发支持功能**
- **状态机管理**: 四状态转换，模式互斥逻辑
- **调试监控系统**: 实时OSD，条件日志输出

## 使用方法

1.  **启动程序**:
    *   **GUI版本**: 运行 `main.py`，启动包含完整PySide6界面的版本，支持所有功能模块。
    *   **特殊版本**: 运行 `main_special.py`，启动专用于特定自动化场景的独立脚本(Z键控制自动左键)。

2.  **配置**: 在GUI中完成配置，支持JSON格式的配置文件加载/保存，配置通过ConfigManager统一管理。

3.  **热键操作**:
    *   **F8 (主控键)**: 在STOPPED和READY状态间切换，准备技能模式执行。
    *   **F7 (洗练键)**: 独立控制装备词缀洗练模式的启动/停止。
    *   **F9 (寻路键)**: 独立控制自动寻路模式的准备/停止。
    *   **Z (执行/暂停键)**: 在READY状态下启动执行(RUNNING)，在RUNNING状态下暂停/恢复(PAUSED)。

4.  **颜色配置格式**: 新版本支持更清晰的多行颜色配置格式：
    ```
    容差值(H,S,V)     # 第一行：全局容差设置
    颜色1(H,S,V)      # 第二行：第一种检测颜色
    颜色2(H,S,V)      # 第三行：第二种检测颜色（可选）
    ...               # 更多颜色（可选）
    ```
    
    **示例配置**：
    - **HP血量检测**：
      ```
      10,20,20        # 容差：H±10, S±20, V±20
      157,75,29       # 红色血量
      40,84,48        # 绿色血量（备用）
      ```
    
    - **MP魔力检测**：
      ```
      5,5,5           # 容差：H±5, S±5, V±5
      104,80,58       # 蓝色魔力
      ```

## 依赖环境与配置

### 系统要求
- **操作系统**: Windows 10/11
- **Python版本**: 3.7+

### 核心依赖
```
PySide6>=6.5.0        # GUI框架
psutil>=5.9.0         # 系统进程监控
pynput>=1.7.6         # 键盘鼠标输入控制
Pillow>=9.0.0         # 图像处理
mss>=9.0.1           # 高性能截图(备用)
numpy>=1.20.0         # 数值计算
opencv-python>=4.5.0  # 计算机视觉
pywin32>=306          # Windows API
paddleocr==2.7.3      # OCR文字识别(固定版本)
```

### 项目结构
```
torchlight_assistant/
├── core/                           # 核心业务逻辑
│   ├── macro_engine.py            # 主控制器和状态管理
│   ├── event_bus.py               # 事件总线
│   ├── unified_scheduler.py       # 统一调度器
│   ├── input_handler.py           # 输入处理器
│   ├── skill_manager.py           # 技能管理
│   ├── resource_manager.py        # 资源检测
│   ├── debug_display_manager.py   # 调试显示
│   ├── simple_affix_reroll_manager.py # 装备洗练
│   ├── pathfinding_manager.py     # 自动寻路
│   └── states.py                  # 状态枚举
├── gui/                           # 用户界面
│   ├── main_window.py             # 主窗口
│   ├── debug_osd_window.py        # 调试覆盖窗口
│   └── ...
├── utils/                         # 工具类
│   ├── multi_priority_queue.py    # 多级优先队列
│   ├── priority_deque.py          # 优先级队列(兼容)
│   ├── native_graphics_capture_manager.py # 图形捕获
│   ├── border_frame_manager.py    # 边框管理
│   ├── hotkey_manager.py          # 热键管理（Windows低级Hook，选择性拦截）
│   └── ...
└── native_capture/                # C++原生捕获库
    ├── capture_lib.cpp            # DXGI捕获实现
    ├── capture_lib.h              # C接口定义
    ├── python_wrapper.py          # Python包装器
    └── ...
```