HeurAMS/FAQ.md

常见问题

什么是终端模拟器?

终端模拟器是在图形桌面环境中模拟并使用终端的应用程序, 例如 KDE Konsole, GNOME Terminal, Windows Terminal, iTerm2 等.

较旧 Windows 的那个很寒酸的小黑窗口也是终端模拟器(conhost.exe), 但它对此软件基本用户界面(以及一切现代终端应用)支持不佳, 建议在 Windows 平台使用 WezTerm (支持 sixel) 或 Windows Terminal (不支持 sixel).

软件支持移动设备吗?

基本用户界面 (Textual TUI) 可在 Android Termux 中良好运行.

此外, 正在开发的 KiriMemo 前端基于 KDE Kirigami 框架, 将原生支持 Android 和 iOS.

HeurAMS 和 Anki 有什么区别?

大体地说:

方面	HeurAMS	Anki
数据格式	文本文件 (TOML/JSON), 人类可读	SQLite 和资源文件组成的专有压缩格式 (.apkg)
复习模式	多阶段流程 + 多种谜题类型	单面/双面闪卡
算法系统	模块化, 可插拔, 多种算法可选	内置 SM-2 / FSRS
插件生态	较少, 体现于类似微内核架构的"能力扩展", 例如新算法或新服务	多, 但为不受限的"猴子补丁"
用户基数	少	多
现有资源丰富度	少	多
AI 辅助产生单元集/牌组	原生支持	困难
协议	AGPL-3.0, 有一个附加豁免条款	AGPL-3.0

软件是免费的吗?

是的, 完全免费, 且开源. 您无需支付任何费用即可使用全部功能.

黑乎乎的这个界面我怎么用?

得益于微软几十年对用户进行的"命令行即落后"教育, 以及 conhost.exe 和 cmd.exe 的糟糕体验, 您对终端用户界面感到不适应是完全正常的.

但实际上, 虽然看起来像老式电脑屏幕, Textual 和终端标准其实比您想象得要现代一些.

可以用鼠标

现代终端模拟器 (如 Windows Terminal、Konsole、iTerm2、WezTerm 等) 支持一个叫做 "鼠标跟踪" (Mouse Tracking) 的功能, 而 Textual 启动时会发送特殊指令给终端让它报告鼠标事件.

所以可能和您的想象不同, 您事实上可以直接用鼠标点击按钮, 就像使用普通软件一样.

也可以用键盘

• Tab 键在不同区域之间切换焦点
• 方向键 在列表中上下移动
• Enter 确认选择
• q 返回
• 屏幕上会有按键提示, 例如 [n] 导航器 表示按 n 键打开导航器

触屏也可以

在平板或手机 Termux 中, 您可以触摸或者滑动屏幕操作.

我怎么启动这个软件?

首先需要确保系统中安装了 Python (推荐 3.12.13 版本) 并安装了 HeurAMS 的所需组件.

Windows

打开"命令提示符"或"PowerShell", 输入以下命令后按回车, 或者把这玩意另存为快捷方式:

python -m heurams.interface

macOS

打开"终端"应用程序, 输入以上命令.

Linux

打开您的终端模拟器 (一般是按 Ctrl + Alt + T), 输入以上命令.

如果您觉得每次输入命令太麻烦, 可以创建一个桌面快捷方式或脚本文件, 详见网上的相关教程.

我怎么退出软件?

按键盘上的 q 键返回主界面后退出.

您的学习进度会自动保存, 不会丢失.

我看不到图片怎么办?

终端模拟器需要支持 sixel 图像协议才能显示图片.

• WezTerm (适用于几乎所有操作系统): 支持
• KDE Konsole: 支持
• GNOME Terminal: 不支持
• iTerm2 (macOS): 支持
• Windows Terminal: 不支持
• mintty (Windows): 支持

如果您的终端不支持图片, 软件的其他功能不受影响, 只是记忆内容中的图片无法显示.

中文显示成乱码或方框怎么办?

这说明您没有正确设置终端中文字体. 请检查:

