[windows][bug] 独占全屏游戏（Minecraft 等）下流式语音输入失效、capsule 不显示

[appergb]

症状

在 Windows 端：

• 全屏游玩游戏（典型例子：Minecraft），或者把 Minecraft 放大到全屏时
• 触发 OpenLess 流式语音输入，capsule 输入提示框不会弹出
• 语音识别出的字符也不会落到游戏里

macOS 上同样的操作正常。

复现条件

• OS: Windows
• 游戏：Minecraft（Java / Bedrock 均报告）
• 游戏窗口模式：全屏 / 最大化
• OpenLess：流式语音输入开启

期望行为

至少 macOS 当前的体验：capsule 显示在游戏窗口之上，识别字符流式落到游戏聊天框（用户已按 T 打开聊天）。

根因分析（代码级 + Windows OS 机制）

按可能性排序：

1. Capsule overlay 在独占全屏（exclusive fullscreen）DirectX/OpenGL 应用之上无法绘制 ← 主要嫌疑

代码现状：`openless-all/app/src-tauri/src/coordinator.rs:4001-4034` 的 `show_capsule_window_no_activate` 用：

```rust
ShowWindow(hwnd, SW_SHOWNOACTIVATE)
SetWindowPos(hwnd, HWND_TOPMOST, ..., SWP_NOACTIVATE | SWP_SHOWWINDOW)
```

这是 Windows 标准 topmost。OS 级限制：

• 独占全屏（exclusive fullscreen）DirectX 应用接管整个显存合成路径，标准 Win32 topmost 窗口不会被绘制在它之上。
• borderless windowed fullscreen（无边框窗口化全屏）则属于普通 desktop 合成，topmost 可以正常叠加。

Minecraft 行为：

• Java 版默认是 borderless windowed（GLFW 实现）
• 但用户按 F11 / 设置切到真正的全屏 / 部分启动器 / 某些 mod 会切到 exclusive fullscreen
• Bedrock / Win10 edition 是 UWP，规则又不一样

macOS 不存在 exclusive fullscreen（所有全屏都是带 Spaces 的 borderless），所以 capsule 必然可见 —— 这就解释了平台差异。

2. UIPI（User Interface Privilege Isolation）阻挡 hotkey

代码现状：`openless-all/app/src-tauri/src/hotkey.rs:748-1003` 用 `SetWindowsHookExW(WH_KEYBOARD_LL, ...)`。

OS 级限制：低权限进程安装的 low-level keyboard hook 收不到高权限进程的按键。

• 若用户的 Minecraft 启动器以管理员身份运行（或 game 本身需要管理员）
• 而 OpenLess 是普通用户权限
• 则 OpenLess 完全收不到 hotkey edge → 录音根本不启动 → capsule 也不显示

3. SendInput 进了游戏窗口但落不到文本输入位置

代码现状：`openless-all/app/src-tauri/src/insertion.rs:388-428` 的 `windows_unicode::send_text` 用 `SendInput(KEYEVENTF_UNICODE)` 发 UTF-16 击键。

• Minecraft 用 GLFW，理论上接收 SendInput → 标准 Windows message queue 路径正常
• 但只有在 聊天框打开（用户按 T） 时字符才落到文本输入区
• 否则按键被游戏当作 movement / 物品栏 / 选项 hotkey 消化掉

这一项不应该是主因（用户应该会先开聊天框）但应排查。

诊断需要的数据

请用户提供：

1. 游戏窗口模式：Minecraft 的 视频设置 → 全屏模式 当前是开还是关；通过 F11 切换的话切到哪种
2. 是否以管理员身份运行：Minecraft 启动器和 OpenLess 各自的权限状态
3. 日志文件：`%LOCALAPPDATA%\OpenLess\Logs\openless.log` —— 重点看：
   • `[hotkey] Windows trigger pressed` 是否出现（验证假设 2）
   • `[coord] session started` 是否出现（验证录音流程是否启动）
   • `[coord] streaming_insert SUCCESS` 是否出现（验证识别完整流程）

修复方向

• (短期 / 文档)：在 README / USAGE 中说明 Windows 独占全屏的限制，建议用户把游戏切到 borderless windowed fullscreen
• (短期 / 代码)：在关键路径加 Windows 专属诊断日志（前台窗口标题、capsule 实际可见性、SendInput 返回值），让用户能给出更精确的复现数据
• (中长期)：考虑接入 DirectX overlay（类似 Discord / MSI Afterburner 的方案），但工程量大、风险高，不在本 issue 范围

