HeurAMS

Appearance

协议规范 ​

HeurAMS 使用一组标准化的文件格式和数据协议来管理记忆内容、学习状态和复习策略. 这些规范确保了系统的可扩展性、数据可移植性和跨版本兼容性.

规范概览 ​

HeurAMS 定义了五种核心数据格式, 分别对应记忆系统中的不同组件：

规范文件格式描述核心概念
NucleonTOML记忆内容文件, 包含学习材料和元数据内容载荷、宏系统、元数据区块
ElectronJSON算法状态文件, 记录学习进度和算法参数易度系数、复习间隔、时间戳系统
OrbitalTOML学习策略文件, 定义谜题类型和复习方案谜题定义、学习方案、宏表达式
Puzzle-谜题对象规范, 定义如何生成具体复习题目MCQ、Cloze、Recognition
Algorithm-算法对象规范, 定义间隔重复算法逻辑SM-2、FSRS、复习质量评分

数据模型关系 ​

这五种规范共同构成了 HeurAMS 的核心数据模型：

mermaid
graph TD
    A[Nucleon<br/>记忆内容] --> B[Orbital<br/>学习策略]
    A --> C[Electron<br/>算法状态]
    B --> D[Puzzle<br/>谜题生成]
    C --> E[Algorithm<br/>间隔重复]
    D --> F[复习界面]
    E --> F
    F --> G[用户反馈]
    G --> E
    G --> C

工作流程 ​

  1. 内容创建：用户创建 Nucleon 文件, 定义记忆内容和元数据
  2. 策略配置：Orbital 定义如何将内容转化为具体谜题
  3. 状态初始化：系统创建 Electron 文件, 记录初始算法状态
  4. 复习生成：结合 Nucleon 和 Orbital 生成 Puzzle 实例
  5. 算法更新：根据用户反馈, Algorithm 更新 Electron 状态
  6. 间隔计算：Algorithm 计算下一次复习时间
  7. 循环重复：重复 4-6 步, 形成学习循环

文件系统布局 ​

在 HeurAMS 工作目录中, 这些文件按照以下结构组织：

工作目录/
├── config/
│   └── config.toml          # 系统配置
├── data/
│   ├── nucleon/             # Nucleon 文件 (*.toml)
│   ├── electron/            # Electron 文件 (*.json)  
│   ├── orbital/             # Orbital 文件 (*.toml)
│   ├── cache/               # 缓存文件
│   └── template/            # 模板文件
└── heurams.log              # 系统日志

文件命名约定 ​

  • Nucleon：{标识符}.toml, 标识符建议使用有意义的英文或拼音
  • Electron：{标识符}.json, 与对应 Nucleon 的标识符相同
  • Orbital：{策略名称}.toml 或嵌入在 Nucleon 的元数据中

核心概念 ​

宏系统 (Macro System) ​

所有规范都支持宏表达式, 用于动态生成内容：

toml
# 在 Nucleon 或 Orbital 中使用宏
text = "eval:nucleon['content'].replace('/', '')"
max_riddles_num = "eval:default['mcq']['max_riddles_num']"
question = "What does {{nucleon['word']}} mean?"

可用变量：

  • nucleon：当前 Nucleon 的所有字段
  • metadata：Nucleon 的 [__metadata__] 内容
  • default：系统默认配置（来自 config.toml）

时间戳系统 ​

系统使用两种时间戳：

  • 日时间戳：整数, 表示自纪元（1970-01-01）以来的天数
  • 高精度时间戳：浮点数, 表示自纪元以来的秒数（含小数）

算法反馈质量 ​

间隔重复算法使用 0-5 的质量评分：

  • 5：完美回忆
  • 4：正确但犹豫
  • 3：困难但正确
  • 2：错误但接近
  • 1：完全错误
  • 0：完全遗忘
  • -1：跳过

版本兼容性 ​

当前版本 (v5) ​

  • Nucleon：TOML 格式, 支持宏系统
  • Electron：JSON 格式, 支持 SM-2 算法
  • Orbital：TOML 格式, 支持三种谜题类型
  • Puzzle：MCQ、Cloze、Recognition
  • Algorithm：SM-2 完整实现

向后兼容性 ​

新版本保持对旧格式的读取兼容性：

  • 自动检测文件版本
  • 必要时进行格式转换
  • 保留关键数据字段

迁移指南 ​

从旧版本迁移时：

  1. 备份原始数据文件
  2. 使用系统内置迁移工具
  3. 验证迁移后的数据完整性
  4. 测试关键功能

扩展开发 ​

添加新谜题类型 ​

  1. 创建新的 Puzzle 类, 继承 BasePuzzle
  2. 实现 refresh() 方法
  3. 在 Orbital 配置中添加新类型支持
  4. 更新谜题注册器

添加新算法 ​

  1. 创建新的 Algorithm 类, 继承 BaseAlgorithm
  2. 定义算法数据结构和默认值
  3. 实现四个核心方法：revisor、is_due、rate、nextdate
  4. 注册到算法注册器

自定义文件格式 ​

  1. 定义新的文件解析器/生成器
  2. 集成到系统的文件管理模块
  3. 添加版本检测和迁移支持
  4. 更新文档和测试

安全考虑 ​

宏执行安全 ​

  • 宏表达式在受限的 Python 环境中执行
  • 禁止文件 I/O、网络访问等危险操作
  • 执行错误会返回错误信息而非抛出异常
  • 建议仅信任可信来源的宏表达式

数据完整性 ​

  • 使用校验和验证文件完整性
  • 定期备份关键数据
  • 支持数据恢复机制
  • 提供数据导出/导入功能

隐私保护 ​

  • 本地存储所有用户数据
  • 可选的加密存储支持
  • 清晰的隐私政策说明
  • 用户控制数据分享权限

相关工具 ​

验证工具 ​

bash
# 验证 Nucleon 文件格式
python -m heurams.tools.validate_nucleon path/to/nucleon.toml

# 验证 Electron 文件格式  
python -m heurams.tools.validate_electron path/to/electron.json

# 验证 Orbital 文件格式
python -m heurams.tools.validate_orbital path/to/orbital.toml

转换工具 ​

bash
# 从旧版本迁移
python -m heurams.tools.migrate_v4_to_v5 old_data/ new_data/

# 格式转换
python -m heurams.tools.convert_to_json path/to/toml/file.toml

# 批量处理
python -m heurams.tools.batch_process --pattern "*.toml" --action validate

分析工具 ​

bash
# 学习统计
python -m heurams.tools.stats --period 30days

# 进度报告
python -m heurams.tools.report --format html --output report.html

# 预测分析
python -m heurams.tools.predict --algorithm sm2 --horizon 90days

获取帮助 ​

  • 文档：查看各个规范的详细说明
  • 示例：参考 data/template/ 目录中的模板文件
  • 社区：访问项目仓库的问题讨论区
  • 开发：查看源代码和 API 文档

贡献指南 ​

欢迎贡献新的规范、改进现有规范或报告问题：

  1. 阅读 贡献指南
  2. 在 GitHub 上创建 Issue 或 Pull Request
  3. 遵循项目代码风格和测试要求
  4. 更新相关文档和示例

*本文档最后更新于 2025-12-18, 基于 HeurAMS 0.4.0 "Fledge" 版本. *

© 2025 Wang Zhiyu 保留所有权