HeurAMS

Appearance

目录结构 ​

本文档详细介绍 HeurAMS 项目的文件和目录组织.

项目根目录 ​

HeurAMS/
├── src/                    # 源代码
├── tests/                  # 测试代码
├── config/                 # 配置模板
├── data/                   # 数据模板
├── pyproject.toml          # 项目元数据
├── requirements.txt        # Python 依赖
├── README.md              # 项目说明
├── CONTRIBUTING.md        # 贡献指南
└── LICENSE                # 许可证文件

源代码目录 (src/heurams/) ​

主包结构 ​

src/heurams/
├── __init__.py            # 包定义和版本
├── __main__.py            # 命令行入口
├── context.py             # 上下文管理
├── services/              # 核心服务
│   ├── __init__.py
│   ├── config.py          # 配置管理
│   ├── logger.py          # 日志系统
│   ├── timer.py           # 时间服务
│   ├── audio_service.py   # 音频服务抽象
│   ├── tts_service.py     # TTS 服务抽象
│   ├── hasher.py          # 哈希工具
│   ├── version.py         # 版本信息
│   └── README.md
├── kernel/                # 核心业务逻辑
│   ├── __init__.py
│   ├── algorithms/        # 间隔重复算法
│   │   ├── __init__.py
│   │   ├── base.py        # 算法基类
│   │   ├── sm2.py         # SM-2 算法
│   │   └── fsrs.py        # FSRS 算法
│   ├── particles/         # 数据模型
│   │   ├── __init__.py
│   │   ├── atom.py        # Atom 类
│   │   ├── nucleon.py     # Nucleon 类
│   │   ├── electron.py    # Electron 类
│   │   ├── orbital.py     # Orbital 类
│   │   ├── loader.py      # 数据加载器
│   │   └── probe.py       # 数据探查工具
│   ├── puzzles/           # 谜题类型
│   │   ├── __init__.py
│   │   ├── base.py        # 谜题基类
│   │   ├── mcq.py         # 选择题
│   │   ├── cloze.py       # 填空题
│   │   └── recognition.py # 识别题
│   ├── reactor/           # 调度反应器
│   │   ├── __init__.py
│   │   ├── fission.py     # 原子分裂处理
│   │   ├── phaser.py      # 阶段处理器
│   │   ├── procession.py  # 队列处理器
│   │   └── states.py      # 状态管理
│   └── README.md
├── providers/             # 外部服务提供者
│   ├── __init__.py
│   ├── audio/             # 音频提供者
│   │   ├── __init__.py
│   │   ├── protocol.py    # 音频协议
│   │   ├── playsound_audio.py  # Playsound 实现
│   │   └── termux_audio.py     # Termux 实现
│   ├── tts/               # TTS 提供者
│   │   ├── __init__.py
│   │   ├── base.py        # TTS 基类
│   │   └── edge_tts.py    # Edge TTS 实现
│   ├── llm/               # LLM 提供者
│   │   ├── __init__.py
│   │   ├── base.py        # LLM 基类
│   │   └── openai.py      # OpenAI 实现
│   └── README.md
├── interface/             # Textual TUI 界面
│   ├── __init__.py
│   ├── __main__.py        # 应用入口点
│   ├── shim.py            # 兼容层
│   ├── widgets/           # UI 组件
│   │   ├── __init__.py
│   │   ├── base_puzzle_widget.py  # 谜题组件基类
│   │   ├── basic_puzzle.py        # 基础谜题组件
│   │   ├── cloze_puzzle.py        # 填空组件
│   │   ├── mcq_puzzle.py          # 选择组件
│   │   ├── recognition.py         # 识别组件
│   │   ├── finished.py            # 完成提示组件
│   │   └── placeholder.py         # 占位符组件
│   ├── screens/           # 应用屏幕
│   │   ├── __init__.py
│   │   ├── dashboard.py   # 仪表板
│   │   ├── memorizor.py   # 记忆界面
│   │   ├── nucreator.py   # 内容创建
│   │   ├── intelinote.py  # 智能笔记
│   │   ├── preparation.py # 准备屏幕
│   │   ├── precache.py    # 预缓存
│   │   ├── register.py    # 注册屏幕
│   │   ├── synctool.py    # 同步工具
│   │   ├── type43.py      # 类型43屏幕
│   │   └── about.py       # 关于页面
│   ├── css/               # 样式表
│   │   └── main.tcss      # 主样式
│   └── README.md
├── default/               # 默认配置和模板
│   └── config/
│       └── config.toml    # 默认配置文件
└── utils/                 # 工具函数
    ├── __init__.py
    └── README.md

