165 lines
9.2 KiB
Markdown
165 lines
9.2 KiB
Markdown
# 一键运行（OneClickRun）
|
||
|
||
以游戏式**快捷轮盘**快速启动软件、打开文件夹、访问网址与运行 PowerShell 脚本的 Windows 桌面工具。
|
||
程序默认驻留系统托盘，按全局快捷键呼出轮盘，选择指令后自动隐藏。
|
||
|
||
- 运行平台：Windows 10 / 11
|
||
- 技术栈：WPF + C#（.NET 8，`net8.0-windows`）
|
||
- 界面语言：简体中文
|
||
|
||
## 功能特性
|
||
|
||
- **快捷轮盘**：透明背景、亚克力风格扇形圆环，支持 1–12 条指令，扇形间留有均匀间距。
|
||
- **等间距几何**：每个扇形边界为平行偏移线，**任意半径处相邻扇形间隙宽度恒定**（默认 10 像素），
|
||
由单元测试与像素级验证双重保证。
|
||
- **呼出与隐藏**：默认隐藏，全局快捷键呼出；执行指令 / Esc / 点击轮盘外区域 / 再按快捷键 均可隐藏。
|
||
- **三种呼出方式**：
|
||
- 点击显示：按一次快捷键显示，再按一次隐藏；
|
||
- 长按显示：按住超过阈值（300–1500ms 可调）后显示；
|
||
- 按住显示：按住时显示、松开即隐藏。
|
||
- **三种选择方式**：
|
||
- 单击选择 / 双击选择；
|
||
- 滑动选择（仅“按住显示”下可用）：按住快捷键移动鼠标，松开时按鼠标所在方位就近命中扇形；
|
||
滑出圆环外、落在扇形间隙或边界处同样能按方向命中，仅中心枢纽内视为无方向。
|
||
- **四类指令**：
|
||
- 打开软件（.exe / .lnk / .bat / .cmd，支持启动参数）；
|
||
- 打开文件夹（资源管理器）；
|
||
- 打开网址（默认浏览器，无协议前缀自动补全 `https://`）；
|
||
- 运行脚本（使用 **PowerShell 7.6.5** 的 `pwsh.exe` 执行，支持脚本参数）。
|
||
- **系统设置**：开机启动、轮盘全局开关、显示位置（屏幕中心 / 鼠标位置）、全局快捷键录制、
|
||
呼出方式、选择方式、长按阈值、主题（日间 / 黑夜 / 跟随系统），全部即时生效并自动保存。
|
||
- **托盘与单实例**：关闭设置窗口后驻留托盘；双击托盘恢复设置；二次启动自动唤起已有实例。
|
||
- **容错**：配置文件损坏自动备份重建；指令执行失败非阻塞提示并记录日志；多显示器 DPI 感知（PerMonitorV2）。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.
|
||
├── OneClickRun.sln
|
||
├── global.json # 固定 .NET SDK 8.0
|
||
├── src/OneClickRun/
|
||
│ ├── OneClickRun.csproj # net8.0-windows; WPF + WinForms(托盘); 无第三方运行时依赖
|
||
│ ├── app.manifest # PerMonitorV2 DPI 感知
|
||
│ ├── App.xaml / App.xaml.cs # 入口：单实例、托盘、服务装配、快照调试模式
|
||
│ ├── Models/ # AppConfig / GeneralSettings / HotkeyBinding / WheelItem / 枚举
|
||
│ ├── Services/
|
||
│ │ ├── ConfigService.cs # %APPDATA%\OneClickRun\config.json 读写与损坏兜底
|
||
│ │ ├── HotkeyService.cs # RegisterHotKey 全局快捷键
|
||
│ │ ├── WheelWindowManager.cs # 三种呼出/选择模式状态机（30ms 按键轮询）
|
||
│ │ ├── CommandRunner.cs # 四类指令执行
|
||
│ │ ├── PowerShellLocator.cs # 定位 pwsh.exe 并构造参数
|
||
│ │ ├── AutostartService.cs # HKCU Run 开机启动
|
||
│ │ ├── ThemeService.cs # 日间/黑夜/跟随系统
|
||
│ │ ├── ToastService.cs # 非阻塞右下角提示
|
||
│ │ └── LogService.cs # 按天滚动文件日志
|
||
│ ├── Helpers/ # Win32 P/Invoke、轮盘几何、热键格式、DPI、全局鼠标钩子、应用图标
|
||
│ ├── Views/ # 主设置窗口、轮盘窗口、三个设置页、托盘宿主窗口、Toast
|
||
│ ├── Controls/ # 快捷键录制控件、指令编辑对话框
|
||
│ ├── Converters/ # 枚举显示/等值/徽标颜色等转换器
|
||
│ ├── Themes/ # Light.xaml / Dark.xaml / Styles.xaml（现代简约控件样式）
|
||
│ └── assets/samples/hello.ps1 # 内置示例脚本
|
||
├── tests/OneClickRun.Tests/ # xUnit：几何等间距、热键格式、配置读写、参数引号
|
||
├── scripts/ # 冒烟/单实例/像素验证脚本（PowerShell 7.6.5）
|
||
└── artifacts/ # 轮盘渲染快照（wheel-light.png / wheel-dark.png）
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- Windows 10 / 11（x64）
|
||
- [.NET 8 Desktop Runtime](https://dotnet.microsoft.com/zh-cn/download/dotnet/8.0)（开发/构建需 .NET SDK 8.0.4xx）
|
||
- **PowerShell 7（建议 7.6.5）**：仅“运行脚本”类指令需要；未安装时该指令会给出安装提示。
|
||
程序按 `PATH` → `%ProgramFiles%\PowerShell\7\pwsh.exe` → `%LocalAppData%\Programs\PowerShell\7\pwsh.exe` 顺序查找。
|
||
- 无需管理员权限；开机启动写入当前用户注册表（HKCU Run）。
|
||
|
||
## 安装与运行
|
||
|
||
```bash
|
||
# 构建（Debug）
|
||
dotnet build OneClickRun.sln -c Debug
|
||
|
||
# 运行
|
||
src/OneClickRun/bin/Debug/net8.0-windows/OneClickRun.exe
|
||
|
||
# 单元测试（26 项：几何等间距 / 热键格式 / 配置读写 / 参数引号）
|
||
dotnet test OneClickRun.sln -c Release
|
||
|
||
# 发布（框架依赖，体积小）
|
||
dotnet publish src/OneClickRun/OneClickRun.csproj -c Release -r win-x64 --self-contained false -o publish/
|
||
|
||
# 发布（自包含，目标机器无需安装 .NET 运行时）
|
||
dotnet publish src/OneClickRun/OneClickRun.csproj -c Release -r win-x64 --self-contained true -o publish/
|
||
```
|
||
|
||
首次运行会生成默认配置（4 条示例指令：打开文档 / 记事本 / 必应 / 示例脚本）并打开设置窗口；
|
||
此后启动直接驻留托盘。
|
||
|
||
## 使用说明
|
||
|
||
- 按全局快捷键（默认 **Ctrl+Alt+Space**）呼出轮盘；点击扇形执行对应指令，轮盘自动隐藏。
|
||
- Esc、点击轮盘外区域或（点击显示模式下）再按一次快捷键可隐藏轮盘。
|
||
- 托盘图标：双击打开设置；右键菜单含“打开设置 / 显示轮盘 / 开机启动 / 退出”。
|
||
- 关闭设置窗口 = 最小化到托盘，应用继续在后台运行；仅托盘“退出”真正退出。
|
||
- 全部设置在“系统设置”页即时生效并自动保存到 `%APPDATA%\OneClickRun\config.json`。
|
||
- 轮盘指令在“轮盘指令”页维护：新建、编辑、删除、上移/下移，按列表顺序在轮盘上顺时针排布。
|
||
- 关于页可查看/打开配置与日志目录，并显示 PowerShell 探测状态。
|
||
|
||
### 内部调试参数
|
||
|
||
- `OneClickRun.exe --snapshot <输出.png> [--dark] [--hover N]`：显示轮盘并导出 PNG 快照后退出（不保存配置），`--hover N` 可模拟悬停第 N 个扇形用于验证中心文本居中，
|
||
用于渲染验证，例如 `artifacts/wheel-light.png`。
|
||
|
||
## 配置与日志
|
||
|
||
- 配置：`%APPDATA%\OneClickRun\config.json`（UTF-8 JSON，原子写入；损坏时备份为
|
||
`config.broken-*.json` 并重建默认配置）。
|
||
- 日志：`%APPDATA%\OneClickRun\logs\app-YYYYMMDD.log`（按天滚动，记录热键注册、指令执行、异常等）。
|
||
- 配置结构示例：
|
||
|
||
```json
|
||
{
|
||
"version": 1,
|
||
"general": {
|
||
"autoStart": false,
|
||
"wheelEnabled": true,
|
||
"wheelPosition": "ScreenCenter",
|
||
"hotkey": { "modifiers": ["Ctrl", "Alt"], "key": "Space" },
|
||
"triggerMode": "Click",
|
||
"longPressMs": 400,
|
||
"selectionMode": "SingleClick",
|
||
"theme": "System"
|
||
},
|
||
"items": [
|
||
{ "id": "…", "name": "记事本", "type": "App", "path": "notepad.exe", "args": "" }
|
||
]
|
||
}
|
||
```
|
||
|
||
## 验证方式
|
||
|
||
- `dotnet test OneClickRun.sln -c Release`：26 项测试全绿；其中
|
||
`AdjacentSectorGapIsConstantAtEveryRadius` 用数值验证**任意半径处相邻扇形间隙恒等于 10px**（误差 < 1e-9）。
|
||
- `pwsh -NoProfile -File scripts/smoke.ps1`：启动冒烟（进程存活、默认配置生成、日志输出）。
|
||
- `pwsh -NoProfile -File scripts/analyze-wheel.ps1`：对轮盘快照做像素级间隙测量
|
||
（三个半径处间隙宽度一致，不随半径增大）。
|
||
- 手动验收清单：三种呼出方式、三种选择方式、四类指令、主题切换、开机启动、多显示器。
|
||
|
||
## 安全与凭据说明
|
||
|
||
- 本工具不收集、不传输任何数据；配置与日志仅保存在本机 `%APPDATA%\OneClickRun`。
|
||
- 开机启动仅写入当前用户注册表（HKCU Run），不使用管理员权限。
|
||
- 脚本类指令以当前用户身份执行，请勿添加来源不明的脚本。
|
||
|
||
## 已知取舍
|
||
|
||
- WPF 透明窗口无法承载系统级 Acrylic 模糊（与逐像素透明互斥），扇形采用**亚克力风格**：
|
||
80% 透明度渐变叠层 + 高光描边，Win10 / Win11 表现一致。
|
||
- 混合 DPI 多显示器已验证（主屏 125% + 副屏 100%）：滑动选择与点击轮盘外判定均按物理像素
|
||
换算命中；轮盘位置超出屏幕时按虚拟屏幕边界夹取。
|
||
- 全局快捷键若被其他程序占用，设置页会给出“注册失败”提示，请更换组合。
|
||
|
||
## 参考资料
|
||
|
||
- [.NET 8 下载](https://dotnet.microsoft.com/zh-cn/download/dotnet/8.0)
|
||
- [PowerShell 7.6 安装](https://learn.microsoft.com/zh-cn/powershell/scripting/install/installing-powershell-on-windows)
|
||
- [RegisterHotKey（Win32）](https://learn.microsoft.com/zh-cn/windows/win32/api/winuser/nf-winuser-registerhotkey)
|