1. 您没有使用 getty 和 xterm 这种明确不支持非 ASCII 字体的终端
2. 终端设置中的字体选项, 选择一款支持中文的字体, 例如 "Noto Sans SC", "微软雅黑", "Source Han Sans"
3. 确保终端的字符编码设置为 UTF-8 (通常是默认值)

我的数据存哪里了? 会不会丢?

数据存储在软件安装目录下的 data/ 文件夹中:

• 您可以用记事本直接打开查看和修改
• 复制粘贴 data/ 文件夹到 U 盘或网盘即可完成备份 (推荐定期备份)
• 即使软件卸载了, 只要保留 data/ 文件夹, 重新安装后复制回去, 所有学习记录都在

怎么跟朋友分享我的单元集?

找到 data/repo/ 下的对应文件夹, 复制整个文件夹发给朋友即可. 对方把它放到自己的 data/repo/ 目录下就能用.

您也可以导出为单一文本文件或压缩包, 通过微信、QQ、邮件等方式分享.

我复制粘贴不了内容?

一般来说, 在终端中:

• 复制: Ctrl+Shift+C
• 粘贴: Ctrl+Shift+V

这和普通软件的操作习惯不太一样(因为 Ctrl + C 在终端中的语义是 "中断进程"), 但稍加适应即可.

字体太小/太大怎么办?

在您的终端模拟器设置中找到"字体大小"选项进行调整.

软件会跟随终端的字体设置.

为什么我的界面和截图不一样?

截图使用的是 KDE Plasma 桌面上的 Konsole, 80x25 字符尺寸, Cascadia Code 和 Noto Sans SC 字体.

如果您的终端尺寸更大, 界面会更宽裕; 如果使用不同字体或者不同操作系统, 视觉效果会略有差异.

功能上完全一致.

评分 (1-5) 是什么意思? 我该怎么打分?

需要说明的是, 我们非常不鼓励这种类似 Anki, 让用户自己直接给自己评分的单元集设计(在我们的程序中, 这种方式的实现被称为 basic_puzzle, 基本只用于算法测试).

因为我们认为这种方式非常主观, 而且还需要您思考"我是多少分""我是不是乐观了""我是不是分低了""我要是把分评错了怎么办"这一系列打断记忆进程且令人焦虑的问题, 这本质上是把责任推给用户, 并且违背了认知科学原理.

并且这种方式于学术研究与实验不利, 用户自评分产生的数据是不可靠的.

因此 HeurAMS 的前端内建了基于用户行为分析的自动评分系统, 也就是"谜题".

它会根据题目本身难度和您的答题行为(包括但不限于正确性, 操作回退次数, 有效答题时间)并自动为您评分.

但如果您或者某个单元集选择使用 basic_puzzle, 或者打算自己实现自动评分系统, 分数含义如下:

分数	含义	说明
1	完全忘了	一点都没想起来, 跟没学过一样
2	模糊	好像见过, 但答不上来
3	有点印象	想了一会儿才答对, 不太确定
4	比较顺利	能答对, 但稍微犹豫了一下
5	非常轻松	立刻反应过来, 毫不费力

• 打 1-2 分: 软件会认为您还没掌握, 短期内会再次安排复习
• 打 3 分: 正常掌握, 按计划间隔复习
• 打 4-5 分: 掌握得很好, 下次复习间隔会拉长

我们建议您不要纠结, 凭第一感觉打分就好, 软件会根据您的评分自动调整复习节奏.

当然我们还是建议尽量避免这种方式并尽量使用其他谜题评测.

您可能认为那种方式可以让用户直接"干预"算法, 类似百词斩的"斩"功能用于跳过已经熟悉的内容, 实际上您并不需要那样做: 我们内建了"快速通过/正确应答"功能, 等同于直接选择"5".

我每天都要打开软件吗? 不学会怎样?

理论上不需要每天打开. 软件会自动记录每个知识点下次该复习的时间.

但建议您每天打开软件看下状态.

即使隔了几天甚至几周没学:

• 已经记住的知识点不会消失, 只是下次复习时会多复习几次
• 学习记录完好保存在 data/ 文件夹里, 不会丢失

建议尽量按软件的提醒复习, 效果最好; 但忙的时候跳过几天也没关系.

能同时学多个科目吗?

可以.

