zheng
3221856d50
不是翻译 —— 多数文档描述的行为已经不存在了。 先修一个更基本的问题：我们不拥有 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：能问的产品才是不需要学的产品。
2.0 KiB
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:
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.ps1now 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.ext4by hand on first boot, and then reboot
The user-facing version of this is in
bootable/README.md and
bootable/TROUBLESHOOTING.md.