Electron 文件规范

Electron 是 HeurAMS 中用于存储记忆算法状态的文件格式. 每个 Electron 文件对应一个记忆单元的学习进度和算法参数.

文件格式

Electron 文件使用 JSON 格式, 文件扩展名为 .json.

推荐 MIME 类型

application/vnd.xyz.imwangzhiyu.heurams-electron.v1+json

文件结构

Electron 文件的核心是一个 JSON 对象, 包含算法数据和元信息.

顶层结构

{
  "ident": "unique_identifier",
  "algodata": {
    "算法名称": {
      "字段1": 值1,
      "字段2": 值2,
      ...
    }
  }
}

字段说明

• ident：字符串, 唯一标识符, 与对应的 Nucleon 文件的 ident 保持一致
• algodata：对象, 包含一个或多个算法的数据, 键为算法名称, 值为该算法的状态数据

算法数据格式

SM-2 算法数据格式

{
  "ident": "example_id",
  "algodata": {
    "SM-2": {
      "efactor": 2.5,
      "real_rept": 0,
      "rept": 0,
      "interval": 0,
      "last_date": 0,
      "next_date": 0,
      "is_activated": 0,
      "last_modify": 1698765432.123456
    }
  }
}

SM-2 字段说明

字段	类型	描述	默认值
efactor	浮点数	易度系数 (E-Factor), 反映记忆难度	2.5
real_rept	整数	实际复习次数（包括失败的重置）	0
rept	整数	当前连续成功复习次数	0
interval	整数	当前间隔天数	0
last_date	整数	上次复习的日时间戳（天数）	0
next_date	整数	下次复习的日时间戳（天数）	0
is_activated	整数	是否已激活（0=未激活, 1=已激活）	0
last_modify	浮点数	最后修改的时间戳（秒, 浮点）	当前时间戳

FSRS 算法数据格式

FSRS 算法当前版本尚未实现, 预留数据结构：

{
  "ident": "example_id",
  "algodata": {
    "FSRS": {
      "stability": 0.0,
      "difficulty": 0.0,
      "retrievability": 0.0,
      "last_review": 0,
      "next_review": 0,
      "elapsed_days": 0,
      "scheduled_days": 0,
      "reps": 0,
      "lapses": 0,
      "is_activated": 0,
      "last_modify": 1698765432.123456
    }
  }
}

时间戳系统

Electron 使用两种时间戳：

1. 日时间戳 (Daystamp)

• 整数类型, 表示自纪元以来的天数
• 用于 last_date 和 next_date 字段
• 示例：1970-01-01 = 0, 2023-10-01 ≈ 19600

2. 高精度时间戳 (Timestamp)

• 浮点数类型, 表示自纪元以来的秒数（含小数）
• 用于 last_modify 字段
• 示例：1698765432.123456

算法状态转换

初始状态（新记忆单元）

{
  "efactor": 2.5,
  "real_rept": 0,
  "rept": 0,
  "interval": 0,
  "last_date": 0,
  "next_date": 0,
  "is_activated": 0,
  "last_modify": 创建时间戳
}

激活状态（首次学习）

• is_activated 设置为 1
• last_modify 更新为当前时间
• last_date 设置为当前日时间戳

复习更新（根据反馈质量）

根据 SM-2 算法规则更新：

• efactor：根据质量调整（范围 1.3-2.5）
• rept：成功时递增, 失败时重置为 0
• real_rept：总是递增
• interval：根据 rept 和 efactor 计算
• last_date：更新为当前日时间戳
• next_date：计算为 last_date + interval
• last_modify：更新为当前时间戳

文件示例

示例 1：新创建的 Electron

{
  "ident": "greeting_hello_world",
  "algodata": {
    "SM-2": {
      "efactor": 2.5,
      "real_rept": 0,
      "rept": 0,
      "interval": 0,
      "last_date": 0,
      "next_date": 0,
      "is_activated": 0,
      "last_modify": 1698765432.123456
    }
  }
}

示例 2：已学习一次的 Electron

{
  "ident": "greeting_hello_world",
  "algodata": {
    "SM-2": {
      "efactor": 2.6,
      "real_rept": 1,
      "rept": 1,
      "interval": 6,
      "last_date": 19600,
      "next_date": 19606,
      "is_activated": 1,
      "last_modify": 1698765432.123456
    }
  }
}

示例 3：复习多次的 Electron

{
  "ident": "advanced_concept",
  "algodata": {
    "SM-2": {
      "efactor": 1.8,
      "real_rept": 5,
      "rept": 3,
      "interval": 45,
      "last_date": 19630,
      "next_date": 19675,
      "is_activated": 1,
      "last_modify": 1698765432.123456
    }
  }
}

编程接口

在 Python 代码中, Electron 通过 heurams.kernel.particles.electron.Electron 类表示：

from heurams.kernel.particles.electron import Electron

# 从字典创建 Electron
electron = Electron(
    ident="unique_id",
    algodata={"SM-2": {"efactor": 2.5, "rept": 0}},
    algo_name="supermemo2"
)

# 访问字段
print(electron.ident)              # "unique_id"
print(electron["efactor"])         # 2.5
print(electron.is_activated())     # False

# 修改状态
electron.activate()                # 激活电子
electron.modify("efactor", 2.6)    # 修改易度系数
electron.revisor(quality=4)        # 根据质量评分更新算法状态

# 检查状态
print(electron.is_due())           # 是否到期需要复习
print(electron.get_rate())         # 获取评分
print(electron.nextdate())         # 获取下次复习日期

Electron 类方法

方法	描述
__init__(ident, algodata, algo_name)	初始化 Electron
activate()	激活电子（设置为已学习状态）
modify(var, value)	修改算法数据字段
is_due()	检查是否到期需要复习
is_activated()	检查是否已激活
get_rate()	获取评分信息（字符串）
nextdate()	获取下次复习日时间戳
revisor(quality, is_new_activation)	根据反馈质量更新算法状态
__getitem__(key)	获取算法数据字段值
__setitem__(key, value)	设置算法数据字段值
__len__()	返回算法数据字段数量
placeholder()	创建占位 Electron

文件操作

保存 Electron 文件

Electron 文件保存在 data/electron/ 目录下, 文件名格式为 {ident}.json.

加载 Electron 文件

import json
import os

def load_electron(ident):
    filepath = f"data/electron/{ident}.json"
    with open(filepath, 'r', encoding='utf-8') as f:
        data = json.load(f)
    return Electron(**data)

自动管理

HeurAMS 会自动管理 Electron 文件的创建、更新和删除, 通常不需要手动操作.

版本历史

• v1 (当前版本)：JSON 格式, 支持 SM-2 算法
• v0：实验性格式（已弃用）

注意事项

1. 文件编码：使用 UTF-8 编码
2. 标识符一致性：ident 必须与对应的 Nucleon 文件保持一致
3. 时间戳同步：确保系统时间准确, 时间戳用于计算复习间隔
4. 算法兼容性：不同算法使用不同的数据字段, 不能混用
5. 数据完整性：修改文件时确保 JSON 格式正确

相关文档

• Nucleon 规范 - 记忆内容文件
• Orbital 规范 - 学习策略文件
• Algorithm 规范 - 算法对象定义
• SM-2 算法参考