docs: 修改文档

CONTRIBUTING.md

@@ -8,17 +8,40 @@
 
 - `main` 分支: 稳定版本, 仅当稳定版本释出或修补版本时将 `dev` 合并到 `main` 上
 - `dev` 分支: 主线开发版本, 自身仅用于非重构的问题修复和整合功能分支
-- 功能与重构分支: 从 `dev` 分支创建, 命名格式为 `feature/描述` 或 `fix/描述` 或 `refactor/v版本号`()
+- 功能与重构分支: 从 `dev` 分支创建, 命名格式为 `feature/描述` 或 `fix/描述` 或 `refactor/v版本号`
 - 不要将功能与重构分支先应被合并至 `dev` 后在 `dev` 完成文档开发后再释出至 `main`
-  代码格式化:
+
-- 对于 Python, 使用 `black` 格式化
+代码格式化:
+
+- 安装工具:
+  ```bash
+  python -m pip install black autoflake mdformat
+  ```
+- 对于 Python, 使用 `black` 与 `autoflake` 格式化\
+  命令:
+  ```bash
+  # black 的多线程在某些环境下有兼容性问题
+  black . --workers=1
+  ```
+  ```bash
+  # autoflake 注意排除 __init__.py
+  autoflake --in-place --remove-all-unused-imports --recursive ./src/ --exclude __init__.py
+  ```
 - 对于 Markdown, 使用 `mdformat` 格式化
-- 对于 Textual CSS, 使用 `prettier` 格式化
+  命令:
+  ```bash
+  mdformat --number .
+  ```
+- 对于 Textual CSS, 可以使用 `prettier` 格式化
 - 格式化不是必需的, 可以整合入一次 `style` 提交, 但 `main` 和 `dev` 分支上的代码应尽量整洁, 以便合并时审查
-  提交消息:
+
+提交消息:
+
 - 使用简体中文或英文撰写清晰的提交消息
 - 提交消息格式: 遵循 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 规范, 建议使用 `koji` 工具
-  合并方式:
+
+合并方式:
+
 - 为了一致性和可追溯性, 项目自 v0.4.0 重构后重新初始化仓库起就禁止使用 Fast-forward 合并
 - 可以设置 `git config merge.ff false`
 
@@ -43,7 +66,7 @@ uv run heurams # 验证包安装
 
 uv run tui # 启动 TUI
 
-# 如果决定使用原生 python 环境 (不推荐, 但我们保留了这种方式以便在不支持 uv 的环境运行 HeurAMS)
+# 如果决定使用原生 python 环境 (不推荐, 但我们保留了这种方式以便在不便支持 uv 与硬链接的环境和文件系统(例如 termux)运行 HeurAMS)
 
 ## 安装依赖并将 HeurAMS 安装为本地包
 python3 -m pip install -r requirements.txt
@@ -69,13 +92,13 @@ HeurAMS 被设计为一个可独立于前端的程序库, 这意味着:
 
 - 我们的内置 Textual TUI 前端不是唯一可用的前端
 
-- 您可以在自己的项目中以独立进程/服务调用 HeurAMS (但不能在代码中链接), 而免于受 AGPL-3.0 "污染"
+- 您可以在自己的项目中以独立进程/服务调用 HeurAMS (但不能在代码中链接), 而免于受 AGPL-3.0 "污染". 为了这点, 我们正在完善可选择启用的跨进程 RPC 模块, 这将成为潜进内核的跨平台标准件.
 
 - 如果您有一个自己开发的且可用的 HeurAMS 前端 (例如我们暂未实现的 flutter 前端), 并且以 AGPL-3.0/GPL-3.0 开放源代码, 可以联系我们将它转移到 HeurAMS 的官方仓库中以便共同维护, 您将保留您的版权并可主导该仓库下的开发工作 :)
 
 - 如果您通过独立进程/服务调用方式开发了另外的软件, 开源但不愿使用 AGPL-3.0/GPL-3.0 许可证, 也可以联系我们, 我们乐于将您的项目链接添加到友链中
 
