docs: 记录阶段 0C 基线与 IME 双时机定位结论

2026-10-06 02:50:09 +08:00
parent 43cf4ac5f7
commit e514a7dbb9
4 changed files with 322 additions and 19 deletions
@@ -0,0 +1,56 @@
+# BUG-20261006-0001
+
+> 适用场景：记录问题本身，不展开完整修复方案。修复内容写入对应的 Fix 文档。
+
+## 基本信息
+
+- ID: BUG-20261006-0001
+- 标题: 搜狗未发送 IME 组合生命周期消息时，候选框未按当前锚点预定位
+- 状态：已验证
+- 严重性：S3
+- 优先级：P1
+- 模块: 阶段 0C / IME 坐标探测 / IMM32
+- 版本 / 分支: `master`；发现基线为 `225bc35` 加开发中的 0C 探测实现，最终收口于 `43cf4ac`
+- 环境: Windows 11 `10.0.22000`、EasyX `25.9.10`、DPI-unaware 虚拟化视图 96 DPI、搜狗拼音
+- 发现人: 用户真实搜狗输入法人工探测
+- 关联 Fix ID: Fix-BUG-20261006-0001
+
+## 问题描述
+
+- 现象: EasyX 探测窗口刚打开时，在 F1/F2 锚点直接输入 `ceshi`，搜狗候选框出现在窗口外的默认位置；首次提交后，候选框只在 F3 附近获得定位，之后切换 F1/F2/F3 仍可能沿用 F3 的旧位置。
+- 影响范围: 阶段 0C-3 无法正确验证搜狗候选框定位；若生产输入系统只在 `WM_IME_STARTCOMPOSITION/WM_IME_COMPOSITION` 中设置位置，会复现同类 stale-position 问题。
+- 期望结果: F1/F2/F3 任一锚点被选中后，在下一次输入开始前就把组合窗口和候选窗口位置写入当前 HWND 的 IME context；IME 生命周期消息到达时再校准一次。
+- 实际结果: 非组合态切换锚点只更新内部索引和画面，不调用 `ImmSetCompositionWindow/ImmSetCandidateWindow`。
+
+## 复现信息
+
+- 前置条件: 使用搜狗拼音运行 `scripts/run-visual-probe.ps1 -Mode ime-position -ImeName Sogou`。
+- 复现步骤:
+
+1. 启动探测窗口并确认搜狗拼音处于活动状态。
+2. 按 F1，输入固定串 `ceshi`，观察候选框位于窗口外的默认位置。
+3. 按 Escape 取消，按 F2 重复，仍观察到默认位置。
+4. 在候选框中按 Space 提交一次，再切换锚点输入；候选框停留在 F3 附近。
+5. 关闭窗口，检查 manifest 与 raw event sequence。
+
+- 复现概率：本次人工测试稳定复现
+- 最小复现 Demo：`EasyX.VisualProbe.exe --mode ime-position --ime-name Sogou`
+- 证据：`TestResults/VisualProbe/20261005-235150-704-4e01df99-019b-41bd-b8ea-b2ff508626e0/ime-position`。
+
+## 初步分析
+
+- 疑似位置: `tests/visual-probe/ImePositionProbe.cpp` 的 F1/F2/F3 `WM_KEYDOWN` 分支。
+- 触发条件: 输入法已经显示候选 UI，但没有向被子类化的 EasyX HWND 发送探测器所依赖的 `WM_IME_STARTCOMPOSITION/WM_IME_COMPOSITION`。
+- 关键证据:
+  - F1 `apiAttemptCount=0`，F2 `apiAttemptCount=0`，F3 `apiAttemptCount=2` 且两次成功。
+  - 原始事件序列中，F1/F2 只有 `anchor_change`；直到 F3 才出现 `ime_start -> ime_composition -> ime_end`。
+  - F1/F2 截图显示候选框在窗口外，F3 截图显示候选框位于最后一次成功设置的位置附近。
+- 根因边界: 这不是 DPI 换算错误；F3 的 IMM 调用和坐标值成功。问题是位置设置触发得太晚，并错误假定所有 IME 都会先向目标 HWND 发送同一组生命周期消息。
+
+## 跟踪信息
+
+- 首次发现时间: 2026-10-05 23:51（人工运行），2026-10-06 完成归档与定位
+- 最后更新时间: 2026-10-06
+- 修复版本: `43cf4ac`（阶段 0C 视觉与 IME 坐标探测）
+- 验证版本: 三平台构建与单元测试通过；搜狗真实输入复验自动与人工状态均为 `pass`
+- 备注: `-ImeName` 只记录操作者预期，当前 HKL/IMM32 身份字段不能自动证明 TSF 输入配置文件；成功复验的实际搜狗身份由操作者确认并写入人工评审旁车。