StellarX-kaifa/开发记录/Fix/Fix-BUG-20261006-0002-阶段0B固定锚点原生键规则与无丢失采集修复.md

Fix-BUG-20261006-0002

适用场景：记录某个 BUG 的修复方案、影响评估、验证结果与落地信息。

关联信息

• Fix ID: Fix-BUG-20261006-0002
• 关联 BUG ID: BUG-20261006-0002
• 修复目标: 让阶段 0B 的真实 IME 实验具备可比较的位置基线、可命中的原生键规则和不因状态锁竞争主动丢记录的采集路径
• 状态：验证完成
• 负责人: Codex
• 分支 / 版本: master，未提交工作区

根因分析

• 根因 1: 0B 复用了只显示说明文字的 UiFixture 场景，没有把 0C 已验证的 caret point/line rect 写入当前 HWND 的 IME context。
• 根因 2: 规则按操作者语义配置为 VK_ESCAPE，但 IME 在 WndProc 前已处理组合态 KeyDown，窗口实际收到 VK_PROCESSKEY；scan code 1 才保留了本轮 Escape 的物理区分信息。
• 根因 3: 单环形缓冲在 safe-point 持锁复制，WndProc 为避免等待使用 TryAcquireSRWLockExclusive；宿主复制期间到达的原生消息会被主动丢弃。

修复方案

• 修复思路: 保持 0B 动作枚举只有 Forward/Consume 两值，仅修正诊断输入、位置基线和采集完整性，不新增生产路由行为。
• 关键改动:
  • 0B 人工 runner 固定窗口为 720×420，传入客户区 caret (225,282) 与 line rect (200,255)-(680,284)。
  • UiFixture 绘制与上述数值一致的 line region 和 caret marker，便于操作者判断候选 UI 是否仍落在窗口外。
  • 在 WM_SETFOCUS、WM_IME_SETCONTEXT、WM_IME_STARTCOMPOSITION、WM_IME_COMPOSITION 观察点准备定位请求；锁外调用 CFS_POINT composition setter 与 CFS_EXCLUDE candidate setter，通过独立 ime_position 记录保存 context、两个 API 结果和坐标。
  • Composition 请求 Consume 时，如果尚无一次两个 setter 同时成功的证据，立即 fail-open 为 ime_position_unavailable。
  • 规则新增可选 scanCode。自动 F24 仍使用 any；人工 Escape 默认使用 WM_KEYDOWN + VK_PROCESSKEY(229) + scanCode 1 + ComposingOnly，界面指令仍要求操作者按 Escape。
  • 分析器在指定 scan code 时同时过滤 WndProc 与 EasyX EX_KEY，并输出位置尝试/成功计数和 imePositionReady。
  • 记录缓冲改为两个固定数组；safe-point 在锁内只交换 active buffer 和重置索引，文件写入在锁外完成。WndProc 使用极短阻塞临界区，不再因 try-lock 失败丢弃记录。
• 涉及文件 / 类 / 函数:
  • src/StellarX/SxInputProbe.cpp
  • tests/UiFixture.cpp
  • scripts/run-input-consume-probe.ps1
  • scripts/run-input-consume-probe-manual.ps1
  • scripts/analyze-input-probe.ps1
• 影响的 API / 行为: 仅 STELLARX_ENABLE_INPUT_PROBE 且显式开启 0B 的诊断路径；公共 API 与默认生产窗口行为不变。
• 回滚点 / 开关: 不设置 STELLARX_INPUT_PROBE_0B 时不装载规则、不调用固定位置逻辑；默认构建不包含探测实现。

影响评估