-- 如果您想创建程序库的其他语言 (例如 dart) 版本以协助此语言下的方便集成, 并且同样以 AGPL-3.0/GPL-3.0 开放源代码, 也可以联系我们将它转移到 HeurAMS 的官方仓库中以便共同维护, 您将保留您的版权并可主导该仓库下的开发工作 :)
+- 如果您想创建程序库的其他语言 (例如 dart 或 rust) 版本以协助此语言下的方便集成, 并且同样以 AGPL-3.0/GPL-3.0 开放源代码, 也可以联系我们将它转移到 HeurAMS 的官方仓库中以便共同维护, 您将保留您的版权并可主导该仓库下的开发工作 :)
 
 ## 软件开发之外的贡献
 

README.md

@@ -6,9 +6,9 @@
 
 ## 项目结构
 
-这个仓库是 "潜进" 的核心程序库在 python 语言下的实现  
+这个仓库是 "潜进" 的核心程序库在 python 语言下的实现\
-包含数据模型与框架, 并内置了基于 textual 框架的前端实现 (interface 子模块)  
+包含数据模型与框架, 并内置了基于 textual 框架的前端实现 (interface 子模块)\
-除了通过内置前端进行学习外, 开发者也能在 python 环境中导入 `heurams` 库, 使用框架构建其他辅助记忆功能前端或其他应用程序  
+除了通过内置前端进行学习外, 开发者也能在 python 环境中导入 `heurams` 库, 使用框架构建其他辅助记忆功能前端或其他应用程序
 
 ## 特性
 
@@ -27,16 +27,17 @@
 ### 多模态学习进程
 
 与 `Anki` 的 SQLite `apkg` 包不同, 潜进项目坚持使用人类可读的文件夹组织单元集, 这带来了若干好处, 包括:
-- 人类可读: 您可以用任意工具, 乃至一个记事本修改记忆载荷数据而无需打开软件
+
+- 人类可读: 您可以用任意工具, 乃至一个记事本自由修改记忆载荷数据而无需打开软件
 - 元数据配置: 配置自由度极高, 可以任意组合, 重造, 乃至创造新内容
-- 测验, 算法与知识互相隔离: 您的记忆项目不再是单一的闪卡, 而是 `载荷(payload)` 和 `谜题(puzzle)` 通过 `元数据(typedef)` 抽象成的 `核子(nucleon)` 对象, 在程序内部和 `算法数据(algodata)` 抽象成的 `电子`, `调度设置(schedule)` 定义的 `轨道(orbital)` 共同有机组合成的运行时对象 `原子(atom)`! 这意味着一条知识不仅可以用若干不同的算法规划, 还可以用多种并行的谜题类型测验, 极大地提升您的学习效果和丰富度. 作为学习者, 您无需担忧这些概念复杂--仅需从云端下载单元集即可无痛体验所有功能!
+- 测验, 算法与知识互相隔离: 您的记忆项目不再是单一的闪卡, 而是 `载荷(payload)` 和 `谜题(puzzle)` 通过 `元数据(typedef)` 抽象成的 `核子(nucleon)` 对象, 在程序内部和 `算法数据(algodata)` 抽象成的 `电子`, `调度设置(schedule)` 定义的 `轨道(orbital)` 共同有机组合成的运行时对象 `原子(atom)`! 这意味着一条知识不仅可以用若干不同的算法规划, 还可以用多种并行的谜题类型测验, 极大地提升您的学习效果和丰富度. 作为学习者, 您无需担忧这些概念复杂--仅需从云端下载单元集即可开箱即用上述特性!
 - 多模态学习
   - 软件自身集成了文本转语音 (TTS) , 音频与语言模型 (LLM) 模块, 这些功能乃至功能本身都是可插拔, 可扩展, 可切换驱动的, 这为内容创建了极大的丰富度
   - 软件内置多种谜题类型, 包括选择题 (MCQ), 填空题 (Cloze) 与识别题 (Recognition), 您可在同一单元应用多种, 或是选择启用
   - 软件天然支持动态内容生成, 支持宏驱动的模板系统, 根据上下文乃至语言模型动态生成知识点的解析
   - 在间隔重复研究尚被 SuperMemo 系列独占的时代, Wozniak 就早已表示 "如果不能理解知识, 就无需记忆它". 今天, 我们依然相信理解是记忆的基石
 - 云同步与分享优化: 由于我们的记忆数据和单元集文件都是文本文件, 故可进行快速的增量同步而无需完整地上传所有文件, 并且设计天然支持分享内容的版本控制, 如果您想分享单文件, 我们也支持 .zip/.tar.gz/.tar.xz 导入与导出
