HeurAMS

Appearance

Orbital 文件规范 ​

Orbital 是 HeurAMS 中用于定义学习策略和谜题配置的文件格式. 它规定了如何将记忆内容转化为具体的复习任务.

文件格式 ​

Orbital 文件使用 TOML v1.0.0 格式, 通常作为 Nucleon 文件的元数据部分存在, 也可以作为独立文件.

嵌入模式（推荐） ​

在 Nucleon 文件的 [__metadata__.orbital] 部分定义：

toml
[__metadata__.orbital.puzzles]
# 谜题定义

[__metadata__.orbital.schedule]
# 学习方案定义

独立模式（实验性） ​

作为独立的 .toml 文件, 结构相同但需要顶层表：

toml
[orbital.puzzles]
# 谜题定义

[orbital.schedule]
# 学习方案定义

文件结构 ​

Orbital 包含两个主要部分：谜题定义 (puzzles) 和学习方案 (schedule).

谜题定义 (puzzles) ​

谜题定义是一个 TOML 表, 键为谜题别名, 值为谜题配置对象.

toml
[__metadata__.orbital.puzzles]
"Recognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:nucleon['content']", secondary = ["eval:nucleon['keyword_note']", "eval:nucleon['note']"], top_dim = ["eval:nucleon['translation']"] }
"SelectMeaning" = { __origin__ = "mcq", __hint__ = "eval:nucleon['content']", mapping = "eval:nucleon['keyword_note']", jammer = "eval:nucleon['keyword_note']", max_riddles_num = "eval:default['mcq']['max_riddles_num']", prefix = "选择正确项: " }
"FillBlank" = { __origin__ = "cloze", __hint__ = "", text = "eval:nucleon['content']", delimiter = "eval:metadata['formation']['delimiter']", min_denominator = "eval:default['cloze']['min_denominator']"}

谜题配置通用字段 ​

字段类型必需描述
__origin__字符串是谜题类型：mcq、cloze、recognition
__hint__字符串否谜题提示文本, 支持宏表达式
其他字段任意否类型特定的配置参数

谜题类型特定配置 ​

MCQ（选择题）配置 ​
toml
"SelectMeaning" = {
  __origin__ = "mcq",
  __hint__ = "eval:nucleon['content']",
  mapping = "eval:nucleon['keyword_note']",
  jammer = "eval:nucleon['keyword_note']",
  max_riddles_num = "eval:default['mcq']['max_riddles_num']",
  prefix = "选择正确项: "
}
  • mapping：字符串或宏表达式, 生成问题-答案映射
  • jammer：字符串或宏表达式, 生成干扰项列表
  • max_riddles_num：整数或宏表达式, 最大题目数量（1-5）
  • prefix：字符串, 题目前缀文本
Cloze（填空题）配置 ​
toml
"FillBlank" = {
  __origin__ = "cloze",
  __hint__ = "",
  text = "eval:nucleon['content']",
  delimiter = "eval:metadata['formation']['delimiter']",
  min_denominator = "eval:default['cloze']['min_denominator']"
}
  • text：字符串或宏表达式, 填空文本
  • delimiter：字符串或宏表达式, 文本分隔符（默认为 /）
  • min_denominator：整数或宏表达式, 填空密度分母（越大填空越少）
Recognition（识别题）配置 ​
toml
"Recognition" = {
  __origin__ = "recognition",
  __hint__ = "",
  primary = "eval:nucleon['content']",
  secondary = ["eval:nucleon['keyword_note']", "eval:nucleon['note']"],
  top_dim = ["eval:nucleon['translation']"]
}
  • primary：字符串或宏表达式, 主要识别内容
  • secondary：字符串数组或宏表达式, 次要识别内容
  • top_dim：字符串数组或宏表达式, 顶部维度内容

学习方案 (schedule) ​

学习方案定义不同的复习阶段和对应的谜题组合.

toml
[__metadata__.orbital.schedule]
quick_review = [["FillBlank", "1.0"], ["SelectMeaning", "0.5"], ["recognition", "1.0"]]
recognition = [["Recognition", "1.0"]]
final_review = [["FillBlank", "0.7"], ["SelectMeaning", "0.7"], ["recognition", "1.0"]]

方案类型 ​

方案名称描述典型用途
quick_review快速复习新记忆单元的首次学习
recognition识别复习仅进行识别练习
final_review最终复习综合性的深度复习

方案格式 ​

每个方案是一个二维数组, 格式为：[["谜题别名", "权重"], ...]

  • 谜题别名：在 puzzles 中定义的别名
  • 权重：字符串形式的浮点数, 表示该谜题在方案中的相对重要性

权重规则：

  • "1.0"：标准权重
  • "0.5"：一半权重（出现概率减半）
  • "0.0"：不出现（但仍可能在其他方案中出现）

宏支持 ​

Orbital 配置支持完整的宏系统, 可以使用以下变量：

变量描述
nucleon当前 Nucleon 的所有字段
metadataNucleon 的 [__metadata__] 内容
default系统默认配置（来自 config.toml）

宏示例 ​

