HeurAMS/README.md

潜进 (HeurAMS) - 启发式辅助记忆调度器

概述

"潜进" (HeurAMS: Heuristic Auxiliary Memorizing Scheduler, 启发式记忆辅助调度器) 是一种基于启发式算法与认知科学理论的辅助记忆调度器, 旨在帮助用户更高效地进行记忆工作与学习规划,
也是一种开放, 优雅, 易于扩展的间隔重复调度器实验平台, 旨在帮助研究者更高效地进行前沿记忆算法的研究.

详细介绍 屏幕截图

快速开始

从 PIP 安装

潜进 (包名是 heurams) 处于早期开发考虑, 尚未上架 PyPI, 但您可以用 pip 支持的 git 协议安装稳定版和开发版本, 这要求您的电脑上安装了 Python 环境 (推荐 3.12.13 及以上) 和 git.

面向用户的安装

从稳定的 master 分支安装, 并安装适用于用户体验的可选依赖(推荐):

pip install --upgrade 'heurams[basic] @ git+https://git.pluv27.top/pluv/heurams.git@master'

从较前沿, 大致稳定的 dev 分支安装, 并安装适用于用户体验的可选依赖(如果您追求较前沿的改进):

pip install --upgrade 'heurams[basic] @ git+https://git.pluv27.top/pluv/heurams.git@dev'

安装适用于一般计算机的通用音频模块(基于 playsound3):
(此项不适用于 termux 环境, termux 的音频支持是内建的)

pip install --upgrade 'heurams[audio-playsound] @ git+https://git.pluv27.top/pluv/heurams.git@master'

面向开发者的安装

Caution

对于部分 Linux 发行版和 Android Termux 用户:
您需要先行安装 cmake 和 libzmq 才能正确安装项目的 zmq 依赖.
例如在 termux 上先运行 pkg install cmake clang libzmq.
项目功能本身不依赖它, 但需要该依赖用于启动可选的调试服务器.

从 dev 分支进行可编辑安装, 并安装全部可选依赖(推荐):

pip install --upgrade -e 'heurams[all] @ git+https://git.pluv27.top/pluv/heurams.git@dev'

您也可以从 refactor/... 等特定分支安装

依赖组说明

由于部分依赖只被少数功能需要, 所以我们把可选依赖分得比较细, 前面提供的命令会安装部分可选依赖, 以下是依赖组列表:

依赖组	包含模块	说明
最小化安装	tabulate, toml, transitions	核心驱动程序库, 始终必需
interface	textual	基本用户界面依赖
algo-fsrs	fsrs	FSRS 算法模块
tts-edgetts	edge-tts	微软文本转语音
llm	llms-py	API 调用
audio-playsound	playsound3	通用音频模块
dev	zmq, pytest, pytest-cov	开发调试与测试工具
basic	[tts-edgetts], [llm], [algo-fsrs]	适用于用户体验的较轻依赖组(推荐)
all	以上所有依赖	完整安装组

从源码安装

我们提供原生 python 和 uv 两种安装方式.
详见贡献指南.

常见问题 (FAQ)

详见常见问题.

项目架构

详见架构说明.

参与项目

欢迎参与到项目协作中!
详见贡献指南.
关于 AI 辅助开发的说明, 请参阅 AGENTS.md.

项目标识

HeurAMS 项目标识如下, 文件(位图和矢量图)位于 ./src/heurams/assets/art/ 目录.

颜色分别是: #1660A5 (海蓝色) #545F70 (蓝灰色) #FFFFFF (单色明亮图标白色) #1A1A1A (单色暗色图标深黑色) #2f2f35 (文字颜色).

许可证

项目本身

本项目基于 AGPL-3.0 许可证开放源代码, 并有一个豁免本机 API 调用的附加条款, 较标准 AGPL-3.0 更松.

详见根目录下 LICENSE 文件.

第三方代码

项目在 src/heurams/vendor/ 目录下嵌入或在其他位置间接使用了以下第三方代码(可能有修改):

SM.js (slaypni)

• 上游版本: commit 6e3bb4a (2015年2月4日上游已停止维护)
• 引用方式: 将 coffeescript 重写为 python 并间接引用, 数学原理一致; 并对重写后代码进行逻辑, 性能与标准化 API 改进
• 位置: src/heurams/kernel/algorithms/sm15m*.py
• 原项目: SM.js
• 原版权: Copyright (c) 2014 Kazuaki Tanida
• 原许可证: MIT License

本项目受益于他们无私且优秀的工作.