平台 / 环境

• OS: Windows
• 影响版本: 现行 beta 1.3.3 之前所有
• 不影响 macOS

cc @baiqing

[appergb]

PR #458 已开，仅文档与注释改动，draft 等 Windows 端实测。

需要复现的人帮跑一下：

1. 把 Minecraft 切到 borderless windowed fullscreen（视频设置 → 全屏 关）—— capsule 应能正常显示；若仍不显示，说明根因不是独占全屏
2. 检查 OpenLess 与 Minecraft 启动器的权限是否一致（任务管理器 → 详细信息 → 加「提升的」列查看）
3. 在 Minecraft 中先按 T 打开聊天框，再触发 OpenLess hotkey

若上述都满足仍不工作，请把 %LOCALAPPDATA%\OpenLess\Logs\openless.log 贴上来，重点截取触发 hotkey 前后 5 秒。

[appergb]

@claude 有没有什么其他办法修复这个问题？

[claude]

Claude finished @appergb's task in 3m 46s —— View job

---

修复方案分析

• 读取相关源码（coordinator.rs, insertion.rs, hotkey.rs, lib.rs）
• 分析各种修复方案的可行性
• 提供技术建议

---

以下按实现难度从低到高列出所有可行的替代修复方向，每种都注明在代码中的落点。

---

方案 A：独占全屏检测 + 优雅降级（推荐，中等难度）

在触发 show_capsule_window_for_recording（coordinator.rs:95）之前，检测前台窗口是否处于独占全屏，若是则跳过 capsule 并切换到其他反馈机制。

检测方法（Win32）：

#[cfg(target_os = "windows")]
fn is_foreground_exclusive_fullscreen() -> bool {
    use windows::Win32::Foundation::RECT;
    use windows::Win32::Graphics::Gdi::{GetMonitorInfoW, MonitorFromWindow, MONITORINFO, MONITOR_DEFAULTTOPRIMARY};
    use windows::Win32::UI::WindowsAndMessaging::{
        GetForegroundWindow, GetWindowLongW, GetWindowRect, GWL_STYLE, WS_CAPTION, WS_POPUP,
    };

    unsafe {
        let hwnd = GetForegroundWindow();
        if hwnd.0.is_null() { return false; }

        let style = GetWindowLongW(hwnd, GWL_STYLE) as u32;
        // 独占全屏特征：有 WS_POPUP，无 WS_CAPTION，且覆盖整个显示器
        if style & WS_POPUP.0 == 0 || style & WS_CAPTION.0 != 0 { return false; }

        let mut win_rect = RECT::default();
        let _ = GetWindowRect(hwnd, &mut win_rect);

        let monitor = MonitorFromWindow(hwnd, MONITOR_DEFAULTTOPRIMARY);
        let mut mi = MONITORINFO { cbSize: std::mem::size_of::<MONITORINFO>() as u32, ..Default::default() };
        if GetMonitorInfoW(monitor, &mut mi).is_err() { return false; }

        // 窗口 rect 覆盖整个显示器 rect → 很可能是独占全屏
        win_rect.left == mi.rcMonitor.left
            && win_rect.top == mi.rcMonitor.top
            && win_rect.right == mi.rcMonitor.right
            && win_rect.bottom == mi.rcMonitor.bottom
    }
}

注意：此方法也会匹配 borderless windowed fullscreen，因此实际上是"全覆盖全屏"检测，包括独占和无边框两种。若需严格区分，需要配合 DXGI IDXGIOutput::GetDisplayModeList 或 DwmGetWindowAttribute(DWMWA_CLOAKED) 做进一步判断，但对于 capsule 可见性来说，这两种都影响叠加，意义有限。

落点：coordinator.rs:95 的 show_capsule_window_for_recording 添加早期检测；若命中则跳过 capsule，改为触发以下方案之一。

---

方案 B：系统托盘图标状态动画（零新依赖，最快）

项目已有完整的托盘图标体系（lib.rs:54 引用的 TrayIconBuilder）。可在录音/转录/写入各状态下切换托盘图标（比如用不同颜色的 mic 图标）。

