故障排查

在使用 Lertaro 的过程中遇到问题？请按照以下步骤逐步排查常见故障原因。

1. 全局热键没有反应

• 检查后台服务运行状态：进入设置 → 运行状态，确认 Lertaro.Service 处于“运行中”。虽然普通热键由 App 处理，但提权挂钩进程依赖后台服务拉起。
• 管理员权限隔离（UIPI）：若当前前台活动窗口是以管理员身份运行的（例如以管理员打开的终端或任务管理器），Windows 系统的安全机制（UIPI）会阻止低权限进程向高权限窗口发送热键。Lertaro 会自动尝试提权热键监听进程；若仍无响应，请确保后台服务处于正常运行状态。
• 检查进程黑名单：在设置 → 热键中检查当前前台程序是否被列入了“进程黑名单”。处于黑名单中的程序在前台时，Lertaro 会主动放行按键不做拦截。
• 全屏游戏/独占应用放行：当检测到前台有独占全屏应用程序（如 3D 游戏、全屏播放器）时，Lertaro 默认会自动放行热键以防干扰操作。如果你希望在全屏下依然能够呼出搜索框，请在设置 → 热键中勾选全屏应用聚焦时仍然响应。

2. 搜索结果未更新或过时

• 本地 NTFS / ReFS 磁盘：Lertaro 通过读取底层 USN 变更日志实现近乎零延迟的毫秒级实时更新。
• FAT32 / exFAT 磁盘：通过系统文件变更事件持续监听。
• 手动重建索引：若由于系统意外断电等原因导致索引不一致，请前往设置 → 索引 → 本地驱动器，在对应的磁盘上点击重建索引即可重新生成干净的内存索引。

3. 网络驱动器未自动刷新

• 定时扫描机制：网络共享（SMB / NAS）没有本地 NTFS 卷的底层变更日志，因此依赖定时轮询机制。
• 检查刷新模式：在设置 → 索引 → 网络驱动器中检查该驱动器的刷新模式是否被误设为了“手动”；若设为手动，必须点击“重建索引”或改为定时刷新。
• 符号链接环路保护：对于 NAS 共享中可能存在的递归符号链接，Lertaro 内置了环路检测引擎，会自动跳过死循环目录。

4. 某个文件或文件夹完全搜不到

• 检查排除规则：进入设置 → 索引 → 排除规则，确认目标文件路径是否被精确路径、Glob 通配符或正则表达式规则意外命中。
• 检查磁盘启用状态：在设置 → 索引 → 本地驱动器中确认该文件所在的物理驱动器或目录是否处于开启状态。

5. 内联窗口中中文输入法候选框未弹出

• 无焦点设计原理：内嵌窗口为了在关闭后无缝将焦点归还给宿主软件，特意采用了非侵入式无焦点设计。输入法候选框依赖 Windows 真实键盘焦点，因此在内联窗口中可能不显示候选浮窗。
• 推荐解决方案：
  1. 直接打拼音：Lertaro 内置了强大的拼音别名引擎，直接输入拼音字母即可跳跃命中中文文件名（详见搜索语法），无需调用输入法候选框。
  2. 切换为快速窗口：按下双击 Ctrl 唤出拥有完整焦点的快速窗口，即可正常使用任何输入法。

6. 日志查看与提交 Issue

若上述步骤均未能解决你的问题，请进入设置 → 运行状态查看详细的运行日志：

• Service 日志：记录后台索引服务、USN 日志读取、网络盘扫描与 IPC 通信状态。
• App 日志：记录前台 UI 渲染、插件加载、快捷键响应与配置变动。
• Hook 日志：记录全局键盘钩子与鼠标导航手势的事件流。

你可以在日志面板中使用搜索框过滤关键词，或按日志等级（Info / Warn / Error）快速定位异常堆栈，并在 GitHub 提交 Issue 时附上相关日志以便快速定位。