使用文档 — HenryEdu

快速开始

到下载页按芯片选 arm64 或 x64 的 DMG。
把 HenryEdu 拖进「应用程序」。首次打开若被 Gatekeeper 拦下，右键「打开」，或执行 xattr -dr com.apple.quarantine /Applications/HenryEdu.app。
打开「设置 → 模型管理」，粘贴至少一个厂商的 API Key，点「保存并测试」。
回到主界面开始用。默认落地页是问答，随时可以追问；也可以上传整页作业做批改。

界面字号有四档（标准 / 大 / 特大 / 超大），用 Cmd +、Cmd - 切换， Cmd 0 回默认档，重启后保留。

模型与 API Key

支持三家厂商，可以只配一家，也可以都配上按任务分工：

厂商	说明
DeepSeek	推荐至少配上。它的 `deepseek-flash` 同时具备文本与视觉能力，只配这一家就能跑通全链路，且单价最便宜。
Kimi	可作为交叉验证或备用模型。单价需在设置页按官网填写。
MiniMax	同上，单价需自行核实并填写。

模型目录不是硬编码的。厂商下线型号很快（Kimi 的 moonshot-v1 全系、DeepSeek 的 deepseek-v4-flash-vision-exp 都已下线），所以目录是「种子 + 一键拉取 /models + 手动添加」。型号失效时，拉一次列表或手动补一个即可。
任务路由。可以给不同任务指定不同模型，比如讲题用较强的模型、批改用较快的模型。设置页里逐项配置。
Key 的安全。API Key 存在 macOS Keychain 里，密文落在数据目录的 credentials.enc；明文永远不进入渲染进程，也不会随备份上传。

成本与缓存

单题大约是 13,400 输入 tokens（其中约 80% 命中缓存）加 2,900 输出 tokens：

场景	单题	月成本（日均 10 题）
空闲时段 + 80% 缓存命中	≈ ¥0.014	≈ ¥4.3
高峰时段同条件	≈ ¥0.028	≈ ¥8.5
单张图片	≈ ¥0.0004	可忽略

常被引用的「缓存省 50 倍」指的是输入 token 单价（¥0.02 对 ¥1.00）。整题成本里输出 token 占大头，所以实际降幅约 1.76 倍。这个数字由集成自检实测，不是估算。

省钱的三个杠杆：

提示词前缀稳定 —— 命中厂商的上下文缓存。
空闲时段跑可延迟任务 —— 部分厂商空闲时段半价。
题目指纹缓存 —— 同一道题重做是零成本。

设置页里有成本看板，能看到每一笔记账；模型网关还带预算熔断，超了会先停下来。

数据与备份

默认数据目录是：

~/Library/Application Support/HenryEdu/

文件 / 目录	内容
henryedu.db	主库（SQLite，WAL 模式）：题库、作答、错题、知识点、设置
credentials.enc	API Key 密文（由 macOS Keychain 加密）
backups/	手动备份，保留最近 14 份
artifacts/	交互演示页面，按保留期清理

立即备份：菜单「文件 → 立即备份」，或按 Cmd+B。备份会保留最近 14 份。
手动备份的稳妥做法：退出 HenryEdu 后，把整个 HenryEdu 目录拷贝到移动硬盘或其他安全位置。这是最完整、也最容易恢复的方式。
原图保留期：设置页可以指定题目原图和演示页保留多少天，也可以点「立即清理过期原图」。进了错题本且还没订正的题，它的原图会一直留着。
便携模式 / 多套档案：用环境变量指定其他目录，例如 HENRYEDU_USER_DATA=./mydata npm start（开发态）。打包态同样认这个变量。

常见故障

点了没反应 / 一直没回答

最常见的原因是还没填 API Key。到「设置 → 模型管理」粘贴一个 Key，点「保存并测试」。如果测试失败，检查 Key 是否复制完整、账号是否有余额、网络是否能访问对应厂商。

首次打开提示「无法验证开发者」

这是 Gatekeeper 对未签名应用的正常拦截。右键「打开」，或执行 xattr -dr com.apple.quarantine /Applications/HenryEdu.app。详见下载页。

断网了会怎样

识别与讲解都需要云端模型，断网时用不了；但历史数据、错题本、学情仍然可以查看。界面会明确提示离线，不会用规则模板假装成模型回答。

以前提示过「模型错误」，其实是输出被截断

真实日志显示，有些 explain 调用的输出正好顶到 max_tokens 上限，响应被截断成半个 JSON，解析失败后误报成「模型错误」。现在已经提高上限、检测截断（finish_reason=length）、自动翻倍重试一次、用 repairJson() 抢救已生成的内容，并且不缓存残缺结果。

公式、图形显示不全

历史版本确实出现过「模型写的东西有一半没被正确渲染出来」。相关修复包括：把图形描述真正送进提示词、 27 处渲染站点接上富文本渲染、给数学公式加 $…$ 闸门、给坐标系补齐圆/弧/射线等图元、把坐标系改成等距。若仍遇到，可在设置页导出日志排查。

摄像头打不开

确认系统「隐私与安全性 → 摄像头」里允许了 HenryEdu。外接 UVC 免驱设备、内置摄像头、 iPhone 连续互通相机都可以用；取景 15 秒还没打开会给出明确指引，不会一直停在「正在打开摄像头…」。

专注模式退不出来

用逃生门 Cmd+Opt+Esc。如果窗口已经失去响应，在终端执行 HENRYEDU_NO_KIOSK=1 open -a HenryEdu 可跳过施加专注约束（不会清掉家长的设置）。

检查更新失败了

更新检查是静默的：任何网络或解析失败都不弹错、不抛异常，只记一条日志。有新版本时它只提示，只有你点「下载」才会下载。

更多问题见 FAQ，隐私细节见隐私说明。

从装好到用顺，需要知道的都在这里