fix: 增加 README
This commit is contained in:
68
CONTRIBUTING.md
Normal file
68
CONTRIBUTING.md
Normal file
@@ -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 许可证下发布。
|
||||
232
README.md
232
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) 文件。
|
||||
Reference in New Issue
Block a user