fix: 改进代码

实验性 SM-15M 逆向工程算法实现

.gitignore

@@ -11,15 +11,16 @@ electron/test.toml
 build/
 dist/
 old/
-
-# Project specific directories
 # config/
 data/cache/
 data/electron/
 data/nucleon/
-!data/nucleon/test*
+data/global/
+!data/nucleon/TEST*
 data/orbital/
+config/config_dev.toml
 AGENTS.md
+*.log.1
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

CONTRIBUTING.md

@@ -10,13 +10,15 @@
    - `dev` 分支: 开发版本
    - 功能分支: 从 `dev` 分支创建, 命名格式为 `feature/描述` 或 `fix/描述` 或 `refactor/描述`
 2. **代码风格**: 
-   - 请使用 Black 格式化代码
+   - 请使用 Black 与 isort 格式化代码
    - 遵循 PEP 8 规范
    - 添加适当的文档字符串  
 3. **提交消息**: 
    - 使用简体中文或英文撰写清晰的提交消息
    - 格式: 遵循 Conventional Commits 规范
-
+4. **合并方式**:
+   - 不使用 Fast-forward 合并
+   - 可以设置 `git config merge.ff false`
 ## 设置开发环境
 
 ```bash

README.md

@@ -1,18 +1,20 @@
 # 潜进 (HeurAMS) - 启发式辅助记忆程序
 
 ## 概述
-"潜进" (HeurAMS: Heuristic Auxiliary Memorizing Scheduler, 启发式记忆辅助调度器) 是为习题册, 古诗词, 及其他问答/记忆/理解型知识设计的多用途辅助记忆软件, 提供动态规划的优化记忆方案  
+"潜进" (HeurAMS: Heuristic Auxiliary Memorizing Scheduler, 启发式记忆辅助调度器) 是为习题册, 古诗词, 及其他问答/记忆/理解型知识设计的开放源代码多用途辅助记忆软件, 提供动态规划的优化记忆方案  
 
 ## 关于此仓库
-"潜进" 软件组项目包含多个子项目  
-此仓库包含了 "潜进" 项目的核心和基于 Textual 的基本用户界面的实现  
+本仓库为 "潜进" 软件组项目的核心部分, 包含核心功能模块以及基于 Textual 框架的基础用户界面(heurams.interface)实现  
+除了通过用户界面进行学习外, 你也可以在 Python 中导入 `heurams` 库, 使用其中实现的状态机, 算法迭代器和数据模型构建辅助记忆功能  
+本仓库在 AGPLv3 下开放源代码(详见 LICENSE 文件)  
 
-## 开发进程
+## 版本日志
 - 0.0.x: 简易调度器实现与最小原型.  
 - 0.1.x: 命令行操作的调度器.  
-- 0.2.x: 使用 Textual 构建富文本终端用户界面, 项目可行性验证, 采用 SM-2 原始算法, 评估方式为用户自评估的原型.  
-- 0.3.x: 简单的多文件项目, 创建了记忆内容/算法数据结构, 基于 SM-2 改进算法的自动复习测评评估. 重点设计古诗文记忆理解功能, 以及 TUI 界面实现, 简单的 TTS 集成.  
-- 0.4.x: 使用模块管理解耦设计, 增加文档与类型标注, 采用上下文设计模式的隐式依赖注入与遵从 IoC, 注册器设计的算法与功能实现, 支持其他调度算法模块 (SM-2, FSRS) 与谜题模块, 采用日志调试, 更新文件格式, 引入动态数据模式(宏驱动的动态内容生成), 与基于文件的策略调控, 更佳的用户数据处理, 加入模块化扩展集成, 将算法数据格式换为 json 提高性能, 采用 provider-service 抽象架构, 支持切换服务提供者, 整体兼容性改进.  
+- 0.2.x: 使用 Textual 构建富文本终端用户界面; 项目可行性验证; 采用 SM-2 原始算法, 评估方式为用户自评估原型.  
+- 0.3.x: 简单的多文件项目; 创建了记忆内容/算法数据结构; 基于 SM-2 改进算法的自动复习测评评估; 重点设计古诗文记忆理解功能; TUI 界面改进; 简单的 TTS 集成.  
+- 0.4.x: 开发目标转为多用途; 使用模块管理解耦设计; 增加文档与类型标注; 采用上下文设计模式的隐式依赖注入与遵从 IoC, 注册器设计的算法与功能实现; 支持其他调度算法模块 (SM-2, SM-18M 逆向工程实现, FSRS) 与谜题模块; 采用日志调试; 更新文件格式; 引入动态数据模式(宏驱动的动态内容生成), 与基于文件的策略调控; 更佳的用户数据处理; 加入模块化扩展集成; 将算法数据格式换为 json 提高性能; 采用 provider-service 抽象架构, 支持切换服务提供者; 整体兼容性改进.  
+- 0.5.x: 以仓库(repo)对象作为文件系统与运行时对象间的桥梁, 提高解耦性与性能; 使用具有列表 - 字典 API 同步特性的 "Lict" 对象作为 Repo 数据的内部存储; 将粒子对象作为纯运行时对象, 数据通过引用自动同步至 Repo, 减少负担; 实现声音形式回顾 "电台" 功能; 改进数据存储结构, 实现选择性持久化; 增强可配置性; 使用 Transitions 状态机库重新实现 reactor 状态机, 增强可维护性; 实现整体回顾记忆功能, 与队列式记忆功能并列; 加入状态机快照功能(基于 pickle), 使中断的记忆流程得以恢复; 增加"整体文章引用"功能, 实现从一篇长文本中摘取内容片段记忆并在原文中高亮查看的组织操作.  
 > 下一步?  
 > 使用 Flutter 构建酷酷的现代化前端, 增加云同步/文档源服务...
 
@@ -30,6 +32,7 @@
 - 自然语音: 集成微软神经网络文本转语音 (TTS) 技术
 - 多种谜题类型: 选择题 (MCQ)、填空题 (Cloze)、识别题 (Recognition)
 - 动态内容生成: 支持宏驱动的模板系统, 根据上下文动态生成题目
+- 云同步支持: 通过 WebDAV 协议同步数据到远程服务器
 
 ### 实用用户界面
 - 响应式 Textual 框架构建的跨平台 TUI 界面
@@ -82,11 +85,27 @@ python -m heurams.interface
 
 ## 配置
 
-配置文件位于 `config/config.toml`（相对于工作目录）. 如果不存在, 会使用内置的默认配置. 
+配置文件位于 `config/config.toml`(相对于工作目录). 如果不存在, 会使用内置的默认配置.
+
+### 同步配置
+同步功能支持 WebDAV 协议，可在配置文件的 `[sync.webdav]` 段进行配置：
+```toml
+[sync.webdav]
+enabled = false
+url = ""                    # WebDAV 服务器地址
+username = ""               # 用户名
+password = ""               # 密码
+remote_path = "/heurams/"   # 远程路径
+sync_mode = "bidirectional" # 同步模式: bidirectional/upload_only/download_only
+conflict_strategy = "newer" # 冲突策略: newer/ask/keep_both
+verify_ssl = true           # SSL 证书验证
+```
+
+启用同步后，可通过应用内的同步工具进行数据备份和恢复。 
 
 ## 项目结构
 
-### 架构图
+### 架构图(待更新 0.5.0)
 
 以下 Mermaid 图展示了 HeurAMS 的主要组件及其关系: 
 
@@ -104,6 +123,7 @@ graph TB
         Timer[时间服务]
         AudioService[音频服务]
         TTSService[TTS服务]
+        SyncService[同步服务]
         OtherServices[其他服务]
     end
 
@@ -146,7 +166,7 @@ graph TB
     Algorithms --> Files
 ```
 