• 正确性: scan code 消除同一 VK_PROCESSKEY 下字母、方向、Escape 等多类组合键的歧义；固定位置成功门槛防止把夹具定位失败算成消费副作用。
• 并发: 双缓冲消除宿主批量复制对 WndProc 的长时间占锁；文件写锁仍串行化多个 flush，状态锁序保持“文件写锁 → 状态锁”。
• 性能: WndProc 每条被观察消息增加一次短阻塞状态锁；Composition 生命周期增加有限的 IMM32 setter。两者只存在于诊断构建。
• 风险:
  • 某些 IME 即使 setter 返回成功也可能自行调整候选 UI，因此仍需人工视觉确认。
  • WndProc 阻塞临界区要求 safe-point 严禁在状态锁内做文件 I/O 或整批复制；后续维护若破坏此不变量可能重新引入卡顿。
  • 首次人工复验发现持状态锁调用 IMM32 setter 会因同步重入 WndProc 自锁；已拆分为“锁内请求 → 锁外调用 → 锁内结果”并增加线程内递归定位保护，详见 Fix-BUG-20261006-0003。
  • VK_PROCESSKEY + scanCode 1 是当前环境观察到的原生 Escape 形态，不得未经新证据外推到全部 IME/键盘布局。

验证结果

• 已完成:
  • Debug x64 探测构建完成编译与链接；仅有 EasyX 头文件既有 C4201 警告。
  • 失败截图已复制到对应忽略运行目录并记录 SHA-256。
  • 默认 Debug x64 单元测试 15/15 通过。
  • Windows PowerShell 5.1.22000.2538 与 PowerShell 7.6.5 对三份 0B 脚本均为 0 个 AST 解析错误。
  • git diff --check 通过，仅输出仓库换行规范提示。
  • 新分析器重放既有有效 F24 KeyDown A/B：Forward 仍为 valid/present_once，Consume 仍为 valid/absent，兼容未携带 targetScanCode 的既有 schema v2 日志。
  • BUG-20261006-0003 修复后的微软拼音 Forward 人工复验为 valid：Escape 原生规则唯一命中并转发，18/18 次定位成功、零孤立结果、零丢失，人工截图确认候选 UI 位于固定锚点附近。
  • 微软拼音 Consume 有效重跑为 valid：Escape 唯一命中并消费，旧过程未调用，对应 EasyX 键消失；7/7 次定位成功、零孤立结果、零丢失且无提交结果。
  • 搜狗 Forward 运行确认候选 UI 可见且位置正常，但目标 HWND 未出现 START/COMPOSITION/END；Escape 到达时 tracked state 仍为 Idle，ComposingOnly 零命中，定位 6/6、零丢失、收口完整。
  • 搜狗最终 Consume 请求按 ime_condition_not_met 正确运行时 fail-open：experimentValidity=runtime_fail_open、零消费、实际 Forward 一次、EasyX 键出现一次、定位 3/3、零丢失，最终 verdict 为 MustForward。
  • 2026-10-07 默认 Debug x64 单元测试 15/15、UI fixture 1 轮和 F24 KeyDown A/B 新运行通过；既有 KeyUp 与 baseline mismatch 证据经当前分析器回放保持有效。
• 当前工具环境限制: 自动 F24 runner 已完成构建并打开夹具，但 Codex 非交互工具宿主无法把窗口切到前台，ClickWindowForActivation 在发键前失败；该运行没有形成新的 A/B 结论，不记为代码失败，也不覆盖既有有效证据。
• 首次微软拼音复验边界: 旧定位实现导致窗口未响应，失败运行保留于 TestResults/InputProbe/0B/20261006-231604-636-4bc775a1-a3f8-41b9-b466-1cce740bc195/forward；该运行只证明诊断死锁，不用于评价 Forward 或微软拼音。
• 验证边界: 自动 SendInput 不能替代真实 IME；搜狗不能被要求“规则唯一命中”，因为缺少可证明 Composition 状态时正确行为就是零命中并 fail-open。该 Fix 以固定定位链、原生键观察、零丢失和明确 MustForward 结论关闭，不把运行时 Forward 伪装成 Consume。

落地信息

• Commit: 待验证与用户确认后提交
• PR：无
• 发布版本：未发布
• 备注: 本修复不进入阶段 1，不实现 FocusManager、生产 InputCollector 或键盘路由。