项目结构
本文档介绍 HeurAMS 的软件架构和项目组织.
架构概述
HeurAMS 采用分层架构设计, 各层职责分离, 支持模块化扩展：
┌────────────────────────────────────────┐
│ 用户界面层 (TUI) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Widgets│ │ Screens │ │ CSS │ │
│ └─────────┘ └─────────┘ └─────────┘ │
└────────────────────────────────────────┘
↓
┌────────────────────────────────────────┐
│ 服务层 │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │配置 │ │日志 │ │音频 │ │ TTS │ │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
└────────────────────────────────────────┘
↓
┌────────────────────────────────────────┐
│ 内核层 │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │算法 │ │数据 │ │谜题 │ │调度器│ │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
└────────────────────────────────────────┘
↓
┌────────────────────────────────────────┐
│ 提供者层 │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │音频 │ │ TTS │ │ LLM │ │
│ └──────┘ └──────┘ └──────┘ │
└────────────────────────────────────────┘
↓
┌────────────────────────────────────────┐
│ 数据层 │
│ ┌────────────────────────┐ │
│ │ 本地文件系统 │ │
│ └────────────────────────┘ │
└────────────────────────────────────────┘设计原则
1. 关注点分离
- 界面层：只负责展示和用户交互
- 业务层：处理核心学习逻辑
- 数据层：管理持久化存储
- 集成层：对接外部服务
2. 依赖倒置
- 高层模块不依赖低层模块, 都依赖抽象
- 使用接口和抽象基类定义契约
- 具体实现通过提供者模式注入
3. 可测试性
- 各层可独立测试
- 使用上下文管理器控制依赖
- 支持模拟外部服务
4. 可扩展性
- 插件化架构
- 注册器模式管理可扩展组件
- 配置驱动行为
核心组件
上下文管理 (context.py)
使用 Python 的 contextvars 实现隐式依赖注入, 支持嵌套上下文.
python
# 示例：临时切换配置
with ConfigContext(test_config):
# 在此作用域内使用 test_config
do_something()
# 恢复原配置服务层 (services/)
- ConfigService：配置管理, 支持 TOML 格式
- Logger：日志系统, 支持轮转文件
- AudioService：音频播放抽象
- TTSService：文本转语音抽象
- Timer：时间服务, 支持时区
内核层 (kernel/)
- Algorithms：间隔重复算法 (SM-2, FSRS)
- Particles：数据模型 (Atom, Nucleon, Electron, Orbital)
- Puzzles：谜题类型 (MCQ, Cloze, Recognition)
- Reactor：调度和处理逻辑
提供者层 (providers/)
- Audio：音频播放实现 (playsound, termux)
- TTS：文本转语音实现 (Edge TTS)
- LLM：大语言模型集成 (OpenAI)
界面层 (interface/)
基于 Textual 框架的终端用户界面：
- Screens：应用屏幕（仪表板、复习、设置等）
- Widgets：UI 组件（按钮、列表、输入框等）
- CSS：样式定义
数据模型
四层数据架构
- Nucleon (核子)：记忆内容本体
- Electron (电子)：算法状态
- Orbital (轨道)：策略配置
- Atom (原子)：运行时关联容器
文件格式
- Nucleon：TOML, 人类可读, 易于编辑
- Electron：JSON, 机器可读, 算法维护
- Orbital：TOML, 策略定义
- Config：TOML, 应用配置
控制流
应用启动流程
- 解析命令行参数
- 加载配置（用户 → 默认）
- 初始化上下文
- 启动日志系统
- 加载服务提供者
- 启动 TUI 应用
复习流程
- 加载到期的 Atom
- 按优先级排序
- 对每个 Atom：
- 根据 Orbital 选择谜题
- 显示问题, 等待用户尝试
- 显示答案, 获取评估
- 更新算法状态
- 计算下次复习时间
- 保存状态到文件
内容创建流程
- 用户输入内容数据
- 应用模板（如有）
- 解析宏（如有）
- 创建 Nucleon 文件
- 初始化 Electron 状态
- 关联到 Orbital 策略
扩展机制
注册器模式
核心组件使用注册器管理：
python
# 算法注册器
algorithm_registry = {
"SM-2": SM2Algorithm,
"FSRS": FSRSAlgorithm,
}
# 谜题注册器
puzzle_registry = {
"mcq": MCQPuzzle,
"cloze": ClozePuzzle,
}
# 提供者注册器
provider_registry = {
"audio": {"playsound": PlaysoundProvider},
"tts": {"edgetts": EdgeTTSProvider},
}插件系统
通过以下方式扩展：
- 新算法：继承
BaseAlgorithm并注册 - 新谜题：继承
BasePuzzle并注册 - 新提供者：实现服务接口并注册
- 新模板：在
data/template/添加 TOML 文件
技术栈
核心语言
- Python 3.8+：主开发语言
- 类型注解：全面使用, 提高代码质量
- 异步支持：部分组件使用 async/await
主要框架
- Textual：终端用户界面
- TOML：配置和内容格式
- JSON：算法状态格式
开发工具
- pytest：测试框架
- Black：代码格式化
- mypy：类型检查
- logging：日志系统
部署架构
单机部署
- 所有组件在同一进程运行
- 数据存储在本地文件系统
- 适合个人使用
未来扩展计划
- 客户端-服务器：分离界面和计算逻辑
- 云同步：多设备数据同步
- Web 界面：浏览器访问
- 移动应用：iOS/Android 原生应用
性能考虑
内存管理
- 惰性加载内容文件
- 缓存频繁访问的数据
- 定期清理未使用的资源
磁盘 I/O
- 批量读写操作
- 使用高效的文件格式
- 异步文件操作（计划中）
网络优化
- TTS 音频缓存
- LLM 响应缓存
- 增量同步
安全架构
数据安全
- 本地存储, 默认不上传
- 可选的端到端加密
- 敏感信息环境变量存储
代码安全
- 依赖包版本锁定
- 定期安全更新
- 代码审计工具
隐私保护
- 明确的数据使用说明
- 可选的匿名化
- 用户数据控制权
监控与维护
日志系统
- 结构化日志记录
- 多级别日志控制
- 日志轮转防止过大
健康检查
- 内置诊断工具
- 数据完整性验证
- 性能监控
更新机制
- 平滑升级路径
- 数据迁移工具
- 向后兼容性保证