测试目录 (tests/) ​

tests/
├── __init__.py
├── interface/             # 界面测试
│   └── __init__.py
└── kernel/               # 内核测试
    ├── __init__.py
    ├── algorithms/       # 算法测试
    │   ├── __init__.py
    │   ├── test_sm2.py   # SM-2 测试
    │   └── test_fsrs.py  # FSRS 测试
    └── particles/        # 数据模型测试
        └── __init__.py

数据目录结构 ​

应用运行时在工作目录创建的数据结构：

工作目录/
├── config/
│   └── config.toml                # 用户配置文件
├── data/
│   ├── nucleon/                   # 记忆内容 (TOML)
│   │   ├── 数学/
│   │   │   ├── 代数/
│   │   │   └── 几何/
│   │   ├── 语文/
│   │   │   ├── 古诗词/
│   │   │   └── 文言文/
│   │   └── 英语/
│   │       └── 单词/
│   ├── electron/                  # 算法状态 (JSON)
│   │   ├── 数学/
│   │   ├── 语文/
│   │   └── 英语/
│   ├── orbital/                   # 策略配置 (TOML)
│   │   ├── default.toml
│   │   └── custom/
│   ├── cache/                     # 缓存文件
│   │   ├── tts/                   # TTS 音频缓存
│   │   │   ├── 哈希1.mp3
│   │   │   └── 哈希2.mp3
│   │   └── images/                # 图片缓存（计划中）
│   └── template/                  # 内容模板
│       ├── blank.toml             # 空白模板
│       ├── poem.toml              # 古诗词模板
│       └── mcq.toml               # 选择题模板
└── heurams.log                    # 应用日志

配置文件说明 ​

默认配置 (src/heurams/default/config/config.toml) ​

  • 位置：源码包内
  • 作用：提供默认值
  • 修改：不应直接修改, 通过用户配置覆盖

用户配置 (config/config.toml) ​

  • 位置：工作目录下的 config/ 子目录
  • 生成：首次运行时自动创建
  • 优先级：高于默认配置

环境特定配置 ​

可通过环境变量指定配置路径：

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

文件命名约定 ​

内容文件 ​

  • Nucleon：[标识符].toml, 如 math_algebra_001.toml
  • Electron：[标识符].json, 与 Nucleon 对应
  • Orbital：[策略名].toml, 如 quick_review.toml

标识符规则 ​

  • 使用小写字母、数字、下划线
  • 避免特殊字符和空格
  • 建议使用有意义的名称
  • 保持一致性便于管理

版本控制 ​

Git 忽略文件 ​

# .gitignore
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
.heurams_data/      # 用户数据目录
heurams.log         # 日志文件
data/               # 运行时数据
config/             # 用户配置

数据备份建议 ​

用户数据（data/ 目录）建议：

  1. 定期备份到外部存储
  2. 使用版本控制（如 Git）管理 nucleon/ 目录
  3. 避免将敏感信息存储在纯文本中

部署结构 ​

开发环境 ​

  • 使用源码目录直接运行
  • 数据存储在项目根目录下
  • 便于调试和修改

生产环境 ​

  • 安装到系统或虚拟环境
  • 数据存储在用户目录
  • 使用独立的数据目录

打包发布 ​

  • 使用 pyproject.toml 定义包元数据
  • 支持 pip install -e . 开发安装
  • 未来计划提供独立可执行文件

相关文档 ​

© 2025 Wang Zhiyu 保留所有权