窗口置顶工具 WinPin

一个轻量级的 Windows 窗口置顶工具：按一下快捷键，把当前窗口"钉"在最前面；再按一下取消。纯 Python 标准库 + Win32 API 实现，无任何运行时依赖，打包为单个 exe 即可使用。

功能特性

• 全局快捷键置顶：默认 F8 置顶/取消当前活动窗口，可自定义任意组合键（如 Ctrl+Alt+P、F9 等）
• 常驻状态提示：置顶中的窗口外圈会显示彩色边框（颜色、宽度可自定义），一眼看出哪些窗口被置顶
• 即时提示标签：置顶/取消时窗口旁弹出短暂的"已置顶 / 已取消置顶"提示标签（带淡入淡出动画）
• 系统气泡通知：同步发送托盘气泡通知（可在设置中关闭）
• 托盘图标：常驻系统托盘，图标随置顶状态变化（灰色=空闲，橙色=有窗口置顶）
  • 左键单击托盘图标：置顶/取消当前窗口
  • 双击：打开设置
  • 右键：菜单（置顶当前窗口 / 鼠标点选窗口置顶 / 取消全部 / 设置 / 开机自启 / 退出）
• 鼠标点选模式：菜单选择"选择窗口置顶"后，移动鼠标到任意窗口（带蓝色预览边框和十字光标），光标旁跟随标签实时显示目标窗口名称（"置顶 · 标题"蓝色 / "取消置顶 · 标题"橙色），单击即可置顶或取消，Esc/右键退出
• 多窗口同时置顶，互不干扰；窗口关闭后自动解除
• 开机自启开关（写入注册表 HKCU...\Run，不弹 UAC）
• 配置自动保存：快捷键、边框颜色/宽度、提示开关等保存在 exe 同目录的 WinPin.config.json

使用方法

1. 双击运行 窗口置顶工具.exe（或 dist\WinPin.exe），程序驻留系统托盘
2. 激活想要置顶的窗口，按 F8（默认）→ 窗口边框变橙色并显示"已置顶"提示，此后它始终显示在其他窗口之上
3. 再次按 F8（或点击托盘图标）取消置顶
4. 右键托盘图标 → 设置 可自定义快捷键、边框颜色/宽度、提示方式、开机自启

提示：无法置顶的窗口（桌面、任务栏、系统弹窗等）会自动被过滤并给出提示。

常见问题

• 双击后没有反应 / 进程自动结束：
  1. 查看诊断日志：exe 同目录的 WinPin_debug.log，或 %TEMP%\WinPin.log（文件资源管理器地址栏输入 %TEMP% 回车即可打开该目录）。
  2. 运行 WinPin_debug.exe（诊断版，带黑色控制台窗口），控制台会逐行显示启动过程；若闪退，把控制台截图或日志文件内容发回即可定位问题。
  3. 若日志里出现 another instance detected：说明托盘区已有一个实例在运行，本次是正常退出而非崩溃（右键托盘图标→退出后再启动）。
  4. 检查安全中心：Defender/第三方杀软可能拦截单文件 exe。加入信任或排除项，或改用便携版目录 窗口置顶工具_便携版\WinPin.exe（文件夹形式，被误杀概率更低）。
• 快捷键没反应 / 被占用：进入设置点击快捷键按钮重新录制；若提示"已被其他程序占用"，换一个组合键。
• 无法置顶管理员窗口（如任务管理器）：普通权限的程序不能改变更高权限窗口的属性。请右键 exe → 以管理员身份运行（此时所有窗口都能置顶）。
• 杀毒软件误报：PyInstaller 单文件打包的程序偶尔会被误报，添加信任即可（本工具源码完全公开，可自行审查后重新打包）。
• 置顶失效：个别程序（如全屏独占游戏、特殊视频渲染窗口）会自绘并覆盖其他窗口，属程序自身行为，无法通过常规置顶解决。

从源码构建

需要 Python 3.8+（本机开发环境为 3.14），仅需安装 PyInstaller：

powershell -ExecutionPolicy Bypass -File build.ps1

脚本会自动：安装 PyInstaller 到 vendor\ → 生成图标 → 打包为单文件 exe。 产物：dist\WinPin.exe，并复制一份为 窗口置顶工具.exe。

诊断版构建（带控制台、可看到全部运行日志）：

$env:PYTHONPATH = "vendor"
python -m PyInstaller --noconfirm --onefile --console --name WinPin_debug `
  --icon "src\winpin\assets\app.ico" --add-data "src\winpin\assets;winpin\assets" `
  --version-file "version_info.txt" "src\launcher.py"

项目结构

src\winpin\
  app.py        主程序（托盘/热键/置顶逻辑/消息循环）
  wintools.py   纯 ctypes Win32 API 封装
  overlay.py    分层窗口渲染（置顶边框/提示标签/十字光标）
  trayicon.py   托盘图标与右键菜单
  hotkey.py     热键格式化与录制
  settings.py   设置窗口（tkinter）
  config.py     配置读写
  diag.py       诊断日志与崩溃捕获（闪退排查用）
  assets\       程序图标与托盘图标（tools\gen_icons.py 生成）
tools\
  gen_icons.py          图标生成器（纯 Python 输出 .ico）
  verify_render.py      渲染结果自动校验
  simulate_interaction.py 托盘点击/热键交互模拟测试
  preview.py            渲染 PNG 预览

自检运行：python src\launcher.py --selftest（会自动注册热键、创建托盘图标与示例边框后退出）。

技术说明

• 置顶通过 SetWindowPos(HWND_TOPMOST) 实现；边框/标签为 WS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_NOACTIVATE 分层窗口（鼠标穿透、不抢焦点），用 UpdateLayeredWindow 逐像素渲染
• 启用 Per-Monitor V2 DPI 感知，高 DPI 屏（125%/150%...）下边框定位精确
• 热键使用 RegisterHotKey（带 MOD_NOREPEAT），托盘用 Shell_NotifyIconW（GUID 注册失败时自动回退传统 uID 方式，资源管理器重启后自动恢复）
• 托盘/热键消息通过纯 Python 队列转交给 Tcl 定时器处理，避免在 Tk 消息分发中重入 Tcl 解释器导致崩溃

开源许可

MIT License © 2026 L-mimimi