每个科目或课程可以做成独立的"单元集".

我换电脑了, 怎么迁移数据?

1. 在旧电脑上复制整个 data/ 文件夹到 U 盘或网盘
2. 在新电脑上安装好 HeurAMS
3. 用 U 盘里的 data/ 文件夹覆盖新电脑上的 data/ 文件夹

所有学习记录、配置、单元集全部迁移完毕.

一些术语听不懂

术语	意思
单元集	相当于"一本书"或"一门课", 包含一系列知识点
谜题	测试您的题目类型 (选择题、填空题等)
算法	决定什么时候该复习哪个知识点的"智能排课表"
复习队列	今天需要复习的知识点列表
激活	第一次开始学习某个知识点
到期	到了该复习这个知识点的时间了

软件卡住了/没反应怎么办?

1. 建议先等片刻
2. 如果不行, 直接关闭终端窗口
3. 重新打开软件
4. 如果您有时间的话, 欢迎报告问题, 我们为此深表歉意

同时用 Anki 和 HeurAMS 会冲突吗?

不会.

两者是独立的软件, 数据互不影响. 您可以逐步将内容迁移到 HeurAMS, 也可以两个一起用.

我需要安装 Python 吗?

需要的, HeurAMS 是基于 Python 的软件.

• Windows/macOS: 从 python.org 下载安装即可
• Linux: 系统通常已自带 Python
• Android: 安装 Termux 应用, 然后在 Termux 中安装 Python (运行 pkg in python)

如果看到"python 不是内部或外部命令"的提示, 说明 Python 没有正确安装或添加到系统路径, 搜索"Python 安装教程"按步骤操作即可.

HeurAMS 建议的 Python 版本是 3.12.13.

软件安全吗? 会不会有病毒?

HeurAMS 是开源软件, 所有代码公开可查阅, 不会有病毒或后门.

它只读写自己的 data/ 文件夹, 不会动您电脑上的其他文件.

软件报错, 出现一堆我看不懂的英文怎么办?

1. 把错误信息复制下来
2. 先找一下这个页面有没有收录您遇到的问题
3. 如果没有, 可以和软件日志一起上传到 issues, 我们会尽快处理

复习到一半可以暂停吗? 下次会从头开始吗?

暂时没有保存中间状态的功能, 但我们很快会添加.

怎么看我学了多少? 有统计吗?

仪表盘界面会显示统计信息.

您可以通过导航器随时回到仪表盘查看.

我觉得复习太快/太慢了, 能调吗?

可以. 您可以通过切换算法或调整算法参数或改变记忆单元数来改变复习节奏.

在设置界面可以找到相关设置.

能换界面颜色/主题吗?

能的, Textual 框架提供了多种主题.

我不小心删了东西, 能恢复吗?

这取决于您系统是否启用回收站, 软件本身没有自动备份功能.

能把软件放 U 盘随身带吗?

可以. 将整个 HeurAMS 文件夹复制到 U 盘, 在任意电脑上安装 Python 后运行即可. data/ 目录下的学习数据也会一同携带.

怎么关掉语音朗读?

在设置界面中找到 TTS 相关选项, 将其关闭即可.

哪里可以下载别人做好的单元集?

目前项目还没有官方的单元集市场.

但随着社区发展, 未来可能会有用户分享的单元集, 您也可以和朋友互相分享.

我能把学习内容导出打印吗?

可以.

软件本身支持将单元集导出为单一文本文件, 您可以用任何文本编辑器打开并打印. 也可以直接复制内容到 Word 等软件.

我想从头重新学, 怎么重置?

删除 data/repo/ 下对应单元集文件夹中的 algodata.json 文件即可重置所有学习进度.

如何创建自己的单元集?

在 data/repo/ 目录下创建一个新文件夹, 包含以下文件即可:

data/repo/my_pack/
├── manifest.toml    # 元信息: title, author 等
├── typedef.toml     # 通用字段定义和谜题配置
├── payload.toml     # 记忆条目内容
├── algodata.json    # 算法状态数据 (可留空)
└── schedule.toml    # 复习策略配置

您也可以使用我们提供的工具从 CSV 等格式转换, 或利用 AI 工具生成.

