HeurAMS

Appearance

Nucleon 文件规范 ​

Nucleon 是 HeurAMS 中用于存储记忆内容的源文件格式. 每个 Nucleon 文件对应一个记忆单元, 包含了该单元的所有内容和元数据.

文件格式 ​

Nucleon 文件使用 TOML v1.0.0 格式, 文件扩展名为 .toml.

推荐 MIME 类型 ​

application/vnd.xyz.imwangzhiyu.heurams-nucleon.v5+toml

文件结构 ​

一个完整的 Nucleon 文件包含以下主要部分：

  1. 元数据区块 ([__metadata__]) - 系统保留字段
  2. 内容载荷 - 用户定义的自由字段
  3. 宏支持 - 动态内容生成

元数据区块 ​

元数据区块使用 [__metadata__] 表头定义, 包含以下子表：

toml
[__metadata__]

[__metadata__.attribution]        # 属性信息
desc = "文件描述"

[__metadata__.annotation]         # 键批注（目前为空表, 保留字段）

[__metadata__.formation]          # 文件配置
# delimiter = "/"                 # 用于 Cloze 谜题的分隔符
# tts_text = "eval:nucleon['content'].replace('/', '')"  # TTS 文本生成规则

[__metadata__.orbital.puzzles]    # 谜题定义
# "Recognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:nucleon['content']", secondary = ["eval:nucleon['keyword_note']", "eval:nucleon['note']"], top_dim = ["eval:nucleon['translation']"] }

[__metadata__.orbital.schedule]   # 学习方案定义
# quick_review = [["FillBlank", "1.0"], ["SelectMeaning", "0.5"], ["recognition", "1.0"]]

元数据字段说明 ​

  • [__metadata__.attribution]：文件属性信息

    • desc：文件描述（字符串）

  • [__metadata__.annotation]：保留字段, 当前版本未使用

  • [__metadata__.formation]：文件格式配置

    • delimiter：字符串分隔符, 用于 Cloze 谜题（默认为 /）
    • tts_text：TTS 音频生成规则, 支持宏表达式

  • [__metadata__.orbital.puzzles]：谜题定义表

    • 键为谜题别名（字符串）
    • 值为谜题配置字典, 包含：
      • __origin__：谜题类型（mcq、cloze、recognition）
      • __hint__：谜题提示文本
      • 其他类型特定参数（详见 Puzzle 规范）

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

    • quick_review：快速复习方案（二维数组）
    • recognition：识别复习方案（二维数组）
    • final_review：最终复习方案（二维数组）
    • 每个方案项格式：["谜题别名", "权重"]

内容载荷 ​

内容载荷是 Nucleon 文件的主体部分, 包含用户定义的自由字段. 这些字段可以通过 nucleon['字段名'] 的方式在宏表达式中引用.

示例：

toml
content = "Hello World"
translation = "你好世界"
keyword_note = "greeting, introduction"
note = "This is a basic greeting phrase."
difficulty = "easy"
category = "phrase"

字段命名规则：

  • 使用小写字母、数字和下划线
  • 建议使用有意义的描述性名称
  • 避免使用系统保留字段名（以 __ 开头）

宏系统 ​

Nucleon 支持动态内容生成, 通过两种宏语法实现：

1. eval: 前缀语法 ​

在字符串值前添加 eval: 前缀, 表示该字符串需要被求值.

toml
tts_text = "eval:nucleon['content'].replace('/', '')"
max_riddles_num = "eval:default['mcq']['max_riddles_num']"

2. 语法 ​

在字符串中使用 进行插值.

toml
question = "What does {{nucleon['content']}} mean?"

可用的宏变量 ​

变量名类型描述
nucleonNucleon 对象当前 Nucleon 的所有字段
metadata字典[__metadata__] 中的所有内容
default字典系统默认配置（来自 config.toml）

宏执行环境 ​

宏表达式在受限的 Python 环境中执行：

  • 只能访问 nucleon、metadata、default 三个变量
  • 支持基本的 Python 表达式和字符串操作
  • 不支持文件 I/O、网络访问等危险操作
  • 执行错误会返回错误信息字符串

文件示例 ​

完整的 Nucleon 文件示例：

toml
# Nucleon 是 HeurAMS 软件项目使用的基于 TOML 的专有源文件格式, 版本 5
# 建议使用的 MIME 类型: application/vnd.xyz.imwangzhiyu.heurams-nucleon.v5+toml

[__metadata__]

[__metadata__.attribution]
desc = "英语基础问候语"

[__metadata__.annotation]

[__metadata__.formation]
delimiter = "/"
tts_text = "eval:nucleon['content'].replace('/', '')"

[__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"]]

# 内容载荷
content = "Hello/World/"
translation = "你好/世界/"
keyword_note = "greeting, introduction, basic"
note = "This is a basic greeting phrase. The slash indicates cloze boundaries."
difficulty = "easy"
category = "phrase"
created_date = "2023-10-01"

编程接口 ​

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

python
from heurams.kernel.particles.nucleon import Nucleon

# 从字典创建 Nucleon
nucleon = Nucleon(
    ident="unique_id",
    payload={"content": "Hello World", "translation": "你好世界"},
    metadata={}
)

# 访问字段
print(nucleon["content"])  # "Hello World"
print(nucleon.ident)       # "unique_id"

# 迭代字段
for key in nucleon:
    print(key, nucleon[key])

# 执行宏表达式
nucleon.do_eval()

Nucleon 类方法 ​

方法描述
__init__(ident, payload, metadata)初始化 Nucleon
__getitem__(key)获取字段值
__iter__()迭代字段键
__len__()返回字段数量
do_eval()执行所有宏表达式
placeholder()创建占位 Nucleon

版本历史 ​

  • v5 (当前版本)：支持 TOML 格式、宏系统、元数据区块
  • v4：早期 JSON 格式（已弃用）
  • v1-v3：实验性格式

注意事项 ​

  1. 文件编码：使用 UTF-8 编码
  2. 大小限制：建议单个文件不超过 10KB
  3. 字段深度：TOML 表嵌套不超过 3 层
  4. 宏安全性：宏表达式在受限环境中执行
  5. 向后兼容：新版本保持对旧格式的读取兼容性

相关文档 ​

© 2025 Wang Zhiyu 保留所有权