故障排除

本文提供 HeurAMS 常见问题的解决方案和调试方法.

快速诊断

遇到问题时, 请按以下步骤诊断：

查看日志文件：heurams.log 包含详细错误信息
检查配置文件：config/config.toml 语法是否正确
验证数据目录：data/ 目录结构是否完整
测试简化场景：使用最小配置重现问题

安装问题

"ModuleNotFoundError: No module named '...'"

问题：缺少Python依赖包.

解决方案：

bash

# 确保在正确目录
cd /path/to/HeurAMS

# 安装所有依赖
pip install -r requirements.txt

# 如果仍有问题, 尝试升级pip
pip install --upgrade pip

# 或使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 venv\Scripts\activate  # Windows
pip install -r requirements.txt

音频相关错误

问题：播放音频时出错或无声.

解决方案：

Windows：

确保系统音频服务正常运行
检查默认播放设备
安装必要的编解码器

Linux：

bash

# 安装系统音频库
sudo apt install alsa-utils pulseaudio  # Debian/Ubuntu
sudo dnf install alsa-lib pulseaudio   # Fedora

macOS：

通常无需额外配置. 检查系统声音设置.

Android (Termux)：

bash

pkg install termux-api
# 授予音频权限
termux-microphone-record

TTS 服务连接失败

问题：Edge TTS 无法连接或超时.

解决方案：

检查网络连接
验证代理设置（如有）

尝试更换语音：

toml

[providers.tts.edgetts]
voice = "zh-CN-XiaoyiNeural"  # 尝试其他语音

临时禁用 TTS：
toml
```
[services]
tts = ""  # 留空禁用
```

运行时问题

应用无法启动

错误信息：ImportError、AttributeError 或启动即崩溃.

解决方案：

检查Python版本：
bash
```
python --version  # 需要 3.8+
```

验证安装：

bash

python -c "import heurams; print(heurams.__version__)"

清理缓存：

bash

rm -rf __pycache__ src/heurams/__pycache__

重新安装：
bash
```
pip install -e . --force-reinstall
```

数据文件损坏

问题：TOML 或 JSON 文件语法错误.

解决方案：

验证 TOML 语法：

bash

python -c "import toml; toml.load('data/nucleon/file.toml')"

备份并修复：

bash

# 备份损坏文件
cp data/nucleon/file.toml data/nucleon/file.toml.bak

# 尝试手动修复或使用工具
python -m heurams.tools.validate_data

使用默认配置：

bash

rm config/config.toml
# 重启应用生成新配置

内存不足

问题：处理大量内容时内存占用过高.

解决方案：

启用惰性加载（默认已启用）

分批处理：

bash

# 使用工具分批导入
python -m heurams.tools.import_csv large.csv --batch-size 100

增加系统交换空间（Linux）：

bash

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

配置问题

配置不生效

问题：修改 config.toml 后应用行为不变.

解决方案：

检查文件位置：

bash

# 确认在当前工作目录
pwd
ls -la config/config.toml

验证语法：

bash

python -c "import toml; toml.load('config/config.toml')"

清除配置缓存：

bash

rm -rf data/cache/config_*.pickle  # 如果有

使用环境变量覆盖：

bash

export HEURAMS_CONFIG_PATH="/absolute/path/to/config.toml"

路径问题

问题：找不到数据文件或目录.

解决方案：

使用绝对路径：

toml

[paths]
nucleon_dir = "/home/user/heurams/data/nucleon"

检查权限：

bash