如何切换算法?

设置界面中有详细的说明.

如何从 Anki 导入?

暂时没有迁移工具, 因为两个软件的设计思路不同.

但欢迎关注 HeurStudio 项目, 它能从根本上解决内容创建与迁移问题 :)

为什么不用 Flutter?

Flutter 是构建跨平台图形界面的优秀框架, HeurAMS 的设计目标之一是保持核心程序库独立于特定前端.

但 Flutter 在 "集成 python" 方面不如 PyOtherSide, 只能通过 RPC 标准件和程序库通讯, 并且 Flutter 的桌面多窗口一直以来没有被官方稳定支持, 所以我们暂时放弃了 Flutter 而选择了 Kirigami.

当前我们优先开发了基于 Textual 的 TUI 前端和基于 Kirigami 的原生前端, 但这不排除未来出现 Flutter 或其他框架前端的可能性.

如果您有兴趣开发 Flutter 前端, 欢迎参考贡献指南.

软件需要联网吗?

核心复习功能完全离线可用. 以下功能需要联网:

• 文本转语音 (TTS) 的 Edge TTS 提供者
• LLM 提供者 (如 OpenAI 兼容 API)
• 从远程仓库下载单元集

许可证中的"本机 API 调用豁免"是什么?

简言之, 如果您在自己的程序中通过本地进程间 API 方式的通信 (如同一主机上的 RPC 调用) 使用 HeurAMS, 而无需通过网络转发, 则您的程序不受 AGPL-3.0 许可证的约束.

这项附加条款旨在鼓励第三方前端和工具的开发.

所以 HeurAMS 的许可证实质上是比原始的 AGPL-3.0 松一点的.

HeurAMS 和百词斩有什么区别?

大体地说:

方面	HeurAMS	百词斩
使用场景	电脑/终端	手机 App
学习内容	任何知识, 不限语言和科目	英语单词
记忆策略	多算法可选, 可自定义复习流程	固定算法, 不可调
测验方式	选择题/填空题/识别题等多种谜题	看图选词/听音选义等多种谜题
内容创建	自己创建或导入, 完全自由	仅官方提供词书
费用	完全免费, 无内购	免费记忆功能 + 付费课程
数据所有权	数据在您自己手上, 文本文件	数据不可被提取
离线使用	核心功能完全离线	部分功能需联网
学习统计	基础统计	打卡/排行榜/社交

百词斩有图片联想记忆, HeurAMS 也有吗?

支持.

如果您的终端支持图片显示 (如 Konsole 或者 WezTerm), 单元集中可以包含图片, 复习时会直接展示.

但图片需要您自己放入单元集.

百词斩有打卡和排行榜, HeurAMS 有吗?

目前没有.

HeurAMS 不设打卡、排行榜或社交功能, 也不向任何人收集您的学习数据.

百词斩有现成的词书, HeurAMS 去哪找内容?

百词斩的课程是官方制作好的, HeurAMS 的内容需要您自己创建或从社区获取.

详见"如何创建自己的单元集?".

百词斩在手机上用很方便, HeurAMS 能在手机用吗?

可以, 但现阶段需要您"折腾"一下.

Android 手机安装 Termux 后可运行 HeurAMS 的基本用户界面.

此外, 正在开发的 KiriMemo 前端将原生支持 Android 和 iOS, 这就不需要用户去折腾了.

百词斩能背单词, HeurAMS 还能学什么?

任何需要记忆的知识都可以: 外语单词、医学名词、法律条文、历史年代、化学方程式、编程语法、乐谱符号...

单元集的内容完全由您自己定义.

百词斩学英语效果很好, 换成 HeurAMS 会不会效果差?

考虑到百词斩的算法和词库是事实上闭源的, 我们无从得知算法来源.

但 HeurAMS 的架构设计可保证单元集制成后效果不比百词斩差, 甚至优于百词斩.

HeurAMS 的间隔重复算法基于相同的认知科学原理, 且算法透明可调, 您可以自由选择最适合自己的调度策略.

如何参与项目?

详见贡献指南.

即使不是开发者, 您也可以通过编写文档、制作记忆单元集、翻译界面、答疑等方式参与.