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 exclusive-fullscreen limits

• Note UIPI hotkey permission mismatch

• Add Minecraft fullscreen FAQ workaround

• Clarify chat-box prerequisite

---

Diagram Walkthrough

flowchart LR
  I["Issue #457: Windows fullscreen failure"]
  C["coordinator.rs comment"]
  U["USAGE.md FAQ"]
  W["User workarounds"]
  I -- "documents root cause" --> C
  I -- "adds guidance" --> U
  C -- "explains OS limits" --> W
  U -- "suggests borderless fullscreen, matching permissions, open chat" --> W

Loading

File Walkthrough

Relevant files

Documentation

coordinator.rs Add Windows fullscreen limitation notes                                    openless-all/app/src-tauri/src/coordinator.rs Adds a Windows-specific comment above show_capsule_window_no_activate Explains why SetWindowPos(HWND_TOPMOST) fails over exclusive fullscreen apps Notes the related UIPI hotkey limitation when privilege levels differ Mentions borderless fullscreen as the practical workaround +12/-0    USAGE.md Add Windows Minecraft fullscreen FAQ                                          USAGE.md Adds a FAQ entry for capsule invisibility and missing text input in Windows games Describes exclusive fullscreen as an OS-level limitation Recommends borderless windowed fullscreen and matching admin privileges Reminds users to open Minecraft chat with T before inputting text +9/-0

---

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit af6fdc9)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 457 - Partially compliant Compliant requirements: Explains the Windows exclusive fullscreen limitation. Documents the borderless windowed fullscreen workaround. Calls out the Windows admin/UIPI constraint. Notes that Minecraft chat must be open for inserted text to land. Non-compliant requirements: Does not implement a runtime fix for capsule visibility or hotkey/input delivery in exclusive fullscreen. Requires further human verification: The documented workaround still needs manual verification on Windows with Minecraft/other fullscreen games.

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ No major issues detected

[github-actions]

Persistent review updated to latest commit af6fdc9