Nucleon 文件格式协议规范

概述

Nucleon 是 HeurAMS 软件项目使用的基于 TOML 的专有源文件格式, 用于存储结构化学习内容, 如内容, 翻译, 注释, 以及推荐的内置学习方案 (orbital) 等.

本文档定义了 Nucleon v2 版本 (被 HeurAMS 0.4.x 支持) 的文件结构和字段含义.

附上版本参照:

Nucleon 版本	HeurAMS 版本	说明
v0	0.1.x - 0.2.9	早期原型验证, 直接基于 json, 无文档
v1	0.3.0 - 0.3.9	被 0.3.x 使用, 分词内容直接作为键名, 字段键名硬编码, 有限的元数据支持, 无文档
v2 (最新)	0.4.0 - latest	被最新版本使用, 定义式字段键名, 参与记忆策略与界面控制, 元数据完整, 有文档
v2d	prototype	动态式内容生成版本格式, 测试中

MIME 标识

使用的 MIME 标识符:

application/vnd.xyz.imwangzhiyu.heurams-nucleon.<版本(含 "v" 字母)>+toml

例如

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

文件头与元数据

["__metadata__"]

根级元数据表, 包含文件的全局信息.

["__metadata__.attribution"]

版权与归属信息:

字段	说明	示例
author	作者标识	"__heurams__"
group	内容分类	"高考古诗文"
name	内容名称	"过秦论"
license	版权协议	"CC-BY-SA 4.0"
desc	内容描述	"高考古诗文 - 过秦论"

["__metadata__.annotation"]

内容字段的键名注册与标注, 将在辨认 (recognition) 界面作为键名的显示字段呈现.

作为例子, 以下是 "建议的古诗文内容单元结构" 的示例说明:

字段	说明
note	笔记
keyword_note	关键词翻译
translation	语句翻译

["__metadata__.config"]

文件配置:

字段	说明	示例
delimiter	内容分隔符	"/"

["__metadata__.presentation"]

内容展示配置:

字段	说明
primary	主要展示字段, 如 ["content"], 此数组应只含有唯一元素
secondery	次要展示字段, 如 ["keyword_note", "note"]
top_dim	顶部展示字段, 如 ["translation"]

["__metadata__.orbital"]

内置学习方案配置, 完整规范请参阅 orbital, 以下是简明文档:

字段	说明
quick_review	快速复习方案, 如 [["cloze", 1], ["mcq", 0.5], ["recognition", 1]]
recognition	识别训练方案
final_review	最终复习方案

在 [["cloze", 1], ["mcq", 0.5], ["recognition", 1]] 中, 子数组的第一项是谜题名称, 第二项是出现概率 (小于 1 时), 和出现次数 (大于等于 1 时), 出现顺序依从主数组元素顺序.

["__metadata__.orbital.puzzle_config"]

谜题生成配置:

字段	说明
cloze	填空题来源字段, 如 { from = "content" }
mcq	选择题来源字段, 如 { from = "keyword_note" }

内容单元结构

每个内容单元以任何唯一标识符 (可以使用原文句子) 作为表名, 例如:

["秦孝公据崤函之固, 拥雍州之地,"]

注意: 内容单元的排序与表名无关, 而是按照文件自上到下顺序排序, 因此 nucleon 并不是标准的 TOML, 还请其他客户端的开发者注意.

对于所含字段, 完全可以自定义, 因为字段的使用范围已在上文元数据 (metadata) 处定义, 类型会被自动推导, 但建议使用 content 作为 "主值".

建议的古诗文内容单元结构

对于每个单元包含以下字段:

字段	类型	说明
note	array[string]	笔记列表, 可空
content	string	分词后的原文, 使用分隔符
translation	string	整句翻译
keyword_note	table[string -> string]	关键词与翻译的映射

注意: 句末应拥有分隔符, 否则将不会将最后一个分隔符后的内容计入分词

示例内容单元

["秦孝公据崤函之固, 拥雍州之地,"]
note = ["点明秦国崛起之初所拥有的地理优势", "给出秦国能够后来统一六国的重要基础"]
content = "秦孝公/据/崤函/之固/, 拥/雍州/之地,/"
translation = "秦孝公占据着崤山和函谷关的险固地势, 拥有雍州的土地,"
keyword_note = {"据" = "占据", "崤函" = "崤山和函谷关", "雍州" = "古代九州之一"}

完整的文件示例

# 过秦论.toml

["__metadata__"]
["__metadata__.attribution"] # 版权元信息
author = "__heurams__"
group = "高考古诗文"
name = "过秦论"
license = "CC-BY-SA 4.0"
desc = "高考古诗文 - 过秦论"

["__metadata__.annotation"] # 键批注
note = "笔记"
keyword_note = "关键词翻译"
translation = "语句翻译"

["__metadata__.config"] # 文件配置
delimiter = "/"

["__metadata__.presentation"] # 内容单元展示配置
primary = ["content"]
secondery = ["keyword_note", "note"]
top_dim = ["translation"]

["__metadata__.orbital"] # 内置的推荐学习方案
quick_review = [["cloze", 1], ["mcq", 0.5], ["recognition", 1]]
recognition = [["recognition", 1]]
final_review = [["cloze", 0.7], ["mcq", 0.7], ["recognition", 1]]

["__metadata__.orbital.puzzle_config"]
cloze = { from = "content"}
mcq = { from = "keyword_note" }

["秦孝公据崤函之固, 拥雍州之地,"]
note = []
content = "秦孝公/据/崤函/之固/, 拥/雍州/之地,/"
translation = "秦孝公占据着崤山和函谷关的险固地势，拥有雍州的土地，"
keyword_note = {"据"="占据", "崤函"="崤山和函谷关", "雍州"="古代九州之一"}

["君臣固守以窥周室,"]
note = []
content = "君臣/固守/以窥/周室,/"
translation = "君臣牢固地守卫着，借以窥视周王室的权力，"
keyword_note = {"窥"="窥视"}

["有席卷天下, 包举宇内, 囊括四海之意, 并吞八荒之心."]
note = []
content = "有/席卷/天下/, 包举/宇内/, 囊括/四海/之意/, 并吞/八荒/之心./"
translation = "有席卷天下，包办天宇之间，囊括四海的意图，并统天下的雄心。"
keyword_note = {"席卷"="像卷席子一样全部卷进去", "包举"="像打包一样全部拿走", "囊括"="像装口袋一样全部装进去", "八荒"="八方荒远之地"}

["当是时也, 商君佐之,"]
note = []
content = "当是时也/, 商君/佐之,/"
translation = "正当这时，商鞅辅佐他，"
keyword_note = {"商君"="商鞅"}

["内立法度, 务耕织, 修守战之具,"]
note = []
content = "内/立法度/, 务/耕织/, 修/守战/之具,/"
translation = "对内建立法规制度，从事耕作纺织，修造防守和进攻的器械；"
keyword_note = {"法度"="法规制度", "务"="从事", "耕织"="耕作纺织", "守战之具"="防守和进攻的器械"}

["外连衡而斗诸侯."]
note = []
content = "外/连衡/而斗/诸侯./"
translation = "对外实行连衡策略，使诸侯自相争斗。"
keyword_note = {"连衡"="连横策略", "斗"="使...相斗"}

["于是秦人拱手而取西河之外."]
note = []
content = "于是/秦人/拱手/而取/西河/之外./"
translation = "因此，秦人轻而易举地夺取了黄河以西的土地。"
keyword_note = {"拱手"="两手相合，形容毫不费力", "西河"="黄河以西地区"}