fix: 🐛 解决 MouseTracker 断言错误及高负载交互下的 GUI 线程卡顿

修复 MouseTracker 冲突：将右键快捷菜单（showMenu）由同步调用改为 Future.microtask 异步触发，防止 UI 覆层变更干扰当前手势命中测试循环（解决 !_debugDuringDeviceUpdate 报错）。 全局稳定性加固：同步优化了主页分类菜单、快捷方式卡片以及详情侧边的交互回调，确保底层硬件事件与 UI 重绘解耦。 性能优化：移除了密集列表中的 GlobalObjectKey 负担，改用 ValueKey 并完善了现代 KeyEvent 处理逻辑。

Author: sqmw

docs/framework_stability_fix.md

@@ -0,0 +1,48 @@
+# 框架稳定性与断言异常修复
+
+在文件管理功能的深度集成过程中，我们遇到了几类涉及 Flutter 框架层面的断言异常（Assertion Failure）。这些异常主要集中在 `MouseTracker` 和 `RenderBox` 的布局状态检测上，通常表现为应用在频繁点击、滚动或右键菜单交互时崩溃。
+
+## 核心问题分析
+
+### 1. MouseTracker 状态冲突 (`!_debugDuringDeviceUpdate`)
+**异常现象**：`Failed assertion: line 199 pos 12: '!_debugDuringDeviceUpdate': is not true.`
+**原因分析**：
+该异常发生在 `MouseTracker` 正在处理设备更新（如鼠标移动）时，又同步触发了另一次设备更新。在我们的应用中，这是由于在同步的 `onSecondaryTapDown`（右键点击）直接调用了 `showMenu`，导致 `Overlay` 同步插入并可能立即触发焦点变化或新的布局测试，从而干扰了正在进行的鼠标状态追踪循环。
+
+### 2. RenderBox 布局异常 (`Cannot hit test a render box that has never been laid out`)
+**异常现象**：命中测试（Hit Testing）路径中包含尚未完成布局的组件。
+**原因分析**：
+- **GlobalObjectKey 过重**：在海量列表项中使用 `GlobalObjectKey` 会显著增加布局负担。当列表快速刷新或过滤时，旧的定位锚点可能在下一帧布局前被命中测试系统尝试访问。
+- **同步 UI 更新**：在手势回调中同步触发重大的 UI 结构变动（如打开菜单或切换面板），可能导致当前的命中测试路径指向已失效或未初始化的 RenderBox。
+
+---
+
+## 解决方案
+
+### 1. 异步触发 Context Menu (Future.microtask)
+为了确保 Overlay 的弹出不干扰手势处理循环，我们将所有页面（`AllPage`, `FilePage`, `FolderPage`）中的快捷菜单显示逻辑进行了 microtask 封装：
+
+```dart
+onSecondaryTapDown: (details) {
+  // 使用 microtask 确保离开当前的手势/命中测试堆栈后执行
+  Future.microtask(() async {
+    if (!mounted) return;
+    final result = await showMenu(...);
+    // 处理结果...
+  });
+}
+```
+
+### 2. 优化列表 Key 管理 (ValueKey)
+移除了 `AllPage` 列表项中不必要的 `GlobalObjectKey`，统一改用轻量级的 `ValueKey(entity.path)`。
+- **优势**：减少了全局 Key 注册表维护开销，稳定了列表项在动态过滤和排序时的布局语义，消除了 layout-during-hit-test 的隐患。
+
+### 3. 下一代键盘事件 API 迁移 (KeyEvent)
+将原有的 `RawKeyboard` 监听完全迁移至现代化的 `HardwareKeyboard` 和 `KeyEvent` API（`KeyDownEvent`, `KeyUpEvent`）。
+- **逻辑增强**：统一了对 Ctrl、Delete 等修饰键和功能键的处理逻辑。
+- **健壮性**：不仅通过事件流判断按键，还通过 `isLogicalKeyPressed` 进行辅助状态校验，彻底解决了“按键状态不同步”导致的 Services 断言失败。
+
+---
+
+## 验证与稳定性提升
+经过上述调整，应用在高频右键、快速滚动以及 Ctrl+C/V 等快捷操作下的稳定性得到了极大提升， terminal 中不再出现 `MouseTracker` 或 `RenderBox` 相关的断言报错。

docs/overview.md

@@ -38,4 +38,5 @@
 ## 运行与工具
 - 开发运行：`fvm flutter pub get`，`fvm flutter run -d windows`。  
 - 代码行统计：`fvm dart run bin/count_lib_loc.dart`。  
+- 框架稳定性：解决了 `MouseTracker` 和 `RenderBox` 相关的断言异常，详见 `docs/framework_stability_fix.md`。
 - 单实例与更新机制详见 `docs/single_instance.md`、`docs/update_service.md`。