-### 目录结构
+### 目录结构(待更新 0.5.0)
 ```
 src/heurams/
 ├── __init__.py              # 包入口点
@@ -156,7 +176,8 @@ src/heurams/
 │   ├── logger.py            # 日志系统
 │   ├── timer.py             # 时间服务
 │   ├── audio_service.py     # 音频播放抽象
-│   └── tts_service.py       # 文本转语音抽象
+│   ├── tts_service.py       # 文本转语音抽象
+│   └── sync_service.py      # WebDAV 同步服务
 ├── kernel/                  # 核心业务逻辑
 │   ├── algorithms/          # 间隔重复算法 (FSRS, SM2)
 │   ├── particles/           # 数据模型 (Atom, Electron, Nucleon, Orbital)

data/config/config.toml

@@ -0,0 +1,59 @@
+# [调试] 将更改保存到文件
+persist_to_file = 1
+
+# [调试] 覆写时间, 设为 -1 以禁用
+daystamp_override = -1
+timestamp_override = -1
+
+# [调试] 一键通过
+quick_pass = 1
+
+# 对于每个项目的默认新记忆原子数量
+scheduled_num = 8
+
+# UTC 时间戳修正 仅用于 UNIX 日时间戳的生成修正, 单位为秒
+timezone_offset = +28800 # 中国标准时间 (UTC+8)
+
+[interface]
+
+[interface.memorizor]
+autovoice = true # 自动语音播放, 仅限于 recognition 组件
+
+[algorithm]
+default = "SM-2" # 主要算法; 可选项: SM-2, SM-15M, FSRS
+
+[puzzles] # 谜题默认配置
+
+[puzzles.mcq]
+max_riddles_num = 2
+
+[puzzles.cloze]
+min_denominator = 3
+
+[paths] # 相对于配置文件的 ".." (即工作目录) 而言 或绝对路径
+data = "./data"
+cache = "./data/cache"
+config = "./data/config"
+global = "./data/global"
+repo = "./data/repo"
+[services] # 定义服务到提供者的映射
+audio = "playsound" # 可选项: playsound(通用), termux(仅用于支持 Android Termux), mpg123(TODO)
+tts = "edgetts" # 可选项: edgetts
+llm = "openai" # 可选项: openai
+sync = "webdav" # 可选项: 留空, webdav
+
+[providers.tts.edgetts] # EdgeTTS 设置
+voice = "zh-CN-XiaoxiaoNeural" # 可选项: zh-CN-YunjianNeural (男声), zh-CN-XiaoxiaoNeural (女声)
+
+[providers.llm.openai] # 与 OpenAI 相容的语言模型接口服务设置
+url = ""
+key = ""
+
+[providers.sync.webdav] # WebDAV 同步设置
+url = ""
+username = ""
+password = ""
+remote_path = "/heurams/"
+verify_ssl = true
+
+[sync]

data/repo/test/algodata.json

@@ -0,0 +1 @@
+{}

data/repo/test/manifest.toml

@@ -0,0 +1,3 @@
+title = "测试单元: 过秦论"
+author = "__heurams__"
+desc = "高考古诗文: 过秦论"

data/repo/test/payload.toml

@@ -0,0 +1,11 @@
+["秦孝公据崤函之固, 拥雍州之地,"]
+note = []
+content = "秦孝公/据/崤函/之固/, 拥/雍州/之地,/"
+translation = "秦孝公占据着崤山和函谷关的险固地势，拥有雍州的土地，"
+keyword_note = {"据"="占据", "崤函"="崤山和函谷关", "雍州"="古代九州之一"}
+
+["君臣固守以窥周室,"]
+note = []
+content = "君臣/固守/以窥/周室,/"
+translation = "君臣牢固地守卫着，借以窥视周王室的权力，"
+keyword_note = {"窥"="窥视"}

data/repo/test/schedule.toml

@@ -0,0 +1,9 @@
+schedule = ["quick_review", "recognition", "final_review"]
+[phases]
+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"]]
+[annotation]
+"quick_review" = "复习旧知"
+"recognition" = "新知识"
+"final_review" = "总复习"

data/repo/test/typedef.toml

@@ -0,0 +1,17 @@
+[annotation]
+note = "笔记"
+keyword_note = "关键词翻译"
+translation = "语句翻译"
+delimiter = "分隔符"
+content = "内容"
+tts_text = "文本转语音文本"
+
+[common]
+delimiter = "/"
+tts_text = "eval:payload['content'].replace('/', '')"
+
+[common.puzzles] # 谜题定义
+# 我们称 "Recognition" 为 recognition 谜题的 alia
+"Recognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:payload['content']", secondary = ["eval:payload['keyword_note']", "eval:payload['note']"], top_dim = ["eval:payload['translation']"] }
+"SelectMeaning" = { __origin__ = "mcq", __hint__ = "eval:payload['content']", primary = "eval:payload['content']", mapping = "eval:payload['keyword_note']", jammer = "eval:list(payload['keyword_note'].values())", max_riddles_num = "eval:default['mcq']['max_riddles_num']", prefix = "选择正确项: " }
+"FillBlank" = { __origin__ = "cloze", __hint__ = "", text = "eval:payload['content']", delimiter = "eval:nucleon['delimiter']", min_denominator = "eval:default['cloze']['min_denominator']"}

data/template/blank.toml

@@ -1,23 +0,0 @@
-# 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" 为 recognition 谜题的 alia
-#"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"]]

examples/data/config/config.toml

@@ -14,6 +14,14 @@ scheduled_num = 8
 # UTC 时间戳修正 仅用于 UNIX 日时间戳的生成修正, 单位为秒
 timezone_offset = +28800 # 中国标准时间 (UTC+8)
 
+[interface]
+
+[interface.memorizor]
+autovoice = true # 自动语音播放, 仅限于 recognition 组件
+
+[algorithm]
+default = "SM-2" # 主要算法; 可选项: SM-2, SM-15M, FSRS
+
 [puzzles] # 谜题默认配置
 
 [puzzles.mcq]
@@ -23,17 +31,26 @@ max_riddles_num = 2
 min_denominator = 3
 
 [paths] # 相对于配置文件的 ".." (即工作目录) 而言 或绝对路径
-nucleon_dir = "./data/nucleon"
-electron_dir = "./data/electron"
-orbital_dir = "./data/orbital"
-cache_dir = "./data/cache"
-template_dir = "./data/template"
+data = "./data"
 
 [services] # 定义服务到提供者的映射
 audio = "playsound" # 可选项: playsound(通用), termux(仅用于支持 Android Termux), mpg123(TODO)
 tts = "edgetts" # 可选项: edgetts
 llm = "openai" # 可选项: openai
+sync = "webdav" # 可选项: 留空, webdav
+
+[providers.tts.edgetts] # EdgeTTS 设置
+voice = "zh-CN-XiaoxiaoNeural" # 可选项: zh-CN-YunjianNeural (男声), zh-CN-XiaoxiaoNeural (女声)
 
 [providers.llm.openai] # 与 OpenAI 相容的语言模型接口服务设置
 url = ""
 key = ""
+
+[providers.sync.webdav] # WebDAV 同步设置
+url = ""
+username = ""
+password = ""
+remote_path = "/heurams/"
+verify_ssl = true
+
+[sync]

examples/jiebatest.py

@@ -0,0 +1,14 @@
+# encoding=utf-8
+import jieba
+
+# jieba.enable_paddle()# 启动paddle模式。 0.40版之后开始支持，早期版本不支持
+strs = ["我来到北京清华大学", "乒乓球拍卖完了", "中国科学技术大学"]
+# for str in strs:
+#    seg_list = jieba.cut(str,use_paddle=True) # 使用paddle模式
+#    print("Paddle Mode: " + '/'.join(list(seg_list)))
+
+seg_list = jieba.cut("秦孝公据崤函之固, 拥雍州之地", cut_all=False)
+print("Default Mode: " + "/ ".join(seg_list))  # 精确模式
+
+seg_list = jieba.cut("他来到了网易杭研大厦")  # 默认是精确模式
+print(", ".join(seg_list))

examples/repo.ipynb

@@ -0,0 +1,719 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "51b89355",
+   "metadata": {},
+   "source": [
+    "# 演练场\n",
+    "此笔记本将带你了解 repomgr 与 particles 对象相关操作"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f5c49014",
+   "metadata": {},
+   "source": [
+    "# 从一个例子开始\n",
+    "## 了解文件结构\n",
+    "了解一下文件结构"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "a5ed9864",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\u001b[01;34m.\u001b[0m\n",
+      "├── \u001b[00mrepo.ipynb\u001b[0m\n",
+      "└── \u001b[01;34mtest_repo\u001b[0m\n",
+      "    ├── \u001b[00malgodata.json\u001b[0m\n",
+      "    ├── \u001b[00mmanifest.toml\u001b[0m\n",
+      "    ├── \u001b[00mpayload.toml\u001b[0m\n",
+      "    ├── \u001b[00mschedule.toml\u001b[0m\n",
+      "    └── \u001b[00mtypedef.toml\u001b[0m\n",
+      "\n",
+      "2 directories, 6 files\n"
+     ]
+    }
+   ],
+   "source": [
+    "!tree # 了解文件结构"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4e10922b",
+   "metadata": {},
+   "source": [
+    "如果你先前运行了单元格, 请运行下面一格清理."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "9777730e",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "zsh:1: no matches found: heurams.log*\n"
+     ]
+    }
+   ],
+   "source": [
+    "!rm -rf test_new_repo\n",
+    "!rm -rf heurams.log*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "058c098f",
+   "metadata": {},
+   "source": [
+    "## 导入模块\n",
+    "导入所需模块, 你会看到欢迎信息, 标示了库所使用的配置.  \n",
+    "HeurAMS 在基础设施也使用配置文件实现隐式的依赖注入.  "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "bf1b00c8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "欢迎使用 HeurAMS 及其组件!\n",
+      "rootdir: /mnt/data/Devel/HeurAMS/HeurAMS/src/heurams\n",
+      "workdir: /mnt/data/Devel/HeurAMS/HeurAMS/examples\n",
+      "未能加载自定义用户配置\n"
+     ]
+    }
+   ],
+   "source": [
+    "import heurams.kernel.repolib as repolib  # 这是 RepoLib 子模块, 用于管理和结构化 repo(中文含义: 仓库) 数据结构与本地文件间的联系\n",
+    "import heurams.kernel.particles as pt  # 这是 Particles(中文含义: 粒子) 子模块, 用于运行时的记忆管理操作\n",
+    "from pathlib import (\n",
+    "    Path,\n",
+    ")  # 这是 Python 的 Pathlib 模块, 用于表示文件路径, 在整个项目中, 都使用此模块表示路径"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ea1f68bb",
+   "metadata": {},
+   "source": [
+    "## 运行时检查\n",
+    "如你所见, repo 在文件系统内存储为一个文件夹.  \n",
+    "因此在载入之前, 首先要检查这是否是一个合乎标准的 repo 文件夹.  "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "897b62d7",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "这是一个 合规 的 repo!\n"
+     ]
+    }
+   ],
+   "source": [
+    "is_vaild = repolib.Repo.check_repodir(Path(\"./test_repo\"))\n",
+    "print(f\"这是一个 {'合规' if is_vaild else '不合规'} 的 repo!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "24a19991",
+   "metadata": {},
+   "source": [
+    "## 加载仓库\n",
+    "接下来, 正式加载 repo."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "708ae7e4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_repo = repolib.Repo.create_from_repodir(Path(\"./test_repo\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "474f8eb7",
+   "metadata": {},
+   "source": [
+    "## 导出为字典\n",
+    "作为一个数据容器, repo 相应地建立了导入和导出的功能.  \n",
+    "我们刚刚从本地文件夹导入了一个 repo.  \n",
+    "现在试试导出为一个字典."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "a11115fb",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{'algodata': [('君臣固守以窥周室,', {}), ('秦孝公据崤函之固, 拥雍州之地,', {})],\n",
+      " 'manifest': {'author': '__heurams__',\n",
+      "              'desc': '高考古诗文: 过秦论',\n",
+      "              'title': '测试单元: 过秦论'},\n",
+      " 'payload': [('君臣固守以窥周室,',\n",
+      "              {'content': '君臣/固守/以窥/周室,/',\n",
+      "               'keyword_note': {'窥': '窥视'},\n",
+      "               'note': [],\n",
+      "               'translation': '君臣牢固地守卫着，借以窥视周王室的权力，'}),\n",
+      "             ('秦孝公据崤函之固, 拥雍州之地,',\n",
+      "              {'content': '秦孝公/据/崤函/之固/, 拥/雍州/之地,/',\n",
+      "               'keyword_note': {'崤函': '崤山和函谷关', '据': '占据', '雍州': '古代九州之一'},\n",
+      "               'note': [],\n",
+      "               'translation': '秦孝公占据着崤山和函谷关的险固地势，拥有雍州的土地，'})],\n",
+      " 'schedule': {'phases': {'final_review': [['FillBlank', '0.7'],\n",
+      "                                          ['SelectMeaning', '0.7'],\n",
+      "                                          ['Recognition', '1.0']],\n",
+      "                         'quick_review': [['FillBlank', '1.0'],\n",
+      "                                          ['SelectMeaning', '0.5'],\n",
+      "                                          ['Recognition', '1.0']],\n",
+      "                         'recognition': [['Recognition', '1.0']]},\n",
+      "              'schedule': ['quick_review', 'recognition', 'final_review']},\n",
+      " 'source': PosixPath('test_repo'),\n",
+      " 'typedef': {'annotation': {'content': '内容',\n",
+      "                            'delimiter': '分隔符',\n",
+      "                            'keyword_note': '关键词翻译',\n",
+      "                            'note': '笔记',\n",
+      "                            'translation': '语句翻译',\n",
+      "                            'tts_text': '文本转语音文本'},\n",
+      "             'common': {'delimiter': '/',\n",
+      "                        'tts_text': \"eval:payload['content'].replace('/', '')\"},\n",
+      "             'puzzles': {'FillBlank': {'__hint__': '',\n",
+      "                                       '__origin__': 'cloze',\n",
+      "                                       'delimiter': \"eval:metadata['formation']['delimiter']\",\n",
+      "                                       'min_denominator': \"eval:default['cloze']['min_denominator']\",\n",
+      "                                       'text': \"eval:payload['content']\"},\n",
+      "                         'Recognition': {'__hint__': '',\n",
+      "                                         '__origin__': 'recognition',\n",
+      "                                         'primary': \"eval:payload['content']\",\n",
+      "                                         'secondary': [\"eval:payload['keyword_note']\",\n",
+      "                                                       \"eval:payload['note']\"],\n",
+      "                                         'top_dim': [\"eval:payload['translation']\"]},\n",
+      "                         'SelectMeaning': {'__hint__': \"eval:payload['content']\",\n",
+      "                                           '__origin__': 'mcq',\n",
+      "                                           'jammer': \"eval:list(payload['keyword_note'].values())\",\n",
+      "                                           'mapping': \"eval:payload['keyword_note']\",\n",
+      "                                           'max_riddles_num': \"eval:default['mcq']['max_riddles_num']\",\n",
+      "                                           'prefix': '选择正确项: ',\n",
+      "                                           'primary': \"eval:payload['content']\"}},\n",
+      "             '古文句': {}}}\n"
+     ]
+    }
+   ],
+   "source": [
+    "test_repo_dic = test_repo.export_to_single_dict()\n",
+    "from pprint import pprint\n",
+    "\n",
+    "pprint(test_repo_dic)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "35a2e06f",
+   "metadata": {},
+   "source": [
+    "## 持久化与部分保存\n",
+    "如你所见, 所有内容被结构化地输出了!  \n",
+    "\n",
+    "现在写回到文件夹!  \n",
+    "\n",
+    "我们注意到, 并非所有的内容都要被修改.  \n",
+    "我们可以只保存接受修改的一部分, 默认情况下, 是迭代的记忆数据(algodata).  \n",
+    "这就是为什么我们一般不使用单个 json 或 toml 来存储 repo.\n",
+    "\n",
+    "persist_to_repodir 接受两个可选参数: \n",
+    "- save_list: 默认为 [\"algodata\"], 是要持久化的数据.\n",
+    "- source: 默认为原目录, 你也可以手动指定为其他文件夹(通过 Path)\n",
+    "\n",
+    "现在做一些演练, 我们将创建一个位于 test_new_repo 的\"克隆\", 此时我们!\n",
+    "除非文件夹已经存在, Repo 对象将会为你自动创建新文件夹."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "05eeaacc",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\u001b[01;34m.\u001b[0m\n",
+      "├── \u001b[00mheurams.log\u001b[0m\n",
+      "├── \u001b[00mrepo.ipynb\u001b[0m\n",
+      "├── \u001b[01;34mtest_new_repo\u001b[0m\n",
+      "│   ├── \u001b[00malgodata.json\u001b[0m\n",
+      "│   ├── \u001b[00mmanifest.toml\u001b[0m\n",
+      "│   ├── \u001b[00mpayload.toml\u001b[0m\n",
+      "│   ├── \u001b[00mschedule.toml\u001b[0m\n",
+      "│   └── \u001b[00mtypedef.toml\u001b[0m\n",
+      "└── \u001b[01;34mtest_repo\u001b[0m\n",
+      "    ├── \u001b[00malgodata.json\u001b[0m\n",
+      "    ├── \u001b[00mmanifest.toml\u001b[0m\n",
+      "    ├── \u001b[00mpayload.toml\u001b[0m\n",
+      "    ├── \u001b[00mschedule.toml\u001b[0m\n",
+      "    └── \u001b[00mtypedef.toml\u001b[0m\n",
+      "\n",
+      "3 directories, 12 files\n"
+     ]
+    }
+   ],
+   "source": [
+    "test_repo.persist_to_repodir(\n",
+    "    save_list=[\"schedule\", \"payload\", \"manifest\", \"typedef\", \"algodata\"],\n",
+    "    source=Path(\"test_new_repo\"),\n",
+    ")\n",
+    "!tree"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "059d7bdf",
+   "metadata": {},
+   "source": [
+    "如你所见, test_new_repo 已被生成!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4ef8925c",
+   "metadata": {},
+   "source": [
+    "# 数据结构\n",
+    "现在讲解 repo 的数据结构"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c19fed95",
+   "metadata": {},
+   "source": [
+    "## Lict 对象\n",
+    "Lict 对象集成了部分列表和字典的功能, 数据在这两种风格的 API 间都可用, 且修改是同步的.  \n",
+    "Lict 默认情况下不会保存序列顺序, 而是在列表形式下, 自动按索引字符序排布, 详情请参阅源代码.  \n",
+    "现在导入并初始化一个 Lict 对象:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "7e88bd7c",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[('age', 12), ('enemy', 'jerry'), ('name', 'tom')]\n",
+      "[('age', 12), ('enemy', 'jerry'), ('name', 'tom')]\n"
+     ]
+    }
+   ],
+   "source": [
+    "from heurams.utils.lict import Lict\n",
+    "\n",
+    "lct = Lict()  # 空的\n",
+    "lct = Lict(initlist=[(\"name\", \"tom\"), (\"age\", 12), (\"enemy\", \"jerry\")])  # 基于列表\n",
+    "print(lct)\n",
+    "lct = Lict(initdict={\"name\": \"tom\", \"age\": 12, \"enemy\": \"jerry\"})  # 基于字典\n",
+    "print(lct)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4d760bf9",
+   "metadata": {},
+   "source": [
+    "### 输出形式\n",
+    "lct 的\"官方\"输出形式是列表形式\n",
+    "你也可以选择输出字典形式"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "248f6cba",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{'name': 'tom', 'age': 12, 'enemy': 'jerry'}\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(lct.dicted_data)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "29dce184",
+   "metadata": {},
+   "source": [
+    "### dicted_data 属性与修改方式\n",
+    "dicted_data 属性是一个字典, 它自动同步来自 Lict 对象操作的修改.\n",
+    "一个注意事项: 不要直接修改 dicted_data, 这将不会触发同步 hook.\n",
+    "如果你一定要这样做, 请在完事后手动运行同步 hook.\n",
+    "推荐的修改方式是直接把 lct 当作一个字典"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "a0eb07a7",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[('age', 12), ('enemy', 'jerry'), ('name', 'tom')]\n",
+      "[('age', 12), ('enemy', 'jerry'), ('name', 'tom'), ('type', 'cat')]\n",
+      "[('age', 12), ('enemy', 'jerry'), ('is_human', False), ('name', 'tom'), ('type', 'cat')]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# 由于 jupyter 的环境处理, 请不要重复运行此单元格, 如果想再看一遍, 请重启 jupyter 后再全部运行\n",
+    "\n",
+    "# 错误的方式\n",
+    "lct.dicted_data[\"type\"] = \"cat\"\n",
+    "print(lct)  # 将不会同步修改\n",
+    "\n",
+    "# 不推荐, 但可用的方式\n",
+    "lct.dicted_data[\"type\"] = \"cat\"\n",
+    "lct._sync_based_on_dict()\n",
+    "print(lct)\n",
+    "\n",
+    "# 推荐方式\n",
+    "lct[\"is_human\"] = False\n",
+    "print(lct)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2337d113",
+   "metadata": {},
+   "source": [
+    "### data 属性与修改方式\n",
+    "data 属性是一个列表, 它自动同步来自 Lict 对象操作的修改.\n",
+    "一个注意事项: 不要直接修改 data, 这将不会触发同步 hook, 并且可能破坏排序.\n",
+    "如果你一定要这样做, 请在完事后手动运行同步 hook 和 sort, 此处不演示.\n",
+    "推荐的修改方式是直接把 lct 当作一个列表, 且避免使用索引修改"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "0ab442d4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{'age': 12, 'enemy': 'jerry', 'is_human': False, 'name': 'tom', 'type': 'cat', 'enemy_2': 'spike'}\n"
+     ]
+    }
+   ],
+   "source": [
+    "# 由于 jupyter 的环境处理, 请不要重复运行此单元格, 如果想再看一遍, 请重启 jupyter 后再全部运行\n",
+    "\n",
+    "# 唯一推荐方式\n",
+    "lct.append((\"enemy_2\", \"spike\"))\n",
+    "print(lct.dicted_data)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a3383f59",
+   "metadata": {},
+   "source": [
+    "### 多面手\n",
+    "Lict 有一些很酷的功能\n",
+    "详情请看源文件\n",
+    "此处是一些例子"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "f3ca752f",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[('age', 12), ('enemy', 'jerry'), ('enemy_2', 'spike'), ('is_human', False), ('name', 'tom'), ('type', 'cat')]\n",
+      "{'age': 12, 'enemy': 'jerry', 'is_human': False, 'name': 'tom', 'type': 'cat', 'enemy_2': 'spike'}\n",
+      "------\n",
+      "('age', 12)\n",
+      "('enemy', 'jerry')\n",
+      "('enemy_2', 'spike')\n",
+      "('is_human', False)\n",
+      "('name', 'tom')\n",
+      "('type', 'cat')\n",
+      "6\n",
+      "('type', 'cat')\n",
+      "[('age', 12), ('enemy', 'jerry'), ('enemy_2', 'spike'), ('is_human', False), ('name', 'tom')]\n",
+      "('name', 'tom')\n",
+      "[('age', 12), ('enemy', 'jerry'), ('enemy_2', 'spike'), ('is_human', False)]\n",
+      "('is_human', False)\n",
+      "[('age', 12), ('enemy', 'jerry'), ('enemy_2', 'spike')]\n",
+      "('enemy_2', 'spike')\n",
+      "[('age', 12), ('enemy', 'jerry')]\n",
+      "('enemy', 'jerry')\n",
+      "[('age', 12)]\n",
+      "('age', 12)\n",
+      "[]\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "Ellipsis"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "lct = Lict(\n",
+    "    initdict={\n",
+    "        \"age\": 12,\n",
+    "        \"enemy\": \"jerry\",\n",
+    "        \"is_human\": False,\n",
+    "        \"name\": \"tom\",\n",
+    "        \"type\": \"cat\",\n",
+    "        \"enemy_2\": \"spike\",\n",
+    "    }\n",
+    ")\n",
+    "print(lct)\n",
+    "print(lct.dicted_data)\n",
+    "print(\"------\")\n",
+    "for i in lct:\n",
+    "    print(i)\n",
+    "print(len(lct))\n",
+    "while len(lct) > 0:\n",
+    "    print(lct.pop())\n",
+    "    print(lct)\n",
+    "lct = Lict(\n",
+    "    initdict={\n",
+    "        \"age\": 12,\n",
+    "        \"enemy\": \"jerry\",\n",
+    "        \"is_human\": False,\n",
+    "        \"name\": \"tom\",\n",
+    "        \"type\": \"cat\",\n",
+    "        \"enemy_2\": \"spike\",\n",
+    "    }\n",
+    ")\n",
+    "..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2d6d3483",
+   "metadata": {},
+   "source": [
+    "关爱环境 从你我做起"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "773bf99c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!rm -rf test_new_repo\n",
+    "!rm -rf heurams.log*"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "8645c5a2",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{   'content': '君臣/固守/以窥/周室,/',\n",
+      "    'delimiter': '/',\n",
+      "    'keyword_note': {'窥': '窥视'},\n",
+      "    'note': [],\n",
+      "    'translation': '君臣牢固地守卫着，借以窥视周王室的权力，',\n",
+      "    'tts_text': '君臣固守以窥周室,'}\n",
+      "{   'SM-2': {   'efactor': 2.5,\n",
+      "                'interval': 1,\n",
+      "                'is_activated': 1,\n",
+      "                'last_date': 20454,\n",
+      "                'last_modify': 1767274438.752494,\n",
+      "                'next_date': 20455,\n",
+      "                'real_rept': 1,\n",
+      "                'rept': 0}}\n",
+      "{   'content': '秦孝公/据/崤函/之固/, 拥/雍州/之地,/',\n",
+      "    'delimiter': '/',\n",
+      "    'keyword_note': {'崤函': '崤山和函谷关', '据': '占据', '雍州': '古代九州之一'},\n",
+      "    'note': [],\n",
+      "    'translation': '秦孝公占据着崤山和函谷关的险固地势，拥有雍州的土地，',\n",
+      "    'tts_text': '秦孝公据崤函之固, 拥雍州之地,'}\n",
+      "{   'SM-2': {   'efactor': 2.5,\n",
+      "                'interval': 1,\n",
+      "                'is_activated': 1,\n",
+      "                'last_date': 20454,\n",
+      "                'last_modify': 1767274438.7534873,\n",
+      "                'next_date': 20455,\n",
+      "                'real_rept': 1,\n",
+      "                'rept': 0}}\n",
+      "{   'algodata': [   (   '君臣固守以窥周室,',\n",
+      "                        {   'SM-2': {   'efactor': 2.5,\n",
+      "                                        'interval': 1,\n",
+      "                                        'is_activated': 1,\n",
+      "                                        'last_date': 20454,\n",
+      "                                        'last_modify': 1767274438.752494,\n",
+      "                                        'next_date': 20455,\n",
+      "                                        'real_rept': 1,\n",
+      "                                        'rept': 0}}),\n",
+      "                    (   '秦孝公据崤函之固, 拥雍州之地,',\n",
+      "                        {   'SM-2': {   'efactor': 2.5,\n",
+      "                                        'interval': 1,\n",
+      "                                        'is_activated': 1,\n",
+      "                                        'last_date': 20454,\n",
+      "                                        'last_modify': 1767274438.7534873,\n",
+      "                                        'next_date': 20455,\n",
+      "                                        'real_rept': 1,\n",
+      "                                        'rept': 0}})],\n",
+      "    'manifest': {   'author': '__heurams__',\n",
+      "                    'desc': '高考古诗文: 过秦论',\n",
+      "                    'title': '测试单元: 过秦论'},\n",
+      "    'payload': [   (   '君臣固守以窥周室,',\n",
+      "                       {   'content': '君臣/固守/以窥/周室,/',\n",
+      "                           'keyword_note': {'窥': '窥视'},\n",
+      "                           'note': [],\n",
+      "                           'translation': '君臣牢固地守卫着，借以窥视周王室的权力，'}),\n",
+      "                   (   '秦孝公据崤函之固, 拥雍州之地,',\n",
+      "                       {   'content': '秦孝公/据/崤函/之固/, 拥/雍州/之地,/',\n",
+      "                           'keyword_note': {   '崤函': '崤山和函谷关',\n",
+      "                                               '据': '占据',\n",
+      "                                               '雍州': '古代九州之一'},\n",
+      "                           'note': [],\n",
+      "                           'translation': '秦孝公占据着崤山和函谷关的险固地势，拥有雍州的土地，'})],\n",
+      "    'schedule': {   'phases': {   'final_review': [   ['FillBlank', '0.7'],\n",
+      "                                                      ['SelectMeaning', '0.7'],\n",
+      "                                                      ['Recognition', '1.0']],\n",
+      "                                  'quick_review': [   ['FillBlank', '1.0'],\n",
+      "                                                      ['SelectMeaning', '0.5'],\n",
+      "                                                      ['Recognition', '1.0']],\n",
+      "                                  'recognition': [['Recognition', '1.0']]},\n",
+      "                    'schedule': [   'quick_review',\n",
+      "                                    'recognition',\n",
+      "                                    'final_review']},\n",
+      "    'source': PosixPath('test_repo'),\n",
+      "    'typedef': {   'annotation': {   'content': '内容',\n",
+      "                                     'delimiter': '分隔符',\n",
+      "                                     'keyword_note': '关键词翻译',\n",
+      "                                     'note': '笔记',\n",
+      "                                     'translation': '语句翻译',\n",
+      "                                     'tts_text': '文本转语音文本'},\n",
+      "                   'common': {   'delimiter': '/',\n",
+      "                                 'tts_text': \"eval:payload['content'].replace('/', \"\n",
+      "                                             \"'')\"},\n",
+      "                   'puzzles': {   'FillBlank': {   '__hint__': '',\n",
+      "                                                   '__origin__': 'cloze',\n",
+      "                                                   'delimiter': \"eval:metadata['formation']['delimiter']\",\n",
+      "                                                   'min_denominator': \"eval:default['cloze']['min_denominator']\",\n",
+      "                                                   'text': \"eval:payload['content']\"},\n",
+      "                                  'Recognition': {   '__hint__': '',\n",
+      "                                                     '__origin__': 'recognition',\n",
+      "                                                     'primary': \"eval:payload['content']\",\n",
+      "                                                     'secondary': [   \"eval:payload['keyword_note']\",\n",
+      "                                                                      \"eval:payload['note']\"],\n",
+      "                                                     'top_dim': [   \"eval:payload['translation']\"]},\n",
+      "                                  'SelectMeaning': {   '__hint__': \"eval:payload['content']\",\n",
+      "                                                       '__origin__': 'mcq',\n",
+      "                                                       'jammer': \"eval:list(payload['keyword_note'].values())\",\n",
+      "                                                       'mapping': \"eval:payload['keyword_note']\",\n",
+      "                                                       'max_riddles_num': \"eval:default['mcq']['max_riddles_num']\",\n",
+      "                                                       'prefix': '选择正确项: ',\n",
+      "                                                       'primary': \"eval:payload['content']\"}},\n",
+      "                   '古文句': {}}}\n"
+     ]
+    }
+   ],
+   "source": [
+    "repo = repolib.Repo.create_from_repodir(Path(\"./test_repo\"))\n",
+    "for i in repo.ident_index:\n",
+    "    n = pt.Nucleon.create_on_nucleonic_data(\n",
+    "        nucleonic_data=repo.nucleonic_data_lict.get_itemic_unit(i)\n",
+    "    )\n",
+    "    e = pt.Electron.create_on_electonic_data(\n",
+    "        electronic_data=repo.electronic_data_lict.get_itemic_unit(i)\n",
+    "    )\n",
+    "    e.activate()\n",
+    "    e.revisor(5, True)\n",
+    "    print(repr(n))\n",
+    "    print(repr(e))\n",
+    "print(repo)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/simplemem.py

@@ -0,0 +1,56 @@
+import heurams.kernel.repolib as repolib
+import heurams.kernel.particles as pt
+from heurams.services.textproc import truncate
+from pathlib import Path
+import time
+
+repo = repolib.Repo.create_from_repodir(Path("./test_repo"))
+alist = list()
+print(repo.ident_index)
+for i in repo.ident_index:
+    n = pt.Nucleon.create_on_nucleonic_data(
+        nucleonic_data=repo.nucleonic_data_lict.get_itemic_unit(i)
+    )
+    e = pt.Electron.create_on_electonic_data(
+        electronic_data=repo.electronic_data_lict.get_itemic_unit(i)
+    )
+    print(n)
+    input()
+    a = pt.Atom(n, e, repo.orbitic_data)
+    alist.append(a)
+    # e.activate()
+    # e.revisor(5, True)
+    print(repr(a))
+    # print(repr(e))
+print(repo)
+input()
+import heurams.kernel.reactor as rt
+
+ph: rt.Phaser = rt.Phaser(alist)
+print(ph)
+pr: rt.Procession = ph.current_procession()  # type: ignore
+print(pr)
+pr.forward()
+print(pr)
+pr.forward()  # 如果过界了?
+print(pr)  # 静默设置状态 无报错
+pr.forward()
+print(pr)
+pr = ph.current_procession()  # type: ignore # 下一个队列
+print(pr)
+pr.forward()
+print(pr)
+pr.append()  # 如果记忆失败了?
+print(pr)
+pr.forward()
+pr.append()  # 如果记忆失败了?
+pr.append()  # 如果记忆失败了?
+pr.append()  # 如果记忆失败了?
+pr.append()  # 如果记忆失败了?
+pr.append()  # 如果记忆失败了?
+# 重复项目只会占据一个车尾
+print(pr)
+pr.forward()
+print(pr)
+pr = ph.current_procession()  # type: ignore
+print(pr)

examples/test_repo/algodata.json

@@ -0,0 +1 @@
+{}

examples/test_repo/manifest.toml

@@ -0,0 +1,3 @@
+title = "测试单元: 过秦论"
+author = "__heurams__"
+desc = "高考古诗文: 过秦论"

examples/test_repo/payload.toml

@@ -0,0 +1,11 @@
+["秦孝公据崤函之固, 拥雍州之地,"]
+note = []
+content = "秦孝公/据/崤函/之固/, 拥/雍州/之地,/"
+translation = "秦孝公占据着崤山和函谷关的险固地势，拥有雍州的土地，"
+keyword_note = {"据"="占据", "崤函"="崤山和函谷关", "雍州"="古代九州之一"}
+
+["君臣固守以窥周室,"]
+note = []
+content = "君臣/固守/以窥/周室,/"
+translation = "君臣牢固地守卫着，借以窥视周王室的权力，"
+keyword_note = {"窥"="窥视"}

examples/test_repo/schedule.toml

@@ -0,0 +1,5 @@
+schedule = ["quick_review", "recognition", "final_review"]
+[phases]
+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"]]

examples/test_repo/typedef.toml

@@ -0,0 +1,17 @@
+[annotation]
+note = "笔记"
+keyword_note = "关键词翻译"
+translation = "语句翻译"
+delimiter = "分隔符"
+content = "内容"
+tts_text = "文本转语音文本"
+
+[common]
+delimiter = "/"
+tts_text = "eval:payload['content'].replace('/', '')"
+
+[common.puzzles] # 谜题定义
+# 我们称 "Recognition" 为 recognition 谜题的 alia
+"Recognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:payload['content']", secondary = ["eval:payload['keyword_note']", "eval:payload['note']"], top_dim = ["eval:payload['translation']"] }
+"SelectMeaning" = { __origin__ = "mcq", __hint__ = "eval:payload['content']", primary = "eval:payload['content']", mapping = "eval:payload['keyword_note']", jammer = "eval:list(payload['keyword_note'].values())", max_riddles_num = "eval:default['mcq']['max_riddles_num']", prefix = "选择正确项: " }
+"FillBlank" = { __origin__ = "cloze", __hint__ = "", text = "eval:payload['content']", delimiter = "eval:nucleon['delimiter']", min_denominator = "eval:default['cloze']['min_denominator']"}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "heurams"
-version = "0.4.0"
+version = "0.5.0"
 description = "Heuristic Assisted Memory Scheduler"
 license = {file = "LICENSE"}
 classifiers = [
@@ -25,3 +25,4 @@ readme = "README.md"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+

requirements.txt

@@ -2,3 +2,5 @@ bidict==0.23.1
 playsound==1.2.2
 textual==5.3.0
 toml==0.10.2
+requests>=2.31.0
+webdavclient3>=3.0.0

src/heurams/context.py

@@ -3,8 +3,10 @@
 以及基准路径
 """
 
-from contextvars import ContextVar
 import pathlib
+from contextvars import ContextVar
+import shutil
+
 from heurams.services.config import ConfigFile
 from heurams.services.logger import get_logger
 
@@ -13,26 +15,39 @@ from heurams.services.logger import get_logger
 # 数据文件路径规定: 以运行目录为准
 
 rootdir = pathlib.Path(__file__).parent
-print(f"rootdir: {rootdir}")
+print(f"项目根目录: {rootdir}")
 logger = get_logger(__name__)
 logger.debug(f"项目根目录: {rootdir}")
 workdir = pathlib.Path.cwd()
-print(f"workdir: {workdir}")
+print(f"工作目录: {workdir}")
 logger.debug(f"工作目录: {workdir}")
+
+if pathlib.Path(workdir / "data" / "config" / "config_dev.toml").exists():
+    print("使用开发设置")
+    logger.debug("使用开发设置")
     config_var: ContextVar[ConfigFile] = ContextVar(
-    "config_var", default=ConfigFile(rootdir / "default" / "config" / "config.toml")
+        "config_var",
+        default=ConfigFile(workdir / "data" / "config" / "config_dev.toml"),
     )
+else:
     try:
         config_var: ContextVar[ConfigFile] = ContextVar(
-        "config_var", default=ConfigFile(workdir / "config" / "config.toml")
+            "config_var",
+            default=ConfigFile(workdir / "data" / "config" / "config.toml"),
         )  # 配置文件
-    print("已加载自定义用户配置")
-    logger.info("已加载自定义用户配置, 路径: %s", workdir / "config" / "config.toml")
     except Exception as e:
-    print("未能加载自定义用户配置")
-    logger.warning("未能加载自定义用户配置, 错误: %s", e)
-
-# runtime_var: ContextVar = ContextVar('runtime_var', default=dict()) # 运行时共享数据
+        input("按下回车以创建新的配置文件, 或按下 Ctrl + C 以终止程序 ")
+        (workdir / "data" / "config").mkdir(parents=True, exist_ok=True)
+        (workdir / "data" / "config" / "config").unlink(missing_ok=True)
+        shutil.copy(
+            (rootdir / "default" / "config" / "config.toml"),
+            workdir / "data" / "config" / "config.toml",
+        )
+    finally:
+        config_var: ContextVar[ConfigFile] = ContextVar(
+            "config_var",
+            default=ConfigFile(workdir / "data" / "config" / "config.toml"),
+        )  # 配置文件
 
 
 class ConfigContext:

src/heurams/default/config/config.toml

@@ -6,14 +6,22 @@ daystamp_override = -1
 timestamp_override = -1
 
 # [调试] 一键通过
-quick_pass = 0
+quick_pass = 1
 
 # 对于每个项目的默认新记忆原子数量
-tasked_number = 8
+scheduled_num = 8
 
 # UTC 时间戳修正 仅用于 UNIX 日时间戳的生成修正, 单位为秒
 timezone_offset = +28800 # 中国标准时间 (UTC+8)
 
+[interface]
+
+[interface.memorizor]
+autovoice = true # 自动语音播放, 仅限于 recognition 组件
+
+[algorithm]
+default = "SM-2" # 主要算法; 可选项: SM-2, SM-15M, FSRS
+
 [puzzles] # 谜题默认配置
 
 [puzzles.mcq]
@@ -22,8 +30,27 @@ max_riddles_num = 2
 [puzzles.cloze]
 min_denominator = 3
 
-[paths] # 相对于工作目录而言 或绝对路径
-nucleon_dir = "./data/nucleon"
-electron_dir = "./data/electron"
-orbital_dir = "./data/orbital"
-cache_dir = "./data/cache"
+[paths] # 相对于配置文件的 ".." (即工作目录) 而言 或绝对路径
+data = "./data"
+
+[services] # 定义服务到提供者的映射
+audio = "playsound" # 可选项: playsound(通用), termux(仅用于支持 Android Termux), mpg123(TODO)
+tts = "edgetts" # 可选项: edgetts
+llm = "openai" # 可选项: openai
+sync = "webdav" # 可选项: 留空, webdav
+
+[providers.tts.edgetts] # EdgeTTS 设置
+voice = "zh-CN-XiaoxiaoNeural" # 可选项: zh-CN-YunjianNeural (男声), zh-CN-XiaoxiaoNeural (女声)
+
+[providers.llm.openai] # 与 OpenAI 相容的语言模型接口服务设置
+url = ""
+key = ""
+
+[providers.sync.webdav] # WebDAV 同步设置
+url = ""
+username = ""
+password = ""
+remote_path = "/heurams/"
+verify_ssl = true
+
+[sync]

src/heurams/interface/__init__.py

@@ -0,0 +1,63 @@
+from textual.app import App
+from textual.widgets import Button
+
+from heurams.context import config_var
+from heurams.services.logger import get_logger
+
+from .screens.about import AboutScreen
+from .screens.dashboard import DashboardScreen
+from .screens.precache import PrecachingScreen
+from .screens.repocreator import RepoCreatorScreen
+from .screens.synctool import SyncScreen
+
+logger = get_logger(__name__)
+
+
+def environment_check():
+    from pathlib import Path
+
+    logger.debug("检查环境路径")
+    subdir = ["cache/voice", "repo", "global", "config"]
+    for i in subdir:
+        i = Path(config_var.get()["paths"]["data"]) / i
+        if not i.exists():
+            logger.info("创建目录: %s", i)
+            print(f"创建 {i}")
+            i.mkdir(exist_ok=True, parents=True)
+        else:
+            logger.debug("目录已存在: %s", i)
+            print(f"找到 {i}")
+    logger.debug("环境检查完成")
+
+
+class HeurAMSApp(App):
+    TITLE = "潜进"
+    CSS_PATH = "css/main.tcss"
+    SUB_TITLE = "启发式辅助记忆调度器"
+    BINDINGS = [
+        ("q", "quit", "退出"),
+        ("d", "toggle_dark", "切换色调"),
+        ("1", "app.push_screen('dashboard')", "仪表盘"),
+        ("2", "app.push_screen('precache_all')", "缓存管理器"),
+        ("3", "app.push_screen('repo_creator')", "创建新仓库"),
+        # ("4", "app.push_screen('synctool')", "同步工具"),
+        ("0", "app.push_screen('about')", "版本信息"),
+    ]
+    SCREENS = {
+        "dashboard": DashboardScreen,
+        "repo_creator": RepoCreatorScreen,
+        "precache_all": PrecachingScreen,
+        "synctool": SyncScreen,
+        "about": AboutScreen,
+    }
+
+    def on_mount(self) -> None:
+        environment_check()
+        self.push_screen("dashboard")
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        self.exit(event.button.id)
+
+    def action_do_nothing(self):
+        print("DO NOTHING")
+        self.refresh()

src/heurams/interface/__main__.py

@@ -1,87 +1,18 @@
 from textual.app import App
 from textual.widgets import Button
-from .screens.dashboard import DashboardScreen
-from .screens.nucreator import NucleonCreatorScreen
-from .screens.precache import PrecachingScreen
-from .screens.about import AboutScreen
+
+from heurams.context import config_var
+from heurams.interface import HeurAMSApp
 from heurams.services.logger import get_logger
 
+from .screens.about import AboutScreen
+from .screens.dashboard import DashboardScreen
+from .screens.precache import PrecachingScreen
+from .screens.repocreator import RepoCreatorScreen
+
 logger = get_logger(__name__)
 
-
-class HeurAMSApp(App):
-    TITLE = "潜进"
-    CSS_PATH = "css/main.tcss"
-    SUB_TITLE = "启发式辅助记忆调度器"
-    BINDINGS = [
-        ("q", "quit", "退出"),
-        ("d", "toggle_dark", "切换色调"),
-        ("1", "app.push_screen('dashboard')", "仪表盘"),
-        ("2", "app.push_screen('precache_all')", "缓存管理器"),
-        ("3", "app.push_screen('nucleon_creator')", "创建新单元"),
-        ("0", "app.push_screen('about')", "版本信息"),
-    ]
-    SCREENS = {
-        "dashboard": DashboardScreen,
-        "nucleon_creator": NucleonCreatorScreen,
-        "precache_all": PrecachingScreen,
-        "about": AboutScreen,
-    }
-
-    def on_mount(self) -> None:
-        self.push_screen("dashboard")
-
-    def on_button_pressed(self, event: Button.Pressed) -> None:
-        self.exit(event.button.id)
-
-    def action_do_nothing(self):
-        print("DO NOTHING")
-        self.refresh()
-
-
-def environment_check():
-    from pathlib import Path
-
-    logger.debug("检查环境路径")
-
-    for i in config_var.get()["paths"].values():
-        i = Path(i)
-        if not i.exists():
-            logger.info("创建目录: %s", i)
-            print(f"创建 {i}")
-            i.mkdir(exist_ok=True, parents=True)
-        else:
-            logger.debug("目录已存在: %s", i)
-            print(f"找到 {i}")
-    logger.debug("环境检查完成")
-
-
-def is_subdir(parent, child):
-    try:
-        child.relative_to(parent)
-        logger.debug("is_subdir: %s 是 %s 的子目录", child, parent)
-        return 1
-    except:
-        logger.debug("is_subdir: %s 不是 %s 的子目录", child, parent)
-        return 0
-
-
-# 开发模式
-from heurams.context import rootdir, workdir, config_var
-from pathlib import Path
-from heurams.context import rootdir
-import os
-
-if is_subdir(Path(rootdir), Path(os.getcwd())):
-    os.chdir(Path(rootdir) / ".." / "..")
-    print(f'转入开发数据目录: {Path(rootdir)/".."/".."}')
-
-environment_check()
-
 app = HeurAMSApp()
+
 if __name__ == "__main__":
     app.run()
-
-
-def main():
-    app.run()

src/heurams/interface/screens/about.py

@@ -1,15 +1,9 @@
-#!/usr/bin/env python3
+"""关于界面"""
+
 from textual.app import ComposeResult
-from textual.widgets import (
-    Header,
-    Footer,
-    Label,
-    Static,
-    Button,
-    Markdown,
-)
-from textual.containers import ScrollableContainer, ScrollableContainer
+from textual.containers import ScrollableContainer
 from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Label, Markdown, Static
 
 import heurams.services.version as version
 from heurams.context import *
@@ -26,7 +20,7 @@ class AboutScreen(Screen):
 
 版本 {version.ver} {version.stage.capitalize()}
   
-开发代号: {version.codename.capitalize()}  
+开发代号: {version.codename.capitalize()} {version.codename_cn} 
 
 一个基于启发式算法的开放源代码记忆调度器, 旨在帮助用户更高效地进行记忆工作与学习规划.  
 
@@ -38,7 +32,8 @@ class AboutScreen(Screen):
 
 特别感谢:
 
-- [Piotr A. Woźniak](https://supermemo.guru/wiki/Piotr_Wozniak): SuperMemo-2 算法
+- [Piotr A. Woźniak](https://supermemo.guru/wiki/Piotr_Wozniak): SM-2 算法与 SM-15 算法理论
+- [Kazuaki Tanida](https://github.com/slaypni): SM-15 算法的 CoffeeScript 实现
 - [Thoughts Memo](https://www.zhihu.com/people/L.M.Sherlock): 文献参考
 
 # 参与贡献

src/heurams/interface/screens/dashboard.py

@@ -1,153 +1,160 @@
-#!/usr/bin/env python3
-from textual.app import ComposeResult
-from textual.widgets import (
-    Header,
-    Footer,
-    Label,
-    ListView,
-    ListItem,
-    Button,
-    Static,
-)
-from textual.containers import ScrollableContainer
-from textual.screen import Screen
-
-from heurams.kernel.particles import *
-from heurams.context import *
-import heurams.services.version as version
-import heurams.services.timer as timer
-from .preparation import PreparationScreen
-from .about import AboutScreen
-from heurams.services.logger import get_logger
+"""仪表盘界面"""
 
 import pathlib
 
+from textual.app import ComposeResult
+from textual.containers import ScrollableContainer
+from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Label, ListItem, ListView, Static
+
+import heurams.services.timer as timer
+import heurams.services.version as version
+from heurams.context import *
+from heurams.kernel.particles import *
+from heurams.kernel.repolib import *
+from heurams.services.logger import get_logger
+
+import heurams.kernel.particles as pt
+from pathlib import Path
+from .about import AboutScreen
+from .preparation import PreparationScreen
+
 logger = get_logger(__name__)
 
 
 class DashboardScreen(Screen):
+    """主仪表盘屏幕"""
+
     SUB_TITLE = "仪表盘"
 
+    def __init__(
+        self,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+    ) -> None:
+        super().__init__(name, id, classes)
+        self.repostat = {}
+        self.title2dirname = {}
+        self.title2repo = {}
+        self._load_data()
+
     def compose(self) -> ComposeResult:
+        """组合界面组件"""
         yield Header(show_clock=True)
         yield ScrollableContainer(
-            Label(f'欢迎使用 "潜进" 启发式辅助记忆调度器', classes="title-label"),
-            Label(f"当前 UNIX 日时间戳: {timer.get_daystamp()}"),
-            Label(f'时区修正: UTC+{config_var.get()["timezone_offset"] / 3600}'),
-            Label("选择待学习或待修改的记忆单元集:", classes="title-label"),
-            ListView(id="union-list", classes="union-list-view"),
+            Label('欢迎使用 "潜进" 启发式辅助记忆调度器', classes="title-label"),
             Label(
-                f'"潜进" 启发式辅助记忆调度器 | 版本 {version.ver} {version.codename.capitalize()} 2025'
+                f"当前 UNIX 日时间戳: {timer.get_daystamp()} (UTC+{config_var.get()["timezone_offset"] / 3600})"
             ),
+            Label(f"全局算法设置: {config_var.get()['algorithm']['default']}"),
+            Label("选择待学习或待修改的项目:", classes="title-label"),
+            ListView(id="repo-list", classes="repo-list-view"),
+            Label(f'"潜进" 启发式辅助记忆调度器 | 版本 {version.ver} '),
         )
         yield Footer()
 
-    def item_desc_generator(self, filename) -> dict:
-        """简单分析以生成项目项显示文本
-
-        Returns:
-            dict: 以数字为列表, 分别呈现单行字符串
-        """
-        res = dict()
-        filestem = pathlib.Path(filename).stem
-        res[0] = f"{filename}\0"
-        from heurams.kernel.particles.loader import load_electron
-        import heurams.kernel.particles as pt
-
-        electron_file_path = pathlib.Path(config_var.get()["paths"]["electron_dir"]) / (
-            filestem + ".json"
+    def _load_data(self):
+        self.repo_dirs = Repo.probe_vaild_repos_in_dir(
+            Path(config_var.get()["paths"]["data"]) / "repo"
         )
+        for repo_dir in self.repo_dirs:
+            repo = Repo.create_from_repodir(repo_dir)
+            self._analyse_repo(repo)
 
-        logger.debug(f"电子文件路径: {electron_file_path}")
-
-        if electron_file_path.exists():  # 未找到则创建电子文件 (json)
-            pass
-        else:
-            electron_file_path.touch()
-            with open(electron_file_path, "w") as f:
-                f.write("{}")
-        electron_dict = load_electron(path=electron_file_path)  # TODO: 取消硬编码扩展名
-        logger.debug(electron_dict)
+    def _analyse_repo(self, repo: Repo):
+        dirname = repo.source.name  # type: ignore
+        title = repo.manifest["title"]
         is_due = 0
-        is_activated = 0
+        unit_sum = len(repo)
+        activated_sum = 0
         nextdate = 0x3F3F3F3F
-        for i in electron_dict.values():
-            i: pt.Electron
-            logger.debug(i, i.is_due())
-            if i.is_due():
+        is_unfinished = unit_sum > activated_sum
+        for i in repo.ident_index:
+            nucleon = pt.Nucleon.create_on_nucleonic_data(
+                nucleonic_data=repo.nucleonic_data_lict.get_itemic_unit(i)
+            )
+            electron = pt.Electron.create_on_electonic_data(
+                electronic_data=repo.electronic_data_lict.get_itemic_unit(i)
+            )
+            if electron.is_activated():
+                activated_sum += 1
+                if electron.is_due():
                     is_due = 1
-            if i.is_activated():
-                is_activated = 1
-            nextdate = min(nextdate, i.nextdate())
-        res[1] = f"下一次复习: {nextdate}\n"
-        res[1] += f"{is_due if "需要复习" else "当前无需复习"}"
-        if not is_activated:
-            res[1] = "  尚未激活"
-        return res
+                nextdate = min(nextdate, electron.nextdate())
+        if is_unfinished:
+            nextdate = min(nextdate, timer.get_daystamp())
+        need_to_study = is_due or is_unfinished
+        prompt = f"{title}\0\n  进度: {activated_sum}/{unit_sum}\n  {"需要学习" if need_to_study else "无需操作"}"
+        stat = {
+            "is_due": is_due,
+            "unit_sum": unit_sum,
+            "title": title,
+            "activated_sum": activated_sum,
+            "nextdate": nextdate,
+            "is_unfinished": is_unfinished,
+            "need_to_study": need_to_study,
+            "prompt": prompt,
+            "dirname": dirname,
+        }
+        self.repostat[dirname] = stat
+        self.title2dirname[title] = dirname
+        self.title2repo[title] = repo
 
     def on_mount(self) -> None:
-        union_list_widget = self.query_one("#union-list", ListView)
+        """挂载组件时初始化"""
+        repo_list_widget = self.query_one("#repo-list", ListView)
 
-        probe = probe_all(0)
-
-        if len(probe["nucleon"]):
-            for file in probe["nucleon"]:
-                text = self.item_desc_generator(file)
-                union_list_widget.append(
-                    ListItem(
-                        Label(text[0] + "\n" + text[1]),
+        # 按下次复习时间排序
+        repodirs = sorted(
+            self.repo_dirs,
+            key=lambda f: self.repostat[f.name]["nextdate"],
+            reverse=True,
         )
-                )
-        else:
-            union_list_widget.append(
+        repotitles = map(lambda f: self.repostat[f.name]["title"], repodirs)
+        # 填充列表
+        if not repodirs:
+            repo_list_widget.append(
                 ListItem(
                     Static(
-                        "在 ./nucleon/ 中未找到任何内容源数据文件.\n请放置文件后重启应用.\n或者新建空的单元集."
+                        "在 ./data/repo/ 中未找到任何仓库.\n"
+                        "请导入仓库后重启应用, 或者新建空的仓库."
                     )
                 )
             )
-            union_list_widget.disabled = True
+            repo_list_widget.disabled = True
+            return
+
+        for repotitle in repotitles:
+            prompt = self.repostat[self.title2dirname[repotitle]]["prompt"]
+            list_item = ListItem(Label(prompt))
+            repo_list_widget.append(list_item)
+
+            # if not self.stay_enabled[repodir]:
+            #    list_item.disabled = True
 
     def on_list_view_selected(self, event) -> None:
+        """处理列表项选择事件"""
         if not isinstance(event.item, ListItem):
             return
 
         selected_label = event.item.query_one(Label)
-        if "未找到任何 .toml 文件" in str(selected_label.renderable):  # type: ignore
+        label_text = str(selected_label.renderable)
+
+        if "未找到任何仓库" in label_text:
             return
 
-        selected_filename = pathlib.Path(
-            str(selected_label.renderable)
-            .partition("\0")[0]  # 文件名末尾截断, 保留文件名
-            .replace("*", "")
-        )  # 去除markdown加粗
+        # 提取文件名
+        selected_repotitle = label_text.partition("\0")[0].replace("*", "")
+        selected_repo = self.title2repo[label_text.partition("\0")[0].replace("*", "")]
 
-        nucleon_file_path = (
-            pathlib.Path(config_var.get()["paths"]["nucleon_dir"]) / selected_filename
+        # 跳转到准备屏幕
+        self.app.push_screen(
+            PreparationScreen(
+                selected_repo, self.repostat[self.title2dirname[selected_repotitle]]
             )
-        electron_file_path = pathlib.Path(config_var.get()["paths"]["electron_dir"]) / (
-            str(selected_filename.stem) + ".json"
         )
-        self.app.push_screen(PreparationScreen(nucleon_file_path, electron_file_path))
-
-    def on_button_pressed(self, event) -> None:
-        if event.button.id == "new_nucleon_button":
-            # 切换到创建单元
-            from .nucreator import NucleonCreatorScreen
-
-            newscr = NucleonCreatorScreen()
-            self.app.push_screen(newscr)
-        elif event.button.id == "precache_all_button":
-            # 切换到缓存管理器
-            from .precache import PrecachingScreen
-
-            precache_screen = PrecachingScreen()
-            self.app.push_screen(precache_screen)
-        elif event.button.id == "about_button":
-            from .about import AboutScreen
-
-            about_screen = AboutScreen()
-            self.app.push_screen(about_screen)
 
     def action_quit_app(self) -> None:
+        """退出应用程序"""
         self.app.exit()

src/heurams/interface/screens/intelinote.py

@@ -0,0 +1 @@
+"""笔记界面"""

src/heurams/interface/screens/memointegrity.py

@@ -0,0 +1 @@
+"""整体式记忆工作界面"""

src/heurams/interface/screens/memoqueue.py

@@ -1,16 +1,19 @@
-#!/usr/bin/env python3
-from textual.app import ComposeResult
-from textual.widgets import Header, Footer, Label, Static, Button
-from textual.containers import Center, ScrollableContainer
-from textual.screen import Screen
-from textual.reactive import reactive
+"""队列式记忆工作界面"""
+
 from enum import Enum, auto
 
-from heurams.services.logger import get_logger
+from textual.app import ComposeResult
+from textual.containers import Center, ScrollableContainer
+from textual.reactive import reactive
+from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Label, Static
+
+import heurams.kernel.evaluators as pz
+import heurams.kernel.particles as pt
 from heurams.context import config_var
 from heurams.kernel.reactor import *
-import heurams.kernel.particles as pt
-import heurams.kernel.puzzles as pz
+from heurams.services.logger import get_logger
+
 from .. import shim
 
 
@@ -25,7 +28,7 @@ logger = get_logger(__name__)
 class MemScreen(Screen):
     BINDINGS = [
         ("q", "pop_screen", "返回"),
-        #    ("p", "prev", "复习上一个"),
+        ("p", "prev", "查看上一个"),
         ("d", "toggle_dark", ""),
         ("v", "play_voice", "朗读"),
         ("0,1,2,3", "app.push_screen('about')", ""),
@@ -37,67 +40,61 @@ class MemScreen(Screen):
 
     def __init__(
         self,
-        atoms: list,
-        name: str | None = None,
-        id: str | None = None,
-        classes: str | None = None,
+        phaser: Phaser,
+        name=None,
+        id=None,
+        classes=None,
     ) -> None:
         super().__init__(name, id, classes)
-        self.atoms = atoms
-        self.phaser = Phaser(atoms)
-        # logger.debug(self.phaser.state)
-        self.procession: Procession = self.phaser.current_procession()  # type: ignore
-        self.atom: pt.Atom = self.procession.current_atom
-        # logger.debug(self.phaser.state)
-        # self.procession.forward(1)
-        for i in atoms:
-            i.do_eval()
-
-    def on_mount(self):
-        self.load_puzzle()
-        pass
-
-    def puzzle_widget(self):
-        try:
-            logger.debug(self.phaser.state)
-            logger.debug(self.procession.cursor)
-            logger.debug(self.atom)
-            self.fission = Fission(self.atom, self.phaser.state)
-            puzzle_debug = next(self.fission.generate())
-            # logger.debug(puzzle_debug)
-            return shim.puzzle2widget[puzzle_debug["puzzle"]](
-                atom=self.atom, alia=puzzle_debug["alia"]
-            )
-        except (KeyError, StopIteration, AttributeError) as e:
-            logger.debug(f"调度展开出错: {e}")
-            return Static("无法生成谜题")
-        # logger.debug(shim.puzzle2widget[puzzle_debug["puzzle"]])
+        self.phaser = phaser
+        self.update_state()
 
     def compose(self) -> ComposeResult:
         yield Header(show_clock=True)
         with ScrollableContainer():
             yield Label(self._get_progress_text(), id="progress")
-
-            # self.mount(self.current_widget()) # type: ignore
             yield ScrollableContainer(id="puzzle-container")
-        # yield Button("重新学习此单元", id="re-recognize", variant="warning")
         yield Footer()
 
+    def update_state(self):
+        """更新状态机"""
+        self.procession: Procession = self.phaser.current_procession()  # type: ignore
+        self.atom: pt.Atom = self.procession.current_atom  # type: ignore
+
+    def on_mount(self):
+        self.mount_puzzle()
+        self.update_display()
+
+    def puzzle_widget(self):
+        try:
+            self.fission = self.procession.get_fission()
+            puzzle = self.fission.get_current_puzzle()
+            return shim.puzzle2widget[puzzle["puzzle"]](  # type: ignore
+                atom=self.atom, alia=puzzle["alia"]  # type: ignore
+            )
+        except (KeyError, StopIteration, AttributeError) as e:
+            logger.debug(f"调度展开出错: {e}")
+            return Static(f"无法生成谜题 {e}")
+
     def _get_progress_text(self):
-        return f"当前进度: {self.procession.process() + 1}/{self.procession.total_length()}"
+        s = f"阶段: {self.procession.phase.name}\n"
+        s += f"当前进度: {self.procession.process() + 1}/{self.procession.total_length()}"
+        return s
 
     def update_display(self):
+        """更新进度显示"""
         progress_widget = self.query_one("#progress")
         progress_widget.update(self._get_progress_text())  # type: ignore
 
-    def load_puzzle(self):
-        self.atom: pt.Atom = self.procession.current_atom
+    def mount_puzzle(self):
+        """挂载当前谜题组件"""
         container = self.query_one("#puzzle-container")
         for i in container.children:
             i.remove()
         container.mount(self.puzzle_widget())
 
-    def load_finished_widget(self):
+    def mount_finished_widget(self):
+        """挂载已完成组件"""
         container = self.query_one("#puzzle-container")
         for i in container.children:
             i.remove()
@@ -108,45 +105,47 @@ class MemScreen(Screen):
     def on_button_pressed(self, event):
         event.stop()
 
+    def action_play_voice(self):
+        self.run_worker(self.play_voice, exclusive=True, thread=True)
+
+    def play_voice(self):
+        """朗读当前内容"""
+        from pathlib import Path
+
+        from heurams.services.audio_service import play_by_path
+        from heurams.services.hasher import get_md5
+
+        path = Path(config_var.get()["paths"]["data"]) / "cache" / "voice"
+        path = path / f"{get_md5(self.atom.registry['nucleon']["tts_text"])}.wav"
+        if path.exists():
+            play_by_path(path)
+        else:
+            from heurams.services.tts_service import convertor
+
+            convertor(self.atom.registry["nucleon"]["tts_text"], path)
+            play_by_path(path)
+
     def watch_rating(self, old_rating, new_rating) -> None:
-        if self.procession == 0:
+        self.update_state()  # 刷新状态
+        if self.procession == None:  # 已经完成记忆
             return
-        if new_rating == -1:
+        if new_rating == -1:  # 安全值
             return
-        forwards = 1 if new_rating >= 4 else 0
+        forwards = 1 if new_rating >= 4 else 0  # 准许前进
         self.rating = -1
         logger.debug(f"试图前进: {"允许" if forwards else "禁止"}")
         if forwards:
             ret = self.procession.forward(1)
             if ret == 0:  # 若结束了此次队列
-                self.procession = self.phaser.current_procession()  # type: ignore
-                if self.procession == 0:  # 若所有队列都结束了
+                self.update_state()
+                if self.procession.phase == PhaserState.FINISHED:  # 若所有队列都结束了
                     logger.debug(f"记忆进程结束")
-                    for i in self.atoms:
-                        i: pt.Atom
-                        i.revise()
-                        i.persist("electron")
-                    self.load_finished_widget()
+                    self.mount_finished_widget()
                     return
                 else:
                     logger.debug(f"建立新队列 {self.procession.phase}")
-            self.load_puzzle()
+            self.update_state()
+            self.mount_puzzle()
         else:  # 若不通过
             self.procession.append()
         self.update_display()
-
-    def action_quick_pass(self):
-        self.rating = 5
-        self.atom.minimize(5)
-        self.atom.registry["electron"].activate()
-        self.atom.lock(1)
-
-    def action_play_voice(self):
-        """朗读当前内容"""
-        pass
-
-    def action_toggle_dark(self):
-        self.app.action_toggle_dark()
-
-    def action_pop_screen(self):
-        self.app.pop_screen()

src/heurams/interface/screens/precache.py

@@ -1,22 +1,18 @@
-#!/usr/bin/env python3
-from textual.app import ComposeResult
-from textual.widgets import (
-    Header,
-    Footer,
-    Label,
-    Button,
-    Static,
-    ProgressBar,
-)
-from textual.containers import ScrollableContainer, Horizontal
-from textual.containers import ScrollableContainer
-from textual.screen import Screen
+"""缓存工具界面"""
+
 import pathlib
 
+from textual.app import ComposeResult
+from textual.containers import Horizontal, ScrollableContainer
+from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Label, ProgressBar, Static
+from textual.worker import get_current_worker
+
 import heurams.kernel.particles as pt
 import heurams.services.hasher as hasher
 from heurams.context import *
-from textual.worker import get_current_worker
+
+cache_dir = pathlib.Path(config_var.get()["paths"]["data"]) / "cache" / "voice"
 
 
 class PrecachingScreen(Screen):
@@ -44,10 +40,6 @@ class PrecachingScreen(Screen):
         self.precache_worker = None
         self.cancel_flag = 0
         self.desc = desc
-        for i in nucleons:
-            i: pt.Nucleon
-            i.do_eval()
-        # print("完成 EVAL")
 
     def compose(self) -> ComposeResult:
         yield Header(show_clock=True)
@@ -96,17 +88,15 @@ class PrecachingScreen(Screen):
 
     def precache_by_text(self, text: str):
         """预缓存单段文本的音频"""
-        from heurams.context import rootdir, workdir, config_var
+        from heurams.context import config_var, rootdir, workdir
 
-        cache_dir = pathlib.Path(config_var.get()["paths"]["cache_dir"])
         cache_dir.mkdir(parents=True, exist_ok=True)
         cache_file = cache_dir / f"{hasher.get_md5(text)}.wav"
         if not cache_file.exists():
-            try:  # TODO: 调用模块消除tts耦合
-                import edge_tts as tts
+            try:
+                from heurams.services.tts_service import convertor
 
-                communicate = tts.Communicate(text, "zh-CN-XiaoxiaoNeural")
-                communicate.save_sync(str(cache_file))
+                convertor(text, cache_file)
                 return 1
             except Exception as e:
                 print(f"预缓存失败 '{text}': {e}")
@@ -115,10 +105,8 @@ class PrecachingScreen(Screen):
 
     def precache_by_nucleon(self, nucleon: pt.Nucleon):
         """依据 Nucleon 缓存"""
-        # print(nucleon.metadata['formation']['tts_text'])
-        ret = self.precache_by_text(nucleon.metadata["formation"]["tts_text"])
+        ret = self.precache_by_text(nucleon["tts_text"])
         return ret
-        # print(f"TTS 缓存: {nucleon.metadata['formation']['tts_text']}")
 
     def precache_by_list(self, nucleons: list):
         """依据 Nucleons 列表缓存"""
@@ -127,7 +115,7 @@ class PrecachingScreen(Screen):
             worker = get_current_worker()
             if worker and worker.is_cancelled:  # 函数在worker中执行且已被取消
                 return False
-            text = nucleon.metadata["formation"]["tts_text"]
+            text = nucleon["tts_text"]
             # self.current_item = text[:30] + "..." if len(text) > 50 else text
             # print(text)
             self.processed += 1
@@ -157,36 +145,30 @@ class PrecachingScreen(Screen):
         # print(f"返回 {ret}")
         return ret
 
-    def precache_by_filepath(self, path: pathlib.Path):
-        """预缓存单个文件的所有内容"""
-        lst = list()
-        for i in pt.load_nucleon(path):
-            lst.append(i[0])
-        return self.precache_by_list(lst)
-
     def precache_all_files(self):
         """预缓存所有文件"""
-        from heurams.context import rootdir, workdir, config_var
+        from heurams.context import config_var, rootdir, workdir
+        from heurams.kernel.repolib import Repo
 
-        nucleon_path = pathlib.Path(config_var.get()["paths"]["nucleon_dir"])
-        nucleon_files = [
-            f for f in nucleon_path.iterdir() if f.suffix == ".toml"
-        ]  # TODO: 解耦合
+        repo_path = pathlib.Path(config_var.get()["paths"]["data"]) / "repo"
+        repo_dirs = Repo.probe_vaild_repos_in_dir(repo_path)
+        repos = map(Repo.create_from_repodir, repo_dirs)
 
         # 计算总项目数
         self.total = 0
-        nu = list()
-        for file in nucleon_files:
+        nucleon_list = list()
+        for repo in repos:
             try:
-                for i in pt.load_nucleon(file):
-                    nu.append(i[0])
+                for i in repo.ident_index:
+                    nucleon_list.append(
+                        pt.Nucleon.create_on_nucleonic_data(
+                            repo.nucleonic_data_lict.get_itemic_unit(i)
+                        )
+                    )
             except:
                 continue
-        self.total = len(nu)
-        for i in nu:
-            i: pt.Nucleon
-            i.do_eval()
-        return self.precache_by_list(nu)
+        self.total = len(nucleon_list)
+        return self.precache_by_list(nucleon_list)
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
         event.stop()
@@ -220,11 +202,10 @@ class PrecachingScreen(Screen):
             # 清空缓存
             try:
                 import shutil
-                from heurams.context import rootdir, workdir, config_var
 
-                shutil.rmtree(
-                    f"{config_var.get()["paths"]["cache_dir"]}", ignore_errors=True
-                )
+                from heurams.context import config_var, rootdir, workdir
+
+                shutil.rmtree(cache_dir, ignore_errors=True)
                 self.update_status("已清空", "音频缓存已清空", 0)
             except Exception as e:
                 self.update_status("错误", f"清空缓存失败: {e}")

src/heurams/interface/screens/preparation.py

@@ -1,22 +1,18 @@
-#!/usr/bin/env python3
+"""记忆准备界面"""
+
 from textual.app import ComposeResult
-from textual.widgets import (
-    Header,
-    Footer,
-    Label,
-    Static,
-    Button,
-    Markdown,
-)
 from textual.containers import ScrollableContainer
+from textual.reactive import reactive
 from textual.screen import Screen
-from heurams.context import config_var
+from textual.widget import Widget
+from textual.widgets import Button, Footer, Header, Label, Markdown, Static
+
 import heurams.kernel.particles as pt
 import heurams.services.hasher as hasher
 from heurams.context import *
-from textual.reactive import reactive
-from textual.widget import Widget
+from heurams.context import config_var
 from heurams.services.logger import get_logger
+from heurams.kernel.repolib import *
 
 logger = get_logger(__name__)
 
@@ -34,24 +30,19 @@ class PreparationScreen(Screen):
 
     scheduled_num = reactive(config_var.get()["scheduled_num"])
 
-    def __init__(self, nucleon_file: pathlib.Path, electron_file: pathlib.Path) -> None:
+    def __init__(self, repo: Repo, repostat: dict) -> None:
         super().__init__(name=None, id=None, classes=None)
-        self.nucleon_file = nucleon_file
-        self.electron_file = electron_file
-        self.nucleons_with_orbital = pt.load_nucleon(self.nucleon_file)
-        self.electrons = pt.load_electron(self.electron_file)
+        self.repo = repo
+        self.repostat = repostat
 
     def compose(self) -> ComposeResult:
         yield Header(show_clock=True)
         with ScrollableContainer(id="vice_container"):
-            yield Label(f"准备就绪: [b]{self.nucleon_file.stem}[/b]\n")
+            yield Label(f"准备就绪: [b]{self.repostat['title']}[/b]\n")
             yield Label(
-                f"内容源文件: {config_var.get()['paths']['nucleon_dir']}/[b]{self.nucleon_file.name}[/b]"
+                f"仓库路径: {config_var.get()['paths']['data']}/repo/[b]{self.repostat['dirname']}[/b]"
             )
-            yield Label(
-                f"元数据文件: {config_var.get()['paths']['electron_dir']}/[b]{self.electron_file.name}[/b]"
-            )
-            yield Label(f"\n单元数量: {len(self.nucleons_with_orbital)}\n")
+            yield Label(f"\n单元数量: {len(self.repo)}\n")
             yield Label(f"单次记忆数量: {self.scheduled_num}", id="schnum_label")
 
             yield Button(
@@ -81,10 +72,11 @@ class PreparationScreen(Screen):
 
     def _get_full_content(self):
         content = ""
-        for nucleon, orbital in self.nucleons_with_orbital:
-            nucleon: pt.Nucleon
-            # print(nucleon.payload)
-            content += " - " + nucleon["content"] + "  \n"
+        for i in self.repo.ident_index:
+            n = pt.Nucleon.create_on_nucleonic_data(
+                nucleonic_data=self.repo.nucleonic_data_lict.get_itemic_unit(i)
+            )
+            content += f"- {n['content']}  \n"
         return content
 
     def action_go_back(self):
@@ -94,9 +86,15 @@ class PreparationScreen(Screen):
         from ..screens.precache import PrecachingScreen
 
         lst = list()
-        for i in self.nucleons_with_orbital:
-            lst.append(i[0])
-        precache_screen = PrecachingScreen(lst)
+        for i in self.repo.ident_index:
+            lst.append(
+                pt.Nucleon.create_on_nucleonic_data(
+                    self.repo.nucleonic_data_lict.get_itemic_unit(i)
+                )
+            )
+        precache_screen = PrecachingScreen(
+            nucleons=lst, desc=self.repo.manifest["title"]
+        )
         self.app.push_screen(precache_screen)
 
     def action_quit_app(self):
@@ -107,38 +105,33 @@ class PreparationScreen(Screen):
         logger.debug("按下按钮")
         if event.button.id == "start_memorizing_button":
             atoms = list()
-            for nucleon, orbital in self.nucleons_with_orbital:
-                atom = pt.Atom(nucleon.ident)
-                atom.link("nucleon", nucleon)
-                try:
-                    atom.link("electron", self.electrons[nucleon.ident])
-                except KeyError:
-                    atom.link("electron", pt.Electron(nucleon.ident))
-                atom.link("orbital", orbital)
-                atom.link("nucleon_fmt", "toml")
-                atom.link("electron_fmt", "json")
-                atom.link("orbital_fmt", "toml")
-                atom.link("nucleon_path", self.nucleon_file)
-                atom.link("electron_path", self.electron_file)
-                atom.link("orbital_path", None)
-                atoms.append(atom)
+            for i in self.repo.ident_index:
+                n = pt.Nucleon.create_on_nucleonic_data(
+                    nucleonic_data=self.repo.nucleonic_data_lict.get_itemic_unit(i)
+                )
+                e = pt.Electron.create_on_electonic_data(
+                    electronic_data=self.repo.electronic_data_lict.get_itemic_unit(i)
+                )
+                a = pt.Atom(n, e, self.repo.orbitic_data)
+                atoms.append(a)
+
             atoms_to_provide = list()
             left_new = self.scheduled_num
             for i in atoms:
                 i: pt.Atom
+                if i.registry["electron"].is_activated():
                     if i.registry["electron"].is_due():
                         atoms_to_provide.append(i)
-                else:
-                    if i.registry["electron"].is_activated():
-                        pass
                 else:
                     left_new -= 1
                     if left_new >= 0:
                         atoms_to_provide.append(i)
-            logger.debug(f"ATP: {atoms_to_provide}")
-            from .memorizor import MemScreen
+            from .memoqueue import MemScreen
+            import heurams.kernel.reactor as rt
 
-            memscreen = MemScreen(atoms_to_provide)
+            pheser = rt.Phaser(atoms_to_provide)
+            memscreen = MemScreen(pheser)
             self.app.push_screen(memscreen)
+
         elif event.button.id == "precache_button":
             self.action_precache()

src/heurams/interface/screens/radio.py

@@ -0,0 +1 @@
+""" "前进电台" 界面"""

src/heurams/interface/screens/repocreator.py

@@ -1,32 +1,27 @@
-#!/usr/bin/env python3
+"""仓库创建向导界面"""
+
+from pathlib import Path
+
+import toml
 from textual.app import ComposeResult
-from textual.widgets import (
-    Header,
-    Footer,
-    Label,
-    Input,
-    Select,
-    Button,
-    Markdown,
-)
 from textual.containers import ScrollableContainer
 from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Input, Label, Markdown, Select
 
-from heurams.services.version import ver
-import toml
-from pathlib import Path
 from heurams.context import config_var
+from heurams.services.version import ver
 
 
-class NucleonCreatorScreen(Screen):
+class RepoCreatorScreen(Screen):
     BINDINGS = [("q", "go_back", "返回")]
-    SUB_TITLE = "单元集创建向导"
+    SUB_TITLE = "仓库创建向导"
 
     def __init__(self) -> None:
         super().__init__(name=None, id=None, classes=None)
 
     def search_templates(self):
         from pathlib import Path
+
         from heurams.context import config_var
 
         template_dir = Path(config_var.get()["paths"]["template_dir"])

src/heurams/interface/screens/synctool.py

@@ -1,22 +1,17 @@
-#!/usr/bin/env python3
-from textual.app import ComposeResult
-from textual.widgets import (
-    Header,
-    Footer,
-    Label,
-    Button,
-    Static,
-    ProgressBar,
-)
-from textual.containers import ScrollableContainer, Horizontal
-from textual.containers import ScrollableContainer
-from textual.screen import Screen
+"""同步工具界面"""
+
 import pathlib
+import time
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal, ScrollableContainer
+from textual.screen import Screen
+from textual.widgets import Button, Footer, Header, Label, ProgressBar, Static
+from textual.worker import get_current_worker
 
 import heurams.kernel.particles as pt
 import heurams.services.hasher as hasher
 from heurams.context import *
-from textual.worker import get_current_worker
 
 
 class SyncScreen(Screen):
@@ -25,22 +20,287 @@ class SyncScreen(Screen):
 
     def __init__(self, nucleons: list = [], desc: str = ""):
         super().__init__(name=None, id=None, classes=None)
+        self.sync_service = None
+        self.is_syncing = False
+        self.is_paused = False
+        self.log_messages = []
+        self.max_log_lines = 50
 
     def compose(self) -> ComposeResult:
         yield Header(show_clock=True)
         with ScrollableContainer(id="sync_container"):
-            pass
+            # 标题和连接状态
+            yield Static("同步工具", classes="title")
+            yield Static("", id="status_label", classes="status")
+
+            # 配置信息
+            yield Static(f"同步协议: {config_var.get()['services']['sync']}")
+            yield Static("服务器配置:", classes="section_title")
+            with Horizontal(classes="config_info"):
+                yield Static("远程服务器:", classes="config_label")
+                yield Static("", id="server_url", classes="config_value")
+            with Horizontal(classes="config_info"):
+                yield Static("远程路径:", classes="config_label")
+                yield Static("", id="remote_path", classes="config_value")
+
+            with Horizontal(classes="control_buttons"):
+                yield Button("测试连接", id="test_connection", variant="primary")
+                yield Button("开始同步", id="start_sync", variant="success")
+                yield Button("暂停", id="pause_sync", variant="warning", disabled=True)
+                yield Button("取消", id="cancel_sync", variant="error", disabled=True)
+
+            yield Static("同步进度", classes="section_title")
+            yield ProgressBar(id="progress_bar", show_percentage=True, total=100)
+            yield Static("", id="progress_label", classes="progress_text")
+
+            yield Static("同步日志", classes="section_title")
+            yield Static("", id="log_output", classes="log_output")
+
         yield Footer()
 
     def on_mount(self):
         """挂载时初始化状态"""
+        self.update_ui_from_config()
+        self.log_message("同步工具已启动")
+
+    def update_ui_from_config(self):
+        """更新 UI 显示配置信息"""
+        try:
+            sync_cfg: dict = config_var.get()["providers"]["sync"]["webdav"]
+            # 更新服务器 URL
+            url = sync_cfg.get("url", "未配置")
+            url_widget = self.query_one("#server_url")
+            url_widget.update(url)  # type: ignore
+            # 更新远程路径
+            remote_path = sync_cfg.get("remote_path", "/")
+            path_widget = self.query_one("#remote_path")
+            path_widget.update(remote_path)  # type: ignore
+
+            # 更新状态标签
+            status_widget = self.query_one("#status_label")
+            if self.sync_service and self.sync_service.client:
+                status_widget.update("✅ 同步服务已就绪")  # type: ignore
+                status_widget.add_class("ready")
+            else:
+                status_widget.update("❌ 同步服务未配置或未启用")  # type: ignore
+                status_widget.add_class("error")
+
+        except Exception as e:
+            self.log_message(f"更新 UI 失败: {e}", is_error=True)
 
     def update_status(self, status, current_item="", progress=None):
         """更新状态显示"""
+        try:
+            status_widget = self.query_one("#status_label")
+            status_widget.update(status)  # type: ignore
+
+            if progress is not None:
+                progress_bar = self.query_one("#progress_bar")
+                progress_bar.progress = progress  # type: ignore
+
+                progress_label = self.query_one("#progress_label")
+                progress_label.update(f"{progress}% - {current_item}" if current_item else f"{progress}%")  # type: ignore
+
+        except Exception as e:
+            self.log_message(f"更新状态失败: {e}", is_error=True)
+
+    def log_message(self, message: str, is_error: bool = False):
+        """添加日志消息并更新显示"""
+        timestamp = time.strftime("%H:%M:%S")
+        prefix = "[ERROR]" if is_error else "[INFO]"
+        log_line = f"{timestamp} {prefix} {message}"
+
+        self.log_messages.append(log_line)
+        # 保持日志行数不超过最大值
+        if len(self.log_messages) > self.max_log_lines:
+            self.log_messages = self.log_messages[-self.max_log_lines :]
+
+        # 更新日志显示
+        try:
+            log_widget = self.query_one("#log_output")
+            log_widget.update("\n".join(self.log_messages))  # type: ignore
+        except Exception:
+            pass  # 如果组件未就绪，忽略错误
 
     def on_button_pressed(self, event: Button.Pressed) -> None:
+        """处理按钮点击事件"""
+        button_id = event.button.id
+
+        if button_id == "test_connection":
+            self.test_connection()
+        elif button_id == "start_sync":
+            self.start_sync()
+        elif button_id == "pause_sync":
+            self.pause_sync()
+        elif button_id == "cancel_sync":
+            self.cancel_sync()
+
         event.stop()
 
+    def test_connection(self):
+        """测试 WebDAV 服务器连接"""
+        if not self.sync_service:
+            self.log_message("同步服务未初始化，请检查配置", is_error=True)
+            self.update_status("❌ 同步服务未初始化")
+            return
+
+        self.log_message("正在测试 WebDAV 连接...")
+        self.update_status("正在测试连接...")
+
+        try:
+            success = self.sync_service.test_connection()
+            if success:
+                self.log_message("连接测试成功")
+                self.update_status("✅ 连接正常")
+            else:
+                self.log_message("连接测试失败", is_error=True)
+                self.update_status("❌ 连接失败")
+        except Exception as e:
+            self.log_message(f"连接测试异常: {e}", is_error=True)
+            self.update_status("❌ 连接异常")
+
+    def start_sync(self):
+        """开始同步"""
+        if not self.sync_service:
+            self.log_message("同步服务未初始化，无法开始同步", is_error=True)
+            return
+
+        if self.is_syncing:
+            self.log_message("同步已在进行中", is_error=True)
+            return
+
+        self.is_syncing = True
+        self.is_paused = False
+        self.update_button_states()
+
+        self.log_message("开始同步数据...")
+        self.update_status("正在同步...", progress=0)
+
+        # 启动后台同步任务
+        self.run_worker(self.perform_sync, thread=True)
+
+    def perform_sync(self):
+        """执行同步任务（在后台线程中运行）"""
+        worker = get_current_worker()
+
+        try:
+            # 获取需要同步的本地目录
+            from heurams.context import config_var
+
+            config = config_var.get()
+            paths = config.get("paths", {})
+
+            # 同步 nucleon 目录
+            nucleon_dir = pathlib.Path(paths.get("nucleon_dir", "./data/nucleon"))
+            if nucleon_dir.exists():
+                self.log_message(f"同步 nucleon 目录: {nucleon_dir}")
+                self.update_status(f"同步 nucleon 目录...", progress=10)
+
+                result = self.sync_service.sync_directory(nucleon_dir)  # type: ignore
+                if result.get("success"):
+                    self.log_message(
+                        f"nucleon 同步完成: 上传 {result.get('uploaded', 0)} 个, 下载 {result.get('downloaded', 0)} 个"
+                    )
+                else:
+                    self.log_message(
+                        f"nucleon 同步失败: {result.get('error', '未知错误')}",
+                        is_error=True,
+                    )
+
+            # 同步 electron 目录
+            electron_dir = pathlib.Path(paths.get("electron_dir", "./data/electron"))
+            if electron_dir.exists():
+                self.log_message(f"同步 electron 目录: {electron_dir}")
+                self.update_status(f"同步 electron 目录...", progress=60)
+
+                result = self.sync_service.sync_directory(electron_dir)  # type: ignore
+                if result.get("success"):
+                    self.log_message(
+                        f"electron 同步完成: 上传 {result.get('uploaded', 0)} 个, 下载 {result.get('downloaded', 0)} 个"
+                    )
+                else:
+                    self.log_message(
+                        f"electron 同步失败: {result.get('error', '未知错误')}",
+                        is_error=True,
+                    )
+
+            # 同步 orbital 目录（如果存在）
+            orbital_dir = pathlib.Path(paths.get("orbital_dir", "./data/orbital"))
+            if orbital_dir.exists():
+                self.log_message(f"同步 orbital 目录: {orbital_dir}")
+                self.update_status(f"同步 orbital 目录...", progress=80)
+
+                result = self.sync_service.sync_directory(orbital_dir)  # type: ignore
+                if result.get("success"):
+                    self.log_message(
+                        f"orbital 同步完成: 上传 {result.get('uploaded', 0)} 个, 下载 {result.get('downloaded', 0)} 个"
+                    )
+                else:
+                    self.log_message(
+                        f"orbital 同步失败: {result.get('error', '未知错误')}",
+                        is_error=True,
+                    )
+
+            # 同步完成
+            self.update_status("同步完成", progress=100)
+            self.log_message("所有目录同步完成")
+
+        except Exception as e:
+            self.log_message(f"同步过程中发生错误: {e}", is_error=True)
+            self.update_status("同步失败")
+        finally:
+            # 重置同步状态
+            self.is_syncing = False
+            self.is_paused = False
+            self.update_button_states()  # type: ignore
+
+    def pause_sync(self):
+        """暂停同步"""
+        if not self.is_syncing:
+            return
+
+        self.is_paused = not self.is_paused
+        self.update_button_states()
+
+        if self.is_paused:
+            self.log_message("同步已暂停")
+            self.update_status("同步已暂停")
+        else:
+            self.log_message("同步已恢复")
+            self.update_status("正在同步...")
+
+    def cancel_sync(self):
+        """取消同步"""
+        if not self.is_syncing:
+            return
+
+        self.is_syncing = False
+        self.is_paused = False
+        self.update_button_states()
+
+        self.log_message("同步已取消")
+        self.update_status("同步已取消")
+
+    def update_button_states(self):
+        """更新按钮状态"""
+        try:
+            start_button = self.query_one("#start_sync")
+            pause_button = self.query_one("#pause_sync")
+            cancel_button = self.query_one("#cancel_sync")
+
+            if self.is_syncing:
+                start_button.disabled = True
+                pause_button.disabled = False
+                cancel_button.disabled = False
+                pause_button.label = "继续" if self.is_paused else "暂停"  # type: ignore
+            else:
+                start_button.disabled = False
+                pause_button.disabled = True
+                cancel_button.disabled = True
+
+        except Exception as e:
+            self.log_message(f"更新按钮状态失败: {e}", is_error=True)
+
     def action_go_back(self):
         self.app.pop_screen()
 

src/heurams/interface/shim.py

@@ -1,36 +1,11 @@
 """Kernel 操作辅助函数库"""
 
-import random
-import heurams.kernel.particles as pt
-import heurams.kernel.puzzles as pz
 import heurams.interface.widgets as pzw
-from typing import TypedDict
-
-staging = {}  # 细粒度缓存区, 是 ident -> quality 的封装
-
-
-def report_to_staging(atom: pt.Atom, quality):
-    staging[atom.ident] = min(quality, staging[atom.ident])
-
-
-def clear():
-    staging = dict()
-
-
-def deploy_to_electron():
-    for atom_ident, quality in staging.items():
-        if pt.atom_registry[atom_ident].registry["electron"].is_activated:
-            pt.atom_registry[atom_ident].registry["electron"].revisor(quality=quality)
-        else:
-            pt.atom_registry[atom_ident].registry["electron"].revisor(
-                quality=quality, is_new_activation=True
-            )
-    clear()
-
+import heurams.kernel.evaluators as pz
 
 puzzle2widget = {
     pz.RecognitionPuzzle: pzw.Recognition,
     pz.ClozePuzzle: pzw.ClozePuzzle,
     pz.MCQPuzzle: pzw.MCQPuzzle,
-    pz.BasePuzzle: pzw.BasePuzzleWidget,
+    pz.BaseEvaluator: pzw.BasePuzzleWidget,
 }

src/heurams/interface/widgets/base_puzzle_widget.py

@@ -1,6 +1,8 @@
 from typing import Iterable
+
 from textual.app import ComposeResult
 from textual.widget import Widget
+
 import heurams.kernel.particles as pt
 
 

src/heurams/interface/widgets/basic_puzzle.py

@@ -1,13 +1,11 @@
-from textual.widgets import (
-    Label,
-    Static,
-    Button,
-)
-from textual.containers import ScrollableContainer, Horizontal
-from textual.widget import Widget
-import heurams.kernel.particles as pt
-from .base_puzzle_widget import BasePuzzleWidget
+from textual.containers import Horizontal, ScrollableContainer
 from textual.message import Message
+from textual.widget import Widget
+from textual.widgets import Button, Label, Static
+
+import heurams.kernel.particles as pt
+
+from .base_puzzle_widget import BasePuzzleWidget
 
 
 class BasicEvaluation(BasePuzzleWidget):
@@ -51,7 +49,7 @@ class BasicEvaluation(BasePuzzleWidget):
         # 显示主要内容
         yield Label(self.atom.registry["nucleon"]["content"], id="main")
 
-        # 显示评估说明（可选）
+        # 显示评估说明(可选)
         yield Static("请评估你对这个内容的记忆程度: ", classes="instruction")
 
         # 按钮容器

src/heurams/interface/widgets/cloze_puzzle.py

@@ -1,17 +1,17 @@
-from textual.widgets import (
-    Label,
-    Button,
-)
-from textual.widget import Widget
-import heurams.kernel.particles as pt
-import heurams.kernel.puzzles as pz
-from .base_puzzle_widget import BasePuzzleWidget
 import copy
 import random
+from typing import TypedDict
+
 from textual.containers import Container
 from textual.message import Message
+from textual.widget import Widget
+from textual.widgets import Button, Label
+
+import heurams.kernel.evaluators as pz
+import heurams.kernel.particles as pt
 from heurams.services.logger import get_logger
-from typing import TypedDict
+
+from .base_puzzle_widget import BasePuzzleWidget
 
 logger = get_logger(__name__)
 
@@ -53,7 +53,7 @@ class ClozePuzzle(BasePuzzleWidget):
         self.hashmap = dict()
 
     def _load(self):
-        setting = self.atom.registry["orbital"]["puzzles"][self.alia]
+        setting = self.atom.registry["nucleon"]["puzzles"][self.alia]
         self.puzzle = pz.ClozePuzzle(
             text=setting["text"],
             delimiter=setting["delimiter"],

src/heurams/interface/widgets/finished.py

@@ -1,8 +1,5 @@
-from textual.widgets import (
-    Label,
-    Button,
-)
 from textual.widget import Widget
+from textual.widgets import Button, Label
 
 
 class Finished(Widget):

src/heurams/interface/widgets/mcq_puzzle.py

@@ -1,17 +1,17 @@
 # 单项选择题
-from textual.widgets import (
-    Label,
-    Button,
-)
-from textual.containers import ScrollableContainer, Container
-from textual.widget import Widget
-import heurams.kernel.particles as pt
-import heurams.kernel.puzzles as pz
-from .base_puzzle_widget import BasePuzzleWidget
 from typing import TypedDict
+
+from textual.containers import Container, ScrollableContainer
+from textual.widget import Widget
+from textual.widgets import Button, Label
+
+import heurams.kernel.evaluators as pz
+import heurams.kernel.particles as pt
 from heurams.services.hasher import hash
 from heurams.services.logger import get_logger
 
+from .base_puzzle_widget import BasePuzzleWidget
+
 logger = get_logger(__name__)
 
 
@@ -54,18 +54,19 @@ class MCQPuzzle(BasePuzzleWidget):
         self._load()
 
     def _load(self):
-        cfg = self.atom.registry["orbital"]["puzzles"][self.alia]
+        cfg = self.atom.registry["nucleon"]["puzzles"][self.alia]
         self.puzzle = pz.MCQPuzzle(
             cfg["mapping"], cfg["jammer"], int(cfg["max_riddles_num"]), cfg["prefix"]
         )
         self.puzzle.refresh()
 
     def compose(self):
-        self.atom.registry["nucleon"].do_eval()
-        setting: Setting = self.atom.registry["nucleon"].metadata["orbital"]["puzzles"][
-            self.alia
-        ]
-        logger.debug(f"Puzzle Setting: {setting}")
+        setting: Setting = self.atom.registry["nucleon"]["puzzles"][self.alia]
+        if len(self.inputlist) > len(self.puzzle.options):
+            logger.debug("ERR IDX")
+            logger.debug(self.inputlist)
+            logger.debug(self.puzzle.options)
+        else:
             current_options = self.puzzle.options[len(self.inputlist)]
         yield Label(setting["primary"], id="sentence")
         yield Label(self.puzzle.wording[len(self.inputlist)], id="puzzle")
@@ -116,7 +117,7 @@ class MCQPuzzle(BasePuzzleWidget):
 
                 self.screen.rating = rating  # type: ignore
                 self.handler(rating)
-                # 重置输入（如果回答错误）
+                # 重置输入(如果回答错误)
                 if not is_correct:
                     self.inputlist = []
                     self.refresh_buttons()
@@ -127,7 +128,7 @@ class MCQPuzzle(BasePuzzleWidget):
                 self.update_display()
 
     def refresh_buttons(self):
-        """刷新按钮显示（用于题目切换）"""
+        """刷新按钮显示(用于题目切换)"""
         # 移除所有选项按钮
         logger.debug("刷新按钮")
         self.cursor += 1

src/heurams/interface/widgets/placeholder.py

@@ -1,8 +1,5 @@
-from textual.widgets import (
-    Label,
-    Button,
-)
 from textual.widget import Widget
+from textual.widgets import Button, Label
 
 
 class Placeholder(Widget):

src/heurams/interface/widgets/recognition.py

@@ -1,20 +1,17 @@
-from textual.reactive import reactive
-from textual.widgets import (
-    Markdown,
-    Label,
-    Static,
-    Button,
-)
-from textual.containers import Center
-from textual.widget import Widget
-from typing import Dict
-import heurams.kernel.particles as pt
 import re
-from .base_puzzle_widget import BasePuzzleWidget
-from typing import TypedDict, List
+from typing import Dict, List, TypedDict
+
+from textual.containers import Center
 from textual.message import Message
+from textual.reactive import reactive
+from textual.widget import Widget
+from textual.widgets import Button, Label, Markdown, Static
+
+import heurams.kernel.particles as pt
 from heurams.services.logger import get_logger
 
+from .base_puzzle_widget import BasePuzzleWidget
+
 logger = get_logger(__name__)
 
 
@@ -52,8 +49,13 @@ class Recognition(BasePuzzleWidget):
         self.alia = alia
 
     def compose(self):
-        cfg: RecognitionConfig = self.atom.registry["orbital"]["puzzles"][self.alia]
-        delim = self.atom.registry["nucleon"].metadata["formation"]["delimiter"]
+        from heurams.context import config_var
+
+        autovoice = config_var.get()["interface"]["memorizor"]["autovoice"]
+        if autovoice:
+            self.screen.action_play_voice()  # type: ignore
+        cfg: RecognitionConfig = self.atom.registry["nucleon"]["puzzles"][self.alia]
+        delim = self.atom.registry["nucleon"]["delimiter"]
         replace_dict = {
             ", ": ",",
             ". ": ".",
@@ -67,11 +69,12 @@ class Recognition(BasePuzzleWidget):
         }
 
         nucleon = self.atom.registry["nucleon"]
-        metadata = self.atom.registry["nucleon"].metadata
+        metadata = self.atom.registry["nucleon"]
         primary = cfg["primary"]
 
         with Center():
-            yield Static(f"[dim]{cfg['top_dim']}[/]")
+            for i in cfg["top_dim"]:
+                yield Static(f"[dim]{i}[/]")
             yield Label("")
 
         for old, new in replace_dict.items():

src/heurams/kernel/algorithms/__init__.py

@@ -1,15 +1,15 @@
+from .base import BaseAlgorithm
 from .sm2 import SM2Algorithm
-from heurams.services.logger import get_logger
-
-logger = get_logger(__name__)
+from .sm15m import SM15MAlgorithm
 
 __all__ = [
     "SM2Algorithm",
+    "BaseAlgorithm",
+    "SM15MAlgorithm",
 ]
 
 algorithms = {
     "SM-2": SM2Algorithm,
-    "supermemo2": SM2Algorithm,
+    "SM-15M": SM15MAlgorithm,
+    "Base": BaseAlgorithm,
 }
-
-logger.debug("算法模块初始化完成, 注册的算法: %s", list(algorithms.keys()))

src/heurams/kernel/algorithms/base.py

@@ -1,5 +1,6 @@
-import heurams.services.timer as timer
 from typing import TypedDict
+
+import heurams.services.timer as timer
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
@@ -9,7 +10,6 @@ class BaseAlgorithm:
     algo_name = "BaseAlgorithm"
 
     class AlgodataDict(TypedDict):
-        efactor: float
         real_rept: int
         rept: int
         interval: int
@@ -51,7 +51,7 @@ class BaseAlgorithm:
         return 1
 
     @classmethod
-    def rate(cls, algodata) -> str:
+    def get_rating(cls, algodata) -> str:
         """获取评分信息"""
         logger.debug(
             "BaseAlgorithm.rate 被调用, algodata keys: %s",
@@ -67,3 +67,11 @@ class BaseAlgorithm:
             list(algodata.keys()) if algodata else [],
         )
         return -1
+
+    @classmethod
+    def check_integrity(cls, algodata):
+        try:
+            cls.AlgodataDict(**algodata[cls.algo_name])
+            return 1
+        except:
+            return 0

src/heurams/kernel/algorithms/sm15m.py

@@ -0,0 +1,295 @@
+"""
+SM-15 接口兼容实现, 基于 SM-15 算法的逆向工程
+全局状态保存在文件中, 项目状态通过 algodata 字典传递
+
+基于: https://github.com/slaypni/sm.js
+原始 CoffeeScript 代码: (c) 2014 Kazuaki Tanida
+MIT 许可证
+"""
+
+import datetime
+import json
+import os
+import pathlib
+from typing import TypedDict
+
+from heurams.context import config_var
+from heurams.kernel.algorithms.sm15m_calc import (
+    MAX_AF,
+    MIN_AF,
+    NOTCH_AF,
+    RANGE_AF,
+    RANGE_REPETITION,
+    SM,
+    THRESHOLD_RECALL,
+    Item,
+)
+
+# 全局状态文件路径
+_GLOBAL_STATE_FILE = os.path.expanduser(
+    pathlib.Path(config_var.get()["paths"]["data"])
+    / "global"
+    / "sm15m_global_state.json"
+)
+
+
+def _get_global_sm():
+    """获取全局 SM 实例, 从文件加载或创建新的"""
+    if os.path.exists(_GLOBAL_STATE_FILE):
+        try:
+            with open(_GLOBAL_STATE_FILE, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            sm_instance = SM.load(data)
+            return sm_instance
+        except Exception:
+            # 如果加载失败, 创建新的实例
+            pass
+
+    # 创建新的 SM 实例
+    sm_instance = SM()
+    # 保存初始状态
+    _save_global_sm(sm_instance)
+    return sm_instance
+
+
+def _save_global_sm(sm_instance):
+    """保存全局 SM 实例到文件"""
+    try:
+        data = sm_instance.data()
+        with open(_GLOBAL_STATE_FILE, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+    except Exception:
+        # 忽略保存错误
+        pass
+
+
+class SM15MAlgorithm:
+    algo_name = "SM-15M"
+
+    class AlgodataDict(TypedDict):
+        efactor: float
+        real_rept: int
+        rept: int
+        interval: int
+        last_date: int
+        next_date: int
+        is_activated: int
+        last_modify: float
+
+    defaults = {
+        "efactor": 2.5,
+        "real_rept": 0,
+        "rept": 0,
+        "interval": 0,
+        "last_date": 0,
+        "next_date": 0,
+        "is_activated": 0,
+        "last_modify": 0.0,
+    }
+
+    @classmethod
+    def _get_timestamp(cls):
+        """获取当前时间戳(秒)"""
+        return datetime.datetime.now().timestamp()
+
+    @classmethod
+    def _get_daystamp(cls):
+        """获取当前天数戳(从某个纪元开始的天数)"""
+        # 使用与原始 SM-2 相同的纪元：1970-01-01
+        now = datetime.datetime.now()
+        epoch = datetime.datetime(1970, 1, 1)
+        delta = now - epoch
+        return delta.days
+
+    @classmethod
+    def _algodata_to_item(cls, algodata, sm_instance):
+        """将 algodata 转换为 Item 实例"""
+        # 从 algodata 获取 SM-2 数据
+        sm15_data = algodata.get(cls.algo_name, cls.defaults.copy())
+
+        # 创建 Item 实例
+        item = Item(sm_instance)
+
+        # 映射字段
+        # efactor -> A-Factor (需要转换)
+        efactor = sm15_data.get("efactor", 2.5)
+        # SM-2 的 efactor 范围 [1.3, 2.5+], SM-15 的 A-Factor 范围 [1.2, 6.9]
+        # 简单线性映射：af = (efactor - 1.3) * (MAX_AF - MIN_AF) / (2.5 - 1.3) + MIN_AF
+        # 但 efactor 可能大于 2.5, 所以需要限制
+        af = max(MIN_AF, min(MAX_AF, efactor * 2.0))  # 粗略映射
+        # 调试
+        # print(f"DEBUG: efactor={efactor}, af before set={af}")
+        item.af(af)
+        # print(f"DEBUG: item.af() after set={item.af()}")
+
+        # rept -> repetition (成功回忆次数)
+        rept = sm15_data.get("rept", 0)
+        item.repetition = (
+            rept - 1 if rept > 0 else -1
+        )  # SM-15 中 repetition=-1 表示新项目
+
+        # real_rept -> lapse? 或者忽略
+        real_rept = sm15_data.get("real_rept", 0)
+        # 可以存储在 value 中或忽略
+
+        # interval -> optimum_interval (需要从天数转换为毫秒)
+        interval_days = sm15_data.get("interval", 0)
+        if interval_days == 0:
+            item.optimum_interval = sm_instance.interval_base
+        else:
+            item.optimum_interval = interval_days * 24 * 60 * 60 * 1000  # 天转毫秒
+
+        # last_date -> previous_date
+        last_date_days = sm15_data.get("last_date", 0)
+        if last_date_days > 0:
+            epoch = datetime.datetime(1970, 1, 1)
+            item.previous_date = epoch + datetime.timedelta(days=last_date_days)
+
+        # next_date -> due_date
+        next_date_days = sm15_data.get("next_date", 0)
+        if next_date_days > 0:
+            epoch = datetime.datetime(1970, 1, 1)
+            item.due_date = epoch + datetime.timedelta(days=next_date_days)
+
+        # is_activated 和 last_modify 忽略
+
+        # 将原始 algodata 保存在 value 中以便恢复
+        item.value = {
+            "front": "SM-15 item",
+            "back": "SM-15 item",
+            "_sm15_data": sm15_data,
+        }
+
+        return item
+
+    @classmethod
+    def _item_to_algodata(cls, item, algodata):
+        """将 Item 实例状态写回 algodata"""
+        if cls.algo_name not in algodata:
+            algodata[cls.algo_name] = cls.defaults.copy()
+
+        sm15_data = algodata[cls.algo_name]
+
+        # A-Factor -> efactor (反向映射)
+        af = item.af()
+        if af is None:
+            af = MIN_AF
+        # 反向粗略映射
+        efactor = max(1.3, min(af / 2.0, 10.0))  # 限制范围
+        # 调试
+        # print(f"DEBUG: item.af()={af}, computed efactor={efactor}")
+        sm15_data["efactor"] = efactor
+
+        # repetition -> rept
+        rept = item.repetition + 1 if item.repetition >= 0 else 0
+        sm15_data["rept"] = rept
+
+        # real_rept: 递增在 revisor 中处理, 这里保持不变
+        # 但如果没有 real_rept 字段, 则初始化为0
+        if "real_rept" not in sm15_data:
+            sm15_data["real_rept"] = 0
+
+        # optimum_interval -> interval (毫秒转天)
+        interval_ms = item.optimum_interval
+        if interval_ms == item.sm.interval_base:
+            sm15_data["interval"] = 0
+        else:
+            interval_days = max(0, round(interval_ms / (24 * 60 * 60 * 1000)))
+            sm15_data["interval"] = interval_days
+
+        # previous_date -> last_date
+        if item.previous_date:
+            epoch = datetime.datetime(1970, 1, 1)
+            last_date_days = (item.previous_date - epoch).days
+            sm15_data["last_date"] = last_date_days
+        else:
+            sm15_data["last_date"] = 0
+
+        # due_date -> next_date
+        if item.due_date:
+            epoch = datetime.datetime(1970, 1, 1)
+            next_date_days = (item.due_date - epoch).days
+            sm15_data["next_date"] = next_date_days
+        else:
+            sm15_data["next_date"] = 0
+
+        # is_activated: 保持不变或设为1
+        if "is_activated" not in sm15_data:
+            sm15_data["is_activated"] = 1
+
+        # last_modify: 更新时间戳
+        sm15_data["last_modify"] = cls._get_timestamp()
+
+        return algodata
+
+    @classmethod
+    def revisor(
+        cls, algodata: dict, feedback: int = 5, is_new_activation: bool = False
+    ):
+        """SM-15 算法迭代决策机制实现"""
+        # 获取全局 SM 实例
+        sm_instance = _get_global_sm()
+
+        # 将 algodata 转换为 Item
+        item = cls._algodata_to_item(algodata, sm_instance)
+
+        # 处理 is_new_activation
+        if is_new_activation:
+            # 重置为初始状态
+            item.repetition = -1
+            item.lapse = 0
+            item.optimum_interval = sm_instance.interval_base
+            item.previous_date = None
+            item.due_date = datetime.datetime.fromtimestamp(0)
+            item.af(2.5)  # 重置 efactor
+
+        # 将项目临时添加到 SM 实例(以便 answer 更新共享状态)
+        sm_instance.q.append(item)
+
+        # 处理反馈(评分)
+        # SM-2 的 feedback 是 0-5, SM-15 的 grade 也是 0-5
+        grade = feedback
+        now = datetime.datetime.now()
+
+        # 调用 answer 方法
+        item.answer(grade, now)
+
+        # 更新共享状态(FI-Graph, ForgettingCurves, OFM)
+        if item.repetition >= 0:
+            sm_instance.forgetting_curves.register_point(grade, item, now)
+            sm_instance.ofm.update()
+            sm_instance.fi_g.update(grade, item, now)
+
+        # 从队列中移除项目
+        sm_instance.q.remove(item)
+
+        # 保存全局状态
+        _save_global_sm(sm_instance)
+
+        # 将更新后的 Item 状态写回 algodata
+        cls._item_to_algodata(item, algodata)
+
+        # 更新 real_rept(总复习次数)
+        algodata[cls.algo_name]["real_rept"] += 1
+
+    @classmethod
+    def is_due(cls, algodata):
+        """检查项目是否到期"""
+        sm15_data = algodata.get(cls.algo_name, cls.defaults.copy())
+        next_date_days = sm15_data.get("next_date", 0)
+        current_daystamp = cls._get_daystamp()
+        return next_date_days <= current_daystamp
+
+    @classmethod
+    def rate(cls, algodata):
+        """获取项目的评分(返回 efactor 字符串)"""
+        sm15_data = algodata.get(cls.algo_name, cls.defaults.copy())
+        efactor = sm15_data.get("efactor", 2.5)
+        return str(efactor)
+
+    @classmethod
+    def nextdate(cls, algodata) -> int:
+        """获取下次复习日期(天数戳)"""
+        sm15_data = algodata.get(cls.algo_name, cls.defaults.copy())
+        next_date_days = sm15_data.get("next_date", 0)
+        return next_date_days

src/heurams/kernel/algorithms/sm2.py

@@ -1,8 +1,10 @@
-from .base import BaseAlgorithm
-import heurams.services.timer as timer
 from typing import TypedDict
+
+import heurams.services.timer as timer
 from heurams.services.logger import get_logger
 
+from .base import BaseAlgorithm
+
 logger = get_logger(__name__)
 
 
@@ -114,7 +116,7 @@ class SM2Algorithm(BaseAlgorithm):
         return result
 
     @classmethod
-    def rate(cls, algodata):
+    def get_rating(cls, algodata):
         efactor = algodata[cls.algo_name]["efactor"]
         logger.debug("SM2.rate: efactor=%f", efactor)
         return str(efactor)

src/heurams/kernel/evaluators/__init__.py

@@ -0,0 +1,26 @@
+"""
+Evaluator 模块 - 生成评估模块
+
+提供多种类型的辅助评估生成器, 支持从字符串、字典等数据源导入题目
+"""
+
+from heurams.services.logger import get_logger
+
+from .base import BaseEvaluator
+from .cloze import ClozePuzzle
+from .mcq import MCQPuzzle
+from .recognition import RecognitionPuzzle
+
+__all__ = [
+    "BaseEvaluator",
+    "ClozePuzzle",
+    "MCQPuzzle",
+    "RecognitionPuzzle",
+]
+
+puzzles = {
+    "mcq": MCQPuzzle,
+    "cloze": ClozePuzzle,
+    "recognition": RecognitionPuzzle,
+    "base": BaseEvaluator,
+}

src/heurams/kernel/evaluators/base.py

@@ -4,11 +4,11 @@ from heurams.services.logger import get_logger
 logger = get_logger(__name__)
 
 
-class BasePuzzle:
+class BaseEvaluator:
     """谜题基类"""
 
     def refresh(self):
-        logger.debug("BasePuzzle.refresh 被调用（未实现）")
+        logger.debug("BasePuzzle.refresh 被调用(未实现)")
         raise NotImplementedError("谜题对象未实现 refresh 方法")
 
     def __str__(self):

src/heurams/kernel/evaluators/cloze.py

@@ -1,11 +1,13 @@
-from .base import BasePuzzle
 import random
+
 from heurams.services.logger import get_logger
 
+from .base import BaseEvaluator
+
 logger = get_logger(__name__)
 
 
-class ClozePuzzle(BasePuzzle):
+class ClozePuzzle(BaseEvaluator):
     """填空题谜题生成器
 
     Args:

src/heurams/kernel/evaluators/guess.py

@@ -0,0 +1,12 @@
+import random
+
+from heurams.services.logger import get_logger
+
+from .base import BaseEvaluator
+
+logger = get_logger(__name__)
+
+
+class GuessEvaluator(BaseEvaluator):
+    def __init__(self):
+        super().__init__()

src/heurams/kernel/evaluators/mcq.py

@@ -1,13 +1,15 @@
 # mcq.py
-from .base import BasePuzzle
 import random
-from typing import List, Dict, Optional, Union
+from typing import Dict, List, Optional, Union
+
 from heurams.services.logger import get_logger
 
+from .base import BaseEvaluator
+
 logger = get_logger(__name__)
 
 
-class MCQPuzzle(BasePuzzle):
+class MCQPuzzle(BaseEvaluator):
     """选择题谜题生成器
 
     该类用于生成和管理选择题谜题, 支持多个题目同时生成,

src/heurams/kernel/evaluators/recognition.py

@@ -1,12 +1,14 @@
 # mcq.py
-from .base import BasePuzzle
 import random
+
 from heurams.services.logger import get_logger
 
+from .base import BaseEvaluator
+
 logger = get_logger(__name__)
 
 
-class RecognitionPuzzle(BasePuzzle):
+class RecognitionPuzzle(BaseEvaluator):
     """识别占位符"""
 
     def __init__(self) -> None:
@@ -14,5 +16,5 @@ class RecognitionPuzzle(BasePuzzle):
         super().__init__()
 
     def refresh(self):
-        logger.debug("RecognitionPuzzle.refresh（空实现）")
+        logger.debug("RecognitionPuzzle.refresh(空实现)")
         pass

src/heurams/kernel/particles/__init__.py

@@ -1,29 +1,21 @@
-"""
-Particle 模块 - 粒子对象系统
-
-提供闪卡所需对象, 使用物理学粒子的领域驱动设计
-"""
-
-from heurams.services.logger import get_logger
-
-logger = get_logger(__name__)
-logger.debug("粒子模块已加载")
-
+from .atom import Atom
 from .electron import Electron
 from .nucleon import Nucleon
-from .orbital import Orbital
-from .atom import Atom, atom_registry
-from .probe import probe_all, probe_by_filename
-from .loader import load_nucleon, load_electron
+from .placeholders import (
+    AtomPlaceholder,
+    NucleonPlaceholder,
+    ElectronPlaceholder,
+    orbital_placeholder,
+)
+
+# from .orbital import Orbital
 
 __all__ = [
+    "Atom",
     "Electron",
     "Nucleon",
-    "Orbital",
-    "Atom",
-    "probe_all",
-    "probe_by_filename",
-    "load_nucleon",
-    "load_electron",
-    "atom_registry",
+    "AtomPlaceholder",
+    "NucleonPlaceholder",
+    "ElectronPlaceholder",
+    "orbital_placeholder",
 ]

src/heurams/kernel/particles/atom.py

@@ -1,14 +1,10 @@
+from typing import TypedDict
+
+
+from heurams.services.logger import get_logger
+
 from .electron import Electron
 from .nucleon import Nucleon
-from .orbital import Orbital
-from typing import TypedDict
-import pathlib
-import typing
-import toml
-import json
-import bidict
-from heurams.context import config_var
-from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
 
@@ -16,19 +12,13 @@ logger = get_logger(__name__)
 class AtomRegister_runtime(TypedDict):
     locked: bool  # 只读锁定标识符
     min_rate: int  # 最低评分
-    newact: bool # 新激活
+    new_activation: bool  # 新激活
 
 
 class AtomRegister(TypedDict):
     nucleon: Nucleon
-    nucleon_path: pathlib.Path
-    nucleon_fmt: str
     electron: Electron
-    electron_path: pathlib.Path
-    electron_fmt: str
-    orbital: Orbital
-    orbital_path: pathlib.Path
-    orbital_fmt: str
+    orbital: dict
     runtime: AtomRegister_runtime
 
 
@@ -41,39 +31,27 @@ class Atom:
         以及关联路径
     """
 
-    def __init__(self, ident=""):
-        logger.debug("创建 Atom 实例, ident: '%s'", ident)
-        self.ident = ident
-        atom_registry[ident] = self
-        logger.debug("Atom 已注册到全局注册表, 当前注册表大小: %d", len(atom_registry))
-        # self.is_evaled = False
-        self.registry: AtomRegister = {  # type: ignore
-            "nucleon": None,
-            "nucleon_path": None,
-            "nucleon_fmt": "toml",
-            "electron": None,
-            "electron_path": None,
-            "electron_fmt": "json",
-            "orbital": None,
-            "orbital_path": None,  # 允许设置为 None, 此时使用 nucleon 文件内的推荐配置
-            "orbital_fmt": "toml",
-            "runtime": {"locked": False, "min_rate": 0x3F3F3F3F, "newact": False},
+    default_runtime = {
+        "locked": False,
+        "min_rate": 0x3F3F3F3F,
+        "new_activation": False,
     }
-        self.do_eval()
-        logger.debug("Atom 初始化完成")
 
-    def link(self, key, value):
-        logger.debug("Atom.link: key='%s', value type: %s", key, type(value).__name__)
-        if key in self.registry.keys():
-            self.registry[key] = value
-            logger.debug("键 '%s' 已链接, 触发 do_eval", key)
-            self.do_eval()
-            if key == 'electron':
-                if self.registry['electron'].is_activated() == 0:
-                    self.registry['runtime']['newact'] = True
-        else:
-            logger.error("尝试链接不受支持的键: '%s'", key)
-            raise ValueError("不受支持的原子元数据链接操作")
+    def __init__(self, nucleon_obj=None, electron_obj=None, orbital_obj=None):
+        self.ident = nucleon_obj["ident"]  # type: ignore
+        self.registry: AtomRegister = {  # type: ignore
+            "ident": nucleon_obj["ident"],  # type: ignore
+            "nucleon": nucleon_obj,
+            "electron": electron_obj,
+            "orbital": orbital_obj,
+            "runtime": dict(),
+        }
+        self.init_runtime()
+        if self.registry["electron"].is_activated() == 0:
+            self.registry["runtime"]["new_activation"] = True
+
+    def init_runtime(self):
+        self.registry["runtime"] = AtomRegister_runtime(**self.default_runtime)
 
     def minimize(self, rating):
         """效果等同于 self.registry['runtime']['min_rate'] = min(rating, self.registry['runtime']['min_rate'])
@@ -104,135 +82,23 @@ class Atom:
         """
         if self.registry["runtime"]["locked"]:
             logger.debug(f"允许总评分: {self.registry['runtime']['min_rate']}")
-            self.registry["electron"].revisor(self.registry["runtime"]["min_rate"], is_new_activation=self.registry["runtime"]["newact"])
+            self.registry["electron"].revisor(
+                self.registry["runtime"]["min_rate"],
+                is_new_activation=self.registry["runtime"]["new_activation"],
+            )
         else:
             logger.debug("禁止总评分")
 
-    def do_eval(self):
-        """
-        执行并以结果替换当前单元的所有 eval 语句
-        TODO: 带有限制的 eval, 异步/多线程执行避免堵塞
-        """
-        logger.debug("Atom.do_eval 开始")
-
-        # eval 环境设置
-        def eval_with_env(s: str):
-            # 初始化默认值
-            nucleon = self.registry["nucleon"]
-            default = {}
-            metadata = {}
-            try:
-                default = config_var.get()["puzzles"]
-                metadata = nucleon.metadata
-            except Exception:
-                # 如果无法获取配置或元数据, 使用空字典
-                logger.debug("无法获取配置或元数据, 使用空字典")
-                pass
-            try:
-                eval_value = eval(s)
-                if isinstance(eval_value, (list, dict)):
-                    ret = eval_value
-                else:
-                    ret = str(eval_value)
-                logger.debug(
-                    "eval 执行成功: '%s' -> '%s'",
-                    s,
-                    str(ret)[:50] + "..." if len(ret) > 50 else ret,
-                )
-            except Exception as e:
-                ret = f"此 eval 实例发生错误: {e}"
-                logger.warning("eval 执行错误: '%s' -> %s", s, e)
-            return ret
-
-        def traverse(data, modifier):
-            if isinstance(data, dict):
-                for key, value in data.items():
-                    data[key] = traverse(value, modifier)
-                return data
-            elif isinstance(data, list):
-                for i, item in enumerate(data):
-                    data[i] = traverse(item, modifier)
-                return data
-            elif isinstance(data, tuple):
-                return tuple(traverse(item, modifier) for item in data)
-            else:
-                if isinstance(data, str):
-                    if data.startswith("eval:"):
-                        logger.debug("发现 eval 表达式: '%s'", data[5:])
-                        return modifier(data[5:])
-                return data
-
-        # 如果 nucleon 存在且有 do_eval 方法, 调用它
-        nucleon = self.registry["nucleon"]
-        if nucleon is not None and hasattr(nucleon, "do_eval"):
-            nucleon.do_eval()
-            logger.debug("已调用 nucleon.do_eval")
-
-        # 如果 electron 存在且其 algodata 包含 eval 字符串, 遍历它
-        electron = self.registry["electron"]
-        if electron is not None and hasattr(electron, "algodata"):
-            traverse(electron.algodata, eval_with_env)
-            logger.debug("已处理 electron algodata eval")
-
-        # 如果 orbital 存在且是字典, 遍历它
-        orbital = self.registry["orbital"]
-        if orbital is not None and isinstance(orbital, dict):
-            traverse(orbital, eval_with_env)
-            logger.debug("orbital eval 完成")
-
-        logger.debug("Atom.do_eval 完成")
-
-    def persist(self, key):
-        logger.debug("Atom.persist: key='%s'", key)
-        path: pathlib.Path | None = self.registry[key + "_path"]
-        if isinstance(path, pathlib.Path):
-            path = typing.cast(pathlib.Path, path)
-            logger.debug("持久化路径: %s, 格式: %s", path, self.registry[key + "_fmt"])
-            path.parent.mkdir(parents=True, exist_ok=True)
-            if self.registry[key + "_fmt"] == "toml":
-                with open(path, "r+") as f:
-                    f.seek(0)
-                    f.truncate()
-                    toml.dump(self.registry[key], f)
-                logger.debug("TOML 数据已保存到: %s", path)
-            elif self.registry[key + "_fmt"] == "json":
-                with open(path, "r+") as f:
-                    origin = json.load(f)
-                    f.seek(0)
-                    f.truncate()
-                    origin[self.ident] = self.registry[key].algodata
-                    json.dump(origin, f, indent=2, ensure_ascii=False)
-                logger.debug("JSON 数据已保存到: %s", path)
-            else:
-                logger.error("不受支持的持久化格式: %s", self.registry[key + "_fmt"])
-                raise KeyError("不受支持的持久化格式")
-        else:
-            logger.error("路径未初始化: %s_path", key)
-            raise TypeError("对未初始化的路径对象操作")
-
     def __getitem__(self, key):
-        logger.debug("Atom.__getitem__: key='%s'", key)
-        if key in self.registry:
-            value = self.registry[key]
-            logger.debug("返回 value type: %s", type(value).__name__)
-            return value
-        logger.error("不支持的键: '%s'", key)
-        raise KeyError(f"不支持的键: {key}")
+        return self.registry[key]
 
     def __setitem__(self, key, value):
-        logger.debug(
-            "Atom.__setitem__: key='%s', value type: %s", key, type(value).__name__
-        )
-        if key in self.registry:
+        if key == "ident":
+            raise AttributeError("应为只读")
         self.registry[key] = value
-            logger.debug("键 '%s' 已设置", key)
-        else:
-            logger.error("不支持的键: '%s'", key)
-            raise KeyError(f"不支持的键: {key}")
 
-    @staticmethod
-    def placeholder():
-        return (Electron.placeholder(), Nucleon.placeholder(), {})
+    def __repr__(self):
+        from pprint import pformat
 
-
-atom_registry: bidict.bidict[str, Atom] = bidict.bidict()
+        s = pformat(self.registry, indent=4)
+        return s

src/heurams/kernel/particles/electron.py

@@ -1,5 +1,8 @@
+from copy import deepcopy
+from typing import TypedDict
+
+import heurams.kernel.algorithms as algolib
 import heurams.services.timer as timer
-from heurams.context import config_var
 from heurams.kernel.algorithms import algorithms
 from heurams.services.logger import get_logger
 
@@ -7,87 +10,62 @@ logger = get_logger(__name__)
 
 
 class Electron:
-    """电子: 记忆分析元数据及算法"""
+    """电子: 单算法支持的记忆数据包装"""
 
-    def __init__(self, ident: str, algodata: dict = {}, algo_name: str = "supermemo2"):
+    def __init__(self, ident: str, algodata: dict = {}, algo_name: str = ""):
         """初始化电子对象 (记忆数据)
 
         Args:
             ident: 算法的唯一标识符, 用于区分不同的算法实例, 使用 algodata[ident] 获取
-            algodata: 算法数据字典, 包含算法的各项参数和设置
-            algo: 使用的算法模块标识
+            algodata: 算法数据字典引用, 包含算法的各项参数和设置
+            algo_name: 使用的算法模块标识
         """
-        logger.debug(
-            "创建 Electron 实例, ident: '%s', algo_name: '%s'", ident, algo_name
-        )
+        if algo_name == "":
+            algo_name = "SM-2"
         self.algodata = algodata
         self.ident = ident
-        self.algo = algorithms[algo_name]
-        logger.debug("使用的算法类: %s", self.algo.__name__)
+        self.algo: algolib.BaseAlgorithm = algorithms[algo_name]
 
-        if self.algo not in self.algodata.keys():
-            self.algodata[self.algo.algo_name] = {}
-            logger.debug("算法键 '%s' 不存在, 已创建空字典", self.algo)
-        if not self.algodata[self.algo.algo_name]:
-            logger.debug("算法数据为空, 使用默认值初始化")
-            self._default_init(self.algo.defaults)
-        else:
-            logger.debug("算法数据已存在, 跳过默认初始化")
-        logger.debug(
-            "Electron 初始化完成, algodata keys: %s", list(self.algodata.keys())
-        )
+        if not self.algo.check_integrity(self.algodata):
+            self.algodata[self.algo.algo_name] = deepcopy(self.algo.defaults)
 
-    def _default_init(self, defaults: dict):
-        """默认初始化包装"""
-        logger.debug(
-            "Electron._default_init: 使用默认值, keys: %s", list(defaults.keys())
-        )
-        self.algodata[self.algo.algo_name] = defaults.copy()
+    def __repr__(self):
+        from pprint import pformat
+
+        s = pformat(self.algodata, indent=4)
+        return s
 
     def activate(self):
         """激活此电子"""
-        logger.debug("Electron.activate: 激活 ident='%s'", self.ident)
         self.algodata[self.algo.algo_name]["is_activated"] = 1
         self.algodata[self.algo.algo_name]["last_modify"] = timer.get_timestamp()
-        logger.debug("电子已激活, is_activated=1")
 
-    def modify(self, var: str, value):
+    def modify(self, key, value):
         """修改 algodata[algo] 中子字典数据"""
-        logger.debug("Electron.modify: var='%s', value=%s", var, value)
-        if var in self.algodata[self.algo.algo_name]:
-            self.algodata[self.algo.algo_name][var] = value
+        if key in self.algodata[self.algo.algo_name]:
+            self.algodata[self.algo.algo_name][key] = value
             self.algodata[self.algo.algo_name]["last_modify"] = timer.get_timestamp()
-            logger.debug("变量 '%s' 已修改, 更新 last_modify", var)
         else:
-            logger.warning("'%s' 非已知元数据字段", var)
-            print(f"警告: '{var}' 非已知元数据字段")
+            raise AttributeError("不存在的子键")
 
     def is_due(self):
         """是否应该复习"""
-        logger.debug("Electron.is_due: 检查 ident='%s'", self.ident)
         result = self.algo.is_due(self.algodata)
-        logger.debug("is_due 结果: %s", result)
         return result and self.is_activated()
 
     def is_activated(self):
         result = self.algodata[self.algo.algo_name]["is_activated"]
-        logger.debug("Electron.is_activated: ident='%s', 结果: %d", self.ident, result)
         return result
 
-    def get_rate(self):
-        "评价"
+    def get_rating(self):
         try:
-            logger.debug("Electron.rate: ident='%s'", self.ident)
-            result = self.algo.rate(self.algodata)
-            logger.debug("rate 结果: %s", result)
+            result = self.algo.get_rating(self.algodata)
             return result
         except:
             return 0
 
     def nextdate(self) -> int:
-        logger.debug("Electron.nextdate: ident='%s'", self.ident)
         result = self.algo.nextdate(self.algodata)
-        logger.debug("nextdate 结果: %d", result)
         return result
 
     def revisor(self, quality: int = 5, is_new_activation: bool = False):
@@ -97,32 +75,7 @@ class Electron:
             quality (int): 记忆保留率量化参数 (0-5)
             is_new_activation (bool): 是否为初次激活
         """
-        logger.debug(
-            "Electron.revisor: ident='%s', quality=%d, is_new_activation=%s",
-            self.ident,
-            quality,
-            is_new_activation,
-        )
         self.algo.revisor(self.algodata, quality, is_new_activation)
-        logger.debug(
-            "revisor 完成, 更新后的 algodata: %s", self.algodata.get(self.algo, {})
-        )
-
-    def __str__(self):
-        return (
-            f"记忆单元预览 \n"
-            f"标识符: '{self.ident}' \n"
-            f"算法: {self.algo} \n"
-            f"易度系数: {self.algodata[self.algo.algo_name]['efactor']:.2f} \n"
-            f"已经重复的次数: {self.algodata[self.algo.algo_name]['rept']} \n"
-            f"下次间隔: {self.algodata[self.algo.algo_name]['interval']} 天 \n"
-            f"下次复习日期时间戳: {self.algodata[self.algo.algo_name]['next_date']}"
-        )
-
-    def __eq__(self, other):
-        if self.ident == other.ident:
-            return True
-        return False
 
     def __hash__(self):
         return hash(self.ident)
@@ -146,6 +99,9 @@ class Electron:
         return len(self.algodata[self.algo.algo_name])
 
     @staticmethod
-    def placeholder():
-        """生成一个电子占位符"""
-        return Electron("电子对象样例内容", {})
+    def create_on_electonic_data(electronic_data: tuple, algo_name: str = ""):
+        _data = electronic_data
+        ident = _data[0]
+        algodata = _data[1]
+        ident = ident
+        return Electron(ident, algodata, algo_name)

src/heurams/kernel/particles/loader.py

@@ -1,71 +0,0 @@
-from .nucleon import Nucleon
-from .electron import Electron
-import heurams.services.hasher as hasher
-import pathlib
-import toml
-import json
-from copy import deepcopy
-from heurams.services.logger import get_logger
-
-logger = get_logger(__name__)
-
-
-def load_nucleon(path: pathlib.Path, fmt="toml"):
-    logger.debug("load_nucleon: 加载文件 %s, 格式: %s", path, fmt)
-    with open(path, "r") as f:
-        dictdata = dict()
-        dictdata = toml.load(f)  # type: ignore
-        logger.debug("TOML 解析成功, keys: %s", list(dictdata.keys()))
-        lst = list()
-        nested_data = dict()
-        # 修正 toml 解析器的不管嵌套行为
-        for key, value in dictdata.items():
-            if "__metadata__" in key:  # 以免影响句号
-                if "." in key:
-                    parts = key.split(".")
-                    current = nested_data
-                    for part in parts[:-1]:
-                        if part not in current:
-                            current[part] = {}
-                        current = current[part]
-                    current[parts[-1]] = value
-                logger.debug("处理元数据键: %s", key)
-            else:
-                nested_data[key] = value
-        logger.debug("嵌套数据处理完成, keys: %s", list(nested_data.keys()))
-        # print(nested_data)
-        for item, attr in nested_data.items():
-            if item == "__metadata__":
-                continue
-            logger.debug("处理项目: %s", item)
-            lst.append(
-                (
-                    Nucleon(item, attr, deepcopy(nested_data["__metadata__"])),
-                    deepcopy(nested_data["__metadata__"]["orbital"]),
-                )
-            )
-        logger.debug("load_nucleon 完成, 加载了 %d 个 Nucleon 对象", len(lst))
-        return lst
-
-
-def load_electron(path: pathlib.Path, fmt="json") -> dict:
-    """从文件路径加载电子对象
-
-    Args:
-        path (pathlib.Path): 路径
-        fmt (str): 文件格式(可选, 默认 json)
-
-    Returns:
-        dict: 键名是电子对象名称, 值是电子对象
-    """
-    logger.debug("load_electron: 加载文件 %s, 格式: %s", path, fmt)
-    with open(path, "r") as f:
-        dictdata = dict()
-        dictdata = json.load(f)  # type: ignore
-        logger.debug("JSON 解析成功, keys: %s", list(dictdata.keys()))
-        dic = dict()
-        for item, attr in dictdata.items():
-            logger.debug("处理电子项目: %s", item)
-            dic[item] = Electron(item, attr)
-        logger.debug("load_electron 完成, 加载了 %d 个 Electron 对象", len(dic))
-        return dic

src/heurams/kernel/particles/nucleon.py

@@ -1,104 +1,64 @@
+from copy import deepcopy
+from logging import config
+
 from heurams.services.logger import get_logger
+from heurams.utils.evalizor import Evalizer
+from heurams.context import config_var
 
 logger = get_logger(__name__)
 
 
 class Nucleon:
-    """原子核: 材料元数据"""
+    """原子核: 带有运行时隔离的模板化只读材料元数据容器"""
 
-    def __init__(self, ident: str, payload: dict, metadata: dict = {}):
-        """初始化原子核 (记忆内容)
-
-        Args:
-            ident: 唯一标识符
-            payload: 记忆内容信息
-            metadata: 可选元数据信息
-        """
-        logger.debug(
-            "创建 Nucleon 实例, ident: '%s', payload keys: %s, metadata keys: %s",
-            ident,
-            list(payload.keys()) if payload else [],
-            list(metadata.keys()) if metadata else [],
-        )
-        self.metadata = metadata
-        self.payload = payload
+    def __init__(self, ident, payload, common):
         self.ident = ident
-        logger.debug("Nucleon 初始化完成")
+        env = {
+            "payload": payload,
+            "default": config_var.get()["puzzles"],
+            "nucleon": (payload | common),
+        }
+        self.evalizer = Evalizer(environment=env)
+        self.data: dict = self.evalizer(deepcopy((payload | common)))  # type: ignore
 
     def __getitem__(self, key):
-        logger.debug("Nucleon.__getitem__: key='%s'", key)
+        if isinstance(key, str):
             if key == "ident":
-            logger.debug("返回 ident: '%s'", self.ident)
                 return self.ident
-        if key in self.payload:
-            value = self.payload[key]
-            logger.debug(
-                "返回 payload['%s'], value type: %s", key, type(value).__name__
-            )
-            return value
+            return self.data[key]
         else:
-            logger.error("键 '%s' 未在 payload 中找到", key)
-            raise KeyError(f"Key '{key}' not found in payload.")
+            raise AttributeError
+
+    def __setitem__(self, key, value):
+        raise AttributeError("应为只读")
+
+    def __delitem__(self, key):
+        raise AttributeError("应为只读")
 
     def __iter__(self):
-        yield from self.payload.keys()
+        return iter(self.data)
+
+    def __contains__(self, key):
+        return key in (self.data)
+
+    def get(self, key, default=None):
+        if key in self:
+            return self[key]
+        return default
 
     def __len__(self):
-        return len(self.payload)
+        return len(self.data)
 
-    def __hash__(self):
-        return hash(self.ident)
+    def __repr__(self):
+        from pprint import pformat
 
-    def do_eval(self):
-        """
-        执行并以结果替换当前单元的所有 eval 语句
-        TODO: 带有限制的 eval, 异步/多线程执行避免堵塞
-        """
-        logger.debug("Nucleon.do_eval 开始")
-
-        # eval 环境设置
-        def eval_with_env(s: str):
-            try:
-                nucleon = self
-                eval_value = eval(s)
-                if isinstance(eval_value, (int, float)):
-                    ret = str(eval_value)
-                else:
-                    ret = eval_value
-                logger.debug(
-                    "eval 执行成功: '%s' -> '%s'",
-                    s,
-                    str(ret)[:50] + "..." if len(ret) > 50 else ret,
-                )
-            except Exception as e:
-                ret = f"此 eval 实例发生错误: {e}"
-                logger.warning("eval 执行错误: '%s' -> %s", s, e)
-            return ret
-
-        def traverse(data, modifier):
-            if isinstance(data, dict):
-                for key, value in data.items():
-                    data[key] = traverse(value, modifier)
-                return data
-            elif isinstance(data, list):
-                for i, item in enumerate(data):
-                    data[i] = traverse(item, modifier)
-                return data
-            elif isinstance(data, tuple):
-                return tuple(traverse(item, modifier) for item in data)
-            else:
-                if isinstance(data, str):
-                    if data.startswith("eval:"):
-                        logger.debug("发现 eval 表达式: '%s'", data[5:])
-                        return modifier(data[5:])
-                return data
-
-        traverse(self.payload, eval_with_env)
-        traverse(self.metadata, eval_with_env)
-        logger.debug("Nucleon.do_eval 完成")
+        s = pformat(self.data, indent=4)
+        return s
 
     @staticmethod
-    def placeholder():
-        """生成一个占位原子核"""
-        logger.debug("创建 Nucleon 占位符")
-        return Nucleon("核子对象样例内容", {})
+    def create_on_nucleonic_data(nucleonic_data: tuple):
+        _data = nucleonic_data
+        payload = _data[1][0]
+        common = _data[1][1]
+        ident = _data[0]  # TODO:实现eval
+        return Nucleon(ident, payload, common)

src/heurams/kernel/particles/orbital.py

@@ -1,29 +1,17 @@
-from typing import TypedDict
-from heurams.services.logger import get_logger
+"""轨道对象"""
 
-logger = get_logger(__name__)
-logger.debug("Orbital 类型定义模块已加载")
+# 似乎没有实现这个类的必要...
+# 那不妨在这儿写点文档
 
-
-class OrbitalSchedule(TypedDict):
-    quick_review: list
-    recognition: list
-    final_review: list
-
-
-class Orbital(TypedDict):
-    schedule: OrbitalSchedule
-    puzzles: dict
-
-
-"""一份示例
-["__metadata__.orbital.puzzles"] # 谜题定义
-"Recognition" = { __origin__ = "recognition", __hint__ = "", primary = "eval:nucleon['content']", secondery = ["eval:nucleon['keyword_note']", "eval:nucleon['note']"], top_dim = ["eval:nucleon['translation']"] }
-"SelectMeaning" = { __origin__ = "mcq", __hint__ = "eval:nucleon['content']", 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, 即轨道, 是定义队列式复习阶段流程的数据结构, 其实就是个字典, 至于为何不用typeddict, 因为懒.
+
+orbital_example = {
+    "schedule": [列表 存储阶段(phases)名称]
+    "phases":{
+        阶段名称 = [["谜题(puzzle 现称 evaluator 评估器)名称", "概率系数 可大于1(整数部分为重复次数) 注意使用字符串包裹(toml 规范)"], ...],
+        ...
+    }
+}
+至于谜题定义 放在 nucleon['puzzles'], 这样设计是为了兼容多种不同谜题实现的记忆单元, 尽管如此, 你也可见其谜题调度方式必须是相同的.
 """

src/heurams/kernel/particles/placeholders.py

@@ -0,0 +1,41 @@
+from heurams.kernel.particles import orbital
+from .electron import Electron
+from .nucleon import Nucleon
+from .atom import Atom
+
+orbital_placeholder = {
+    "schedule": ["quick_review", "recognition", "final_review"],
+    "phases": {
+        "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],
+        ],
+    },
+}
+
+
+class NucleonPlaceholder(Nucleon):
+    def __init__(self):
+        super().__init__("__placeholder__", {}, {})
+
+    def __getitem__(self, key):
+        return f"__placeholder__ attempted {key}"
+
+
+class ElectronPlaceholder(Electron):
+    def __init__(self):
+        super().__init__("__placeholder__", {"": {"": ""}}, "")
+
+
+class AtomPlaceholder(Atom):
+    def __init__(self):
+        super().__init__(
+            NucleonPlaceholder(), ElectronPlaceholder(), orbital_placeholder
+        )

src/heurams/kernel/particles/probe.py

@@ -1,61 +0,0 @@
-from heurams.context import config_var
-import pathlib
-from heurams.services.logger import get_logger
-
-logger = get_logger(__name__)
-
-
-def probe_by_filename(filename):
-    """探测指定文件 (无扩展名) 的所有信息"""
-    logger.debug("probe_by_filename: 探测文件 '%s'", filename)
-    paths: dict = config_var.get().get("paths")
-    logger.debug("配置路径: %s", paths)
-    formats = ["toml", "json"]
-    result = {}
-    for item, attr in paths.items():
-        for i in formats:
-            attr: pathlib.Path = pathlib.Path(attr) / filename + "." + i
-            if attr.exists():
-                logger.debug("找到文件: %s", attr)
-                result[item.replace("_dir", "")] = str(attr)
-            else:
-                logger.debug("文件不存在: %s", attr)
-    logger.debug("probe_by_filename 结果: %s", result)
-    return result
-
-
-def probe_all(is_stem=1):
-    """依据目录探测所有信息
-
-    Args:
-        is_stem (boolean): 是否**删除**文件扩展名
-
-    Returns:
-        dict: 有三项, 每一项的键名都是文件组类型, 值都是文件组列表, 只包含文件名
-    """
-    logger.debug("probe_all: 开始探测, is_stem=%d", is_stem)
-    paths: dict = config_var.get().get("paths")
-    logger.debug("配置路径: %s", paths)
-    result = {}
-    for item, attr in paths.items():
-        attr: pathlib.Path = pathlib.Path(attr)
-        result[item.replace("_dir", "")] = list()
-        logger.debug("扫描目录: %s", attr)
-        file_count = 0
-        for i in attr.iterdir():
-            if not i.is_dir():
-                file_count += 1
-                if is_stem:
-                    result[item.replace("_dir", "")].append(str(i.stem))
-                else:
-                    result[item.replace("_dir", "")].append(str(i.name))
-        logger.debug("目录 %s 中找到 %d 个文件", attr, file_count)
-    logger.debug("probe_all 完成, 结果 keys: %s", list(result.keys()))
-    return result
-
-
-if __name__ == "__main__":
-    import os
-
-    print(os.getcwd())
-    print(probe_all())

src/heurams/kernel/puzzles/__init__.py

@@ -1,63 +0,0 @@
-"""
-Puzzle 模块 - 谜题生成系统
-
-提供多种类型的谜题生成器, 支持从字符串、字典等数据源导入题目
-"""
-
-from heurams.services.logger import get_logger
-
-logger = get_logger(__name__)
-
-from .base import BasePuzzle
-from .cloze import ClozePuzzle
-from .mcq import MCQPuzzle
-from .recognition import RecognitionPuzzle
-
-__all__ = [
-    "BasePuzzle",
-    "ClozePuzzle",
-    "MCQPuzzle",
-    "RecognitionPuzzle",
-]
-
-puzzles = {
-    "mcq": MCQPuzzle,
-    "cloze": ClozePuzzle,
-    "recognition": RecognitionPuzzle,
-    "base": BasePuzzle,
-}
-
-
-@staticmethod
-def create_by_dict(config_dict: dict) -> BasePuzzle:
-    """
-    根据配置字典创建谜题
-
-    Args:
-        config_dict: 配置字典, 包含谜题类型和参数
-
-    Returns:
-        BasePuzzle: 谜题实例
-
-    Raises:
-        ValueError: 当配置无效时抛出
-    """
-    logger.debug(
-        "puzzles.create_by_dict: config_dict keys=%s", list(config_dict.keys())
-    )
-    puzzle_type = config_dict.get("type")
-
-    if puzzle_type == "cloze":
-        return puzzles["cloze"](
-            text=config_dict["text"],
-            min_denominator=config_dict.get("min_denominator", 7),
-        )
-    elif puzzle_type == "mcq":
-        return puzzles["mcq"](
-            mapping=config_dict["mapping"],
-            jammer=config_dict.get("jammer", []),
-            max_riddles_num=config_dict.get("max_riddles_num", 2),
-            prefix=config_dict.get("prefix", ""),
-        )
-    else:
-        raise ValueError(f"未知的谜题类型: {puzzle_type}")

src/heurams/kernel/reactor/README.md

@@ -0,0 +1 @@
+# Reactor - 记忆过程状态机模块

src/heurams/kernel/reactor/__init__.py

@@ -1,11 +1,8 @@
-from .states import PhaserState, ProcessionState
-from .procession import Procession
-from .fission import Fission
-from .phaser import Phaser
 from heurams.services.logger import get_logger
 
-logger = get_logger(__name__)
+from .fission import Fission
+from .phaser import Phaser
+from .procession import Procession
+from .states import PhaserState, ProcessionState
 
 __all__ = ["PhaserState", "ProcessionState", "Procession", "Fission", "Phaser"]
-
-logger.debug("反应堆模块已加载")

src/heurams/kernel/reactor/fission.py

@@ -1,26 +1,34 @@
-import heurams.kernel.particles as pt
-import heurams.kernel.puzzles as puz
 import random
-from .states import PhaserState
+
+import heurams.kernel.evaluators as puz
+import heurams.kernel.particles as pt
 from heurams.services.logger import get_logger
 
+from .states import PhaserState
+
 
 class Fission:
-    """裂变器: 单原子调度展开器"""
+    """单原子调度展开器"""
 
-    def __init__(self, atom: pt.Atom, phase=PhaserState.RECOGNITION):
+    def __init__(self, atom: pt.Atom, phase_state=PhaserState.RECOGNITION):
+        self.cursor = 0
         self.logger = get_logger(__name__)
         self.atom = atom
-        # print(f"{phase.value}")
-        self.orbital_schedule = atom.registry["orbital"]["schedule"][phase.value]  # type: ignore
-        self.orbital_puzzles = atom.registry["orbital"]["puzzles"]
-        # print(self.orbital_schedule)
+
+        # NOTE: phase 为 PhaserState 枚举实例，需要获取其value
+        phase_value = (
+            phase_state.value if isinstance(phase_state, PhaserState) else phase_state
+        )
+
+        self.orbital_schedule = atom.registry["orbital"]["phases"][phase_value]  # type: ignore
+        self.orbital_puzzles = atom.registry["nucleon"]["puzzles"]
+
         self.puzzles = list()
         for item, possibility in self.orbital_schedule:  # type: ignore
-            print(f"ad:{item}")
-            self.logger.debug(f"开始处理 orbital 项: {item}")
+            self.logger.debug(f"开始处理: {item}")
             if not isinstance(possibility, float):
                 possibility = float(possibility)
+
             while possibility > 1:
                 self.puzzles.append(
                     {
@@ -29,6 +37,7 @@ class Fission:
                     }
                 )
                 possibility -= 1
+
             if random.random() <= possibility:
                 self.puzzles.append(
                     {
@@ -36,8 +45,23 @@ class Fission:
                         "alia": item,
                     }
                 )
-            print(f"ok:{item}")
+
             self.logger.debug(f"orbital 项处理完成: {item}")
 
-    def generate(self):
-        yield from self.puzzles
+    def get_puzzles(self):
+        return self.puzzles
+
+    def get_current_puzzle(self, forward=0):
+        if forward:
+            if len(self.puzzles) <= self.cursor + 1:
+                return 0
+            self.cursor += 1
+            return self.puzzles[self.cursor]
+        else:
+            return self.puzzles[self.cursor]
+
+    def check_passed(self):
+        for i in self.puzzles:
+            if i["finished"] == 0:
+                return 0
+        return 1

src/heurams/kernel/reactor/phaser.py

@@ -1,50 +1,142 @@
-# 移相器类定义
-
 import heurams.kernel.particles as pt
-from .states import PhaserState, ProcessionState
-from .procession import Procession
+from heurams.kernel.particles.placeholders import AtomPlaceholder
 from heurams.services.logger import get_logger
+from transitions import Machine
+
+from .procession import Procession
+from .states import PhaserState, ProcessionState
 
 logger = get_logger(__name__)
 
 
-class Phaser:
-    """移相器: 全局调度阶段管理器"""
+class Phaser(Machine):
+    """全局调度阶段管理器"""
 
     def __init__(self, atoms: list[pt.Atom]) -> None:
         logger.debug("Phaser.__init__: 原子数量=%d", len(atoms))
+
         new_atoms = list()
         old_atoms = list()
-        self.state = PhaserState.UNSURE
+
         for i in atoms:
             if not i.registry["electron"].is_activated():
                 new_atoms.append(i)
             else:
                 old_atoms.append(i)
+
         logger.debug("新原子数量=%d, 旧原子数量=%d", len(new_atoms), len(old_atoms))
+
         self.processions = list()
+        # TODO: 改进为基于配置文件的可变复习阶段管理
         if len(old_atoms):
             self.processions.append(
                 Procession(old_atoms, PhaserState.QUICK_REVIEW, "初始复习")
             )
             logger.debug("创建初始复习 Procession")
+
         if len(new_atoms):
             self.processions.append(
                 Procession(new_atoms, PhaserState.RECOGNITION, "新记忆")
             )
             logger.debug("创建新记忆 Procession")
+
         self.processions.append(Procession(atoms, PhaserState.FINAL_REVIEW, "总体复习"))
         logger.debug("创建总体复习 Procession")
         logger.debug("Phaser 初始化完成, processions 数量=%d", len(self.processions))
 
+        # 设置transitions状态机
+        states = [
+            {"name": PhaserState.UNSURE.value, "on_enter": "on_unsure"},
+            {"name": PhaserState.QUICK_REVIEW.value, "on_enter": "on_quick_review"},
+            {"name": PhaserState.RECOGNITION.value, "on_enter": "on_recognition"},
+            {"name": PhaserState.FINAL_REVIEW.value, "on_enter": "on_final_review"},
+            {"name": PhaserState.FINISHED.value, "on_enter": "on_finished"},
+        ]
+
+        transitions = [
+            {"trigger": "to_unsure", "source": "*", "dest": PhaserState.UNSURE.value},
+            {
+                "trigger": "to_quick_review",
+                "source": "*",
+                "dest": PhaserState.QUICK_REVIEW.value,
+            },
+            {
+                "trigger": "to_recognition",
+                "source": "*",
+                "dest": PhaserState.RECOGNITION.value,
+            },
+            {
+                "trigger": "to_final_review",
+                "source": "*",
+                "dest": PhaserState.FINAL_REVIEW.value,
+            },
+            {
+                "trigger": "to_finished",
+                "source": "*",
+                "dest": PhaserState.FINISHED.value,
+            },
+        ]
+
+        Machine.__init__(
+            self,
+            states=states,
+            transitions=transitions,
+            initial=PhaserState.UNSURE.value,
+        )
+
+        self.to_unsure()
+
+    def on_unsure(self):
+        """进入UNSURE状态时的回调"""
+        logger.debug("Phaser 进入 UNSURE 状态")
+
+    def on_quick_review(self):
+        """进入QUICK_REVIEW状态时的回调"""
+        logger.debug("Phaser 进入 QUICK_REVIEW 状态")
+
+    def on_recognition(self):
+        """进入RECOGNITION状态时的回调"""
+        logger.debug("Phaser 进入 RECOGNITION 状态")
+
+    def on_final_review(self):
+        """进入FINAL_REVIEW状态时的回调"""
+        logger.debug("Phaser 进入 FINAL_REVIEW 状态")
+
+    def on_finished(self):
+        """进入FINISHED状态时的回调"""
+        logger.debug("Phaser 进入 FINISHED 状态")
+
     def current_procession(self):
         logger.debug("Phaser.current_procession 被调用")
         for i in self.processions:
             i: Procession
-            if not i.state == ProcessionState.FINISHED:
-                self.state = i.phase
+            if i.state != ProcessionState.FINISHED.value:
+                # 根据当前procession的phase更新Phaser状态
+                if i.phase == PhaserState.QUICK_REVIEW:
+                    self.to_quick_review()
+                elif i.phase == PhaserState.RECOGNITION:
+                    self.to_recognition()
+                elif i.phase == PhaserState.FINAL_REVIEW:
+                    self.to_final_review()
+
                 logger.debug("找到未完成的 Procession: phase=%s", i.phase)
                 return i
-        self.state = PhaserState.FINISHED
+
+        # 所有Procession都已完成
+        self.to_finished()
         logger.debug("所有 Procession 已完成, 状态设置为 FINISHED")
-        return 0
+        return Procession([AtomPlaceholder()], PhaserState.FINISHED)
+
+    def __repr__(self):
+        from heurams.services.textproc import truncate
+        from tabulate import tabulate as tabu
+
+        lst = [
+            {
+                "Type": "Phaser",
+                "State": self.state,
+                "Processions": list(map(lambda f: (f.name_), self.processions)),
+                "Current Procession": "None" if not self.current_procession() else self.current_procession().name_,  # type: ignore
+            },
+        ]
+        return str(tabu(lst, headers="keys")) + "\n"

src/heurams/kernel/reactor/procession.py

@@ -1,59 +1,102 @@
 import heurams.kernel.particles as pt
-from .states import PhaserState, ProcessionState
 from heurams.services.logger import get_logger
+from transitions import Machine
+from tabulate import tabulate as tabu
+
+from .fission import Fission
+from .states import PhaserState, ProcessionState
 
 logger = get_logger(__name__)
 
 
-class Procession:
+class Procession(Machine):
     """队列: 标识单次记忆流程"""
 
-    def __init__(self, atoms: list, phase: PhaserState, name: str = ""):
+    def __init__(self, atoms: list, phase_state: PhaserState, name_: str = ""):
         logger.debug(
             "Procession.__init__: 原子数量=%d, phase=%s, name='%s'",
             len(atoms),
-            phase.value,
-            name,
+            phase_state.value,
+            name_,
         )
+        self.current_atom: pt.Atom | None
         self.atoms = atoms
         self.queue = atoms.copy()
-        self.current_atom = atoms[0]
+        self.current_atom = atoms[0] if atoms else None
         self.cursor = 0
-        self.name = name
-        self.phase = phase
-        self.state: ProcessionState = ProcessionState.RUNNING
+        self.name_ = name_
+        self.phase = phase_state
+
+        states = [
+            {"name": ProcessionState.RUNNING.value, "on_enter": "on_running"},
+            {"name": ProcessionState.FINISHED.value, "on_enter": "on_finished"},
+        ]
+
+        transitions = [
+            {
+                "trigger": "finish",
+                "source": ProcessionState.RUNNING.value,
+                "dest": ProcessionState.FINISHED.value,
+            },
+            {
+                "trigger": "restart",
+                "source": ProcessionState.FINISHED.value,
+                "dest": ProcessionState.RUNNING.value,
+            },
+        ]
+
+        Machine.__init__(
+            self,
+            states=states,
+            transitions=transitions,
+            initial=ProcessionState.RUNNING.value,
+        )
+
         logger.debug("Procession 初始化完成, 队列长度=%d", len(self.queue))
 
+    def on_running(self):
+        """进入RUNNING状态时的回调"""
+        logger.debug("Procession 进入 RUNNING 状态")
+
+    def on_finished(self):
+        """进入FINISHED状态时的回调"""
+        logger.debug("Procession 进入 FINISHED 状态")
+
     def forward(self, step=1):
+        """将记忆原子指针向前移动并依情况更新原子(返回 1)或完成队列(返回 0)"""
         logger.debug("Procession.forward: step=%d, 当前 cursor=%d", step, self.cursor)
         self.cursor += step
-        if self.cursor == len(self.queue):
-            self.state = ProcessionState.FINISHED
+        if self.cursor >= len(self.queue):
+            if self.state != ProcessionState.FINISHED.value:
+                self.finish()  # 触发状态转换
             logger.debug("Procession 已完成")
         else:
-            self.state = ProcessionState.RUNNING
-        try:
-            logger.debug("cursor 更新为: %d", self.cursor)
+            if self.state != ProcessionState.RUNNING.value:
+                self.restart()  # 确保在RUNNING状态
             self.current_atom = self.queue[self.cursor]
-            logger.debug("当前原子更新为: %s", self.current_atom.ident)
+            logger.debug("cursor 更新为: %d", self.cursor)
+            logger.debug(
+                "当前原子更新为: %s",
+                self.current_atom.ident if self.current_atom else "None",
+            )
             return 1  # 成功
-        except IndexError as e:
-            logger.debug("IndexError: %s", e)
-            self.state = ProcessionState.FINISHED
-            logger.debug("Procession 因索引错误而完成")
         return 0
 
     def append(self, atom=None):
-        if atom == None:
+        """追加(回忆失败的)原子(默认为当前原子)到队列末端"""
+        if atom is None:
             atom = self.current_atom
         logger.debug("Procession.append: atom=%s", atom.ident if atom else "None")
-        if self.queue[len(self.queue) - 1] != atom or len(self) <= 1:
+
+        if not self.queue or self.queue[-1] != atom or len(self) <= 1:
             self.queue.append(atom)
             logger.debug("原子已追加到队列, 新队列长度=%d", len(self.queue))
         else:
-            logger.debug("原子未追加（重复或队列长度<=1）")
+            logger.debug("原子未追加(重复或队列长度<=1)")
 
     def __len__(self):
+        if not self.queue:
+            return 0
         length = len(self.queue) - self.cursor
         logger.debug("Procession.__len__: 剩余长度=%d", length)
         return length
@@ -68,6 +111,24 @@ class Procession:
         return total
 
     def is_empty(self):
-        empty = len(self.queue)
-        logger.debug("Procession.is_empty: %d", empty)
+        empty = len(self.queue) == 0
+        logger.debug("Procession.is_empty: %s", empty)
         return empty
+
+    def get_fission(self):
+        return Fission(atom=self.current_atom, phase_state=self.phase)  # type: ignore
+
+    def __repr__(self):
+        from heurams.services.textproc import truncate
+
+        dic = [
+            {
+                "Type": "Procession",
+                "Name": self.name_,
+                "State": self.state,
+                "Progress": f"{self.cursor + 1} / {len(self.queue)}",
+                "Queue": list(map(lambda f: truncate(f.ident), self.queue)),
+                "Current Atom": self.current_atom.ident,  # type: ignore
+            }
+        ]
+        return str(tabu(dic, headers="keys")) + "\n"

src/heurams/kernel/reactor/states.py

@@ -1,4 +1,5 @@
 from enum import Enum, auto
+
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
@@ -13,8 +14,8 @@ class PhaserState(Enum):
 
 
 class ProcessionState(Enum):
-    RUNNING = auto()
-    FINISHED = auto()
+    RUNNING = "running"
+    FINISHED = "finished"
 
 
 logger.debug("状态枚举定义已加载")

src/heurams/kernel/repolib/__init__.py

@@ -0,0 +1,3 @@
+from .repo import Repo, RepoManifest
+
+__all__ = ["Repo", "RepoManifest"]

src/heurams/kernel/repolib/navi.py

@@ -0,0 +1,3 @@
+class Navi:
+    def __init__(self, init) -> None:
+        pass

src/heurams/kernel/repolib/repo.py

@@ -0,0 +1,176 @@
+import json
+from functools import reduce
+from pathlib import Path
+from typing import TypedDict
+
+import toml
+
+import heurams.kernel.particles as pt
+
+from ...utils.lict import Lict
+
+
+class RepoManifest(TypedDict):
+    title: str
+    author: str
+    desc: str
+
+
+class Repo:
+    file_mapping = {
+        "schedule": "schedule.toml",
+        "payload": "payload.toml",
+        "algodata": "algodata.json",
+        "manifest": "manifest.toml",
+        "typedef": "typedef.toml",
+    }
+
+    type_mapping = {
+        "schedule": "dict",
+        "payload": "lict",
+        "algodata": "lict",
+        "manifest": "dict",
+        "typedef": "dict",
+    }
+
+    default_save_list = ["algodata"]
+
+    def __init__(
+        self,
+        schedule: dict,
+        payload: Lict,
+        manifest: dict,
+        typedef: dict,
+        algodata: Lict,
+        source=None,
+    ) -> None:
+        self.schedule: dict = schedule
+        self.manifest: RepoManifest = manifest  # type: ignore
+        self.typedef: dict = typedef
+        self.payload: Lict = payload
+        self.algodata: Lict = algodata
+        self.source: Path | None = source  # 若存在, 指向 repo 所在 dir
+        self.database = {
+            "schedule": self.schedule,
+            "payload": self.payload,
+            "manifest": self.manifest,
+            "typedef": self.typedef,
+            "algodata": self.algodata,
+            "source": self.source,
+        }
+        self.generate_particles_data()
+
+    def generate_particles_data(self):
+
+        self.nucleonic_data_lict = Lict(
+            initlist=list(map(self._nucleonic_proc, self.payload))
+        )
+        self.orbitic_data = self.schedule
+        self.ident_index = self.nucleonic_data_lict.keys()
+        for i in self.ident_index:
+            self.algodata.append_new((i, {}))
+        self.electronic_data_lict = self.algodata
+
+    def _nucleonic_proc(self, unit):
+        ident = unit[0]
+        common = self.typedef["common"]
+        return (ident, (unit[1], common))
+
+    @staticmethod
+    def _merge(value):
+        def inner(x):
+            return (x, value)
+
+        return inner
+
+    def __len__(self):
+        return len(self.payload)
+
+    def __repr__(self):
+        from pprint import pformat
+
+        s = pformat(self.database, indent=4)
+        return s
+
+    def persist_to_repodir(
+        self, save_list: list | None = None, source: Path | None = None
+    ):
+        if save_list == None:
+            save_list = self.default_save_list
+        if self.source != None and source == None:
+            source = self.source
+        if source == None:
+            raise FileNotFoundError("不存在仓库到文件的映射")
+        source.mkdir(parents=True, exist_ok=False)
+        for keyname in save_list:
+            filename = self.file_mapping[keyname]
+            with open(source / filename, "w") as f:
+                try:
+                    dict_data = self.database[keyname].dicted_data
+                except:
+                    dict_data = dict(self.database[keyname])
+                if filename.endswith("toml"):
+                    toml.dump(dict_data, f)
+                elif filename.endswith("json"):
+                    json.dump(dict_data, f)
+                else:
+                    raise ValueError(f"不支持的文件类型: {filename}")
+
+    def export_to_single_dict(self):
+        return self.database
+
+    @classmethod
+    def create_new_repo(cls, source=None):
+        default_database = {
+            "schedule": {},
+            "payload": Lict([]),
+            "algodata": Lict([]),
+            "manifest": {},
+            "typedef": {},
+            "source": source,
+        }
+        return Repo(**default_database)
+
+    @classmethod
+    def create_from_repodir(cls, source: Path):
+        database = {}
+        for keyname, filename in cls.file_mapping.items():
+            with open(source / filename, "r") as f:
+                loaded: dict
+                if filename.endswith("toml"):
+                    loaded = toml.load(f)
+                elif filename.endswith("json"):
+                    loaded = json.load(f)
+                else:
+                    raise ValueError(f"不支持的文件类型: {filename}")
+                if cls.type_mapping[keyname] == "lict":
+                    database[keyname] = Lict(list(loaded.items()))
+                elif cls.type_mapping[keyname] == "dict":
+                    database[keyname] = loaded
+                else:
+                    raise ValueError(f"不支持的数据容器: {cls.type_mapping[keyname]}")
+        database["source"] = source
+        return Repo(**database)
+
+    @classmethod
+    def create_from_single_dict(cls, dictdata, source: Path | None = None):
+        database = dictdata
+        database["source"] = source
+        return Repo(**database)
+
+    @classmethod
+    def check_repodir(cls, source: Path):
+        try:
+            cls.create_from_repodir(source)
+            return 1
+        except:
+            return 0
+
+    @classmethod
+    def probe_vaild_repos_in_dir(cls, folder: Path):
+        lst = list()
+        for i in folder.iterdir():
+            if i.is_dir():
+                if cls.check_repodir(i):
+                    lst.append(i)
+        return lst

src/heurams/providers/audio/__init__.py

@@ -1,8 +1,8 @@
 # 音频播放器, 必须基于文件操作
-from . import termux_audio
-from . import playsound_audio
 from heurams.services.logger import get_logger
 
+from . import playsound_audio, termux_audio
+
 logger = get_logger(__name__)
 
 __all__ = [

src/heurams/providers/audio/playsound_audio.py

@@ -5,7 +5,9 @@
 
 import os
 import pathlib
+
 import playsound
+
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)

src/heurams/providers/audio/protocol.py

@@ -1,5 +1,6 @@
-from typing import Protocol
 import pathlib
+from typing import Protocol
+
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)

src/heurams/providers/audio/termux_audio.py

@@ -5,6 +5,7 @@
 
 import os
 import pathlib
+
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)

src/heurams/providers/llm/openai.py

@@ -2,4 +2,4 @@ from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
 
-logger.debug("OpenAI provider 模块已加载（未实现）")
+logger.debug("OpenAI provider 模块已加载(未实现)")

src/heurams/providers/tts/__init__.py

@@ -1,6 +1,7 @@
+from heurams.services.logger import get_logger
+
 from .base import BaseTTS
 from .edge_tts import EdgeTTS
-from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
 

src/heurams/providers/tts/base.py

@@ -1,4 +1,5 @@
 import pathlib
+
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)

src/heurams/providers/tts/edge_tts.py

@@ -1,8 +1,12 @@
-from .base import BaseTTS
 import pathlib
+
 import edge_tts
+
+from heurams.context import config_var
 from heurams.services.logger import get_logger
 
+from .base import BaseTTS
+
 logger = get_logger(__name__)
 
 
@@ -15,7 +19,7 @@ class EdgeTTS(BaseTTS):
         try:
             communicate = edge_tts.Communicate(
                 text,
-                "zh-CN-YunjianNeural",
+                config_var.get()["providers"]["tts"]["edgetts"]["voice"],
             )
             logger.debug("EdgeTTS 通信对象创建成功, 正在保存音频")
             communicate.save_sync(str(path))

src/heurams/services/audio_service.py

@@ -1,12 +1,13 @@
 # 音频服务
+from typing import Callable
+
 from heurams.context import config_var
 from heurams.providers.audio import providers as prov
-from typing import Callable
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
 
 play_by_path: Callable = prov[config_var.get()["services"]["audio"]].play_by_path
 logger.debug(
-    "音频服务初始化完成, 使用 provider: %s", config_var.get()["services"]["audio"]
+    "音频服务初始化完成, 使用 Provider: %s", config_var.get()["services"]["audio"]
 )

src/heurams/services/config.py

@@ -1,7 +1,9 @@
 # 配置文件服务
 import pathlib
-import toml
 import typing
+
+import toml
+
 from heurams.services.logger import get_logger
 
 

src/heurams/services/hasher.py

@@ -1,5 +1,6 @@
 # 哈希服务
 import hashlib
+
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)

src/heurams/services/logger.py

@@ -45,7 +45,7 @@ def setup_logging(
     # 创建formatter
     formatter = logging.Formatter(log_format, date_format)
 
-    # 创建文件handler（使用RotatingFileHandler防止日志过大）
+    # 创建文件handler(使用RotatingFileHandler防止日志过大)
     file_handler = logging.handlers.RotatingFileHandler(
         filename=log_path,
         maxBytes=max_bytes,
@@ -55,7 +55,7 @@ def setup_logging(
     file_handler.setFormatter(formatter)
     file_handler.setLevel(log_level)
 
-    # 配置root logger - 设置为 WARNING 级别（只记录重要信息）
+    # 配置root logger - 设置为 WARNING 级别(只记录重要信息)
     root_logger = logging.getLogger()
     root_logger.setLevel(logging.WARNING)  # 这里改为 WARNING
 
@@ -63,7 +63,7 @@ def setup_logging(
     for handler in root_logger.handlers[:]:
         root_logger.removeHandler(handler)
 
-    # 创建自己的应用logger（单独设置DEBUG级别）
+    # 创建自己的应用logger(单独设置DEBUG级别)
     app_logger = logging.getLogger("heurams")
     app_logger.setLevel(log_level)  # 保持DEBUG级别
     app_logger.addHandler(file_handler)
@@ -146,7 +146,7 @@ def exception(msg: str, *args, **kwargs) -> None:
     get_logger().exception(msg, *args, **kwargs)
 
 
-# 初始化日志系统（硬编码配置）
+# 初始化日志系统(硬编码配置)
 setup_logging()
 
 

src/heurams/services/textproc.py

@@ -0,0 +1,4 @@
+def truncate(text):
+    if len(text) <= 3:
+        return text
+    return text[:3] + ">"

src/heurams/services/timer.py

@@ -1,6 +1,7 @@
 # 时间服务
-from heurams.context import config_var
 import time
+
+from heurams.context import config_var
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)

src/heurams/services/tts_service.py

@@ -1,12 +1,13 @@
 # 文本转语音服务
-from heurams.context import config_var
-from heurams.providers.tts import TTSs
 from typing import Callable
+
+from heurams.context import config_var
+from heurams.providers.tts import providers as prov
 from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
 
-convert: Callable = TTSs[config_var.get().get("tts_provider")]
+convertor: Callable = prov[config_var.get()["services"]["tts"]].convert
 logger.debug(
-    "TTS服务初始化完成, 使用 provider: %s", config_var.get().get("tts_provider")
+    "TTS服务初始化完成, 使用 provider: %s", config_var.get()["services"]["tts"]
 )

src/heurams/services/version.py

@@ -3,8 +3,9 @@ from heurams.services.logger import get_logger
 
 logger = get_logger(__name__)
 
-ver = "0.4.0"
+ver = "0.5.0"
 stage = "prototype"
-codename = "fledge"  # 雏鸟, 0.4.x 版本
+codename = "fulcrom"
+codename_cn = "支点"
 
 logger.info("HeurAMS 版本: %s (%s), 阶段: %s", ver, codename, stage)

src/heurams/services/vfs.py

@@ -0,0 +1,20 @@
+"""vfs.py
+得益于 FSSpec, 无需实现大部分虚拟文件系统的 Providers
+"""
+
+from pathlib import Path
+
+import fsspec as fs
+
+
+class VFSObject:
+    def __init__(self, protocol, base_url):
+        self.base_url = base_url
+        self.protocol = protocol
+        self.fs = fs.filesystem(protocol=protocol, base_url=base_url)
+
+    def open(self, path: Path):
+        return self.fs.open(path)
+
+    def open_by_list(self, path_list: list[Path]):
+        return self.fs.open_files(path_list)

src/heurams/utils/README.md

@@ -1,2 +0,0 @@
-# Utils - 实用工具
-脚本与部分分离式工具函数

src/heurams/utils/__init__.py

@@ -0,0 +1,5 @@
+from .evalizor import Evalizer
+from .lict import Lict
+from .refvar import RefVar
+
+__all__ = ["Evalizer", "Lict", "RefVar"]

src/heurams/utils/evalizor.py

@@ -0,0 +1,33 @@
+class Evalizer:
+    """几乎无副作用的模板系统
+
+    接受环境信息并创建一个模板解析工具, 工具传入参数支持list, dict及其嵌套
+    副作用问题: 仅存在于 eval 函数
+    """
+
+    # TODO: 弃用风险极高的 eval
+    # TODO: 异步/多线程执行避免堵塞
+    def __init__(self, environment: dict) -> None:
+        self.env = environment
+
+    def __call__(self, anyobj):
+        return self.travel(anyobj)
+
+    def travel(self, anyobj):
+        if isinstance(anyobj, list):
+            return list(map(self.travel, anyobj))
+        elif isinstance(anyobj, dict):
+            return dict(map(self.travel, anyobj.items()))
+        elif isinstance(anyobj, tuple):
+            return tuple(map(self.travel, anyobj))
+        elif isinstance(anyobj, str):
+            if anyobj.startswith("eval:"):
+                return self.eval_with_env(anyobj[5:])
+            else:
+                return anyobj
+        else:
+            return anyobj
+
+    def eval_with_env(self, s: str):
+        ret = eval(s, globals(), self.env)
+        return ret

src/heurams/utils/lict.py

@@ -0,0 +1,149 @@
+from collections import UserList
+from typing import Any, Iterator
+
+
+class Lict(UserList):  # TODO: 优化同步(惰性同步), 当前性能为 O(n)
+    """ "列典" 对象
+
+    同时兼容字典和列表大多数 API, 两边数据同步的容器
+    列表数据是 dictobj.items() 的格式
+    支持根据字典或列表初始化
+    限制要求:
+    - 键名一定唯一, 且仅能为字符串
+    - 值一定是引用对象
+    - 不使用并发
+    - 不在乎列表顺序语义(严格按键名字符序排列)和列表索引查找, 因此外部的 sort, index 等功能不可用
+    - append 的元组中, 表示键名的元素不能重复, 否则会导致覆盖行为
+
+    只有在 Python 3.7+ 中, forced_order 行为才能被取消.
+    """
+
+    def __init__(
+        self,
+        initlist: list | None = None,
+        initdict: dict | None = None,
+        forced_order=False,
+    ):
+        self.dicted_data = {}
+        if initdict != None:
+            initlist = list(initdict.items())
+        super().__init__(initlist=initlist)
+        self.forced_order = forced_order
+        self._sync_based_on_list()
+        if self.forced_order:
+            self.data.sort()
+
+    def _sync_based_on_dict(self):
+        self.data = list(self.dicted_data.items())
+        if self.forced_order:
+            self.data.sort()
+
+    def _sync_based_on_list(self):
+        self.dicted_data = {}
+        for i in self.data:
+            self.dicted_data[i[0]] = i[1]
+
+    def __iter__(self) -> Iterator:
+        return self.data.__iter__()
+
+    def __getitem__(self, i):
+        if isinstance(i, str):
+            return self.dicted_data[i]
+        else:
+            return super().__getitem__(i)
+
+    def get_itemic_unit(self, ident):
+        return (ident, self.dicted_data[ident])
+
+    def __setitem__(self, i, item):
+        if isinstance(i, str):
+            self.dicted_data[i] = item
+            self._sync_based_on_dict()
+        else:
+            if item != (item[0], item[1]):
+                raise NotImplementedError
+            super().__setitem__(i, item)
+            self._sync_based_on_list()
+
+    def __delitem__(self, i):
+        if isinstance(i, str):
+            del self.dicted_data[i]
+            self._sync_based_on_dict()
+        else:
+            super().__delitem__(i)
+            self._sync_based_on_list()
+
+    def __contains__(self, item):
+        return item in self.data or item in self.keys() or item in self.values()
+
+    def append(self, item: Any) -> None:
+        if item != (item[0], item[1]):
+            raise NotImplementedError
+        super().append(item)
+        self._sync_based_on_list()
+        if self.forced_order:
+            self.data.sort()
+
+    def append_new(self, item: Any):
+        if item != (item[0], item[1]):
+            raise NotImplementedError
+        if item[0] not in self:
+            super().append(item)
+            self._sync_based_on_list()
+            if self.forced_order:
+                self.data.sort()
+
+    def insert(self, i: int, item: Any) -> None:
+        if item != (item[0], item[1]):  # 确保 item 是遵从限制的元组
+            raise NotImplementedError
+        super().insert(i, item)
+        self._sync_based_on_list()
+        if self.forced_order:
+            self.data.sort()
+
+    def pop(self, i: int = -1) -> Any:
+        res = super().pop(i)
+        self._sync_based_on_list()
+        return res
+
+    def remove(self, item: Any) -> None:
+        if isinstance(item, str):
+            item = (item, self.dicted_data[item])
+        if item != (item[0], item[1]):
+            raise NotImplementedError
+        super().remove(item)
+        self._sync_based_on_list()
+        if self.forced_order:
+            self.data.sort()
+
+    def clear(self) -> None:
+        super().clear()
+        self._sync_based_on_list()
+
+    def index(self):
+        raise NotImplementedError
+
+    def extend(self):
+        raise NotImplementedError
+
+    def sort(self):
+        raise NotImplementedError
+
+    def reverse(self):
+        raise NotImplementedError
+
+    def keys(self):
+        return self.dicted_data.keys()
+
+    def values(self):
+        return self.dicted_data.values()
+
+    def items(self):
+        return self.data
+
+    def keys_equal_with(self, other):
+        return self.key_equality(self, other)
+
+    @classmethod
+    def key_equality(cls, a, b):
+        return a.keys() == b.keys()

src/heurams/utils/refvar.py

@@ -0,0 +1,241 @@
+class RefVar:
+    def __init__(self, initvalue) -> None:
+        self.data = initvalue
+
+    def __repr__(self) -> str:
+        return f"RefVar({repr(self.data)})"
+
+    def __str__(self) -> str:
+        return str(self.data)
+
+    def __add__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data + other.data)
+        return RefVar(self.data + other)
+
+    def __radd__(self, other):
+        return RefVar(other + self.data)
+
+    def __sub__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data - other.data)
+        return RefVar(self.data - other)
+
+    def __rsub__(self, other):
+        return RefVar(other - self.data)
+
+    def __mul__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data * other.data)
+        return RefVar(self.data * other)
+
+    def __rmul__(self, other):
+        return RefVar(other * self.data)
+
+    def __truediv__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data / other.data)
+        return RefVar(self.data / other)
+
+    def __rtruediv__(self, other):
+        return RefVar(other / self.data)
+
+    def __floordiv__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data // other.data)
+        return RefVar(self.data // other)
+
+    def __rfloordiv__(self, other):
+        return RefVar(other // self.data)
+
+    def __mod__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data % other.data)
+        return RefVar(self.data % other)
+
+    def __rmod__(self, other):
+        return RefVar(other % self.data)
+
+    def __pow__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data**other.data)
+        return RefVar(self.data**other)
+
+    def __rpow__(self, other):
+        return RefVar(other**self.data)
+
+    def __neg__(self):
+        return RefVar(-self.data)
+
+    def __pos__(self):
+        return RefVar(+self.data)
+
+    def __abs__(self):
+        return RefVar(abs(self.data))
+
+    def __eq__(self, other):
+        if isinstance(other, RefVar):
+            return self.data == other.data
+        return self.data == other
+
+    def __ne__(self, other):
+        return not self.__eq__(other)
+
+    def __lt__(self, other):
+        if isinstance(other, RefVar):
+            return self.data < other.data
+        return self.data < other
+
+    def __le__(self, other):
+        if isinstance(other, RefVar):
+            return self.data <= other.data
+        return self.data <= other
+
+    def __gt__(self, other):
+        if isinstance(other, RefVar):
+            return self.data > other.data
+        return self.data > other
+
+    def __ge__(self, other):
+        if isinstance(other, RefVar):
+            return self.data >= other.data
+        return self.data >= other
+
+    # 位运算
+    def __and__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data & other.data)
+        return RefVar(self.data & other)
+
+    def __rand__(self, other):
+        return RefVar(other & self.data)
+
+    def __or__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data | other.data)
+        return RefVar(self.data | other)
+
+    def __ror__(self, other):
+        return RefVar(other | self.data)
+
+    def __xor__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data ^ other.data)
+        return RefVar(self.data ^ other)
+
+    def __rxor__(self, other):
+        return RefVar(other ^ self.data)
+
+    def __lshift__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data << other.data)
+        return RefVar(self.data << other)
+
+    def __rlshift__(self, other):
+        return RefVar(other << self.data)
+
+    def __rshift__(self, other):
+        if isinstance(other, RefVar):
+            return RefVar(self.data >> other.data)
+        return RefVar(self.data >> other)
+
+    def __rrshift__(self, other):
+        return RefVar(other >> self.data)
+
+    def __invert__(self):
+        return RefVar(~self.data)
+
+    # 类型转换
+    def __int__(self):
+        return int(self.data)
+
+    def __float__(self):
+        return float(self.data)
+
+    def __bool__(self):
+        return bool(self.data)
+
+    def __complex__(self):
+        return complex(self.data)
+
+    def __bytes__(self):
+        return bytes(self.data)
+
+    def __hash__(self):
+        return hash(self.data)
+
+    # 容器操作（如果底层数据支持）
+    def __len__(self):
+        return len(self.data)
+
+    def __getitem__(self, key):
+        return self.data[key]
+
+    def __setitem__(self, key, value):
+        self.data[key] = value
+
+    def __delitem__(self, key):
+        del self.data[key]
+
+    def __contains__(self, item):
+        return item in self.data
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __iadd__(self, other):
+        if isinstance(other, RefVar):
+            self.data += other.data
+        else:
+            self.data += other
+        return self
+
+    def __isub__(self, other):
+        if isinstance(other, RefVar):
+            self.data -= other.data
+        else:
+            self.data -= other
+        return self
+
+    def __imul__(self, other):
+        if isinstance(other, RefVar):
+            self.data *= other.data
+        else:
+            self.data *= other
+        return self
+
+    def __itruediv__(self, other):
+        if isinstance(other, RefVar):
+            self.data /= other.data
+        else:
+            self.data /= other
+        return self
+
+    def __ifloordiv__(self, other):
+        if isinstance(other, RefVar):
+            self.data //= other.data
+        else:
+            self.data //= other
+        return self
+
+    def __imod__(self, other):
+        if isinstance(other, RefVar):
+            self.data %= other.data
+        else:
+            self.data %= other
+        return self
+
+    def __ipow__(self, other):
+        if isinstance(other, RefVar):
+            self.data **= other.data
+        else:
+            self.data **= other
+        return self
+
+    def __call__(self, *args, **kwargs):
+        if callable(self.data):
+            return self.data(*args, **kwargs)
+        raise TypeError(f"'{type(self.data).__name__}' object is not callable")
+
+    def __getattr__(self, name):
+        return getattr(self.data, name)

tests/interface/test_dashboard.py

@@ -1,152 +0,0 @@
-#!/usr/bin/env python3
-"""
-DashboardScreen 的测试, 包括单元测试和 pilot 测试. 
-"""
-import unittest
-import tempfile
-import pathlib
-import time
-from unittest.mock import patch, MagicMock
-from textual.pilot import Pilot
-
-from heurams.context import ConfigContext
-from heurams.services.config import ConfigFile
-from heurams.interface.__main__ import HeurAMSApp
-from heurams.interface.screens.dashboard import DashboardScreen
-
-
-class TestDashboardScreenUnit(unittest.TestCase):
-    """DashboardScreen 的单元测试（不启动完整应用）. """
-
-    def setUp(self):
-        """在每个测试之前运行, 设置临时目录和配置. """
-        # 创建临时目录用于测试数据
-        self.temp_dir = tempfile.TemporaryDirectory()
-        self.temp_path = pathlib.Path(self.temp_dir.name)
-
-        # 创建默认配置, 并修改路径指向临时目录
-        default_config_path = (
-            pathlib.Path(__file__).parent.parent.parent
-            / "src/heurams/default/config/config.toml"
-        )
-        self.config = ConfigFile(default_config_path)
-        # 更新配置中的路径
-        config_data = self.config.data
-        config_data["paths"]["nucleon_dir"] = str(self.temp_path / "nucleon")
-        config_data["paths"]["electron_dir"] = str(self.temp_path / "electron")
-        config_data["paths"]["orbital_dir"] = str(self.temp_path / "orbital")
-        config_data["paths"]["cache_dir"] = str(self.temp_path / "cache")
-        # 禁用快速通过, 避免测试干扰
-        config_data["quick_pass"] = 0
-        # 禁用时间覆盖
-        config_data["daystamp_override"] = -1
-        config_data["timestamp_override"] = -1
-
-        # 创建目录
-        for dir_key in ["nucleon_dir", "electron_dir", "orbital_dir", "cache_dir"]:
-            pathlib.Path(config_data["paths"][dir_key]).mkdir(
-                parents=True, exist_ok=True
-            )
-
-        # 使用 ConfigContext 设置配置
-        self.config_ctx = ConfigContext(self.config)
-        self.config_ctx.__enter__()
-
-    def tearDown(self):
-        """在每个测试之后清理. """
-        self.config_ctx.__exit__(None, None, None)
-        self.temp_dir.cleanup()
-
-    def test_compose(self):
-        """测试 compose 方法返回正确的部件. """
-        screen = DashboardScreen()
-        # 手动调用 compose 并收集部件
-        from textual.app import ComposeResult
-
-        result = screen.compose()
-        widgets = list(result)
-        # 检查是否包含 Header 和 Footer
-        from textual.widgets import Header, Footer
-
-        header_present = any(isinstance(w, Header) for w in widgets)
-        footer_present = any(isinstance(w, Footer) for w in widgets)
-        self.assertTrue(header_present)
-        self.assertTrue(footer_present)
-        # 检查是否有 ScrollableContainer
-        from textual.containers import ScrollableContainer
-
-        container_present = any(isinstance(w, ScrollableContainer) for w in widgets)
-        self.assertTrue(container_present)
-        # 使用 query_one 查找 union-list, 即使屏幕未挂载也可能有效
-        list_view = screen.query_one("#union-list")
-        self.assertIsNotNone(list_view)
-        self.assertEqual(list_view.id, "union-list")
-        self.assertEqual(list_view.__class__.__name__, "ListView")
-
-    def test_item_desc_generator(self):
-        """测试 item_desc_generator 函数. """
-        screen = DashboardScreen()
-        # 模拟一个文件名
-        filename = "test.toml"
-        result = screen.item_desc_generator(filename)
-        self.assertIsInstance(result, dict)
-        self.assertIn(0, result)
-        self.assertIn(1, result)
-        # 检查内容
-        self.assertIn("test.toml", result[0])
-        # 由于 electron 文件不存在, 应显示“尚未激活”
-        self.assertIn("尚未激活", result[1])
-
-
-@unittest.skip("Pilot 测试需要进一步配置, 暂不运行")
-class TestDashboardScreenPilot(unittest.TestCase):
-    """使用 Textual Pilot 的集成测试. """
-
-    def setUp(self):
-        """配置临时目录和配置. """
-        self.temp_dir = tempfile.TemporaryDirectory()
-        self.temp_path = pathlib.Path(self.temp_dir.name)
-
-        default_config_path = (
-            pathlib.Path(__file__).parent.parent.parent
-            / "src/heurams/default/config/config.toml"
-        )
-        self.config = ConfigFile(default_config_path)
-        config_data = self.config.data
-        config_data["paths"]["nucleon_dir"] = str(self.temp_path / "nucleon")
-        config_data["paths"]["electron_dir"] = str(self.temp_path / "electron")
-        config_data["paths"]["orbital_dir"] = str(self.temp_path / "orbital")
-        config_data["paths"]["cache_dir"] = str(self.temp_path / "cache")
-        config_data["quick_pass"] = 0
-        config_data["daystamp_override"] = -1
-        config_data["timestamp_override"] = -1
-
-        for dir_key in ["nucleon_dir", "electron_dir", "orbital_dir", "cache_dir"]:
-            pathlib.Path(config_data["paths"][dir_key]).mkdir(
-                parents=True, exist_ok=True
-            )
-
-        self.config_ctx = ConfigContext(self.config)
-        self.config_ctx.__enter__()
-
-    def tearDown(self):
-        self.config_ctx.__exit__(None, None, None)
-        self.temp_dir.cleanup()
-
-    def test_dashboard_loads_with_pilot(self):
-        """使用 Pilot 测试 DashboardScreen 加载. """
-        with patch("heurams.interface.__main__.environment_check"):
-            app = HeurAMSApp()
-            # 注意: Pilot 在 Textual 6.9.0 中的用法可能不同
-            # 以下为示例代码, 可能需要调整
-            pilot = Pilot(app)
-            # 等待应用启动
-            pilot.pause()
-            screen = app.screen
-            self.assertEqual(screen.__class__.__name__, "DashboardScreen")
-            union_list = app.query_one("#union-list")
-            self.assertIsNotNone(union_list)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/kernel/algorithms/test_sm2.py

@@ -1,186 +0,0 @@
-import unittest
-from unittest.mock import patch, MagicMock
-
-from heurams.kernel.algorithms.sm2 import SM2Algorithm
-
-
-class TestSM2Algorithm(unittest.TestCase):
-    """测试 SM2Algorithm 类"""
-
-    def setUp(self):
-        # 模拟 timer 函数
-        self.timestamp_patcher = patch(
-            "heurams.kernel.algorithms.sm2.timer.get_timestamp"
-        )
-        self.daystamp_patcher = patch(
-            "heurams.kernel.algorithms.sm2.timer.get_daystamp"
-        )
-        self.mock_get_timestamp = self.timestamp_patcher.start()
-        self.mock_get_daystamp = self.daystamp_patcher.start()
-
-        # 设置固定返回值
-        self.mock_get_timestamp.return_value = 1000.0
-        self.mock_get_daystamp.return_value = 100
-
-    def tearDown(self):
-        self.timestamp_patcher.stop()
-        self.daystamp_patcher.stop()
-
-    def test_defaults(self):
-        """测试默认值"""
-        defaults = SM2Algorithm.defaults
-        self.assertEqual(defaults["efactor"], 2.5)
-        self.assertEqual(defaults["real_rept"], 0)
-        self.assertEqual(defaults["rept"], 0)
-        self.assertEqual(defaults["interval"], 0)
-        self.assertEqual(defaults["last_date"], 0)
-        self.assertEqual(defaults["next_date"], 0)
-        self.assertEqual(defaults["is_activated"], 0)
-        # last_modify 是动态的, 仅检查存在性
-        self.assertIn("last_modify", defaults)
-
-    def test_revisor_feedback_minus_one(self):
-        """测试 feedback = -1 时跳过更新"""
-        algodata = {SM2Algorithm.algo_name: SM2Algorithm.defaults.copy()}
-        SM2Algorithm.revisor(algodata, feedback=-1)
-        # 数据应保持不变
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["efactor"], 2.5)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["rept"], 0)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["interval"], 0)
-
-    def test_revisor_feedback_less_than_3(self):
-        """测试 feedback < 3 重置 rept 和 interval"""
-        algodata = {
-            SM2Algorithm.algo_name: {
-                "efactor": 2.5,
-                "rept": 5,
-                "interval": 10,
-                "real_rept": 3,
-            }
-        }
-        SM2Algorithm.revisor(algodata, feedback=2)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["rept"], 0)
-        # rept=0 导致 interval 被设置为 1
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["interval"], 1)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["real_rept"], 4)  # 递增
-
-    def test_revisor_feedback_greater_equal_3(self):
-        """测试 feedback >= 3 递增 rept"""
-        algodata = {
-            SM2Algorithm.algo_name: {
-                "efactor": 2.5,
-                "rept": 2,
-                "interval": 6,
-                "real_rept": 2,
-            }
-        }
-        SM2Algorithm.revisor(algodata, feedback=4)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["rept"], 3)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["real_rept"], 3)
-        # interval 应根据 rept 和 efactor 重新计算
-        # rept=3, interval = round(6 * 2.5) = 15
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["interval"], 15)
-
-    def test_revisor_new_activation(self):
-        """测试 is_new_activation 重置 rept 和 efactor"""
-        algodata = {
-            SM2Algorithm.algo_name: {
-                "efactor": 3.0,
-                "rept": 5,
-                "interval": 20,
-                "real_rept": 5,
-            }
-        }
-        SM2Algorithm.revisor(algodata, feedback=5, is_new_activation=True)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["rept"], 0)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["efactor"], 2.5)
-        # interval 应为 1（因为 rept=0）
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["interval"], 1)
-
-    def test_revisor_efactor_calculation(self):
-        """测试 efactor 计算"""
-        algodata = {
-            SM2Algorithm.algo_name: {
-                "efactor": 2.5,
-                "rept": 1,
-                "interval": 6,
-                "real_rept": 1,
-            }
-        }
-        SM2Algorithm.revisor(algodata, feedback=5)
-        # efactor = 2.5 + (0.1 - (5-5)*(0.08 + (5-5)*0.02)) = 2.5 + 0.1 = 2.6
-        self.assertAlmostEqual(
-            algodata[SM2Algorithm.algo_name]["efactor"], 2.6, places=6
-        )
-
-        # 测试 efactor 下限为 1.3
-        algodata[SM2Algorithm.algo_name]["efactor"] = 1.2
-        SM2Algorithm.revisor(algodata, feedback=5)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["efactor"], 1.3)
-
-    def test_revisor_interval_calculation(self):
-        """测试 interval 计算规则"""
-        algodata = {
-            SM2Algorithm.algo_name: {
-                "efactor": 2.5,
-                "rept": 0,
-                "interval": 0,
-                "real_rept": 0,
-            }
-        }
-        SM2Algorithm.revisor(algodata, feedback=4)
-        # rept 从 0 递增到 1, 因此 interval 应为 6
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["interval"], 6)
-
-        # 现在 rept=1, 再次调用 revisor 递增到 2
-        SM2Algorithm.revisor(algodata, feedback=4)
-        # rept=2, interval = round(6 * 2.5) = 15
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["interval"], 15)
-
-        # 单独测试 rept=1 的情况
-        algodata2 = {
-            SM2Algorithm.algo_name: {
-                "efactor": 2.5,
-                "rept": 1,
-                "interval": 0,
-                "real_rept": 0,
-            }
-        }
-        SM2Algorithm.revisor(algodata2, feedback=4)
-        # rept 递增到 2, interval = round(0 * 2.5) = 0
-        self.assertEqual(algodata2[SM2Algorithm.algo_name]["interval"], 0)
-
-    def test_revisor_updates_dates(self):
-        """测试更新日期字段"""
-        algodata = {SM2Algorithm.algo_name: SM2Algorithm.defaults.copy()}
-        self.mock_get_daystamp.return_value = 200
-        SM2Algorithm.revisor(algodata, feedback=5)
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["last_date"], 200)
-        self.assertEqual(
-            algodata[SM2Algorithm.algo_name]["next_date"],
-            200 + algodata[SM2Algorithm.algo_name]["interval"],
-        )
-        self.assertEqual(algodata[SM2Algorithm.algo_name]["last_modify"], 1000.0)
-
-    def test_is_due(self):
-        """测试 is_due 方法"""
-        algodata = {SM2Algorithm.algo_name: {"next_date": 100}}
-        self.mock_get_daystamp.return_value = 150
-        self.assertTrue(SM2Algorithm.is_due(algodata))
-
-        algodata[SM2Algorithm.algo_name]["next_date"] = 200
-        self.assertFalse(SM2Algorithm.is_due(algodata))
-
-    def test_rate(self):
-        """测试 rate 方法"""
-        algodata = {SM2Algorithm.algo_name: {"efactor": 2.7}}
-        self.assertEqual(SM2Algorithm.rate(algodata), "2.7")
-
-    def test_nextdate(self):
-        """测试 nextdate 方法"""
-        algodata = {SM2Algorithm.algo_name: {"next_date": 12345}}
-        self.assertEqual(SM2Algorithm.nextdate(algodata), 12345)
-
-
-if __name__ == "__main__":
-    unittest.main()