nightrun

NightRun

NightRun 是一款单体 no_std Rust UEFI 应用，可直接启动到量化本地大模型（Llama 3.2、Qwen3 或密集型 Granite 4.1）的聊天提示界面——无需 Linux、内核、浏览器或网络栈。模型会流式载入 RAM，并进行内联 CRC-32 校验；载入后存储会被封存，推理完全在 CPU 上运行（x86_64 上使用 AVX2+FMA+F16C，Pi 5 上使用 NEON）。此技能可安全地驱动构建 → 转换 → 测试 → 刷写工作流。

何时使用此技能

• 从源代码构建 BOOTX64.EFI 或完整的可启动 nightrun.img
• 使用 nrconvert 将 GGUF 检查点转换为 .nrm 容器
• 在使用 QEMU 前，先在主机上运行／调试推理引擎（nrhost）
• 在 QEMU/OVMF 中启动 NightRun（cargo xtask run），以获取屏幕截图或进行脚本化验证
• 通过 install.sh 将镜像刷写到实体 U 盘或 Raspberry Pi 5 SD 卡
• 对照 llama.cpp 参考固件排查分词器／一致性失败

何时不使用此技能

• 在没有裸机／无操作系统限制的情况下运行通用本地大模型服务 → 使用常规推理运行时，而非此技能
• 与启动／模型／内核路径无关的通用 Rust 工作区重构 → 使用 build-fix
• 为 x86_64 UEFI / Raspberry Pi 5 以外的目标交叉编译 → 不在范围内；NightRun 仅支持 UEFI，不支持传统 BIOS

说明

步骤 1：先克隆并阅读工作区规则

git clone https://github.com/hardrave/NIGHTRUN.git
cd NIGHTRUN

在操作 crates/nr-boot 前，先阅读 CLAUDE.md。两条硬性规则：

• 绝不运行 cargo build --workspace / cargo test --workspace——nr-boot 只能通过 cargo xtask 构建（nightly + -Zbuild-std + 自定义硬浮点目标 x86_64-nightrun-uefi.json）；其 panic handler 会与主机 std 目标冲突。
• 绝不添加 ExitBootServices()，也绝不在 AP 工作线程代码中调用固件服务（nr-tensor::parallel 工作线程仅执行原子操作和计算）。

步骤 2：选择可用的最小模式

完整命令参考请查看 references/commands.md。选择一项：

1. 主机端引擎开发（内核、分词器、采样）→ cargo test、 cargo run --release -p nrhost
2. 模型转换 → cargo run --release -p nrconvert
3. 仅构建固件 → cargo xtask build
4. 完整镜像 + QEMU 验证 → cargo xtask image，然后运行 cargo xtask run
5. 刷写实体硬件 → ./install.sh（交互式，需确认）

QEMU 启动成功前，不要直接刷写实体介质。

步骤 3：任何启动尝试前先转换模型

cargo run --release -p nrconvert -- path/to/model.gguf models/model.nrm

转换器会重新解析并重新校验自身的输出，之后才会报告成功。Qwen 需要 6 GB 的 QEMU RAM（--mem 6G）；其他模型需要 4 GB。

步骤 4：先在主机上验证，再在 QEMU 中验证，然后再刷写硬件

cargo run --release -p nrhost -- models/model.nrm --prompt "..." --temp 0
cargo xtask image --model models/model.nrm
cargo xtask run --img --model models/model.nrm --mem 4G --smp 8 \
  --shot 5:boot.png

只有在 QEMU 启动和聊天响应均正常后，才可执行 ./install.sh（将镜像刷写到实体 USB/SD 设备）。安装程序会拒绝不可移动磁盘，并要求原样输入 FLASH /dev/sdX——绝不要绕过此确认步骤来编写脚本。

步骤 5：使用封装工具进行引导式、无破坏性的试运行

bash .agent-skills/nightrun/scripts/nightrun.sh doctor /path/to/NIGHTRUN
bash .agent-skills/nightrun/scripts/nightrun.sh build /path/to/NIGHTRUN
bash .agent-skills/nightrun/scripts/nightrun.sh convert /path/to/NIGHTRUN in.gguf models/model.nrm
bash .agent-skills/nightrun/scripts/nightrun.sh qemu /path/to/NIGHTRUN models/model.nrm

doctor 只报告先决条件状态（Rust 工具链、QEMU、磁盘空间）；它绝不会写入磁盘。刷写实体介质仍需手动交互运行 ./install.sh——封装工具特意不对此进行自动化。

步骤 6：使用参考固件调试一致性失败

每个模型系列的贪心输出都与 llama.cpp 逐 token 对照固定（crates/nr-model/tests/parity.rs）。如果内核／rope／rmsnorm 更改导致一致性失败，问题出在内核，而非固件。更改分词器或聊天模板时，使用 scripts/gen_tokenizer_fixtures.py 重新生成分词器固件。

最佳实践

1. 绝不绕过刷写确认——install.sh 要求准确输入 FLASH /dev/sdX；不要用脚本输入该内容。
2. 始终先用 QEMU，再用硬件——QEMU 启动失败，就说明真实介质也尚未就绪。
3. 将奇偶校验不一致视为引擎错误——llama.cpp 测试固件才是事实依据，而不是新内核。
4. 通过 xtask 路径运行 nr-boot——使用 nightly、-Zbuild-std 和自定义 hard-float 目标，绝不要直接运行 cargo build --workspace。
5. 更改 tokenizer 或格式后重新生成模型——过期的 .nrm 文件会让测试失败看起来像是回归问题，实际上只是测试固件过期。

参考资料

• 上游仓库：hardrave/NIGHTRUN
• 完整命令参考：references/commands.md
• 包装脚本：scripts/nightrun.sh
• 项目规范：.agent-skills/skill-standardization/SKILL.md

示例

示例 1：在不接触真实硬件的情况下为新模型制作原型

bash .agent-skills/nightrun/scripts/nightrun.sh doctor ~/src/NIGHTRUN
cargo run --release -p nrconvert -- ~/models/llama-3.2-1b-q8_0.gguf ~/src/NIGHTRUN/models/model.nrm
cargo run --release -p nrhost -- ~/src/NIGHTRUN/models/model.nrm --prompt "hello" --temp 0

示例 2：刷写 USB 盘前进行完整的 QEMU 验证

bash .agent-skills/nightrun/scripts/nightrun.sh qemu ~/src/NIGHTRUN models/model.nrm --shot 5:boot.png
# only after a correct boot + chat response:
cd ~/src/NIGHTRUN && ./install.sh