# xinyi-key-mouse-recoder

**Repository Path**: eersoft/xinyi-key-mouse-recoder

## Basic Information

- **Project Name**: xinyi-key-mouse-recoder
- **Description**: 心仪键鼠记录器
- **Primary Language**: C#
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-30
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 心仪键鼠记录器（XinyiKeyMouseRecorder）

> 出品：**EERSOFT** ｜ 官方网站：<https://www.eersoft.top>
> 基于 .NET 8 + WPF 的全局键盘鼠标记录、统计分析与可视化演示工具。

![tech](https://img.shields.io/badge/.NET-8.0-512BD4) ![wpf](https://img.shields.io/badge/UI-WPF-512BD4) ![db](https://img.shields.io/badge/DB-SQLite-003B57)

## 功能特性

1. **后台常驻 + 托盘**：随系统自动启动（可选），关闭窗口不退出，托盘菜单可快速操作（显示主窗口 / 暂停记录 / 开机自启动 / 关于 / 退出）。
2. **全局键盘鼠标记录**：
   - 键盘：记录按键（虚拟键码 + 键名）与按下/松开的时间；
   - 鼠标：**仅记录左键、右键点击与滚轮滚动**（delta，120 = 1 格），不记录移动距离、中键与侧键（X1/X2）；
   - 所有事件按时间顺序写入本地 SQLite 数据库，默认位于 `文档\XinyiKeyMouseRecorder\records.db`，支持在设置中自定义路径。
3. **统计报表**：
   - 按日统计：每日按键次数、鼠标点击次数、滚动距离；
   - 按小时统计：日期段内每天每小时的上述三项指标；
   - 按键次数统计：日期段内各按键的总次数；
   - 展示方式：表格（DataGrid）+ 柱状图（按日）+ 折线图（按小时）。
4. **可视化演示**：标准键盘视图 + 鼠标视图，选定日期段后可动态按时间顺序播放按键/点击/滚轮，并在对应键位上高亮、累计显示次数；播放使用**固定间隔**（忽略真实记录间隔，速度可调），键位颜色随累计次数形成**热力图**（白→黄→橙→红），文字使用 WCAG 对比度选色 + 光晕描边保证任何颜色下清晰可读；支持 **2D / 3D 双视图**切换——3D 视图基于 WPF 原生 Viewport3D，参考 Three.js 键鼠模型设计重建：梯形键帽（顶面缩放）+ 圆角矩形外壳 + 分组配色（修饰键/导航键/方向键/空格/F 键）+ 四光源（主光/补光/轮廓光）+ 按下平滑下沉与蓝色发光动画 + 顶面文字纹理（宽高比匹配、超宽自动缩字号、热力对比色与次数），可拖拽旋转、滚轮缩放，建议在独立显卡上体验最佳效果。
5. **JSON 数据导出**：选定日期段一键导出为 JSON，供自建网页可视化展示（导出结构见下文）。
6. **数据库管理**：设置页支持“打开数据库文件夹”；一键“清空数据库”，清空前自动备份到数据库目录（文件名如 `20260831清空前备份数据.db`，同日重复清空自动加序号）。
7. **全屏游戏记录**：低级钩子可记录绝大多数全屏游戏（含现代 DirectX/OpenGL/Vulkan 独占全屏）的按键、鼠标点击与滚轮；若游戏以管理员权限运行（反作弊、任务管理器等），请使用托盘菜单或设置页的“以管理员身份重启”（触发一次 UAC 确认）后即可记录。
8. **品牌信息**：工具名称、托盘、关于页均包含 EERSOFT 品牌与官网链接。

## 技术栈与稳定性设计

- .NET 8（net8.0-windows）、WPF、MVVM 轻量实现；
- 存储：Microsoft.Data.Sqlite；图表：LiveCharts2（SkiaSharp）；托盘：Hardcodet.NotifyIcon.Wpf；
- **全局钩子稳定性（对应微软官方建议）**：
  - 低级钩子（`WH_KEYBOARD_LL` / `WH_MOUSE_LL`）安装在**独立线程 + 自有 GetMessage 消息泵**上，绝不装在 WPF UI 线程；
  - 回调内**只做轻量入队/距离累加，绝不阻塞、绝不触碰 UI、绝不写库**，避免被系统摘钩；
  - 回调一律调用 `CallNextHookEx` 传递钩子链，不影响输入法、截图工具、游戏反作弊等其他钩子；
  - 数据库写入由独立写库线程**批量事务**完成，与钩子线程完全解耦；
  - 队列设有上限，极端情况下丢弃新事件也不让内存膨胀。

## 构建

```bash
# 需要 .NET 8 SDK
dotnet restore XinyiKeyMouseRecorder.sln
dotnet build XinyiKeyMouseRecorder.sln -c Release
# 输出目录：src/XinyiKeyMouseRecorder/bin/Release/net8.0-windows/
```

## 发布（单文件，不带框架）

```bash
# 不带框架（framework-dependent）+ 单文件，原生库一并嵌入 exe（运行时自动解压到临时目录）
dotnet publish src/XinyiKeyMouseRecorder/XinyiKeyMouseRecorder.csproj -c Release -r win-x64 \
  --self-contained false -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true \
  -p:DebugType=None -o publish
# 输出：publish/XinyiKeyMouseRecorder.exe（约 23MB 单文件）
```

> 不带框架发布依赖目标机器已安装 **.NET 8 Desktop Runtime**；如需免安装运行（自包含），去掉 `--self-contained false` 即可（文件约 150MB+）。

## 使用说明

1. 首次运行：双击 `XinyiKeyMouseRecorder.exe`，程序自动在 `文档\XinyiKeyMouseRecorder\` 创建数据库并开始全局记录；
2. 关闭主窗口 = 最小化到托盘，程序继续在后台记录；
3. 开机自启动：托盘菜单或「设置 → 运行选项」勾选（写入 HKCU Run，无需管理员权限，自启动时以 `--minimized` 后台运行）；
4. 更改数据库路径：设置页浏览选择新位置并「保存设置」，立即生效。

## 兼容性与注意事项（重要）

- **全屏游戏**：低级钩子（`WH_KEYBOARD_LL`/`WH_MOUSE_LL`）可记录绝大多数全屏游戏——现代 Windows 上全屏游戏（独占或窗口化全屏）的键鼠输入仍会经过系统消息管线，钩子可在分发前拦截记录。两个例外：① 游戏**以管理员权限运行**时普通权限钩子收不到，请用托盘/设置页的“以管理员身份重启”；② 极老式 DirectInput **独占**模式游戏（约 2007 年前）可能绕过消息队列，此类游戏的事件收不到（现代游戏基本不受影响）。
- **权限**：默认以普通用户权限运行（无 UAC 弹窗），因此无法收到**以管理员身份运行**的进程（如任务管理器、多数反作弊进程）的键鼠事件；需要时通过托盘菜单或设置页“以管理员身份重启”（触发一次 UAC 确认，重启后自动等待旧实例退出再安装钩子，避免双钩子重复记录）；
- **杀软误报**：全局键盘钩子是键盘记录器的典型特征，Defender / 杀软可能拦截或误报。请将本工具加入白名单；正式分发前建议完成**代码签名**（至少自签名 + 引导用户加白）；
- **数据隐私**：所有数据仅保存在本地 SQLite，程序不上传任何内容；
- **DPI**：已启用 PerMonitorV2 DPI 感知。

## JSON 导出结构（供网页可视化）

导出文件为 UTF-8（无 BOM）JSON，顶层字段：

```jsonc
{
  "app": "心仪键鼠记录器",
  "company": "EERSOFT",
  "website": "https://www.eersoft.top",
  "version": "1.1.3",
  "exportedAt": "2026-08-31 12:00:00",
  "period": { "startDate": "2026-08-01", "endDate": "2026-08-31" },
  "summary": {
    "keyCount": 12345,            // 按键总次数（按下）
    "mouseClickCount": 678,       // 鼠标点击总次数（左键+右键）
    "wheelDistanceNotches": 88.5, // 滚动距离（格，120 delta = 1 格）
    "eventCount": 13012           // 事件总条数
  },
  "dailyStats": [
    { "date": "2026-08-01", "keyCount": 1200, "mouseClickCount": 80, "wheelDistance": 12.5 }
  ],
  "hourlyStats": [
    { "date": "2026-08-01", "hour": 9, "keyCount": 300, "mouseClickCount": 20, "wheelDistance": 3.0 }
  ],
  "keyCountStats": [
    { "keyCode": 65, "keyName": "A", "count": 800 }
  ],
  "events": [
    {
      "time": "2026-08-01 09:00:00.123",   // 本地时间
      "device": "keyboard",                 // keyboard | mouse
      "event": "Down",                      // 键盘: Down/Up; 鼠标: ButtonDown/ButtonUp/WheelV/WheelH
      "keyCode": 65, "keyName": "A",
      "button": "Left",                     // 鼠标按键: Left/Right/Middle/X1/X2
      "x": 1234, "y": 567,                  // 屏幕坐标（点击/滚轮）
      "wheelDelta": 120                     // 仅滚轮事件
    }
  ]
}
```

网页端可直接消费 `events`（按时间顺序）做动态演示、`dailyStats` / `hourlyStats` 绘制图表、`keyCountStats` 展示按键热度。

## 项目结构

```
src/XinyiKeyMouseRecorder/
├── App.xaml(.cs)            # 入口：单实例、服务装配、托盘、全局异常日志
├── MainWindow.xaml(.cs)     # 主窗体（统计 / 演示 / 设置）
├── Models/                  # InputEvent、DailyStat、HourlyStat、KeyCountStat
├── Services/
│   ├── NativeMethods.cs     # Win32 P/Invoke（钩子、消息泵、托盘）
│   ├── GlobalHookService.cs # 全局钩子（独立线程消息泵、队列、批量落库）
│   ├── DatabaseService.cs   # SQLite 存储与统计查询
│   ├── ExportService.cs     # JSON 导出
│   ├── SettingsService.cs   # 设置持久化（%AppData%\EERSOFT\XinyiKeyMouseRecorder）
│   ├── AutoStartService.cs  # 开机自启动（HKCU Run）
│   ├── KeyNames.cs          # 虚拟键码 → 显示名
│   └── IconFactory.cs       # 运行时生成 EERSOFT 品牌图标
└── Views/
    ├── StatisticsView       # 表格 + 柱状图 + 折线图 + JSON 导出
    ├── DemoView             # 可视化演示（播放控制）
    ├── SettingsView         # 设置
    ├── AboutWindow          # 关于
    └── Controls/            # KeyboardView（2D 标准键盘）、MouseView（2D 鼠标）、Keyboard3DView / Mouse3DView（3D 建模，WPF Viewport3D）、HeatPalette（热力配色）、MeshBuilder（3D 网格）、KeycapTexture（键帽文字纹理）
```

## 版权

© 2025 EERSOFT（<https://www.eersoft.top>）。保留所有权利。