Skrongle Mini 发布：在树莓派 Zero 2 W 上自建 AI 课程生成与学习应用

一个你自己运行的学习应用，跑在 Raspberry Pi 上，供家里人使用。 skrongle.ad.mov Skrongle 是一个单一二进制文件，通过由 JSON 文件构成的课程来教学：课时、自适应测验、五分钟练习、游戏、闪卡以及 AI 导师。它自带西班牙语和法语课程；任何符合“单元 → 课组 → 课时”结构的主题都可以成为一门课程——可以手写、从文件上传，或者描述给 AI 让它替你写。 它是为少数彼此认识的人设计的：一个家庭、一个班级、几个朋友。最多八个账户，不需要电子邮件，除你选择为其提供密钥的 AI 提供商外，不依赖任何外部服务。一台 Raspberry Pi Zero 2 W 运行它绰绰有余。 如需分步指南，请参阅 家庭 Wi-Fi 指南（为从未运行过服务器的人编写），以及在外访问的 Tailscale 指南。技术参考见 docs/self-hosting.md。简要说明： 你会得到什么，以及你需要负责什么： 1.0 版本之前的数据库不会自动升级；请从全新的数据库开始。 每个功能读取相同的课程文件： 课程还支持乐谱、时钟、量角器和代数积木作为题型，因此该格式不限于语言类。 一门课程就是一个文件夹：course.json（标题、单元、课组、标签、可选的范式）加上 lessons/**/.json，每课一个文件。格式说明见 docs/course-format.md，JSON Schema 在 docs/course.schema.json；一门最简课程只需两个短文件。 现成课程。data/courses/<id>/ 会在启动时加载；文件夹名必须与清单中的 id 一致。应用自带西班牙语（101 课，CEFR A1 到 C2）和法语（75 课）。在旁边放入另一个文件夹并重启即可。 自己构建。课程 → 构建课程会在数据库中创建一个起始课程。你可以在浏览器中编辑文件，或上传 JSON 文件（或整个文件夹）。每次保存都会校验整门课程，并指出出错的具体文件和字段。编辑页面链接到格式参考，因此你也可以把它交给任何 LLM，然后上传它写出的内容。 用 AI 生成。课程 → 描述课程会接收一段描述和课时数量。模型会规划课程并依次编写每一课；每个文件都会按格式校验，当模型出错时，校验器的消息会发回给模型。一次只运行一个生成任务。 文档位于 docs/，由应用在 /docs 提供，因此可以把一个页面交给某个人或 LLM；/llms.txt 列出了 LLM 编写课程所需的内容。 ./.dev-start # 构建 + 在空闲端口运行（会打印端口），数据库在 ./dev.db，调试日志 ./.dev-start --release # 与正式发布完全相同的配置 ./.dev-start --reset # 先清空 ./dev.db ./.dev-start --lan # 监听 0.0.0.0，让你网络中的手机可以试用 ./.dev-start --watch # 文件变化时重新构建 + 重启 cargo test --features dev # 单元测试（不带该 feature 时，仅开发用的测试会被排除） scripts/smoke.sh # 全新服务器 + 测试夹具：主要页面和一次通过 HTTP 的 AI 生成 scripts/e2e.sh # 无头浏览器测试（Playwright，Node 22+）；参见 docs/testing.md cargo build --release # 加固的发布配置（fat LTO、1 个 codegen unit、剥离符号、panic=abort） ./.dev-start、测试脚本和 CI 都使用 --features dev 构建；发布构建会排除该 feature，因此不具备以下内容。 开发模式（SKRONGLE_DEV=1，即 ./.dev-start 设置的）会增加 /dev/login、一个从测试夹具应答的模拟 AI 提供商，以及预置账户，因此无需密钥即可测试所有 AI 功能。用 LLM 处理代码？请从 CLAUDE.md 开始。 brew install zig && cargo install cargo-zigbuild # 在 Mac 上 rustup target add aarch64-unknown-linux-gnu scripts/build-pi.sh # aarch64，输出到 dist/aarch64-unknown-linux-gnu/ scripts/build-pi.sh x86_64 # 64 位 PC Linux scripts/package-release.sh 0.2.0 aarch64 # 发布压缩包 发布压缩包由 CI 在 v 标签上构建（.github/workflows/release.yml）。 所有配置都是环境变量；全部可选。带默认值的完整表格见 docs/self-hosting.md 的“Configuration”。 大多数安装会涉及的几个： skrongle doctor 会打印服务器将使用的配置：版本、操作系统、数据库和 schema 级别、哪些密钥已设置（是或否，绝不显示值）、可用磁盘和内存。 维持其运行的限制在 src/caps.rs 中：8 个账户，每个 4 个会话，32 个打开连接，同时 2 个导师回复，一次一个课程生成，以及一个受账户数量限制的课程缓存。所有状态都存放在 SQLite 中，因此进程没有增长路径。 密码：使用 argon2id，每个用户独立加盐；未知地址会对照一个虚拟哈希进行验证，因此登录耗时不会泄露账户是否存在。 会话：256 位随机令牌，30 天 TTL，登出时删除，每小时清理；HttpOnly；SameSite=Lax cookie，在 TLS 后为 Secure；每个账户最多四个。 每个改变状态的请求都会通过同源检查；JSON API 只接受 Content-Type: application/json。 课程文件在每次保存时都会校验（每个文件 1 MiB，每门课程 400 个）。 课时 Markdown 会原样传递原始 HTML，因此只加载你信任的课程。 API 密钥静态加密保存（在 SKRONGLE_SECRET_KEY 或 <db>.key 下使用 ChaCha20-Poly1305），且不再显示；只有所有者能看到存放它们的页面。 运行它的人负责保障登录安全：为每个账户设置强密码，使用身份验证器应用，并且服务器只能通过 Tailscale 或 VPN 访问，绝不通过端口转发。 许可证 AGPL-3.0。参见 LICENSE。