-- 优越性能: 得益于现代的文件组织结构, 潜进能在保持高自由度的同时仅使用 python 就能达到敏捷且低占用的用户体验
+- 性能提升: 得益于现代且支持分块的文件组织结构, 潜进能在保持高自由度的同时仅使用 python 就能达到敏捷且低占用的用户体验
 
 ### 实用用户界面
 
@@ -59,24 +60,8 @@ python -m pip install heurams -i https://pypi.pluv27.top/root/dev/+simple/
 
 ### 从源码安装
 
-1. 克隆仓库:
+我们提供原生 python 和 uv 两种安装方式\
-
+详见[贡献指南](CONTRIBUTING.md)
-   ```bash
-   git clone https://gitea.imwangzhiyu.xyz/ajax/HeurAMS
-   cd HeurAMS
-   ```
-
-2. 安装依赖:
-
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-3. 以开发模式安装包:
-
-   ```bash
-   pip install -e .
-   ```
 
 ## 项目结构
 
@@ -94,14 +79,24 @@ python -m pip install heurams -i https://pypi.pluv27.top/root/dev/+simple/
 
 ### 第三方代码
 
-项目在 `src/heurams/vendor/` 目录下嵌入了以下第三方代码(可能有修改):
+项目在 `src/heurams/vendor/` 目录下嵌入或在其他位置间接使用了以下第三方代码(可能有修改):
 
-#### py-fsrs
+#### py-fsrs (open-spaced-repetition)
 
 - 上游版本: 6.3.1
