docs(windows): 独占全屏游戏 capsule/hotkey OS 级限制 (#457)

[appergb]

User description

关联 issue #457。

摘要

记录 Windows 端独占全屏游戏（典型例：Minecraft）下 OpenLess 行为失效的操作系统级根因与用户侧 workaround：

• 代码侧（coordinator.rs）：在 show_capsule_window_no_activate Windows 路径上方加注释块，说明 SetWindowPos(HWND_TOPMOST) 对独占全屏 DirectX/OpenGL 应用无效（绕过桌面合成器），以及 UIPI 阻挡 hotkey 的同源现象。给后续维护者留下「这条路走不通」的明确路标。
• 文档侧（USAGE.md）：FAQ 加 1 条 —— 用户应把游戏切到 borderless windowed fullscreen，对齐管理员权限，预先打开聊天框。

不修改运行时行为。 真正绕过独占全屏需要 DirectX overlay 注入（Discord / MSI Afterburner 路线），工程量 + 风险都超出 surgical 修复范围；本 PR 不动这一层。

根因分析

按可能性排序（详见 issue #457）：

1. 独占全屏 OS 限制：标准 Win32 topmost 窗口（无论 WS_EX_TOPMOST 还是运行时 SetWindowPos(HWND_TOPMOST)）不会被绘制在独占全屏 DirectX/OpenGL 应用之上。借助 desktop 合成器叠加 = 必然不可见。
2. UIPI 阻挡 hotkey：低权限进程的 WH_KEYBOARD_LL 收不到高权限进程的按键。若游戏以管理员运行而 OpenLess 不是，hotkey 完全不触发。
3. 游戏聊天框未打开：SendInput Unicode keystrokes 进游戏窗口但落不到文本输入位置。Minecraft 必须先按 T 打开聊天框。

macOS 不存在独占全屏（所有"全屏"都是带 Spaces 的 borderless），故平台不可比。

改动

文件	改动类型	行数
openless-all/app/src-tauri/src/coordinator.rs	注释块	+12
USAGE.md	FAQ 条目	+9

Why draft

我（claude code session）的当前环境是 macOS，无法在 Windows 本机实测用户场景。本 PR 是 0 行为变更的纯文档改动，cargo check 通过（仅 pre-existing warnings），但仍标 draft 以便 reviewer 在 Windows 机器上：

• 实际验证 USAGE.md 中给出的 workaround 路径（borderless windowed + admin 对齐 + 聊天框）是否能让 OpenLess 在 Minecraft 下正常工作
• 决定是否还需要补充用户面更详细的诊断步骤（如何在游戏内确认是哪种 fullscreen 模式）

测试计划

• cargo check 通过（macOS 本机已通过；Windows CI 待跑）
• Windows 实测：把 Minecraft 切到 borderless windowed → capsule 应能正常显示
• Windows 实测：把 Minecraft 切到 exclusive fullscreen → capsule 不可见（确认 OS 限制）
• Windows 实测：游戏以 admin 运行 + OpenLess 普通用户 → hotkey 应被 UIPI 阻挡
• 阅读 USAGE.md FAQ：表述是否对非技术用户友好

---

PR Type

Documentation

---

Description

• Document Windows fullscreen overlay limits

• Explain admin and hotkey restrictions

• Add Minecraft workaround FAQ entry

---

File Walkthrough

Relevant files

Documentation

coordinator.rs Document capsule overlay OS limitations                                    openless-all/app/src-tauri/src/coordinator.rs Adds a Windows-specific comment block above show_capsule_window_no_activate Explains why SetWindowPos(HWND_TOPMOST) fails in exclusive fullscreen Notes the related UIPI hotkey limitation and borderless workaround +12/-0    USAGE.md Add Windows fullscreen FAQ guidance                                            USAGE.md Adds a FAQ entry for Minecraft and other fullscreen Windows games Recommends borderless windowed fullscreen and aligned admin privileges Reminds users to open the Minecraft chat box with T +9/-0

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ❌ 457 - Not compliant Non-compliant requirements: The PR does not change runtime behavior to make the capsule visible over exclusive fullscreen games. The PR does not change runtime behavior to ensure streamed speech is inserted into the game on Windows. Requires further human verification: Whether the new FAQ guidance is accurate across Minecraft Java/Bedrock variants and different fullscreen modes.

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ No major issues detected