Orbital 文件格式协议规范

概述

Orbital 是 HeurAMS 软件项目使用的基于 TOML 的专有文件格式，用于存储学习策略配置和谜题生成规则。

本文档定义了 Orbital v1 版本的文件结构和字段含义。

附上版本参照:

Orbital 版本	HeurAMS 版本	说明
v1 (最新)	0.4.0 - latest	被最新版本使用，支持多种学习策略和谜题配置

MIME 标识

使用的 MIME 标识符:

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

例如

application/vnd.xyz.imwangzhiyu.heurams-orbital.v1+toml

文件结构

Orbital 文件采用 TOML 格式，包含学习策略配置和谜题生成规则。

根级结构

quick_view = [
  ["<谜题类型>", <出现概率或次数>],
  ...
]

recognition = [
  ["<谜题类型>", <出现概率或次数>],
  ...
]

final_review = [
  ["<谜题类型>", <出现概率或次数>],
  ...
]

[puzzle_config]
<谜题类型> = { from = "<来源字段>" }
...

学习策略字段

quick_view

快速复习策略配置，用于快速回顾学习内容。

类型: array[array[string, number]]

说明:

• 每个子数组包含两个元素：谜题类型和出现概率/次数
• 当概率 < 1 时，表示出现概率
• 当概率 ≥ 1 时，表示出现次数
• 执行顺序按照数组元素顺序

recognition

识别训练策略配置，用于训练内容识别能力。

类型: array[array[string, number]]

说明:

• 配置方式同 quick_view
• 主要用于训练对内容的快速识别和回忆

final_review

最终复习策略配置，用于全面复习和巩固。

类型: array[array[string, number]]

说明:

• 配置方式同 quick_view
• 通常包含更全面的谜题类型组合

支持的谜题类型

谜题类型	说明	支持版本
cloze	填空题，从指定字段生成填空	v1
mcq	选择题，从指定字段生成选项	v1
recognition	识别题，要求识别内容	v1

谜题配置字段

[puzzle_config]

谜题生成配置表，定义各谜题类型的生成规则。

cloze

填空题配置

字段:

• from (string): 填空题来源字段

示例:

cloze = { from = "content" }

mcq

选择题配置

字段:

• from (string): 选择题来源字段

示例:

mcq = { from = "keyword_note" }

recognition

识别题配置

字段:

• from (string): 识别题来源字段（可选）

示例:

recognition = { from = "content" }

策略配置说明

概率与次数

• 概率模式 (< 1): 每次练习时按概率决定是否出现该谜题

  • 示例: ["cloze", 0.7] 表示填空题有 70% 的概率出现
  • 示例: ["mcq", 0.5] 表示选择题有 50% 的概率出现

• 次数模式 (≥ 1): 每次练习时固定出现指定次数

  • 示例: ["recognition", 1] 表示识别题固定出现 1 次
  • 示例: ["cloze", 2] 表示填空题固定出现 2 次

执行顺序

谜题按照配置数组的顺序依次执行：

quick_view = [
  ["cloze", 1],      # 先执行填空题 (1次)
  ["mcq", 0.5],      # 然后执行选择题 (50%概率)
  ["recognition", 1] # 最后执行识别题 (1次)
]

文件示例

基础配置示例

# 快速复习策略
quick_view = [
  ["cloze", 1],
  ["mcq", 0.5],
  ["recognition", 1]
]

# 识别训练策略
recognition = [
  ["recognition", 1]
]

# 最终复习策略
final_review = [
  ["cloze", 0.7],
  ["mcq", 0.7],
  ["recognition", 1]
]

# 谜题生成配置
[puzzle_config]
cloze = { from = "content" }
mcq = { from = "keyword_note" }

进阶配置示例

# 密集练习策略
quick_view = [
  ["cloze", 2],      # 填空题出现2次
  ["mcq", 0.8],      # 选择题80%概率出现
  ["recognition", 2] # 识别题出现2次
]

# 专注识别训练
recognition = [
  ["recognition", 3] # 识别题出现3次
]

# 全面复习策略
final_review = [
  ["cloze", 1],      # 填空题1次
  ["mcq", 1],        # 选择题1次
  ["recognition", 1] # 识别题1次
]

# 详细谜题配置
[puzzle_config]
cloze = { from = "content" }
mcq = { from = "keyword_note" }
recognition = { from = "content" }

概率混合配置示例

# 混合概率和次数配置
quick_view = [
  ["cloze", 0.9],    # 90%概率出现填空题
  ["mcq", 2],        # 固定出现2次选择题
  ["recognition", 1] # 固定出现1次识别题
]

recognition = [
  ["recognition", 0.7] # 70%概率出现识别题
]

final_review = [
  ["cloze", 1],
  ["mcq", 1],
  ["recognition", 1]
]

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

使用场景

快速复习

适用于日常的快速回顾，通常配置较少的谜题类型和较低的重复次数。

识别训练

专门训练对内容的快速识别能力，通常只包含识别题。

最终复习

用于学习阶段的全面复习，包含所有谜题类型的完整练习。

兼容性说明

• 字段扩展: 新版本可以添加新的谜题类型和配置字段
• 向后兼容: 新版本应能读取旧版本格式的文件
• 默认行为: 对于未知的谜题类型，系统应忽略而不报错
• 配置验证: 系统应验证配置的合理性，如概率值应在 0-1 范围内