toml
# 使用 Nucleon 字段
text = "eval:nucleon['content']"

# 使用元数据配置
delimiter = "eval:metadata['formation']['delimiter']"

# 使用系统默认值
max_riddles_num = "eval:default['mcq']['max_riddles_num']"

# 字符串插值
prefix = "请翻译: {{nucleon['content']}}"

文件示例 ​

完整示例（嵌入在 Nucleon 中） ​

toml
# Nucleon 文件部分内容
[__metadata__.orbital.puzzles]
"Recognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:nucleon['content']", secondary = ["eval:nucleon['keyword_note']", "eval:nucleon['note']"], top_dim = ["eval:nucleon['translation']"] }
"SelectMeaning" = { __origin__ = "mcq", __hint__ = "eval:nucleon['content']", mapping = "eval:nucleon['keyword_note']", jammer = "eval:nucleon['keyword_note']", max_riddles_num = "eval:default['mcq']['max_riddles_num']", prefix = "选择正确项: " }
"FillBlank" = { __origin__ = "cloze", __hint__ = "", text = "eval:nucleon['content']", delimiter = "eval:metadata['formation']['delimiter']", min_denominator = "eval:default['cloze']['min_denominator']"}

[__metadata__.orbital.schedule]
quick_review = [["FillBlank", "1.0"], ["SelectMeaning", "0.5"], ["recognition", "1.0"]]
recognition = [["Recognition", "1.0"]]
final_review = [["FillBlank", "0.7"], ["SelectMeaning", "0.7"], ["recognition", "1.0"]]

独立 Orbital 文件示例 ​

toml
# orbital_english.toml - 英语学习策略
[orbital.puzzles]
"WordRecognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:nucleon['word']", secondary = ["eval:nucleon['definition']"], top_dim = ["eval:nucleon['example']"] }
"SentenceCloze" = { __origin__ = "cloze", __hint__ = "", text = "eval:nucleon['sentence']", delimiter = " ", min_denominator = 5 }
"GrammarMCQ" = { __origin__ = "mcq", __hint__ = "eval:nucleon['question']", mapping = "eval:nucleon['correct']", jammer = "eval:nucleon['distractors']", max_riddles_num = 3, prefix = "语法选择: " }

[orbital.schedule]
quick_review = [["WordRecognition", "1.0"], ["SentenceCloze", "0.8"]]
recognition = [["WordRecognition", "1.0"]]
final_review = [["GrammarMCQ", "1.0"], ["SentenceCloze", "1.0"], ["WordRecognition", "0.5"]]

编程接口 ​

在 Python 代码中, Orbital 通过 heurams.kernel.particles.orbital 模块中的类型定义表示：

python
from heurams.kernel.particles.orbital import Orbital, OrbitalSchedule

# 创建 Orbital 配置
orbital_config: Orbital = {
    "puzzles": {
        "FillBlank": {
            "__origin__": "cloze",
            "__hint__": "",
            "text": "Hello/World/",
            "delimiter": "/",
            "min_denominator": 3
        }
    },
    "schedule": {
        "quick_review": [["FillBlank", "1.0"]],
        "recognition": [],
        "final_review": [["FillBlank", "1.0"]]
    }
}

# 使用 TypedDict 类型检查
schedule: OrbitalSchedule = orbital_config["schedule"]
puzzles: dict = orbital_config["puzzles"]

Orbital 类型定义 ​

python
from typing import TypedDict

class OrbitalSchedule(TypedDict):
    quick_review: list
    recognition: list
    final_review: list

class Orbital(TypedDict):
    schedule: OrbitalSchedule
    puzzles: dict

策略设计指南 ​

1. 根据内容类型选择谜题 ​

内容类型推荐谜题说明
单词Recognition + Cloze识别拼写 + 填空练习
短语MCQ + Cloze选择含义 + 填空练习
句子Cloze + Recognition填空练习 + 识别理解
概念MCQ + Recognition选择题 + 识别关键点

2. 权重分配原则 ​

  • 快速复习：侧重基础识别（权重 1.0-0.8）
  • 识别复习：仅包含识别类谜题
  • 最终复习：综合所有类型, 适当降低简单谜题权重

3. 宏表达式使用技巧 ​

  • 动态内容：使用 eval:nucleon['field'] 引用 Nucleon 字段
  • 配置继承：使用 eval:default['section']['key'] 继承系统默认值
  • 条件逻辑：在宏表达式中使用三元运算符
    toml
    text = "eval:nucleon.get('sentence', nucleon.get('content', ''))"

版本历史 ​

  • v1 (当前版本)：TOML 格式, 支持三种谜题类型, 宏系统
  • v0：实验性 JSON 格式（已弃用）

注意事项 ​

  1. 谜题别名：在同一个 Orbital 中必须唯一
  2. 权重值：必须是字符串形式的浮点数（如 "1.0"）
  3. 宏安全性：宏表达式在受限环境中执行
  4. 方案完整性：每个方案至少包含一个谜题
  5. 兼容性：确保引用的谜题别名在 puzzles 中已定义

相关文档 ​

© 2025 Wang Zhiyu 保留所有权