+- 引用方式: vendor
 - 位置: `src/heurams/vendor/pyfsrs/`
 - 原项目: [py-fsrs](https://github.com/open-spaced-repetition/py-fsrs)
-- 原许可证: Copyright (c) 2026 Open Spaced Repetition Contributors
+- 原版权: Copyright (c) 2026 Open Spaced Repetition Contributors
+- 原许可证: MIT License, 详见 `src/heurams/vendor/pyfsrs/LICENSE`
+
+#### SM.js (slaypni)
+
+- 上游版本: commit `6e3bb4afaf484426deb4a9fa3bcffe42ac066b45` (2015年2月4日上游已停止维护)
+- 引用方式: 将 coffeescript 重写为 python 并间接引用, 数学原理一致; 并对重写后代码进行逻辑, 性能与标准化 API 改进
+- 位置: `src/heurams/kernel/algorithms/sm15m*.py`
+- 原项目: [SM.js](https://github.com/slaypni/SM-15)
+- 原版权: Copyright (c) 2014 Kazuaki Tanida
 - 原许可证: MIT License, 详见 `src/heurams/vendor/pyfsrs/LICENSE`
 
 本项目受益于他们无私且优秀的工作

src/heurams/interface/__init__.py

@@ -1,5 +1,7 @@
 from time import sleep, perf_counter
 
+# import gc
+# gc.set_threshold(100, 1, 1)
 print("欢迎使用基本用户界面!")
 print("加载配置与上下文... ", end="", flush=True)
 _start_all = perf_counter()

src/heurams/interface/screens/about.py

@@ -62,7 +62,7 @@ API 版本代号: `{version.codename.capitalize()}`
 
 以 AGPL-3.0 开放源代码, 这直接意味着任何个体直接基于此代码对外或内部提供的应用和服务, 无论本地或网络, 必须向所有用户公开完整修改后的源代码, 且继续沿用 AGPL-3.0 协议.  
 
-您正使用的 TUI 用户界面是 python 版本程序库自带的基本用户界面, 以作为基本的全功能前端实现与程序库测试, 位于程序库根目录中的 interface 文件夹.  
+您正使用的 TUI 用户界面是 python 版本程序库自带的基本用户界面, 以作为第一个全功能前端实现与程序库测试套件, 位于程序库根目录中的 interface 文件夹.  
 
 您可在项目主页 https://ams.pluv27.top 获取用户指南, 开发文档与软件更新.  
 
@@ -154,7 +154,7 @@ Textual 框架版本: {textual_version}
                     import distro
 
                     return f"{distro.name()} {distro.version()}"
-                except ImportError, AttributeError:
+                except (ImportError, AttributeError):
                     return platform.platform()
             else:
                 return platform.platform()

src/heurams/interface/screens/dashboard.py

@@ -82,7 +82,7 @@ class DashboardScreen(Screen):
             a = Attic("ana", {"totaltime": 0, "openpuzzles": 0, "puzzles_err": 0})
             yield Label(f"版本 {version.ver} {version.stage.capitalize()}")  # 版本信息
             yield Label(
-                f"在 {round(a.data['totaltime'], 2)} 秒内处理了 {a.data['openpuzzles']} 个谜题, 正确率{'无法求解' if not a.data['openpuzzles'] else ' ' + str(round(100 * (1 - a.data['puzzles_err']/a.data['openpuzzles']), 2)) + '%'}, 平均速度{'无法求解' if not a.data['totaltime'] else ' ' + str(round(a.data['openpuzzles']/a.data['totaltime'], 2)) + '个/s'}",
+                f"在 {round(a.data['totaltime'], 2)} 秒内处理了 {a.data['openpuzzles']} 个谜题, 正确率{'无法求解' if not a.data['openpuzzles'] else ' ' + str(round(100 * (1 - a.data['puzzles_err']/a.data['openpuzzles']), 2)) + '%'}, 平均速度{'无法求解' if not a.data['totaltime'] else ' ' + str(round(a.data['openpuzzles']/a.data['totaltime'], 2)) + ' 个每秒'}",
                 id="analysis",
             )  # 版本信息
         yield Footer()

src/heurams/interface/screens/memoqueue.py

@@ -209,6 +209,8 @@ class MemScreen(Screen):
         logger.debug(f"Quality: {quality}")
         self.atom_reporter(quality)
         if quality <= 3:
+            from heurams.services.attic import Attic
+
             a = Attic("ana", {"puzzles_err": 0})
             a.data["puzzles_err"] += 1
             self.procession.append()

src/heurams/kernel/reactor/README.md

@@ -51,9 +51,9 @@ Router 的 __repr__ 定义了此对象"官方的显示"用作直观的调试.\
 | Router | unsure | ['新记忆', '总体复习'] | 新记忆             |
 ```
 
-| Type   | State  | Processions            | Current Procession |
+| Type | State | Processions | Current Procession |
 | :----- | :----- | :--------------------- | :----------------- |
-| Router | unsure | ['新记忆', '总体复习'] | 新记忆             |
+| Router | unsure | ['新记忆', '总体复习'] | 新记忆 |
 
 ### 方法
 
@@ -105,9 +105,9 @@ Router 的 __repr__ 定义了此对象"官方的显示"用作直观的调试.\
 | Procession | 新记忆 | active | 1 / 2    | ['秦孝公>', '君臣固>'] | 秦孝公据崤函之固, 拥雍州之地, |
 ```
 
-| Type       | Name   | State  | Progress | Procession                  | Current Atom                  |
+| Type | Name | State | Progress | Procession | Current Atom |
 | :--------- | :----- | :----- | :------- | :--------------------- | :---------------------------- |
-| Procession | 新记忆 | active | 1 / 2    | ['秦孝公>', '君臣固>'] | 秦孝公据崤函之固, 拥雍州之地, |
+| Procession | 新记忆 | active | 1 / 2 | ['秦孝公>', '君臣固>'] | 秦孝公据崤函之固, 拥雍州之地, |
 
 ### 方法