ls -la data/
chmod 755 data/  # 确保可读可执行
chmod 644 data/*/*  # 确保文件可读

创建缺失目录：

bash

mkdir -p data/{nucleon,electron,orbital,cache,template}

功能问题

复习队列异常

问题：没有内容显示或显示错误内容.

解决方案：

检查日期设置：

toml

# config/config.toml
daystamp_override = -1  # 禁用日期覆盖

验证内容状态：

bash

# 查看哪些内容到期
python -m heurams.tools.list_due

重置算法状态（谨慎使用）：

bash

# 备份后重置
cp -r data/electron data/electron.backup
rm data/electron/*.json

模板不生效

问题：自定义模板无法加载或使用.

解决方案：

检查模板位置：
bash
```
ls data/template/*.toml
```

验证模板语法：

bash

python -m heurams.tools.validate_template data/template/mytemplate.toml

清除模板缓存：
bash
```
rm -rf data/cache/template_*.pickle
```

宏无法解析

问题：占位符未被替换.

解决方案：

启用宏系统：
toml
```
[macros]
enable = true
```
检查宏名称：确保使用内置宏或已注册的宏
查看解析日志：
bash
```
grep -i "macro" heurams.log | tail -20
```

性能问题

启动缓慢

问题：应用启动时间过长.

解决方案：

减少初始加载内容：

toml

scheduled_num = 5  # 减少每日新内容数量

优化数据目录：
- 删除不需要的内容文件
- 将内容分到多个子目录
- 归档已掌握的内容

禁用调试日志：

toml

# 设置更高的日志级别
# 需在代码中配置, 或通过环境变量
export HEURAMS_LOG_LEVEL=WARNING

复习卡顿

问题：复习界面响应缓慢.

解决方案：

减少同时加载的内容：

toml

[puzzles.mcq]
max_riddles_num = 2  # 减少选择题干扰项

禁用动画：

toml

[interface]
animation_speed = 0  # 禁用动画

清理缓存：

bash

python -m heurams.tools.clean_cache --all

网络与外部服务

API 密钥问题

问题：LLM 或其他外部服务认证失败.

解决方案：

验证密钥格式：

toml

[providers.llm.openai]
key = "sk-..."  # 确保正确, 无多余空格

使用环境变量（更安全）：

bash

export OPENAI_API_KEY="sk-..."
# 然后在配置中留空或使用变量引用

检查配额和权限：确保 API 密钥有效且有足够配额

代理配置

问题：无法访问外部服务（如 TTS、LLM）.

解决方案：

系统代理：配置系统级代理

应用特定（如果支持）：

toml

[network]
proxy = "http://proxy.example.com:8080"

离线模式：禁用需要网络的功能

平台特定问题

Windows 问题

终端编码

问题：中文显示乱码.

解决方案：

使用 Windows Terminal 或 PowerShell

设置编码为 UTF-8：

powershell

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

使用支持中文的字体（如 "Microsoft YaHei Mono"）

路径长度限制

问题：路径过长导致文件操作失败.

解决方案：

使用较短的工作目录路径
启用 Windows 长路径支持（组策略）

Linux 问题

权限问题

问题：无法写入数据目录.

解决方案：

bash

# 检查当前用户权限
whoami
ls -la data/

# 修复权限
chown -R $USER:$USER data/
chmod 755 data/

系统依赖

问题：缺少系统库.

解决方案：

bash

# Debian/Ubuntu
sudo apt install python3-dev build-essential

# Fedora
sudo dnf install python3-devel gcc

macOS 问题

权限提示

问题：应用被 Gatekeeper 阻止.

解决方案：

右键点击 → "打开"

或在终端中：

bash

xattr -d com.apple.quarantine /path/to/app

音频问题

问题：没有声音或权限错误.

解决方案：

系统偏好设置 → 安全性与隐私 → 麦克风/音频
授予终端或 Python 音频权限

Android (Termux) 问题

存储权限

问题：无法访问外部存储.

解决方案：

bash

termux-setup-storage
# 在/data/data/com.termux/files/home/storage 创建符号链接

后台运行

问题：应用在后台被终止.

解决方案：

bash

# 使用 termux-wake-lock
pkg install termux-services
sv-enable termux-wake-lock

日志分析

日志位置

主日志：heurams.log（工作目录）
系统日志：/var/log/syslog（Linux）或事件查看器（Windows）

常见错误信息

"TOMLDecodeError"

bash

# 查找有问题的文件
grep -l "TOMLDecodeError" heurams.log
# 然后检查该文件的 TOML 语法

"FileNotFoundError"

bash

# 查看缺失的文件
grep "FileNotFoundError" heurams.log | awk '{print $NF}'

"PermissionError"

bash

# 检查文件和目录权限
grep "PermissionError" heurams.log
ls -la $(grep "PermissionError" heurams.log | awk '{print $NF}')

启用详细日志

临时启用调试日志：

bash

# 环境变量方式
export HEURAMS_LOG_LEVEL=DEBUG
python -m heurams.interface

# 或修改配置
echo 'log_level = "DEBUG"' >> config/config.toml

数据恢复

备份策略

定期备份：

bash

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/heurams_$DATE"
mkdir -p "$BACKUP_DIR"
cp -r data config heurams.log "$BACKUP_DIR/"
echo "Backup saved to: $BACKUP_DIR"

恢复步骤

停止应用：确保没有正在运行的实例

恢复文件：

bash

cp -r /backup/heurams_20251218/data .
cp /backup/heurams_20251218/config/config.toml config/

验证恢复：
bash
```
python -m heurams.tools.validate_data
```

部分恢复

如果只有部分文件损坏：

bash

# 恢复单个 Nucleon
cp backup/data/nucleon/important.toml data/nucleon/

# 恢复算法状态
cp backup/data/electron/item.json data/electron/

寻求帮助

如果以上方法无法解决问题：

收集信息

日志文件：heurams.log
配置信息：config/config.toml（移除敏感信息）

系统信息：

bash

python --version
uname -a  # Linux/macOS
# 或 systeminfo | findstr /B /C:"OS"  # Windows

问题描述：详细的重现步骤

报告渠道

项目仓库：Issue 页面
社区讨论：相关论坛或聊天群组
文档更新：如果发现本文档缺失, 欢迎补充

提供最小重现

创建最小测试用例：

bash

mkdir test_problem
cd test_problem
# 最小配置和内容文件
# 描述重现步骤

故障排除 ​

快速诊断 ​

安装问题 ​

"ModuleNotFoundError: No module named '...'" ​

音频相关错误 ​

Windows： ​

Linux： ​

macOS： ​

Android (Termux)： ​

TTS 服务连接失败 ​

运行时问题 ​

应用无法启动 ​

数据文件损坏 ​

内存不足 ​

配置问题 ​

配置不生效 ​

路径问题 ​

功能问题 ​

复习队列异常 ​

模板不生效 ​

宏无法解析 ​

性能问题 ​

启动缓慢 ​

复习卡顿 ​

网络与外部服务 ​

API 密钥问题 ​

代理配置 ​

平台特定问题 ​

Windows 问题 ​

终端编码 ​

路径长度限制 ​

Linux 问题 ​

权限问题 ​

系统依赖 ​

macOS 问题 ​

权限提示 ​

音频问题 ​

Android (Termux) 问题 ​

存储权限 ​

后台运行 ​

日志分析 ​

日志位置 ​

常见错误信息 ​

"TOMLDecodeError" ​

"FileNotFoundError" ​

"PermissionError" ​

启用详细日志 ​

数据恢复 ​

备份策略 ​

恢复步骤 ​

部分恢复 ​

寻求帮助 ​

收集信息 ​

报告渠道 ​

提供最小重现 ​

预防措施 ​

定期维护 ​

监控建议 ​

故障排除

快速诊断

安装问题

"ModuleNotFoundError: No module named '...'"

音频相关错误

Windows：

Linux：

macOS：

Android (Termux)：

TTS 服务连接失败

运行时问题

应用无法启动

数据文件损坏

内存不足

配置问题

配置不生效

路径问题

功能问题

复习队列异常

模板不生效

宏无法解析

性能问题

启动缓慢

复习卡顿

网络与外部服务

API 密钥问题

代理配置

平台特定问题

Windows 问题

终端编码

路径长度限制

Linux 问题

权限问题

系统依赖

macOS 问题

权限提示

音频问题

Android (Termux) 问题

存储权限

后台运行

日志分析

日志位置

常见错误信息

"TOMLDecodeError"

"FileNotFoundError"

"PermissionError"

启用详细日志

数据恢复

备份策略

恢复步骤

部分恢复

寻求帮助

收集信息

报告渠道

提供最小重现

预防措施

定期维护

监控建议