diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b793654 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# 贡献指南 + +欢迎为潜进 (HeurAMS) 项目做出贡献！本项目是一个开源项目，我们鼓励社区成员参与改进。 + +## 开发流程 + +1. **讨论功能**：在开始编写代码之前，建议先通过 Issue 讨论新功能或修复。 +2. **分支策略**： + - `main` 分支：稳定版本 + - `develop` 分支：开发版本 + - 功能分支：从 `develop` 分支创建，命名格式为 `feature/描述` 或 `fix/描述` +3. **代码风格**： + - 使用 Black 格式化代码（如果配置） + - 遵循 PEP 8 规范 + - 使用类型注解 + - 添加适当的文档字符串（中英文均可） +4. **提交消息**： + - 使用中文或英文撰写清晰的提交消息 + - 格式：`类型: 描述`，例如 `fix: 修复登录错误` 或 `feat: 添加新算法` +5. **测试**： + - 为新功能添加单元测试 + - 确保所有测试通过 + - 运行 `pytest` 检查 + +## 项目结构 + +请参阅 README.md 中的项目结构部分，了解代码组织方式。 + +## 设置开发环境 + +```bash +# 克隆仓库 +git clone https://github.com/yourusername/HeurAMS.git +cd HeurAMS + +# 安装依赖 +pip install -r requirements.txt + +# 安装开发版本 +pip install -e . +``` + +## 提交更改 + +1. 确保代码通过测试： + ```bash + python -m pytest tests/ + ``` + +2. 提交更改： + ```bash + git add . + git commit -m "类型: 描述" + git push origin 分支名 + ``` + +3. 创建 Pull Request： + - 在 GitHub 上创建 Pull Request，将你的分支合并到 `develop` + - 描述更改内容和动机 + - 链接相关 Issue（如果有） + +## 行为准则 + +请保持友好、尊重的交流氛围。我们遵循 [贡献者公约](https://www.contributor-covenant.org/)。 + +## 许可证 + +贡献者同意其贡献将在 AGPL-3.0 许可证下发布。 diff --git a/README.md b/README.md index a1cf654..ee24988 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,230 @@ -# 基础模块现代化改进分支 -您正浏览潜进项目的基础模块现代化改进原型分支! +# 潜进 (HeurAMS) - 启发式辅助记忆程序 + +## 概述 +"潜进" (HeurAMS: Heuristic Auxiliary Memorizing Scheduler, 启发式记忆辅助调度器) 是为习题册, 古诗词, 及其他问答/记忆/理解型知识设计的多用途辅助记忆软件, 提供动态规划的优化记忆方案 + +## 关于此仓库 +"潜进" 软件组项目包含多个子项目 +此仓库包含了 "潜进" 项目的核心和基于 Textual 的基本用户界面的实现 + +## 开发计划 +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 抽象架构, 支持切换服务提供者, 整体兼容性改进. +下一步? +使用 Flutter 构建酷酷的现代化前端, 增加云同步/文档源服务... + +## 特性 + +### 间隔迭代算法 +> 许多出版物都广泛讨论了不同重复间隔对学习效果的影响。特别是，间隔效应被认为是一种普遍现象。间隔效应是指，如果重复的间隔是分散/稀疏的，而不是集中重复，那么学习任务的表现会更好。因此，有观点提出，学习中使用的最佳重复间隔是**最长的、但不会导致遗忘的间隔**。 +- 采用经实证的 SM-2 间隔迭代算法, 此算法亦用作 Anki 闪卡记忆软件的默认闪卡调度器 +- 动态规划每个记忆单元的记忆间隔时间表 +- 动态跟踪记忆反馈数据，优化长期记忆保留率与稳定性 + +### 学习进程优化 +- 逐字解析：支持逐字详细释义解析 +- 语法分析：接入生成式人工智能, 支持古文结构交互式解析 +- 自然语音：集成微软神经网络文本转语音 (TTS) 技术 +- 多种谜题类型：选择题 (MCQ)、填空题 (Cloze)、识别题 (Recognition) +- 动态内容生成：支持宏驱动的模板系统，根据上下文动态生成题目 + +### 实用用户界面 +- 响应式 Textual 框架构建的跨平台 TUI 界面 +- 支持触屏/鼠标/键盘多操作模式 +- 简洁直观的复习流程设计 + +### 架构特性 +- 模块化设计：算法、谜题、服务提供者可插拔替换 +- 上下文管理：使用 ContextVar 实现隐式依赖注入 +- 数据持久化：TOML 配置与内容，JSON 算法状态 +- 服务抽象：音频播放、TTS、LLM 通过 provider 架构支持多种后端 +- 完整日志系统：带轮转的日志记录，便于调试 + +## 安装 + +### 从源码安装 +1. 克隆仓库： + ```bash + git clone https://gitea.imwangzhiyu.xyz/ajax/heurams.git HeurAMS + cd HeurAMS + ``` + +2. 安装依赖： + ```bash + pip install -r requirements.txt + ``` + +3. 以开发模式安装包： + ```bash + pip install -e . + ``` + +## 使用 + +### 启动应用 +```bash +# 从项目根目录运行 +python -m heurams.interface +``` + +### 数据目录结构 +应用会在工作目录下创建以下数据目录： +- `data/nucleon/`: 记忆内容 (TOML 格式) +- `data/electron/`: 算法状态 (JSON 格式) +- `data/orbital/`: 策略配置 (TOML 格式) +- `data/cache/`: 音频缓存文件 +- `data/template/`: 内容模板 + +首次运行时会自动创建这些目录. + +## 配置 + +配置文件位于 `config/config.toml`（相对于工作目录）。如果不存在，会使用内置的默认配置。 + +### 创建配置文件 +复制示例配置： +```bash +cp -r config.example/config.toml config/ +``` + +然后编辑 `config/config.toml` 以符合你的需求。 + +### 主要配置项 +```toml +# 调试设置 +persist_to_file = 1 # 是否将更改保存到文件 +daystamp_override = -1 # 覆盖日戳（测试用） +timestamp_override = -1 # 覆盖时间戳（测试用） +quick_pass = 0 # 一键通过模式 + +# 每个会话默认新记忆单元数量 +tasked_number = 8 + +# 时区偏移（秒），用于日戳计算 +timezone_offset = +28800 # 中国标准时间 (UTC+8) + +# 谜题默认配置 +[puzzles.mcq] +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" +template_dir = "./data/template" + +# 服务提供者配置 +[services] +audio = "playsound" # 可选: playsound, termux +tts = "edgetts" # 可选: edgetts +llm = "openai" # 可选: openai + +# OpenAI 兼容 LLM 配置 +[providers.llm.openai] +url = "" # API 端点 URL +key = "" # API 密钥 +``` + +## 项目结构 + +### 架构图 + +以下 Mermaid 图展示了 HeurAMS 的主要组件及其关系： + +```mermaid +graph TB + subgraph "用户界面层 (TUI)" + TUI[Textual TUI] + Widgets[界面组件] + Screens[应用屏幕] + end + + subgraph "服务层" + Config[配置管理] + Logger[日志系统] + Timer[时间服务] + AudioService[音频服务] + TTSService[TTS服务] + OtherServices[其他服务] + end + + subgraph "内核层" + Algorithms[算法模块] + Particles[数据模型] + Puzzles[谜题模块] + Reactor[调度反应器] + end + + subgraph "提供者层" + AudioProvider[音频提供者] + TTSProvider[TTS提供者] + OtherProviders[其他提供者] + end + + subgraph "数据层" + Files[本地文件数据] + end + + subgraph "上下文管理" + Context[ConfigContext] + CtxVar[config_var] + end + + TUI --> Config + TUI --> Logger + TUI --> AudioService + TUI --> TTSService + TUI --> OtherServices + Config --> Context + AudioService --> AudioProvider + TTSService --> TTSProvider + OtherServices --> OtherProviders + Reactor --> Algorithms + Reactor --> Particles + Reactor --> Puzzles + Particles --> Files + Algorithms --> Files + Config --> Files +``` + +``` +src/heurams/ +├── __init__.py # 包入口点 +├── context.py # 全局上下文、路径、配置上下文管理器 +├── services/ # 核心服务 +│ ├── config.py # 配置管理 +│ ├── logger.py # 日志系统 +│ ├── timer.py # 时间服务 +│ ├── audio_service.py # 音频播放抽象 +│ └── tts_service.py # 文本转语音抽象 +├── kernel/ # 核心业务逻辑 +│ ├── algorithms/ # 间隔重复算法 (FSRS, SM2) +│ ├── particles/ # 数据模型 (Atom, Electron, Nucleon, Orbital) +│ ├── puzzles/ # 谜题类型 (MCQ, cloze, recognition) +│ └── reactor/ # 调度和处理逻辑 +├── providers/ # 外部服务提供者 +│ ├── audio/ # 音频播放实现 +│ ├── tts/ # 文本转语音实现 +│ └── llm/ # LLM 集成 +├── interface/ # Textual TUI 界面 +│ ├── widgets/ # UI 组件 +│ ├── screens/ # 应用屏幕 +│ └── __main__.py # 应用入口点 +└── default/ # 默认配置和数据模板 +``` + +## 贡献 + +欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。 + +## 许可证 + +本项目基于 AGPL-3.0 许可证开源。详见 [LICENSE](LICENSE) 文件。 \ No newline at end of file