HeurAMS

Appearance

Kernel API 文档 ​

概述 ​

Kernel 是 HeurAMS 的核心业务逻辑模块，负责管理记忆系统的所有核心功能，包括数据模型、算法、谜题生成和流程控制。

子模块 ​

1. Particles - 数据模型层 ​

Atom 类 ​

统一的数据容器，管理记忆单元的所有组件。

python
class Atom()

构造函数:

python
def __init__(self, ident = "")

核心方法:

  • link(key, value) - 链接组件到原子
  • persist(key) - 持久化组件数据到文件
  • __getitem__(key) - 字典式访问组件
  • __setitem__(key, value) - 字典式设置组件

Electron 类 ​

算法元数据管理，处理记忆调度信息。

python
class Electron:

构造函数:

python
def __init__(self, ident: str, algodata: dict = {}, algo: str = "supermemo2")

核心方法:

  • activate() - 激活此电子
  • modify(var, value) - 修改算法数据
  • revisor(quality, is_new_activation) - 算法迭代决策

Nucleon 类 ​

记忆内容数据管理。

python
class Nucleon:

构造函数:

python
def __init__(self, ident, payload)

核心方法:

  • __getitem__(key) - 访问载荷数据
  • __iter__() - 迭代载荷键名
  • __len__() - 获取载荷大小

Orbital 类型 ​

学习策略配置。

python
class Orbital(TypedDict):

字段:

  • quick_view: list - 快速复习策略
  • recognition: list - 识别训练策略
  • final_review: list - 最终复习策略
  • puzzle_config: dict - 谜题生成配置

2. Reactor - 流程控制层 ​

Reactor 类 ​

核心反应堆，管理记忆流程的状态机。

python
class Reactor:

核心方法:

  • 多阶段记忆流程管理
  • 原子调度和资源分配
  • 质量反馈机制
  • 自动重定向逻辑

Glimpse 类 ​

状态查看器，提供流程状态信息。

python
class Glimpse:

功能:

  • 实时查看记忆流程状态
  • 调试和监控接口

3. Puzzles - 谜题生成层 ​

BasePuzzle 类 ​

谜题基类，定义统一的谜题接口。

python
class BasePuzzle:

抽象方法:

  • refresh() - 刷新谜题内容
  • validate() - 验证用户答案
  • get_hint() - 获取提示信息

MCQPuzzle 类 ​

选择题生成器。

python
class MCQPuzzle(BasePuzzle):

特性:

  • 从指定字段生成选择题
  • 支持干扰项生成
  • 自动评分机制

ClozePuzzle 类 ​

填空题生成器。

python
class ClozePuzzle(BasePuzzle):

特性:

  • 从指定字段生成填空题
  • 支持多种填空模式
  • 智能空格检测

PuzzleRegistry 类 ​

谜题注册表，管理所有可用的谜题类型。

python
class PuzzleRegistry:

方法:

  • register(name, puzzle_class) - 注册谜题类型
  • get_puzzle(name) - 获取谜题实例
  • list_puzzles() - 列出所有谜题类型

4. Algorithms - 算法层 ​

SM-2 算法 ​

SuperMemo 2 间隔重复算法实现。

算法参数:

  • efactor - 易度系数 (1.3-2.5)
  • rept - 重复次数
  • interval - 下次间隔 (天数)
  • next_date - 下次复习时间戳

迭代规则:

  1. 用户提供记忆质量评分 (0-5)
  2. 根据质量评分更新易度系数
  3. 计算新的复习间隔
  4. 更新下次复习日期

算法注册机制 ​

统一的算法管理和扩展接口。

python
def get_algorithm(name: str) -> dict

功能:

  • 获取指定算法的配置
  • 支持算法插件扩展
  • 统一的算法接口

使用示例 ​

创建完整的记忆单元 ​

python
from heurams.kernel.particles import Atom, Electron, Nucleon
from heurams.kernel.particles.orbital import Orbital

# 创建原子
atom = Atom("learning_unit_001")

# 链接核子
nucleon = Nucleon("content_001", {
    "content": "学习内容",
    "translation": "翻译内容"
})
atom.link("nucleon", nucleon)

# 链接电子
electron = Electron("algo_001", {}, "supermemo2")
atom.link("electron", electron)

# 链接轨道
orbital: Orbital = {
    "quick_view": [["cloze", 1], ["mcq", 0.5]],
    "recognition": [["recognition", 1]],
    "final_review": [["cloze", 0.7], ["mcq", 0.7]],
    "puzzle_config": {
        "cloze": {"from": "content"},
        "mcq": {"from": "keyword_note"}
    }
}
atom.link("orbital", orbital)

使用谜题系统 ​

python
from heurams.kernel.puzzles import PuzzleRegistry

# 获取谜题实例
puzzle = PuzzleRegistry.get_puzzle("mcq")
puzzle.refresh()

# 验证用户答案
is_correct = puzzle.validate(user_answer)

算法迭代 ​

python
# 激活电子
electron.activate()

# 算法迭代
electron.revisor(quality=4, is_new_activation=False)

设计模式 ​

原子化数据模型 ​

  • Atom: 统一的数据容器
  • Electron: 算法元数据
  • Nucleon: 内容数据
  • Orbital: 学习策略

插件化架构 ​

  • 算法和谜题采用注册机制
  • 支持动态扩展
  • 统一的接口规范

状态机驱动 ​

  • Reactor 管理完整的记忆流程
  • 多阶段状态转换
  • 质量反馈机制

版本兼容性 ​

  • HeurAMS 0.4.x: 完全支持
  • HeurAMS 0.3.x: 部分支持 (需要适配)
  • HeurAMS 0.2.x: 不支持

© 2025 Wang Zhiyu 保留所有权