• 独占全屏下用户虽然看不到 capsule，但任务栏/托盘在绝大多数 borderless windowed fullscreen 场景下仍可见
• 在真正的独占全屏下，用户 Alt+Tab 或鼠标移向角落时可看到托盘
• 实现代价极低：TrayIcon::set_icon() + 准备几套图标资源

落点：coordinator.rs:emit_capsule → 按 CapsuleState 值调用 app.tray_by_id("main-tray").set_icon(...)

---

方案 C：Windows Toast 系统通知作为备用视觉反馈（中等难度）

Windows Toast 通知由系统 Shell 渲染，优先级高于用户态 topmost 窗口，可显示在独占全屏应用之上（和游戏内 Xbox Game Bar 通知同级）。

需要在 Cargo.toml 添加 WinRT feature：

[target.'cfg(target_os = "windows")'.dependencies]
windows = { version = "0.58", features = [
  # ... 现有 features ...
  "UI_Notifications",
  "Data_Xml_Dom",
  "Foundation",
] }

代码骨架：

#[cfg(target_os = "windows")]
fn show_toast_recording_started(text_so_far: &str) {
    use windows::UI::Notifications::{ToastNotification, ToastNotificationManager};
    use windows::Data::Xml::Dom::XmlDocument;

    let xml = XmlDocument::new().unwrap();
    xml.LoadXml(&format!(
        r#"<toast><visual><binding template="ToastText01"><text id="1">🎙 OpenLess 正在录音…{}</text></binding></visual></toast>"#,
        text_so_far
    )).ok();
    let notifier = ToastNotificationManager::CreateToastNotifierWithId(
        &windows::core::HSTRING::from("OpenLess")
    ).unwrap();
    let toast = ToastNotification::CreateToastNotification(&xml).unwrap();
    notifier.Show(&toast).ok();
}

局限：Toast 是异步弹出的（有淡入动画），无法做流式字符更新；适合作为"录音结束 / 识别完成"的一次性通知，而不是逐字实时显示。

---

方案 D："游戏模式"设置（中等难度，用户体验最佳）

增加一个用户设置项 gaming_mode: bool，当开启时：

1. 跳过 capsule，改用托盘图标状态（方案 B）
2. 跳过流式 Unicode SendInput，改为等待最终识别结果后一次性粘贴（insert_via_clipboard_fallback，insertion.rs:57）
3. 可选：识别完成后播报 Toast 通知

这样在游戏场景下，用户先按 T 开聊天框，再触发 OpenLess，说完话，识别结果一次性粘贴到聊天框。与 macOS 流式体验相比有延迟，但功能完整。

代码落点：

• types.rs 新增 gaming_mode 偏好字段
• coordinator.rs 在 streaming_insert_* 路径判断 gaming_mode：若是，缓冲所有分片直到 session_ended，再统一调用 inserter.insert_via_clipboard_fallback

---

方案 E：提权运行（仅修复 UIPI 热键问题，零代码）

若 Minecraft 启动器以管理员权限运行，而 OpenLess 是普通权限：

• WH_KEYBOARD_LL hook 完全收不到游戏的按键
• 解决方法：以管理员身份运行 OpenLess（右键 → 以管理员身份运行；或在 app.manifest 中设 requestedExecutionLevel = requireAdministrator）

注意：提权只解决热键问题（根因 2），不解决独占全屏 capsule 不显示（根因 1）。

---

方案 F：DirectX / DXGI Overlay（长期，工程量大）

像 Discord、Steam、MSI Afterburner 那样通过 Hook IDXGISwapChain::Present 注入渲染，或使用 Vulkan 的 VK_LAYER_ 机制。可以在独占全屏下显示任意 UI。

代价极高：

• 需要将 DLL 注入到游戏进程
• 可能触发 VAC / EasyAntiCheat / BattleEye 检测 → 用户封号风险
• 需要维护 D3D9/D3D11/D3D12/Vulkan 多条路径
• 不在本 issue 的合理范围内，仅作为远期参考

---

优先级建议

方案	难度	解决的问题
B：托盘图标动画	低	capsule 反馈替代
A：全屏检测 + 降级	中	capsule 替代（主因）
D：游戏模式设置	中	完整体验替代
C：Toast 通知	中	识别结果展示替代
E：提权运行	零代码	热键不触发（次因）
F：DirectX Overlay	极高	完整 capsule 显示

短期内最有价值的组合是 A + B（检测到全屏时自动降级为托盘指示）+ 文档说明 用户切到无边框窗口或启用游戏模式。