# SL5 Aura 故障排除

## 快速诊断

始终从这里开始：

__代码_块_0__

---

## 问题：Aura 无法启动

**症状：** 无启动声音，`pgrep` 中看不到进程。

**检查日志：**
__代码_块_1__

**常见原因：**

|日志中的错误 |修复 |
|---|---|
| `模块未找到错误` |再次运行安装脚本：`bash setup/manjaro_arch_setup.sh` |
| `没有名为'objgraph'的模块` | `.venv` 已重新创建 — 重新安装：`pip install -rrequirements.txt` |
| `地址已被使用` |终止旧进程：`pkill -9 -f aura_engine` |
| `找不到模型` |重新运行安装程序以下载丢失的模型 |
| `pygame.mixer 不可用` |请参阅下面的“启动时没有声音”|

---

## 问题：启动时没有声音（pygame.mixer）

**症状：** 有关“pygame.mixer”不可用的警告或错误。光环开始
但不播放任何声音。

**原因：** 您系统的 pygame 版本不包含音频支持或 SDL2
音频库丢失。

**修复 Arch/Manjaro：**
__代码_块_2__

**在 Ubuntu/Debian 上修复：**
__代码_块_3__

Aura 将在没有声音的情况下继续工作 — 这不是致命错误。

---

## 问题：首次听写后 Aura 崩溃

**症状：** 工作一次，然后悄无声息地消失。

**检查标准错误：**
__代码_块_4__

**如果您看到“分段错误”或“双重释放”：**

这是 glibc 2.43+（CachyOS、较新的 Arch）系统上的一个已知问题。

__代码_块_5__

如果安装了mimalloc，启动脚本会自动使用它。确认它处于活动状态 - 您应该在启动时看到以下内容：
__代码_块_6__

---

## 问题：触发键不起作用

**症状：** 您按下热键但没有任何反应 - 没有声音，没有文本。

**检查文件观察器是否正在运行：**
__代码_块_7__

如果没有出现任何内容，请重新启动 Aura：
__代码_块_8__

**检查是否正在创建触发器文件：**
__代码_块_9__

如果该文件从未创建，则您的热键不起作用 - 见下文。

---

## 问题：热键在 Wayland 上不起作用

**症状：** CopyQ 已安装并配置，但按热键却不起作用
Wayland 会话中没有任何内容。

**原因：** CopyQ 全局热键在 Wayland 上无法可靠工作，无需
额外的配置。这会影响 KDE Plasma、GNOME 和其他
韦兰合成器。

### 选项 1：KDE 系统设置（推荐用于 KDE Plasma）

1. 打开**系统设置→快捷方式→自定义快捷方式**
2. 创建 **Command/URL** 类型的新快捷方式
3. 将命令设置为：
__代码_块_10__
4. 指定您喜欢的组合键（例如“F9”或“Ctrl+Alt+Space”）

### 选项 2：dotool（适用于任何 Wayland 合成器）

__代码_块_11__

然后使用桌面的快捷方式管理器运行：
__代码_块_12__

### 选项 3：ydotool

__代码_块_13__

然后配置您的快捷方式来运行：
__代码_块_14__

### 选项 4：GNOME（使用 dconf / GNOME 设置）

1. 打开 **设置 → 键盘 → 自定义快捷键**
2. 使用命令添加新的快捷方式：
__代码_块_15__
3. 指定组合键

### 选项 5：CopyQ 与 Wayland 修复

如果以以下方式启动，某些 Wayland 合成器允许 CopyQ 工作：
__代码_块_16__

这迫使 CopyQ 使用支持全局热键的 XWayland。

---

## 问题：文本出现但没有更正

**症状：** 听写可以工作，但所有内容都保持小写，没有语法修复。

**检查LanguageTool是否正在运行：**
__代码_块_17__

如果返回错误，则 LanguageTool 未运行。光环应该启动它
自动 — 检查日志中是否有与 LanguageTool 相关的错误：

__代码_块_18__

**检查LanguageTool日志：**
__代码_块_19__

---

## 问题：Aura 在 DEV_MODE 中挂起

**症状：** 当“DEV_MODE = 1”时，Aura 在第一次触发后挂起并停止
回应。

**原因：** 来自多个线程的高日志量会导致日志系统超载。

**修复：** 在`config/filters/settings_local_log_filter.py`中添加日志过滤器：

__代码_块_20__

保存文件 - Aura 自动重新加载过滤器。无需重新启动。

---

## 问题：plugins.zip 无限增长/CPU 占用过高

**症状：** CPU 100%，风扇全速运转，`plugins.zip`不断增长。

**原因：** 安全打包程序正在无限循环中重新打包文件。

**修复：** 确保“.blob”和“.zip”文件从时间戳扫描中排除。
检查第 86 行附近的 `scripts/py/func/secure_packer_lib.py`：

__代码_块_21__

如果缺少此行，请添加它。

---

## 问题：规则未触发

**症状：** 您口述触发短语，但规则不执行任何操作。

**清单：**

1. 规则是否位于正确的文件中？ (`FUZZY_MAP_pre.py` = 在 LanguageTool 之前，
`FUZZY_MAP.py` = 之后）
2. 地图文件是否保存？保存时 Aura 会重新加载 — 检查日志
‘重新加载成功’。
3. 该模式与 Vosk 实际转录的内容相符吗？检查日志
原始转录：
__代码_块_22__
4. 是否设置了“only_in_windows”并且激活了错误的窗口？
5. 是否先匹配更通用的规则？规则是从上到下处理的 -
将具体规则放在一般规则之前。

---

## 收集错误报告日志

报告问题时，请包括：

__代码_块_23__

发布至：[GitHub Issues](https://github.com/sl5net/SL5-aura-service/issues)