配置选项

本文详细介绍 HeurAMS 的所有配置选项, 包括算法参数、界面设置、服务集成等.

配置文件位置

默认配置

• 位置：src/heurams/default/config/config.toml
• 作用：内置默认值, 不应修改

用户配置

• 位置：工作目录/config/config.toml
• 作用：用户自定义设置, 优先级高于默认配置
• 生成：首次运行时自动创建, 或手动创建

配置优先级

1. 运行时参数（命令行）
2. 用户配置文件
3. 默认配置文件

配置结构总览

# 调试选项
persist_to_file = 1
daystamp_override = -1
quick_pass = 1

# 学习设置
scheduled_num = 8
timezone_offset = +28800

# 路径设置
[paths]
nucleon_dir = "./data/nucleon"
electron_dir = "./data/electron"

# 服务配置
[services]
audio = "playsound"
tts = "edgetts"

# 算法配置
[algorithm.sm2]
initial_interval = 1

# 谜题配置
[puzzles.mcq]
max_riddles_num = 2

调试选项

persist_to_file

• 类型：整数 (0/1)
• 默认：1
• 说明：是否将更改保存到文件. 0=仅内存, 1=保存到磁盘.

daystamp_override / timestamp_override

• 类型：整数
• 默认：-1
• 说明：覆盖当前日期/时间戳, 用于测试. 设为-1禁用.

quick_pass

• 类型：整数 (0/1)
• 默认：1
• 说明：是否启用一键通过模式（调试用）.

学习设置

scheduled_num

• 类型：整数
• 默认：8
• 说明：每天计划的新学习项目数量.

timezone_offset

• 类型：整数
• 默认：+28800 (UTC+8, 中国标准时间)
• 说明：时区偏移秒数, 用于日期计算.

路径配置 ([paths])

所有路径相对于工作目录, 或使用绝对路径.

nucleon_dir

• 默认："./data/nucleon"
• 说明：存储记忆内容 (Nucleon) 的目录.

electron_dir

• 默认："./data/electron"
• 说明：存储算法状态 (Electron) 的目录.

orbital_dir

• 默认："./data/orbital"
• 说明：存储策略配置 (Orbital) 的目录.

cache_dir

• 默认："./data/cache"
• 说明：缓存文件（音频、临时数据）目录.

template_dir

• 默认："./data/template"
• 说明：内容模板目录.

服务配置 ([services])

定义使用哪个提供者实现特定服务.

audio

• 可选值："playsound", "termux", "mpg123" (计划中)
• 默认："playsound"
• 说明：音频播放服务提供者.

tts

• 可选值："edgetts", "pyttsx3" (计划中)
• 说明：文本转语音服务提供者.

llm

• 可选值："openai", "litellm" (计划中)
• 说明：大语言模型服务提供者.

算法配置

SM-2 算法 ([algorithm.sm2])

[algorithm.sm2]
initial_interval = 1          # 初始间隔(天)
easy_bonus = 1.3              # "简单"评估的间隔乘数
hard_factor = 1.2             # "困难"评估的间隔除数
max_interval = 36500          # 最大间隔(天)
min_efactor = 1.3             # 最小易度因子
max_efactor = 2.5             # 最大易度因子

FSRS 算法 ([algorithm.fsrs])

[algorithm.fsrs]
# FSRS 参数（需通过训练获得）
weights = [0.4, 0.6, 0.9, 0.2, 0.5, 0.7, 0.3]

谜题配置 ([puzzles])

选择题 ([puzzles.mcq])

[puzzles.mcq]
max_riddles_num = 2           # 最大干扰项数量
shuffle_options = true        # 是否随机排序选项
show_explanation = true       # 是否显示解析

填空题 ([puzzles.cloze])

[puzzles.cloze]
min_denominator = 3           # 最小分母（影响空格数量）
hint_level = 1                # 提示级别 (0=无,1=首字母,2=长度)
case_sensitive = false        # 是否区分大小写

识别题 ([puzzles.recognition])

[puzzles.recognition]
time_limit = 30               # 时间限制(秒)
require_confirmation = true   # 是否需要确认

提供者配置

OpenAI LLM ([providers.llm.openai])

[providers.llm.openai]
url = ""                      # API 端点, 留空使用默认
key = ""                      # API 密钥
model = "gpt-3.5-turbo"       # 模型名称
temperature = 0.7             # 温度参数
max_tokens = 1000             # 最大生成令牌数

Edge TTS ([providers.tts.edgetts])

[providers.tts.edgetts]
voice = "zh-CN-XiaoxiaoNeural"  # 语音名称
rate = "+0%"                    # 语速调整
pitch = "+0Hz"                  # 音调调整
volume = "+0%"                  # 音量调整

Playsound 音频 ([providers.audio.playsound])

[providers.audio.playsound]
blocking = false               # 是否阻塞播放

界面配置 ([interface])

[interface]
theme = "dark"                # 主题: dark, light, auto
language = "zh_CN"            # 界面语言
animation_speed = 1.0         # 动画速度
show_progress_bar = true      # 显示进度条
confirm_exit = true           # 退出前确认

高级配置

宏系统 ([macros])

[macros]
enable = true                 # 启用宏系统
cache_size = 100              # 宏缓存大小
preload_common = true         # 预加载常用宏

缓存策略 ([cache])

[cache]
tts_max_size = 100            # TTS 缓存最大文件数(个)
tts_max_age = 30              # TTS 缓存最大保存时间(天)
audio_max_size = 50           # 音频缓存最大文件数(个)
cleanup_interval = 7          # 自动清理间隔(天)

环境变量覆盖

部分配置可通过环境变量覆盖：

• HEURAMS_CONFIG_PATH：指定配置文件路径
• HEURAMS_DATA_DIR：指定数据目录
• HEURAMS_LOG_LEVEL：日志级别 (DEBUG, INFO, WARNING, ERROR)
• HEURAMS_TTS_VOICE：TTS 语音

export HEURAMS_DATA_DIR="/path/to/my/data"
python -m heurams.interface

配置示例

最小配置

# config/config.toml
scheduled_num = 10
timezone_offset = +28800

完整配置

# config/config.toml
persist_to_file = 1
daystamp_override = -1
quick_pass = 0
scheduled_num = 15
timezone_offset = +28800

[paths]
nucleon_dir = "./data/nucleon"
electron_dir = "./data/electron"
orbital_dir = "./data/orbital"
cache_dir = "./data/cache"
template_dir = "./data/template"

[services]
audio = "playsound"
tts = "edgetts"
llm = "openai"

[algorithm.sm2]
initial_interval = 1
easy_bonus = 1.3
hard_factor = 1.2
max_interval = 36500
min_efactor = 1.3
max_efactor = 2.5

[puzzles.mcq]
max_riddles_num = 3
shuffle_options = true

[providers.llm.openai]
key = "sk-..."  # 实际密钥
model = "gpt-4"
temperature = 0.7

配置验证

检查配置

python -m heurams.tools.validate_config

重置配置

删除 config/config.toml 文件, 重启应用将恢复默认配置.

故障排除

配置不生效

1. 检查文件位置是否正确
2. 检查 TOML 语法是否正确
3. 查看日志文件中的配置加载信息
4. 重启应用

路径问题

确保路径存在且有读写权限. 可使用绝对路径避免相对路径歧义.

服务连接失败

检查提供者配置, 特别是 API 密钥和端点 URL.

下一步

• 高级功能：使用配置实现自动化
• 故障排除：解决配置相关问题
• 项目结构：了解配置在架构中的位置