HeurAMS

Appearance

高级功能 ​

本文介绍 HeurAMS 的高级特性, 包括模板系统、宏、插件架构、自动化脚本等.

模板系统深度指南 ​

模板结构 ​

模板文件 (data/template/*.toml) 定义记忆内容的结构和呈现方式：

toml
# 示例：古诗词模板
[__metadata__]
[__metadata__.attribution]
desc = "古诗词学习模板"

[__metadata__.formation]
tts_text = "eval:nucleon['title'] + ', ' + nucleon['author'] + ', ' + nucleon['content']"

[__metadata__.orbital.puzzles]
"朗读背诵" = {
    __origin__ = "recognition",
    primary = "eval:nucleon['content']",
    secondary = ["eval:nucleon['translation']"]
}
"填空测试" = {
    __origin__ = "cloze",
    text = "eval:nucleon['content']",
    delimiter = "/",
    min_denominator = 3
}

模板字段说明 ​

元数据部分 ([__metadata__]) ​

  • attribution：模板描述、版本等信息
  • annotation：字段注释, 用于界面显示
  • formation：内容格式化规则, 如 TTS 文本生成

轨道配置 ([__metadata__.orbital]) ​

  • puzzles：定义可用的谜题类型及其参数
  • schedule：推荐的学习方案序列

动态表达式 (eval:) ​

在模板中使用 eval: 前缀执行动态表达式：

toml
# 访问 Nucleon 字段
primary = "eval:nucleon['content']"

# 访问配置默认值
max_riddles_num = "eval:default['mcq']['max_riddles_num']"

# 简单运算
tts_text = "eval:nucleon['title'] + ' by ' + nucleon['author']"

# 条件逻辑
hint = "eval:'提示：' + nucleon['hint'] if 'hint' in nucleon else ''"

宏系统 ​

宏定义 ​

宏是运行时替换的动态占位符, 在内容中使用 格式：

toml
# Nucleon 中使用宏
question = "{{random_number}} 的平方是多少？"
answer = "{{eval:str(int(macro_context['random_number'])**2)}}"

内置宏 ​

宏名称说明示例输出
当前日期2025-12-18
当前时间14:30:25
随机整数 (1-100)42
从列表中随机选择"选项A"
随机排序列表["B", "A", "C"]

自定义宏 ​

通过插件系统添加自定义宏（开发中）：

python
# 示例：自定义宏插件
from heurams.kernel.macros import register_macro

@register_macro("current_year")
def current_year_macro(context):
    import datetime
    return str(datetime.datetime.now().year)

Provider 插件架构 ​

架构概述 ​

HeurAMS 使用 Provider-Service 架构, 支持可插拔的后端实现：

用户界面 → 服务接口 → Provider 实现 → 外部服务
    ↓           ↓           ↓           ↓
   TUI    →  TTSService → EdgeTTS → 微软 TTS
            AudioService → Playsound → 系统音频

实现新的 Provider ​

  1. 创建 Provider 类：
python
# providers/tts/my_tts.py
from heurams.providers.tts.base import BaseTTSProvider

class MyTTSProvider(BaseTTSProvider):
    name = "mytts"
    
    def synthesize(self, text, voice=None):
        # 实现 TTS 合成逻辑
        return audio_data
  1. 注册 Provider：
python
# providers/tts/__init__.py
from .my_tts import MyTTSProvider

providers = {
    "mytts": MyTTSProvider,
    "edgetts": EdgeTTSProvider,
}
  1. 配置使用：
toml
# config/config.toml
[services]
tts = "mytts"

脚本与自动化 ​

Python API ​

HeurAMS 提供 Python API 用于脚本控制：

python
import heurams

# 初始化上下文
with heurams.ConfigContext(config_path):
    # 加载内容
    atoms = heurams.load_atoms()
    
    # 执行复习
    for atom in atoms.get_due():
        result = atom.review(feedback=3)
        print(f"Reviewed: {atom.nucleon.id}, next: {result.next_date}")
    
    # 导出统计
    stats = heurams.get_statistics()
    print(f"Retention rate: {stats.retention_rate:.1%}")

命令行工具 ​

内置命令行工具：

bash
# 批量导入
python -m heurams.tools.import_csv data.csv --tags "数学,公式"

# 导出统计报告
python -m heurams.tools.export_stats --format json --output stats.json

# 清理缓存
python -m heurams.tools.clean_cache --older-than 30

# 数据迁移
python -m heurams.tools.migrate --from-version 0.3 --to-version 0.4

自动化脚本示例 ​

每日备份 ​

bash
#!/bin/bash
# daily_backup.sh
BACKUP_DIR="/backup/heurams/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"
cp -r ./data "$BACKUP_DIR/"
cp ./config/config.toml "$BACKUP_DIR/"
echo "Backup completed: $BACKUP_DIR"

批量添加标签 ​

python
# add_tags.py
import heurams
import sys

def add_tags_to_directory(dir_path, tags):
    with heurams.ConfigContext():
        for nucleon in heurams.load_nucleons(dir_path):
            current_tags = nucleon.get('tags', [])
            nucleon['tags'] = list(set(current_tags + tags))
            nucleon.save()

if __name__ == "__main__":
    add_tags_to_directory(sys.argv[1], sys.argv[2].split(','))

性能优化 ​

缓存策略 ​

TTS 缓存 ​

  • 位置：data/cache/tts/
  • 策略：基于文本内容和语音参数哈希
  • 清理：自动清理30天前的文件

算法状态缓存 ​

  • 内存缓存最近访问的 Electron 状态
  • 减少文件 I/O, 提高复习速度

数据库优化 ​

对于大量内容（>1000条）, 建议：

  1. 分目录存储：按主题分成多个子目录
  2. 定期归档：将已掌握的内容移动到归档目录
  3. 索引文件：创建内容索引加速搜索

内存管理 ​

  • 惰性加载：仅在需要时加载内容文件
  • 智能卸载：长时间未访问的内容从内存释放
  • 批量操作：减少频繁的磁盘写入

扩展开发 ​

创建新谜题类型 ​

  1. 定义谜题类：
python
# kernel/puzzles/wordsearch.py
from .base import BasePuzzle

class WordSearchPuzzle(BasePuzzle):
    name = "wordsearch"
    
    def generate(self, nucleon, orbital):
        # 生成字谜逻辑
        pass
    
    def evaluate(self, user_input, correct_answer):
        # 评估用户输入
        pass
  1. 注册到系统：
python
# kernel/puzzles/__init__.py
from .wordsearch import WordSearchPuzzle

puzzle_types = {
    "wordsearch": WordSearchPuzzle,
    "mcq": MCQPuzzle,
    # ...
}

创建新算法 ​

  1. 实现算法类：
python
# kernel/algorithms/my_algo.py
from .base import BaseAlgorithm

class MyAlgorithm(BaseAlgorithm):
    algo_name = "MyAlgo"
    
    @classmethod
    def revisor(cls, algodata, feedback, is_new_activation=False):
        # 实现间隔计算逻辑
        pass
  1. 配置使用：
toml
[algorithm]
default = "MyAlgo"

集成与同步 ​

云同步（计划中） ​

未来版本计划支持：

  • WebDAV：与 Nextcloud、OwnCloud 等同步
  • Git：版本控制同步, 支持分支和合并
  • 自定义 API：通过插件支持其他服务

外部工具集成 ​

Anki 兼容性 ​

  • 导入 .apkg 文件（开发中）
  • 导出为 Anki 兼容格式
  • 双向同步插件

笔记软件集成 ​

  • Obsidian：通过插件同步标记文件
  • Logseq：兼容其块引用语法
  • Roam Research：导出为 JSON 格式

安全考虑 ​

数据加密 ​

敏感数据（如 API 密钥）建议：

  1. 环境变量：存储密钥在环境变量中
  2. 加密配置文件：使用操作系统密钥链
  3. 访问控制：配置文件权限设置为 600

隐私保护 ​

  • 本地处理：所有数据默认在本地处理
  • 可选的匿名化：导出时移除个人信息
  • 透明数据流：明确记录数据发送到外部服务

故障排除与调试 ​

启用调试模式 ​

toml
# config/config.toml
persist_to_file = 1
daystamp_override = -1  # 或设置具体日期用于测试
quick_pass = 0  # 禁用一键通过

日志分析 ​

日志文件 heurams.log 包含详细信息：

bash
# 查看最新日志
tail -f heurams.log

# 搜索错误
grep -i error heurams.log

# 按模块筛选
grep "kernel.algorithms" heurams.log

性能分析 ​

bash
# 内存使用
python -m heurams.tools.profile --memory

# 执行时间
python -m heurams.tools.profile --timing

# 生成性能报告
python -m heurams.tools.profile --output profile.html

社区贡献 ​

插件开发 ​

欢迎贡献：

  1. Provider 插件：新的 TTS、音频、LLM 后端
  2. 谜题插件：创新的评估方式
  3. 算法插件：新的间隔重复算法
  4. 工具插件：数据导入导出、分析工具

模板分享 ​

将优秀模板提交到社区仓库, 帮助其他用户.

文档改进 ​

完善本文档, 添加使用案例、教程等.

下一步 ​

© 2025 Wang Zhiyu 保留所有权