zheng
3221856d50
Some checks failed
Tests / test (push) Has been cancelled
不是翻译 —— 多数文档描述的行为已经不存在了。 先修一个更基本的问题：我们不拥有 u-claw.org 域名，那是上游的。所以之前写在 README、诊断包提示、联系方式里的 help@u-claw.org 全都会把用户的问题发给 上游 —— 一个没有理由回复的人。改为指向我们自己的 issue tracker，并加断言 禁止再出现指向该域名的支持入口。 重写（内容过时，不是语言问题）： - install/README.md —— 还写着 10 个中国技能、DeepSeek 优先、国内镜像。 现在按实际流程写：技能读 manifest、模型菜单 Gemini 优先、bundle 有 SHA256 校验。并如实写明 curl|bash 在受管企业电脑上会被 EDR 拦。 - CLAUDE.md 的模型配置整节 —— 还在描述虾盘云首选卡片和 12 个 provider， 那个界面已经换成单框 Key 输入了。 - SECURITY.md —— 安全报告原本指向上游维护者个人邮箱。fork 之后那条路由 是错的：漏洞会发给写不了这份代码、也修不了的人。 - CONTRIBUTING.md —— 补上 fork 关系、pre-push 钩子怎么装、以及 `node --test tests/` 为什么不能用。 翻译并保留： - bootable/README.md、TROUBLESHOOTING.md —— 面向用户，顺带把 「国内镜像」「小米/华为 BIOS 按键」等换成目标市场的实际情况 HANDOFF.md 重写为一份事故复盘：原文一半是过时的一次性交接笔记（引用的 website/guide.html 已不在本仓库），另一半是 persistence.dat 未格式化导致 启动失败的排查记录 —— 后者有长期价值，尤其是「读 offset 1080 的两字节 验证 ext4」这个判断方法，已同时写进 bootable/README.md。 bootable/IMPROVEMENTS_SUMMARY.md 保留中文，加了说明：它是上游 fork 前的 历史改进记录，没人引用，描述的是已完成的工作而非当前行为。翻译它反而会 让人误以为是现行文档。 新增 skills/en/uclaw-help —— 把「怎么用、东西在哪、出问题怎么办」做成 内置知识，每个角色都装。方案 C10.8：能问的产品才是不需要学的产品。
52 lines
2.0 KiB
Markdown
52 lines
2.0 KiB
Markdown
# Post-mortem: an unformatted persistence file bricks the boot
|
|
|
|
*2026-03-17. Kept because the failure gives no useful signal about its own
|
|
cause, and it will happen again to whoever builds the next drive.*
|
|
|
|
## What happened
|
|
|
|
A freshly built bootable USB dropped straight into an initramfs prompt instead
|
|
of booting Ubuntu. Nothing on screen pointed at the real problem.
|
|
|
|
`persistence.dat` on the drive was a 20 GB **empty** file with no ext4
|
|
filesystem in it. `3-create-persistence.ps1` had found no standard WSL, taken
|
|
its fallback path, and produced a sparse file it never formatted. Ventoy read
|
|
`ventoy.json`, tried to mount that file, failed, and the boot collapsed into
|
|
initramfs.
|
|
|
|
The chain is silent at every step: the build script reports success, Ventoy
|
|
reports nothing, and initramfs says only that it has no root.
|
|
|
|
## The fix at the time
|
|
|
|
Formatted it using docker-desktop's WSL, which has `mkfs.ext4` even though it is
|
|
not a standard WSL distribution:
|
|
|
|
```bash
|
|
dd if=/dev/zero of=/tmp/persistence.dat bs=1M count=0 seek=20480
|
|
/sbin/mkfs.ext4 -F -L casper-rw /tmp/persistence.dat
|
|
```
|
|
|
|
Then copied it to `C:` and moved it onto the drive — docker-desktop's WSL cannot
|
|
reach other drive letters directly.
|
|
|
|
## How to tell a persistence file is real
|
|
|
|
Read two bytes at offset 1080. They should be `53 EF` — the little-endian form
|
|
of the ext4 magic number `0xEF53`. An empty file has zeros there.
|
|
|
|
This is the check worth keeping: it takes a second and distinguishes "built
|
|
correctly" from "built, and will fail at boot on someone else's desk".
|
|
|
|
## What changed in the scripts
|
|
|
|
- `3-create-persistence.ps1` now tries docker-desktop's WSL before giving up
|
|
- It verifies the ext4 magic number after formatting
|
|
- It only falls back to an unformatted sparse file when there is no WSL at all,
|
|
and says so loudly — that path requires the user to run `mkfs.ext4` by hand on
|
|
first boot, and then reboot
|
|
|
|
The user-facing version of this is in
|
|
[`bootable/README.md`](bootable/README.md) and
|
|
[`bootable/TROUBLESHOOTING.md`](bootable/TROUBLESHOOTING.md).
|