核心模块
本文档详细介绍 HeurAMS 各核心模块的功能和实现.
上下文管理模块 (context.py)
功能概述
提供全局上下文管理和隐式依赖注入机制, 基于 Python 的 contextvars 模块.
核心组件
config_var
python
config_var: ContextVar[ConfigFile] = ContextVar(
"config_var", default=ConfigFile(default_config_path)
)全局配置上下文变量, 支持嵌套覆盖.
ConfigContext 类
上下文管理器, 用于临时切换配置：
python
class ConfigContext:
def __init__(self, config_provider: ConfigFile):
self.config_provider = config_provider
def __enter__(self):
self._token = config_var.set(self.config_provider)
return self
def __exit__(self, exc_type, exc_val, exc_tb):
config_var.reset(self._token)使用场景
- 测试：临时使用测试配置
- 多用户：快速切换不同用户配置
- 功能开关：临时启用/禁用特定功能
服务层模块 (services/)
配置服务 (config.py)
ConfigFile 类
python
class ConfigFile:
def __init__(self, path: pathlib.Path):
self.path = path
self.data = {}
self._load()
def get(self, key: str, default: Any = None) -> Any:
return self.data.get(key, default)
def modify(self, key: str, value: Any):
self.data[key] = value
self.save()
def save(self):
with open(self.path, "w") as f:
toml.dump(self.data, f)特性
- TOML 格式支持
- 自动创建缺失文件
- 类型安全的访问接口
- 实时保存更改
日志服务 (logger.py)
功能特性
- 多级别日志控制 (DEBUG, INFO, WARNING, ERROR)
- 文件轮转防止过大
- 结构化日志格式
- 模块化日志记录器
配置示例
python
logger = get_logger(__name__)
logger.debug("调试信息")
logger.info("操作完成")
logger.warning("警告信息")
logger.error("错误信息")时间服务 (timer.py)
功能
- 统一的时区处理
- 日期戳转换
- 时间间隔计算
- 支持时间覆盖（测试用）
核心函数
python
def get_daystamp() -> int:
"""获取当前日期戳（自纪元的天数）"""
def get_timestamp() -> float:
"""获取当前时间戳（秒）"""
def daystamp_to_date(daystamp: int) -> datetime.date:
"""日期戳转日期对象"""音频服务 (audio_service.py)
抽象接口
python
class AudioService:
@abstractmethod
def play(self, audio_data: bytes) -> bool:
"""播放音频数据"""
@abstractmethod
def stop(self) -> bool:
"""停止播放"""TTS 服务 (tts_service.py)
抽象接口
python
class TTSService:
@abstractmethod
def synthesize(self, text: str, voice: Optional[str] = None) -> bytes:
"""合成语音"""
@abstractmethod
def get_available_voices(self) -> List[str]:
"""获取可用语音列表"""内核层模块 (kernel/)
算法模块 (algorithms/)
基类 BaseAlgorithm
python
class BaseAlgorithm(ABC):
algo_name: str = ""
defaults: Dict[str, Any] = {}
@classmethod
@abstractmethod
def revisor(cls, algodata: dict, feedback: int,
is_new_activation: bool = False):
"""更新算法状态"""
@classmethod
def get_next_review_date(cls, algodata: dict) -> int:
"""计算下次复习日期"""SM-2 算法 (sm2.py)
基于 SuperMemo 2.0 算法, Anki 使用的经典算法.
算法参数：
efactor：易度因子 (1.3-2.5)interval：当前间隔（天）rept：连续正确次数real_rept：实际复习次数
更新规则：
- 评估 quality (0-5)
- 更新 efactor：
efactor = efactor + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02)) - 限制 efactor 在 [1.3, 2.5] 范围内
- 根据 quality 和 rept 计算新间隔
FSRS 算法 (fsrs.py)
自由间隔重复调度器, 基于机器学习的现代算法.
特点：
- 自适应学习速率
- 更准确的长期记忆预测
- 可训练的参数权重
数据模型模块 (particles/)
Atom 类 (atom.py)
python
class Atom:
"""关联 Nucleon、Electron、Orbital 的运行时容器"""
def __init__(self, ident: str = ""):
self.ident = ident
self.registry: AtomRegister = {
"nucleon": None,
"electron": None,
"orbital": None,
"runtime": {"locked": False, "min_rate": 0, "newact": False}
}功能：
- 统一管理三者的关联
- 提供便捷的访问接口
- 处理持久化操作
- 支持运行时状态
Nucleon 类 (nucleon.py)
python
class Nucleon:
"""记忆内容容器"""
def __init__(self, data: Dict[str, Any], path: pathlib.Path):
self.data = data
self.path = path字段示例：
toml
# data/nucleon/example.toml
id = "math_001"
question = "勾股定理公式是什么？"
answer = "a² + b² = c²"
tags = ["数学", "几何", "定理"]
metadata = {source = "教科书", chapter = "第三章"}Electron 类 (electron.py)
python
class Electron:
"""算法状态容器"""
def __init__(self, data: Dict[str, Any], path: pathlib.Path):
self.data = data
self.path = path字段示例：
json
{
"SM-2": {
"efactor": 2.3,
"interval": 15,
"rept": 3,
"last_date": 19657,
"next_date": 19672
}
}Orbital 类 (orbital.py)
python
class Orbital:
"""策略配置容器"""
def __init__(self, data: Dict[str, Any], path: pathlib.Path):
self.data = data
self.path = path字段示例：
toml
# data/orbital/quick_review.toml
name = "快速复习"
puzzles = [
{type = "cloze", weight = 1.0},
{type = "mcq", weight = 0.5}
]
schedule = "daily"谜题模块 (puzzles/)
基类 BasePuzzle
python
class BasePuzzle(ABC):
name: str = ""
@abstractmethod
def generate(self, nucleon: Nucleon, orbital: Orbital) -> PuzzleData:
"""生成谜题数据"""
@abstractmethod
def evaluate(self, user_input: str, correct_answer: str) -> Tuple[bool, str]:
"""评估用户输入"""选择题 (mcq.py)
特性：
- 支持多个干扰项
- 随机选项顺序
- 可配置最大干扰项数量
- 支持解析说明
配置：
toml
[puzzles.mcq]
max_riddles_num = 3
shuffle_options = true
show_explanation = true填空题 (cloze.py)
特性：
- 自动检测填空位置
- 可配置最小分母（影响空格数量）
- 支持提示级别
- 大小写敏感选项
配置：
toml
[puzzles.cloze]
min_denominator = 3
hint_level = 1 # 0=无,1=首字母,2=长度
case_sensitive = false识别题 (recognition.py)
特性：
- 快速识别判断
- 时间限制选项
- 确认要求选项
- 适合快速复习
配置：
toml
[puzzles.recognition]
time_limit = 30
require_confirmation = true调度反应器 (reactor/)
fission.py - 原子分裂处理
处理 Atom 的拆分和重组, 用于复杂内容的分解学习.
phaser.py - 阶段处理器
管理学习的不同阶段：新学、复习、巩固、测试.
procession.py - 队列处理器
管理复习队列的排序、优先级和调度.
states.py - 状态管理
跟踪应用和学习的全局状态.
提供者层模块 (providers/)
音频提供者 (audio/)
playsound_audio.py
基于 playsound 库的跨平台音频播放.
特性：
- 支持常见音频格式
- 简单易用的 API
- 跨平台兼容性
termux_audio.py
Android Termux 专用的音频播放.
特性：
- 针对移动设备优化
- 终端环境适配
- 低资源消耗
TTS 提供者 (tts/)
edge_tts.py
基于微软 Edge TTS 服务的语音合成.
特性：
- 高质量的神经网络语音
- 多语言支持
- 可调节语速、音调
- 本地缓存机制
配置：
toml
[providers.tts.edgetts]
voice = "zh-CN-XiaoxiaoNeural"
rate = "+0%"
pitch = "+0Hz"LLM 提供者 (llm/)
openai.py
OpenAI 兼容的 API 接口.
特性：
- 支持 GPT 系列模型
- 可配置参数（温度、最大令牌数等）
- 错误处理和重试机制
配置：
toml
[providers.llm.openai]
url = "https://api.openai.com/v1"
key = "sk-..."
model = "gpt-3.5-turbo"
temperature = 0.7界面层模块 (interface/)
应用入口 (__main__.py)
python
def main():
"""TUI 应用主函数"""
app = HeurAMSApp()
app.run()屏幕模块 (screens/)
dashboard.py - 主仪表板
显示学习统计、进度、快捷操作.
memorizor.py - 记忆界面
核心复习界面, 显示谜题和收集反馈.
nucreator.py - 内容创建
创建和编辑记忆内容的界面.
intelinote.py - 智能笔记
集成 LLM 的智能内容生成界面.
preparation.py - 准备屏幕
复习前的准备和设置界面.
组件模块 (widgets/)
base_puzzle_widget.py
谜题组件的基类, 定义通用接口和行为.
具体谜题组件
mcq_puzzle.py：选择题组件cloze_puzzle.py：填空题组件recognition.py：识别题组件
工具模块 (utils/)
哈希工具 (hasher.py)
python
def hash_text(text: str) -> str:
"""生成文本的哈希标识"""
return hashlib.md5(text.encode()).hexdigest()文件工具
文件操作、路径处理、格式转换等实用函数.
模块间依赖关系
编译时依赖
interface → services → providers
↓ ↓
kernel → particles运行时依赖
通过上下文管理器动态注入, 减少硬编码依赖.
数据流依赖
用户输入 → 界面层 → 服务层 → 内核层 → 数据层
↓
提供者层 → 外部服务扩展点
1. 新算法
继承 BaseAlgorithm 并注册到 algorithm_registry.
2. 新谜题
继承 BasePuzzle 并注册到 puzzle_registry.
3. 新提供者
实现服务接口并注册到相应的提供者注册表.
4. 新模板
在 data/template/ 目录添加 TOML 模板文件.
5. 新界面组件
继承 Textual 组件并集成到相应屏幕.
性能优化
内存优化
- 惰性加载大文件
- 缓存频繁访问数据
- 及时释放未使用资源
磁盘优化
- 批量读写操作
- 使用高效序列化格式
- 定期清理临时文件
网络优化
- 请求合并和批处理
- 本地缓存策略
- 异步网络操作
测试策略
单元测试
- 每个模块独立的测试
- 模拟外部依赖
- 边界条件覆盖
集成测试
- 模块间接口测试
- 数据流验证
- 端到端功能测试
性能测试
- 内存使用监控
- 响应时间测量
- 并发处理能力