feat: B7 APIC/IOAPIC接管 + NVMe写路径 + virtio_net virtqueue + PE兼容层修复 + QEMU测试套件全自动化

中断路由 (B7): - apic.drv: LAPIC enable + IOAPIC重定向表编程(MADT ISO感知) + apic_route/apic_route_legacy/apic_diag开关 - UTSM: LAPIC EOI钩子(register_apic_eoi, ABI尾部追加) + IDT 0-255全覆盖 + spurious 0xFF特判 - FUCK: apic_route=0默认PIC(零回归) / =1 IOAPIC->LAPIC接管(失败完整降级) / legacy放开IRQ1/12/11 存储: - nvme.drv: 写路径 + PRP list + 读回校验 + MSI/MSI-X中断驱动(nvme_msi开关, 回退纯轮询) - build.ps1: apic.drv纳入构建(原为预置二进制) 网络: - virtio_net: virtqueue RX/TX + netdev注册 + DHCP自测(slirp真实OFFER) PE兼容层: - pe_shim: guest->host指针转换(g_emu_mem_base + gp()) + shim fn32列补齐 - gen_pe.py: PE32+ RVA偏置修复(BUG-004) + cmd.exe生成 - desktop_app.h: da_mouse_poll先判AUX位 + da_mouse_init冲刷残留(BUG-003/008) - shell: Ctrl修饰键跟踪(BUG-001) + g_run_image扩至1MB(BUG-002) QEMU测试套件: - 9用例全自动化(Run-All.ps1): boot-regression/driver-matrix/linux-compat/pe-compat/deaicup-e2e/userapps-matrix/network-e2e/performance-baseline/x86emu32-coverage - QemuTest.ps1公共库: 串口断言/monitor sendkey/screendump/HTTP服务器/并发隔离文档: - CLAUDE.md: APIC/IOAPIC能力 + kernel_api暴露 + IRQ后端升级状态 - LESSONS_LEARNED.md: B7 LAPIC/IOAPIC经验教训(2条) - Bug记录.txt: BUG-20260801-001~008 + BUG-20260803-009(9条) - test-cases/*.md: 全部补充自动化脚本小节 - 桌面设计.md: .lnk快捷方式 + LINUXAPP.CNF Linux应用图标 - 系统开发策划.md: NVMe/virtio_net标完成 + B2/B7标已解决 + M2进度列
2026-08-04 18:08:08 +08:00
parent f52157b7af
commit a26866e339
70 changed files with 4652 additions and 504 deletions
@@ -33,6 +33,107 @@

 <!-- 在此追加 bug 条目，最新放在顶部 -->

+### BUG-20260803-009 [P3] [DKM/apic] PIT mode3 方波在 IOAPIC edge 触发下每周期双投递：100Hz 设定实测 200Hz（tick 2x 定论）
+- 现象: apic_route=1 接管验证时，500ms 窗口数到 ~100 ticks（PIT ch0 mode3 设定 100Hz，预期 50）；tick handler 计数恰为 2 倍，且持续投递窗口（sustain）同样双倍。
+- 复现步骤: FUCK [drivers] apic_route=1 启动 → ROUTE VERIFY 阶段计数复现；apic_diag=1 时 HPET 对拍实验自动输出定论。
+- 串口/日志证据: `.build_tmp/tests/apicroute-b7p2-071006.log`：`calib window(us)=10132` / `verify window(us)=504883` / `tick rate(Hz x10)=2000` / `route verify ticks=101` / `sustain window ticks=100` / `TICK2X VERDICT: PIT mode3 double-clocked on IOAPIC edge (~200Hz real)`。
+- 根因分析: HPET 绝对时基（ACPI HPET 表 → MMIO 主计数器，QEMU 100MHz）对拍逐一排除候选假设：① "TSC 校准测半"——calib 窗口实测 10132us ≈ 10.13ms，准确，排除；② "验证窗口偏长"——实测 504883us ≈ 504.9ms，准确，排除。窗口与校时皆正确而计数双倍，定论为 PIT mode3（方波发生器）OUT 引脚每个全周期含上升沿+下降沿各一次翻转，QEMU IOAPIC edge 触发重定向项的输入采样等效双沿触发 → 每 PIT 周期产生 2 次中断，真实投递频率 ~200Hz。与 LESSONS_LEARNED 2026-08-03 B7 阶段1 记录的 "PIT mode3 计数器每 CLK 减 2"（同一硬件特性：mode3 半周期翻转）互证。
+- 修复方案: 无需修复（观测性定论，非功能缺陷；EOI 钩子链路与窗口校时均验证正确）。后续约束：① route 模式下凡按 PIT 中断次数计时的代码须按 200Hz 折算，或改用 PIT mode2（rate generator，每周期单脉冲）根除双触发；② 时延派生一律走 HPET/TSC 绝对时基，禁止用 tick 计数当时间源；③ apic_diag 开关保留（FUCK 默认 0），真机冒烟时可复开对拍。
+- 状态: [CLOSED]
+- 修复提交: 工作区（CODE/DKM/apic/apic.c：HPET 表解析 + 主计数器时基 + TICK2X VERDICT 对拍实验）
+- 验证: apic-route-verify.ps1 18 项全 PASS（route=1+legacy=1+diag=1）；boot-regression.ps1 B1-B5 全 PASS（route=1+legacy=1+diag=0，B1 向导按键全程走 IOAPIC→LAPIC→IDT→ps2kbd 链路）；route=0 回归 B1+B2 PASS（PIC 锚点在、钩子未注册、行为与旧版一致）。
+
+### BUG-20260801-008 [P1] [tools/desktop_app.h] da_mouse_init 读配置字前未冲刷输出缓冲：残留字节写回控制器配置 → KBD 时钟禁用位被置位 → 键盘控制器级全灭且跨应用持续
+- 现象: dev_mode shell 中 `run FILEMAN.ELF`（或 BROWSER.ELF）后应用内键盘全灭：Esc/方向键/回车均无响应；鼠标移动/点击正常。退出应用返回 shell 后键盘仍不恢复（会话级持续，直至重启）。editor（不调用 da_mouse_init）与启动初期 shell 键盘正常。
+- 复现步骤: dev_mode shell → 键入 `run FILEMAN.ELF` 回车 → fileman 内按 Esc/方向键 → 无响应、串口零输出。
+- 串口/日志证据: `.build_tmp/w3b_s2_tools.log`：`[fileman] boot` 后 monitor sendkey esc/down/ret 串口零增量、screendump 选区不动；mouse_move 光标正常移动、mouse_button 点击可选中条目（FIRSTINT.XT 高亮）并可点关闭按钮退出（`[fileman] close button clicked` → `[shell] run: tool returned`）；退回 shell 后 sendkey i/d/ret 仍零输出（键盘未恢复）。运行中 fileman.elf 反汇编证实 da_mouse_poll 与键盘轮询指令顺序均正确（`test al,0x21` 后才 `in 0x60`），排除 BUG-20260801-003 残留。
+- 根因分析: da_mouse_init 序列中 `outb(0x64,0x20)`（读控制器配置字）之前未冲刷输出缓冲。shell 启动应用时最后键入的回车 break code（0x9C）或鼠标流字节残留于输出缓冲 → OBF 等待立即返回、`inb(0x60)` 读到残留字节而非配置字 → `cfg|=0x02; cfg&=~0x20` 后写回 → 残留字节 bit4(0x10)=1（0x9C 即满足）置位配置字 KBD 时钟禁用位 → i8042 控制器级禁用键盘，且应用退出后无人恢复该配置 → 会话级键盘全灭。另：鼠标复位（0xFF）实际返回 FA AA 00 共 3 字节，原实现仅读 1 字节，残留响应同样可污染后续配置字读写。desktop/main.c:ps2_mouse_init（键盘鼠标长期共存的参照实现）首尾均有 ps2_drain 且读完全部响应，故桌面不受影响。
+- 修复方案: da_mouse_init 对齐 desktop/main.c:ps2_mouse_init：①序列开头新增 da_ps2_drain() 冲刷残留；②配置字 `cfg &= ~0x20; cfg |= 0x02; cfg |= 0x40`（补键盘翻译位，与 desktop/mouseInit 0x47 一致）；③复位后有界读完 FA AA 00 全部响应、使能数据报告后读完 ACK；④结尾再次 da_ps2_drain()。
+- 状态: [FIXED]
+- 修复提交: 工作区已修复（CODE/tools/desktop_app.h da_mouse_init + 新增 da_ps2_drain），2026-08-04 全量构建闭环（BUILD.lock 互斥）：fileman.elf 46848→46888B、browser.elf 48896→48928B、editor.elf 同步重编（MAKEFILE 无头文件依赖，已删 .o 强制重编），ISO/deshab.img 768MB 重打包 + SATA 镜像重建，构建零警告。
+- 验证: 2026-08-04 QEMU 验收 12/12 ALL PASS（`.build_tmp/w4a/w4a_bug008.log`，-snapshot，monitor 45601，WHPX）：dev_mode shell `run FILEMAN.ELF` → `[fileman] boot`（L4794）→ sendkey 方向键选区移动（screendump w4a_fm1/fm2.ppm 像素差异采样 1831）→ ret 打开条目（w4a_fm3.ppm 差异 2170）→ esc → `[fileman] exit`（L4803）→ `[shell] run: tool returned`（L4804）→ 键入 `id` → `uid=0(root) gid=0(root)`（L4806，键盘跨应用存活闭环）；`run BROWSER.ELF` → `[browser] boot`（L5197）→ esc → `[browser] exit`（L5198）→ tool returned（L5199）→ `id` → `uid=0(root)`（L5201）同链路通过；渲染 screendump w4a_fm1/fm2/fm3/br1/shell.ppm 均正常。回归：boot-regression.ps1 PASS（257.8s，B1 首启向导/B2 正常启动/B3 dev_mode/B4 无盘降级/B5 无 NIC 全过，无 [PANIC]）；userapps-matrix.ps1 系统行为全 PASS（dev_tests/help/pci 存活/Esc→cmd→desktop 链路/fileman boot/browser boot），唯一 FAIL 为 editor 断言陈旧——脚本仍期待 BUG-002 修复前的 "run: ELF 加载失败"，实测 `[editor] boot`→`[editor] exit` 正常（userapps-matrix-125211.log L5066-5067），该断言升级属测试脚本维护范畴，非系统回归。
+
+### BUG-20260801-007 [P1] [UTSM/pe] PE32 解释器 shim fn64 回退把 guest 指针当 host 指针：shim_printf 解引用 0x401017 → #PF → 三重故障
+- 现象: `pe HELLO32.EXE` 解释执行时串口止于 "[PE] running PE32 via x86emu32"，无 "Hello from PE32!"，guest 三重故障，QEMU（-no-reboot）静默退出。TCG 与 WHPX 表现一致。
+- 复现步骤: x86emu32-coverage.ps1（AUTOEXEC `pe HELLO32.EXE`）→ 会话在 "[PE] running PE32 via x86emu32" 后立即退出。
+- 串口/日志证据: `.build_tmp/tests/x86emu32-tcg-134351.log` 尾部止于 "[PE] running PE32 via x86emu32"；此前 QEMU `-d int` 捕获 v=0e（#PF）RIP 落在 shim_printf 函数体内（utsm.elf 反汇编确认），无 "[PE32] emulator error"——**解释器本身无差错，故障在 host 侧 shim**。
+- 根因分析（静态全链定案）:
+  1. pe_shim.c shim 表条目第 4 初始化元全为 0（如 `{"msvcrt.dll","printf",(void*)shim_printf,0}` 只设 fn64）→ **全表 fn32=NULL，pe_shim.h 设计的 fn32 列（"从模拟栈读参数调用 fn32"）整体缺失**。
+  2. x86emu32.c try_iat_call() 拦截 CALL IAT（合成地址 0x0001xxxx）后 fn32 为空 → 走 fn64 回退 `f(a0,a1,a2,a3)`，a0..a3 是从模拟栈读出的**原始 32 位 guest 值**：hello32 的 `push 0x401017`（msg guest VA = image_base 0x400000 + 0x1017）→ a0=0x401017。
+  3. shim_printf（pe_shim.c L219）`const char *f = (const char *)fmt;` 把 guest VA 直接当 host 指针解引用，**无 guest→host 转换**（解释器映像驻留在 emu->mem 大缓冲区，正确地址应为 emu->mem + 0x401017）→ host 低地址 0x401017 未映射 → #PF → BUG-20260801-005 放大为三重故障。
+  拦截前链路均正确：0x68 push imm32、FF /2 `call [disp32]` ModRM 解码、read_rm32 读 IAT 合成地址、try_iat_call 参数读取——解释器覆盖率不记倒退。
+- 修复方案（系统侧，本轮测试任务约束不改系统代码，仅登记）: ①为每个含指针参数的 shim 实现 fn32（接收 esp_ptr=&emu->mem[esp]，guest VA 经 emu->mem 基址转换为 host 指针）；②或 fn64 回退前设置全局 g_emu_mem_base，shim 内对 <0x10000000 的指针统一加基址转换；③kernel32 WriteFile/ReadFile 等指针参数函数同理。
+- 状态: [OPEN]
+- 修复提交: 待提交
+- 验证: 修复后 x86emu32-coverage.ps1 应见 "Hello from PE32!" → "[cmd] PE run end" → "[DSK] cmd.elf returned"；pe-compat.ps1 会话 B 同步验证（两处均已留自动升级断言：日志出现即升 PASS）。
+
+### BUG-20260801-006 [P1] [UTSM/pe] pe_shim setjmp/longjmp 跨已返回函数 UB：longjmp 恢复脏栈寄存器 → 野指针 call → 三重故障
+- 现象: `pe HELLO64.EXE` 原生执行成功打印 "Hello from PE32+!"（BUG-004 修复后），随后在 ExitProcess 阶段 guest 三重故障，QEMU（-no-reboot）静默退出；后续 AUTOEXEC 命令（HELLO32/NONEXIST/exit）全部不再执行。TCG 与 WHPX 表现一致。
+- 复现步骤: pe-compat.ps1（AUTOEXEC `pe HELLO64.EXE`）→ 串口止于 "Hello from PE32+!"。
+- 串口/日志证据: QEMU `-d int` 追踪（`.build_tmp/tests/pe-int-dbg.log`）：
+  `v=0e e=0003 IP=0028:ffffffff80014796 SP=0030:ffffffff80003030 CR2=ffffffff80003028`（**写保护违例**，非缺页）→ 投递 #PF 即 #GP（BUG-005 放大）→ v=08 → Triple fault。
+  现场寄存器：R12=0x6666666666667830("0xfffffff")、R13=0x3033326530386666("ff80e230")——正是 log_hex64("[PE] stack_top=",0xffffffff80e23000) 格式化缓冲区 ASCII 残片；R14/R15/RBP 均为脏值。
+  反汇编定案（utsm.elf）：fault RIP `pe_service_run+0x226` = `call *%r15`（pe_call_on_stack 内联汇编调 PE 入口那条）；但 R15=0xffffffff8055b260 并非 PE 入口 0xffffffff80d22000、RSP=0xffffffff80003030 并非 PE 栈顶 0xffffffff80e23000——**这是 longjmp 用脏栈"恢复"出来的假现场**，不是正常调用路径。
+  pe_shim_setup_exit（0xffffffff80014d60）反汇编：clang 把 __builtin_setjmp 实现为 `g_exit_jmp={RBP,RSP,resume=0x80014d94}`，恢复后从 0x80014d94 起执行函数尾声 `pop rbx;pop r12;pop r13;pop r14;pop r15;pop rbp;ret`——**从恢复的栈上弹 7 个槽**。
+- 根因分析: pe_shim_setup_exit() 内调 __builtin_setjmp 后**即返回**（C 标准：含 setjmp 的函数已返回时再 longjmp 为未定义行为）。setjmp→longjmp 之间 pe_service_run 又调用 log_hex64×2（"[PE] entry="/"[PE] stack_top="），其栈帧**精确复用** pe_shim_setup_exit 尾声要弹的那片栈区 → longjmp 尾声 pop 出的 rbx/r12-r15/rbp 全是 log_hex64 帧残片（R12/R13 即十六进制字符串残片），最后 `ret` 弹到 [X-8] 槽位的残留返回地址 0x8001478c（log_hex64 调用点返回地址）→ 落到 pe_call_on_stack 内联汇编正中间（`mov %rsp,g_pe_saved_rsp; mov %r14,%rsp; call *%r15`）→ 以脏 R14 为栈、脏 R15 为入口野调用 → 写返回地址到只读页 0xffffffff80003028 → #PF(保护违例) → BUG-005 放大为三重故障。PE32 解释器路径同一 setjmp/longjmp 机制，同样暴露在 UB 下（只是中间无 log 调用、脏数据不同，崩溃形态可能不同）。
+- 修复方案（系统侧，本轮测试任务约束不改系统代码，仅登记）: ①把 setjmp 下沉到 pe_service_run 本体内（含 PE 调用全程存活的作用域），不要用"setjmp 包装函数"；②或弃用 __builtin_setjmp/longjmp，改用显式上下文保存结构（保存 callee-saved + RSP/RIP 到 pe_service_run 帧内，ExitProcess 经受控 trampoline 返航）；③PE32 路径同理。
+- 状态: [OPEN]
+- 修复提交: 待提交
+- 验证: 修复后 pe-compat.ps1 应见 "[PE] ExitProcess code=" → "[cmd] PE run end" → "[DSK] cmd.elf returned" 完整链路；x86emu32-coverage.ps1 动态链路同步验证。
+
+### BUG-20260801-004 [P1] [tools/pe-samples] gen_pe.py PE32+ 二进制双重构造缺陷 → 原生执行三重故障
+- 现象: `pe HELLO64.EXE` 原生执行时 guest 直接三重故障，QEMU（-no-reboot）进程退出；串口最后一行为 `[PE] stack_top=...`，无 "Hello from PE32+!"。WHPX 下表现为 "Unexpected VP exit code 4"，TCG 下同样退出（此前误判为 WHPX 平台限制）。
+- 复现步骤: pe-compat.ps1（AUTOEXEC `pe HELLO64.EXE`）→ 会话在 `[PE] running PE32+ natively` 后退出。
+- 串口/日志证据: QEMU `-d int,cpu_reset` 追踪（`.build_tmp/pe-dbg-qemu.log` 尾部）：`v=0e e=0010 IP=0028:...0300 CR2=0x300`（在 0x300 取指缺页）→ 投递 #PF 时 #GP → `v=08` → Triple fault。RIP=0x300 正是未被 shim 修补的 IAT[0] 原始值（printf 名称 RVA）。
+- 根因分析（双重缺陷，均属 gen_pe.py 构造错误）:
+  1. **call disp32 写错偏移**：call 指令位于 code[7..12]（FF 15 + disp32），disp32 应写偏移 9，实际写偏移 10 → disp 左移一字节变为 0x1F300，同时覆盖下一条指令首字节。
+  2. **import 区 RVA 全部缺 +0x1000（code_rva）偏置**（修复①后仍失败的真正主因）：build_pe32_plus/build_cmd_exe 中 printf_name/exitproc_name/msvcrt/kernel32/import_desc 写成裸缓冲区偏移 0x300/0x320/0x350/0x360/0x400 → 数据目录 Import RVA=0x400 落在 headers 区 → rva_to_offset 返回 0xFFFFFFFF → resolve_imports 静默返回 → IAT 永不被 shim 修补 → `call [rip+0x1F3]` 跳到 0x300 → #PF → 三重故障。build_pe32 一直是正确的（0x1300 等带偏置），PE32+ 两个 builder 抄错。
+  3. 放大器（系统侧，另立 BUG-20260801-005）：DSK 阶段任何 CPU 异常都无法投递，直接三重故障重启，串口零诊断。
+- 修复方案: ①两处 disp32 pack_into 偏移 10→9；②build_pe32_plus/build_cmd_exe 的 name/DLL/import_desc RVA 全部加 code_rva 偏置（0x1300/0x1320/0x1350/0x1360/0x1400），IAT thunk 同步修正；③重新生成 hello64.exe/hello32.exe/cmd.exe 并同步 SYSTEM/bin/。
+- 状态: [FIXED]
+- 修复提交: 工作区已修复（CODE/tools/pe-samples/gen_pe.py build_pe32_plus/build_cmd_exe）
+- 验证: hello64.exe 静态校验全绿——.text `call [rip+0x1F3]`→IAT 0x1200、ImportDir RVA=0x1400、desc0/desc1 OFT/FT=0x1200/0x1210、Name=0x1350/0x1360、IAT thunk=0x1300/0x1320；pe-compat.ps1 复测。
+
+### BUG-20260801-005 [P1] [UTSM/IDT] DSK 阶段 CPU 异常无法投递：#PF 投递即 #GP → 三重故障重启，串口零诊断
+- 现象: DSK/cmd/PE 阶段一旦发生 #PF/#GP 等异常，guest 立即三重故障，QEMU（-no-reboot）静默退出，串口无任何异常信息（无向量号/RIP/CR2）。
+- 复现步骤: 运行含缺陷的 HELLO64.EXE（BUG-004，call 到未映射地址 0x300）→ QEMU 直接退出；或任何 DSK 阶段空指针解引用。
+- 串口/日志证据: QEMU `-d int` 追踪（`.build_tmp/pe-dbg-qemu.log`）：`check_exception old: 0xffffffff new 0xe`（#PF at RIP=0x300, CR2=0x300, RSP=0xffffffff80e22ff0 栈有效）→ `old: 0xe new: 0xd`（**投递 #PF 时即 #GP**）→ `old: 0x8 new 0xd`（投递 DF 时再 #GP）→ Triple fault。现场：IDT=ffffffff8002b000 lim=0xfff，GDT=ffff80007fe3d000 lim=0x47，CS=0028/SS=0030，TR=0038 且 TSS base=0。
+- 根因分析: BUG-20260729-013 的 `idt_halt_all()` 把 256 个 IDT 条目换成 halt stub，意图 cli;hlt 安全停机；但实测异常**投递本身**就 #GP——halt 门描述符的选择子/IST 与 DSK 阶段 GDT/TSS（TSS base=0）不匹配，异常帧无法压栈。净效果：DSK 阶段是无异常容错的裸奔环境，任何 guest bug 都表现为"QEMU 静默退出"，测试侧只能开 `-d int` 才能定位。
+- 修复方案（系统侧，本轮测试任务约束不改系统代码，仅登记）: ① halt IDT 门用 DSK 阶段 GDT 内有效选择子重建、IST=0；② 或 DSK 入口自建最小 IDT（#PF/#GP/#DF 打印向量+CR2+RIP 后 cli;hlt）；③ 恢复 TSS 有效基址。
+- 状态: [OPEN]
+- 修复提交: 待提交
+- 验证: 修复后重跑含缺陷 PE：串口应输出异常诊断而非 QEMU 静默退出。
+
+### BUG-20260801-003 [P1] [tools/desktop_app.h] da_mouse_poll 吞键盘扫描码导致应用键盘全灭
+- 现象: fileman/browser/editor（所有 #include desktop_app.h 的全屏应用）内键盘输入完全无效：Esc 无法退出、方向键/回车无响应；应用只能由宿主动作（关机/会话终止）结束。
+- 复现步骤: dev_mode shell → `run FILEMAN.ELF` → 启动后按 Esc → 无 `[fileman] exit`，应用永久停留。
+- 串口/日志证据: `.build_tmp/tests/userapps-matrix-021449.log`：`[fileman] boot` 后 3 次 Esc（每次等 20s）均无 `[fileman] exit`。
+- 根因分析: `da_mouse_poll()`（desktop_app.h L287-291）先 `inb(0x64)` 判有数据即 `inb(0x60)` 读走字节，再判 `st & 0x20` 发现是键盘字节直接 return 丢弃 → 键盘扫描码被鼠标轮询消耗。应用主循环每轮先调 da_mouse_poll 再轮询键盘 → 键盘字节永远到不了键盘分支。desktop/main.c 的 `ps2_mouse_poll()` 顺序正确（先判 0x20 再读 0x60），桌面不受影响；desktop_app.h 注释自称"与 desktop 保持一致"但实际不一致。
+- 修复方案: `da_mouse_poll()` 调整为：`(st & 1) && (st & 0x20)` 时才 `inb(0x60)`，与 desktop/main.c ps2_mouse_poll 对齐。
+- 状态: [FIXED]
+- 修复提交: 工作区已修复（CODE/tools/desktop_app.h da_mouse_poll：先判 AUX 位 st&0x20 再读 0x60）
+- 验证: QEMU 实测（`.build_tmp/w3b_s2_tools.log`）：editor 键盘输入与 Esc 退出正常（`[editor] boot`→`[editor] exit`→`[shell] run: tool returned`）；fileman 鼠标移动/点击选中/关闭按钮退出正常；运行中 fileman.elf 反汇编确认键盘字节（st&0x20==0）不再被鼠标轮询消耗。注：fileman/browser 键盘在修复后仍全灭，深挖定位为另一独立根因——da_mouse_init 配置字污染（BUG-20260801-008），该条目修复后 `[fileman] exit`/`[browser] exit` 断言方可完全恢复。
+
+### BUG-20260801-002 [P1] [shell] g_run_image 仅 256KB，editor.elf（496KB 内存镜像）run 拒绝加载
+- 现象: dev_mode shell 中 `run EDITOR.ELF` 输出 "run: ELF 加载失败（无效格式或过大）"，编辑器无法从 shell 启动（桌面宿主 g_elf_image=1MB，可正常启动）。
+- 复现步骤: dev_mode shell → `run EDITOR.ELF`。
+- 串口/日志证据: `.build_tmp/tests/userapps-matrix-021449.log` L4821/5167/5513 "run: ELF 加载失败（无效格式或过大）" ×3。
+- 根因分析: shell `g_run_image[262144]`（256KB）上限；editor.elf 文件 43KB 但 BSS NOBITS 内存镜像 496KB（编辑器大文本缓冲）→ `sh_load_elf` 返回 -5。其余工具内存镜像均在限内：fileman 208KB / browser 116KB / ping 128KB / curl 200KB。
+- 修复方案: `g_run_image` 扩至 1MB（与 desktop g_elf_image 对齐），或改为按 ELF memsz 动态划分。
+- 状态: [FIXED]
+- 修复提交: 工作区已修复（CODE/shell/main.c g_run_image 262144→1048576，与 desktop 宿主 g_elf_image 对齐）
+- 验证: QEMU dev_mode shell 实测（`.build_tmp/w3b_s2_tools.log` L4732-4735）：`run EDITOR.ELF` → `[shell] run: jumping to tool` → `[editor] boot` → `[editor] exit` → `[shell] run: tool returned`，editor.elf 496KB 内存镜像成功载入 1MB 缓冲并运行、退出；userapps-matrix.ps1 的 `[editor] boot` 断言应可升级。
+
+### BUG-20260801-001 [P1] [shell] 扫描码 0x15/0x17/0x0B 被误当 Ctrl+U/W/K，字母 y/i/0 无法输入
+- 现象: shell 交互输入中字母 i、y、数字 0 被吞：`id` 变 "d"、`ping` 变 "ng"、`whoami`/`exit`/`editor` 等含 i 命令均无法键入；串口回显 "未知命令: d" / "未知命令: ng"。
+- 复现步骤: dev_mode shell 提示符下键入 `id` 回车（QEMU monitor sendkey 或真实键盘均可复现）。
+- 串口/日志证据: `.build_tmp/tests/userapps-matrix-021449.log` L4431/4438/4445 "未知命令: d" ×3，L4460/4467/4474 "未知命令: ng" ×3。
+- 根因分析: shell 主循环（CODE/shell/main.c L3399-3401）将扫描码 0x15(y)/0x17(i)/0x0B(0) 直接映射为 Ctrl+U(kill_line)/Ctrl+W(删整行)/Ctrl+K(kill_to_end) 快捷键，但 shell 未跟踪 Ctrl 修饰键状态，也无 Ctrl 按下判定 → 普通按键被当作快捷键吞掉。`ping` 的 p 插入后 i 触发"删整行"→ 剩 "ng"。
+- 修复方案: 增加 Ctrl 修饰键跟踪（0x1D/0x9D 左右 Ctrl），仅在 Ctrl 按下时启用 0x15/0x17/0x0B 快捷键分支。
+- 状态: [FIXED]
+- 修复提交: 工作区已修复（CODE/shell/main.c：新增 ctrl 变量跟踪 0x1D 按下/0x9D 释放，0x15/0x17/0x0B 快捷键分支加 && ctrl 条件）
+- 验证: QEMU dev_mode shell monitor sendkey 实测（`.build_tmp/w3b_s1_shell.log`）：`id` → 输出 `uid=0(root) gid=0(root)`（L4405，i 不再被吞）；吞键对照测试 `y0i ok` 完整回显（L4407，y/0/i 三键全通，修复前分别触发 Ctrl+U/W/K 被吞）；`ping` → `[ping] boot`（L5214，i 不再被吞）。Ctrl+U/W/K 快捷键逻辑保留，仅在按住 Ctrl 时生效。userapps-matrix.ps1 的 id/whoami/ping MANUAL 断言可升级。
+
 ### BUG-20260729-021 [P2] [DSK/kernel_api] 硬偏移读取 kernel_api.block 脆弱性
 - 现象: DSK 通过 `*(u64*)(api + 0xA8)` 硬偏移读取 `dkm_kernel_api.block`，若结构体在 `block` 字段前插入新字段，DSK 将读取到错误指针 → 解引用 → 立即崩溃，无日志。
 - 复现步骤: 修改 dkm.h 中 `dkm_kernel_api` 在 `block` 字段前增加任意字段 → 编译 DSK（不重新编译）→ 启动。
@@ -25,14 +25,57 @@

 ## 自动化执行

-```powershell
-# 运行全部自动化测试场景
-.\ISO\run_tests.bat
+PowerShell 5.1 测试套件位于 [tests/qemu/](../../../tests/qemu/)，每份矩阵文档的"自动化脚本"小节
+列出对应用例脚本与参数。总运行器顺序执行全部 9 个用例并汇总：

-# 输出
-# ISO/logs/test-report-<timestamp>.md
+```powershell
+# 全量（先构建镜像再跑 9 用例）
+.\tests\qemu\Run-All.ps1 -Build
+
+# 复用现有镜像全量跑
+.\tests\qemu\Run-All.ps1
+
+# 只跑指定用例（逗号分隔，大小写不敏感）
+.\tests\qemu\Run-All.ps1 -Only network-e2e,x86emu32-coverage
 ```

+| 用例脚本 | 对应文档 | 说明 |
+|---|---|---|
+| boot-regression.ps1 | [boot-regression.md](boot-regression.md) | B1~B5 启动场景（-Scenarios 过滤） |
+| driver-matrix.ps1 | [driver-matrix.md](driver-matrix.md) | 16 清单驱动加载矩阵 + NVMe 写路径 |
+| linux-compat.ps1 | [linux-compat.md](linux-compat.md) | VMM 分流（-Cpu max 走路径 A） |
+| pe-compat.ps1 | [pe-compat.md](pe-compat.md) | PE32+ 原生 + PE32 x86emu32 |
+| deaicup-e2e.ps1 | [pe-compat.md](pe-compat.md) | Deaicup GUI PE 端到端（首帧像素/键鼠消息/Esc 退出链） |
+| userapps-matrix.ps1 | [userapps-matrix.md](userapps-matrix.md) | shell dev_tests + id/ping/editor/fileman/browser 全交互（sendkey 驱动 + Esc 退出链） |
+| network-e2e.ps1 | [network-e2e.md](network-e2e.md) | N-A netman / N-B curl（-Scenarios NA,NB） |
+| performance-baseline.ps1 | [performance-baseline.md](performance-baseline.md) | 启动阶段墙上计时（-Runs N） |
+| x86emu32-coverage.ps1 | [x86emu32-coverage.md](x86emu32-coverage.md) | 静态枚举 + hello32 动态执行 + shim/返回链硬断言（末锚点被 cmd AUTOEXEC 缓冲别名系统 bug 阻塞，见文档） |
+
+公共库 [tests/qemu/lib/QemuTest.ps1](../../../tests/qemu/lib/QemuTest.ps1) 提供 QEMU 会话管理、
+串口日志断言（必须/禁止/顺序/计数）、monitor sendkey/screendump、firstInit/AUTOEXEC 场景
+备份-替换-恢复、极简 HTTP 测试服务器。所有 QEMU 启动带 `-snapshot`（镜像只读，避免写锁与并发冲突；
+可用 `-NoSnapshot` 关闭），monitor 端口按用例固定分配（boot-regression=45501、
+driver-matrix=45502、linux-compat=45503、pe-compat=45504、deaicup-e2e=45454、
+userapps-matrix=45505、network-e2e=45506、performance-baseline=45507、x86emu32-coverage=45508；
+被占用时段内自动退让，兜底 45509-45599），避开人工调试 4444 与其他套件 456xx/457xx。清理策略只杀本套件 `-name deshabtest-` 标记的会话，
+绝不全局杀 QEMU（并发代理/人工调试不受影响）。
+
+并发隔离（套件可与其他代理/人工的 QEMU+build 并发运行）：
+
+- QEMU 只挂私有镜像副本：deshab/nvme/usb 镜像在 `Initialize-QemuTest` 时复制到
+  `.build_tmp\tests\img\`（share-tolerant 读取 + 60s 重试；mtime+size 未变则跳过）；
+- 场景翻转（firstInit.txt / AUTOEXEC.BAT）只写 `.build_tmp\tests\SYSTEM\` 镜像树
+  （robocopy /MIR 自共享 SYSTEM 同步），SATA 镜像由 `.build_tmp\tests\fat32gen\` 下的
+  mkfat32.ps1 副本生成到私有路径——共享 SYSTEM 树与 `.build_tmp\sata_fat32_dsk.img`
+  全程不被套件读写；
+- 会话早夭自愈：WHPX 分区强杀后偶发重建异常（guest 启动即三重故障，日志仅一行
+  `Ignoring request for interrupt vector 0`），启动 3s 内死亡且日志 <4KB 时自动重开一次。
+
+临时文件与日志输出到 `.build_tmp\tests\`（Run-All 汇总日志在 `.build_tmp\tests\runall\`，
+性能基线 JSON 在 `.build_tmp\perf_baseline.json`）。每用例独立子进程 + 场景恢复，幂等可重复执行。
+
+退出码约定：用例全部 PASS → 0；任一 FAIL → 1。MANUAL/SKIP 项不影响退出码。
+
 ## Bug 跟踪

 所有测试发现的 bug 登记到 [../Bug记录.txt](../Bug记录.txt)，并在对应测试文档中引用 bug 编号。
@@ -63,6 +63,26 @@ stage 3 (optional): e1000 → virtio_net → ath9k → ps2kbd
 -device virtio-net-pci,netdev=net0 ^
 ```

+## 自动化脚本
+
+[tests/qemu/driver-matrix.ps1](../../../tests/qemu/driver-matrix.ps1) 单次 QEMU 会话挂全设备
+（SATA 测试盘 + NVMe 测试盘 + xHCI USB 盘 + e1000），断言 4 个 stage 共 16 个清单驱动的
+加载顺序与功能锚点：
+
+```powershell
+.\tests\qemu\driver-matrix.ps1            # 复用现有镜像
+.\tests\qemu\driver-matrix.ps1 -Build     # 先全量构建再测
+```
+
+自动断言内容：
+
+- 16 个 `driver ready` 锚点按 manifest 顺序（ath9k 走 FUCK 禁用路径，断言 `[DSM] driver disabled by FUCK`）
+- 功能锚点：ahci/nvme block provider 注册、fat32 经块设备解析镜像、e1000 netdev+link、ps2kbd IRQ1、virtio_net 无设备降级
+- NVMe 写路径回归：LBA0 签名识别 → write+flush+readback 逐字节校验（PRP2 + PRP list 两趟）→ 签名完好，且 ahci0=0 → nvme0=1 注册顺序
+- `[DKM] external driver active` ≥ 15、`[DSM] stage end` × 4
+
+已知限制（与上方一致）：virtio_net 在 e1000-only 拓扑断言降级锚点；xhci USB MSC 枚举仅断言驱动就绪。
+
 ## 已知限制

 - NVMe BAR0 在 QEMU 中常位于 4G 以上，当前 HHDM 不能安全访问，需 Phase 0 高位 MMIO 映射解决
@@ -38,6 +38,23 @@
 | exec daemon 先发 EXEC_READY 再 HLT | daemon 源码 [utsm_exec_daemon.c](../../CODE/linux/initramfs/bin/utsm_exec_daemon.c) | ⬜ |
 | UTSM hypercall ABI: RAX=magic\|op | 检查 [hypercall.c](../../CODE/UTSM/vmm/hypercall.c) 处理 | ⬜ |

+## 自动化脚本
+
+[tests/qemu/linux-compat.ps1](../../../tests/qemu/linux-compat.ps1) 动态检测 VMM 可用性，自动分流：
+
+```powershell
+.\tests\qemu\linux-compat.ps1              # QEMU WHPX：走路径 B（VMM unavailable 优雅降级）
+.\tests\qemu\linux-compat.ps1 -Cpu max     # 真机/KVM nested VMX：走路径 A（完整双内核流程）
+```
+
+- **路径 A**（guest VMX 可用）：按序断言 A5.1~A5.7 启动链锚点
+  （VMM init → self-test → bzImage → IPC shm → vmlaunch → `Linux version` → daemon park →
+  `[LNXC] service ready` → DSK），随后经 monitor 按键执行 `dsl` / `dsl ls` / `dsl uname -a` /
+  `dsl nosuchprog` 覆盖 A5.8~A5.12。
+- **路径 B**（QEMU WHPX/TCG 无 nested VMX，本环境预期）：断言 `[UTSM] VMM unavailable` 后
+  DSK 正常接管、dev_tests 完成、`dsl` 报告运行态不可用、Esc 到 desktop；
+  A5.1~A5.12 标记 SKIP（环境限制，非产品缺陷）。
+
 ## 已知限制

 - QEMU TCG 不支持 VMX，必须 WHPX 或真机
@@ -55,6 +55,28 @@
 - curl 64KB 页面接收无明显停顿
 - DHCP 总耗时 < 5s

+## 自动化脚本
+
+[tests/qemu/network-e2e.ps1](../../../tests/qemu/network-e2e.ps1) 分两个场景：
+
+```powershell
+.\tests\qemu\network-e2e.ps1                  # N-A + N-B 全跑
+.\tests\qemu\network-e2e.ps1 -Scenarios NA    # 只跑 netman 全链路
+.\tests\qemu\network-e2e.ps1 -Scenarios NB    # 只跑 curl 主机侧端到端
+```
+
+- **场景 N-A**（netman 全链路，首启调度，覆盖 N1~N5）：firstInit=`0\n0`，挂 e1000(net0) +
+  virtio-net(net1) 双网卡。断言 virtio_net selftest（真实 slirp DHCP OFFER）→
+  netman 双设备枚举 → DHCP DISCOVER/OFFER/REQUEST/ACK → ARP 网关解析 → DNS example.com →
+  `network final rc=0x0000000000000000`，并禁止 `no OFFER / ARP timeout / DNS timeout / [PANIC]`。
+- **场景 N-B**（curl.elf 主机侧端到端，覆盖 N8/N10）：dev_mode shell → 交互 `curl` →
+  输入 `http://10.0.2.2:8000/`。脚本在主机 127.0.0.1:8000 起极简 HTTP 服务器
+  （QemuTest.ps1 `Start-TestHttpServer`），断言主机侧收到 `GET / HTTP/1.0`
+  （TCP+IP+ETH 全链路最强证据），guest 侧断言 `[curl] boot/exit` 与 shell 回收。
+  HTTP 响应体渲染仅帧缓冲，标 MANUAL。
+- N6/N11（ping 链路）由 [userapps-matrix.ps1](../../../tests/qemu/userapps-matrix.ps1) 交互阶段覆盖；
+  N7/N9（外网）依赖主机联网，不在自动化断言范围。
+
 ## 已知限制

 - HTTPS/TLS 不支持（curl 仅 http）
@@ -65,6 +65,58 @@ int main(void) {

 若无 MinGW/MSVC，使用 [CODE/tools/pe-samples/gen_pe.py](../../CODE/tools/pe-samples/gen_pe.py) 生成最小 PE 程序。

+## 自动化脚本
+
+[tests/qemu/pe-compat.ps1](../../../tests/qemu/pe-compat.ps1) 正常启动到 cmd.elf，
+AUTOEXEC.BAT 自动执行 PE 命令序列：
+
+```powershell
+.\tests\qemu\pe-compat.ps1            # 复用现有镜像
+.\tests\qemu\pe-compat.ps1 -Build     # 先全量构建再测
+```
+
+因两个已登记系统 bug（[Bug记录.txt](../Bug记录.txt) BUG-20260801-006/007），脚本拆三个独立会话：
+
+- **会话 A (pe64)**：B2.1 `pe HELLO64.EXE` → `[PE] PE32+ (64-bit)` →
+  `[PE] running PE32+ natively` → `Hello from PE32+!`（自动断言 PASS）。
+  随后的 ExitProcess 触发 BUG-006（setjmp/longjmp UB → 三重故障），会话终止；
+  `[cmd] PE run end` 返回链标 MANUAL，日志出现即自动升级 PASS。
+- **会话 B (pe32)**：B2.2 `pe HELLO32.EXE` → `[PE] running PE32 via x86emu32`
+  解释器接管（自动断言 PASS，且无 emulator error / unimplemented）。
+  首个 shim 调用 printf 触发 BUG-007（fn64 回退 guest 指针当 host 指针），
+  会话终止；`Hello from PE32!` 标 MANUAL，出现即自动升级 PASS。
+- **会话 C (peerr)**：B2.4 `pe NONEXIST.EXE` 错误路径（不产生 `[cmd] PE run begin`）
+  + `exit` 正常返回 DSK（`[DSK] cmd.elf returned`，自动断言 PASS）。
+
+WHPX 下任一会话未命中锚点自动以 `-Accel tcg` 重跑（可 `-Accel tcg` 直接指定）。
+禁止锚点：`[PANIC]` / `[PE32] emulator error` / `[PE] unimplemented import`。
+
+B2.3/B2.7（peinfo）与 B2.5（无参用法提示）仅写帧缓冲（cmd 非 dev_mode 无串口镜像），标 MANUAL。
+PE32 解释器指令级覆盖率另见 [x86emu32-coverage.ps1](../../../tests/qemu/x86emu32-coverage.ps1)。
+
+### GUI 应用端到端：deaicup-e2e.ps1
+
+[tests/qemu/deaicup-e2e.ps1](../../../tests/qemu/deaicup-e2e.ps1) 验证 Deaicup
+（Rust/egui 移植的原始 Win32 API PE64 GUI 应用）端到端：AUTOEXEC `pe DEAICUP.EXE` 启动后
+经 monitor 驱动键鼠并断言串口锚点 + screendump 像素：
+
+- **9 锚点顺序链**：`[cmd] cmdline: DEAICUP.EXE` → `[PE] running PE32+ natively` →
+  `[deaicup] mainCRTStartup` → `[shim] RegisterClassExW ok` → `[shim] CreateWindowExW ok` →
+  `[shim] CreateDIBSection ok` → `[dc] Context::default ok` →
+  `[shim] BitBlt first frame on screen` → `[dc] bitblt ok`
+- **首帧像素分析**：非全黑（nonBlack≥100000）、颜色种数 ≥32、GUI 窗口矩形检测
+  （窗口主体色 #1B1B1B 行扫描实心段 → 800x508 包围盒、填充率 ≥75%）
+- **鼠标**：AUX 初始化 + mouse_move → `[shim] mpkt`（WM_MOUSEMOVE）、
+  mouse_button → `[shim] LDOWN/LUP` 边沿（WM_LBUTTONDOWN/UP）、
+  两次 screendump 光标区像素差异（8..60000 采样点）
+- **键盘**：sendkey → `[shim] KEYDOWN/CHAR/KEYUP`（WM_KEYDOWN/WM_CHAR/WM_KEYUP）
+- **退出链**：Esc → WM_CLOSE → `[deaicup] quit, ExitProcess(0)` →
+  `[PE] ExitProcess code=` → `[cmd] PE run end`（回归 BUG-006 长运行返回链、BUG-005 异常噪声）
+- 禁止锚点：`[PANIC]` / `[IDT] exception` / `Unimplemented handler`
+
+WHPX 未命中首帧锚点自动以 `-Accel tcg` 重跑（可 `-Accel tcg` 直接指定）；monitor 固定 45454。
+证据帧输出 `.build_tmp/tests/deaicup-frame.png`。
+
 ## 已知限制

 - pe_shim 实现的 Win32 API 子集有限，测试程序仅使用 WriteFile + ExitProcess
@@ -81,6 +81,32 @@ foreach ($m in $curr.metrics) {
 }
 ```

+## 自动化脚本
+
+[tests/qemu/performance-baseline.ps1](../../../tests/qemu/performance-baseline.ps1) 以主机墙上时钟
+轮询串口锚点，测量启动阶段耗时（正常启动 firstInit=`1\n0`，AUTOEXEC=ver/exit）：
+
+```powershell
+.\tests\qemu\performance-baseline.ps1            # 默认 3 轮取中位数
+.\tests\qemu\performance-baseline.ps1 -Runs 5    # 自定义轮数
+```
+
+测量锚点与阶段换算：
+
+| 阶段 | 起 → 止 | 对应指标 |
+|---|---|---|
+| ovmf_bootloader_ms | QEMU 进程启动 → `[UTSM] boot` | OVMF + Limine |
+| utsm_drivers_ms | `[UTSM] boot` → `[UTSM] SELFTEST PASS` | P1（UTSM+16 驱动装载） |
+| selftest_to_dsk_ms | SELFTEST → `[DSK] boot` | DSK 加载（FAT32 read + PIE load） |
+| dsk_to_desktop_ms | `[DSK] boot` → `desktop ready` | DSK → 桌面就绪 |
+| total_boot_ms | QEMU 启动 → `desktop ready` | 端到端总启动 |
+
+结果写入 `.build_tmp\perf_baseline.json`（锚点绝对时刻 + 各轮数据 + 中位数 + 环境信息）。
+本脚本只测量展示、不做阈值断言；轮询精度 ±200ms，QEMU 数值仅作回归参考。
+
+未自动化项（需内核 TSC 打点日志，当前串口无锚点，保持 PENDING）：P2/P3/P6（单 ELF 加载计时）、
+P4 ping RTT、P5 linux RTT、P7 桌面帧率、P8~P11（PE/VMM/Linux）、P12 DHCP 耗时。
+
 ## 已知限制

 - QEMU 性能数据不等于真机，仅作回归参考
@@ -70,6 +70,40 @@ shell → run CURL.ELF → curl.elf
 | 窗口拖动 | 流畅，无撕裂 | ⬜ |
 | 任务栏点击 | 窗口切换 | ⬜ |

+## 自动化脚本
+
+[tests/qemu/userapps-matrix.ps1](../../../tests/qemu/userapps-matrix.ps1) dev_mode 单会话覆盖
+shell 内建命令与工具程序（dev_mode 串口镜像开启，全程可断言）：
+
+```powershell
+.\tests\qemu\userapps-matrix.ps1            # 复用现有镜像
+.\tests\qemu\userapps-matrix.ps1 -Build     # 先全量构建再测
+```
+
+自动断言（两阶段，单会话；2026-08-04 BUG-20260801-001/002/003/008 全部修复后，
+原 MANUAL 降级项已回收为自动化）：
+
+1. **dev_tests 硬编码序列**：`[DSK:SCHED] decision: dev_mode -> shell.elf` →
+   `[1] ls` → `[2] echo>` → `[3] cat` → `[4] cp` → `[6] mv` → `[8] rm` → `[10] ls`
+   → `=== 自动测试完成 ===`（SATA 镜像无 test.bas 时走 fallback 分支）。
+2. **交互阶段**（monitor sendkey 驱动）：`help` → `id`（断言 `uid=0(root) gid=0(root)`，
+   BUG-001 修复回归守护）→ `pci` 存活验证 →
+   `ping`（PATH 查找 `/bin/PING.ELF` → `[ping] boot`，输入 10.0.2.2 发四报文，
+   Esc → `[ping] exit` → `[shell] path: tool returned`）→
+   `run EDITOR.ELF`（`[editor] boot` → 按键插入 → Esc → `[editor] exit`，
+   BUG-002 修复后行为，原"超限优雅拒绝"断言已升级）→
+   `run FILEMAN.ELF`（`[fileman] boot` → 方向键选区移动 → Esc → `[fileman] exit`，
+   BUG-003/008 修复后键盘路径）→
+   `run BROWSER.ELF`（`[browser] boot` → Esc → `[browser] exit`）→
+   Esc 回 DSK → cmd(AUTOEXEC=ver/exit) → `desktop ready`。
+   锚点：`[shell] path: running /bin/ tool` / `[shell] path: tool returned` /
+   `[shell] run: jumping to tool` / `[shell] run: tool returned` /
+   `[ping|editor|fileman|browser] boot|exit`。
+
+标 MANUAL 项（帧缓冲限定，无串口锚点）：ping ICMP reply/RTT 与四报文统计、
+editor 编辑内容渲染与保存、fileman 列表渲染/进入子目录；
+FirstInit/login/desktop UI（双击/拖动/任务栏，boot-regression B1 已覆盖向导按键）。
+
 ## 已知问题

 - fileman.elf 之前触发过 QEMU 退出（访问未支持 boot context 字段），需观察是否复现
@@ -84,3 +84,36 @@
 ```

 目标：核心指令（MOV/ADD/SUB/CMP/JMP/CALL/RET/PUSH/POP）覆盖率 100%。
+
+## 自动化脚本
+
+[tests/qemu/x86emu32-coverage.ps1](../../../tests/qemu/x86emu32-coverage.ps1) 两层验证：
+
+```powershell
+.\tests\qemu\x86emu32-coverage.ps1            # 复用现有镜像
+.\tests\qemu\x86emu32-coverage.ps1 -Build     # 先全量构建再测
+```
+
+1. **静态枚举**（无需 QEMU）：解析 [x86emu32.c](../../CODE/UTSM/pe/x86emu32.c) 统计
+   `case 0xNN` 操作码分支数（覆盖率分母，含 0F 扩展页），并校验 hello32.exe 头
+   （machine=0x14C / optional magic=0x10B，确为 PE32 样本）。
+2. **动态执行**：正常启动 → cmd.elf，AUTOEXEC.BAT 执行 `pe HELLO32.EXE` + `exit`。
+   自动断言 `[PE] running PE32 via x86emu32` 解释器接管；禁止 `[PE32] emulator error` /
+   `[PE] unimplemented import` / `[PE] unimplemented API called` / `[PANIC]`。
+   注意 `[PE] PE32 (32-bit)` 仅 PE32+ 原生路径（pe_load_image）输出，解释器路径
+   （pe32_load_into）不打印该行，不可作锚点。
+
+   BUG-20260801-006/007 已修复（[Bug记录.txt](../Bug记录.txt)），原软升级项已转
+   硬断言（回归守护）：`Hello from PE32!`（shim IAT 拦截输出）与
+   `[cmd] PE run end` → `[DSK] cmd.elf returned`（完整返回链）。
+
+   已知系统侧阻塞（2026-08-04 monitor 取证定案）：末锚点 `[DSK] cmd.elf returned`
+   当前必缺失。根因不在 PE 层——cmd `run_autoexec` 的 `data`/`size` 直指共享静态
+   缓冲 `f32_data`（fat32_io.h），首行 `pe HELLO32.EXE` 加载 PE 文件即覆盖剩余
+   脚本，`exit` 行丢失，cmd 停留交互主循环轮询键盘（guest 存活、无异常投递、
+   无三重故障）。反证：pe-compat 会话 C（`pe NONEXIST.EXE` + `exit`，文件未找到
+   不覆盖缓冲）返回链正常。待 cmd 侧修复（脚本先拷入私有缓冲再逐行执行）后
+   末锚点自动转绿。
+
+指令级逐条覆盖（上方矩阵 test_arith/test_logic/test_control/test_string）依赖
+CODE/tools/pe-samples/ 下尚未构建的分类测试 PE，标 MANUAL。