Deaicup/Deshab-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5db517f4356a9bf0649d0d8a605217ca5fb2aad7
Deshab-OS/docs/上下文/260805/交接文档-多智能体推进收尾.md
T
xyou 8717ea8f20 docs: 多智能体推进收尾交接文档 + Bug记录/策划文档状态修正 
新增 docs/上下文/260805/交接文档-多智能体推进收尾.md：W2-W6 全程成果、W6 丢失项、Bug 状态核对、下一步优先级、环境坑点

Bug记录.txt: BUG-005/006/007 状态 OPEN->FIXED（代码已修于 a26866e，文档过时未同步）

系统开发策划.md: M2 进度更新（vector allocator/LAPIC EOI 标完成，MSI-X 标 NVMe完成/virtio_net待做，B7 阻塞点更新）
2026-08-05 14:08:11 +08:00

14 KiB
Raw Blame History

交接文档 — 多智能体推进收尾（2026-08-05）

接手者须知：本文档记录截至 2026-08-05 的工作全貌。此前通过多轮多智能体并发推进 W2→W6，主体成果已合并提交（commit a26866e + 019585f），但第六波（W6）三线成果全部丢失未入库，需重做。请先读"未完成工作"与"Bug 状态核对"两节。

一、项目方向与当前里程碑

Deshab OS：SAS-R0 单地址空间 Ring0 内核，UTSM 内置 PE 兼容层 + Linux 兼容层（VMX guest）。

当前里程碑：M2 — 存储升级 + 中断后端（docs/系统开发策划.md §4.4）。

本轮大方向：通过多智能体并发推进，把 M2 的阻塞点逐个清掉——NVMe 写路径、virtio_net 数据路径、B7 IRQ 后端（APIC/IOAPIC/MSI-X）、PE 兼容层缺陷、用户态输入缺陷、QEMU 测试套件脚本化。

二、已落地成果（commit a26866e + 019585f，已核实代码在库）

1. B7 IRQ 后端（APIC/IOAPIC）— stage1+2 完成

  • DKM apic.drv（CODE/DKM/apic/apic.c，+1025 行）：LAPIC 接管、MADT/ISO 解析、IOAPIC IOREDTBL 编程（82093AA 位布局已修正 bit13/15/16）、FUCK 开关 apic_route=0/1（0=PIC 零回归，1=IOAPIC→LAPIC 接管，失败完整降级）、apic_route_legacy 放开 IRQ1/12/11、apic_diag HPET 对拍。
  • UTSM LAPIC EOI 钩子（CODE/UTSM/arch/x86_64/idt.c + dkm.h 尾部追加 register_apic_eoi，ABI 兼容）：idt_handler 分发后调钩子写 LAPIC EOI，0xFF spurious 特判，PIC EOI 保留无害。DSK diag IDT（idt_install_dsk_diag）让 0-31 号异常打印完整现场后安全停机。
  • tick 链路验证：route=1 下 500ms 窗口 100 ticks（PIT mode3 双沿触发，定论为 200Hz，BUG-20260803-009 CLOSED，非缺陷）。
  • 生产配置：FUCK apic_route=1 已启用，boot-regression B1-B5 全 PASS（含 FirstInit 向导真实按键走 IOAPIC→LAPIC→IDT 链路）。

2. NVMe — 写路径 + MSI/MSI-X 中断驱动完成

  • 写路径 + PRP list 多页 + 读回校验自检（CODE/DKM/nvme/nvme.c）。
  • MSI/MSI-X 中断驱动化（commit 019585f）：vector allocator（bitmap+ctzll，0x40-0xDF 池，O(1)）、MSI-X 表项编程、完成槽+irqsave 自适应轮询混合模型、幽灵 CQE 三层 CID 校验防御（BUG-20260803-010 FIXED，QEMU 在 unmask 边界补投 CID=0 幽灵 CQE）、handler 自写 LAPIC EOI。FUCK nvme_msi=1 默认开，0 强制轮询。
  • 三配置回归全绿（MSI-X / route=0 PIC / nvme_msi=0 纯轮询），driver-matrix.ps1 PASS。

3. virtio_net — virtqueue RX/TX 完成（纯轮询，无 MSI-X）

  • legacy transitional 探测、feature negotiation、RXQ/TXQ 各 256 描述符、netdev 注册 index=1、boot 时 DHCP 自测（slirp 真实 OFFER）。
  • 数据路径纯轮询：rx_poll 轮询 used ring，TX 后同步等待。IRQ handler 已注册但未用于数据路径。
  • MSI-X 中断驱动化未完成（W6-B 丢失，见第三节）。

4. PE 兼容层 — 004/005/006/007 全部修复

  • BUG-004（gen_pe.py PE32+ RVA 偏置）：call disp32 偏移 + import RVA 全部加 code_rva 偏置，重新生成 hello64/hello32/cmd.exe。
  • BUG-005（DSK 阶段异常无法投递）：idt_install_dsk_diag 装配最小 IDT，#PF/#GP/#DF 打印向量+CR2+RIP+CS 后 cli;hlt。
  • BUG-006（pe_shim longjmp 跨已返回函数 UB）：setjmp 下沉到 pe_service_run 本体，g_exit_jmp[24] 缓冲区，pe_shim_setup_exit 只提供缓冲区（setjmp 帧在 PE 执行全程存活）。
  • BUG-007（shim fn32 guest 指针当 host 指针）：g_emu_mem_base + pe_shim_set_emu_base() + gp() 转换（va<0x10000000 加基址），原生路径恒等映射零影响。
  • Deaicup GUI 端到端验证通过（首帧渲染 + PS/2 键盘 + AUX 鼠标 + 软件光标 + Esc 退出链），raster.rs 重心坐标符号 bug 顺带修复。

5. 用户态输入/加载 — 001/002/003/008 全部修复

  • BUG-001（shell 吞 y/i/0）：Ctrl 修饰键跟踪（0x1D/0x9D），快捷键仅 Ctrl 按下时生效。
  • BUG-002（g_run_image 256KB）：扩至 1MB，editor.elf（496KB 内存镜像）可加载。
  • BUG-003（da_mouse_poll 吞键盘扫描码）：先判 AUX 位（st&0x20）再读 0x60。
  • BUG-008（da_mouse_init 配置字污染）：序列首尾 da_ps2_drain 冲刷残留，配置字补 0x40，复位读完 FA AA 00。

6. QEMU 测试套件 — 9 用例全自动化

tests/qemu/（commit a26866e 已入库，已核实存在）：

  • lib/QemuTest.ps1：公共框架（启动 QEMU/计时杀/串口断言/monitor TCP sendkey/screendump/HTTP 服务器/并发隔离端口分配）。
  • 9 用例：boot-regression / driver-matrix / linux-compat / pe-compat / deaicup-e2e / userapps-matrix / network-e2e / performance-baseline / x86emu32-coverage。
  • Run-All.ps1：汇总表 + 退出码。
  • W5-A 基线实跑 8/9 PASS（唯一 FAIL 是 cmd AUTOEXEC 缓冲别名，见 BUG-011）。
  • docs/RE/test-cases/ 8 份用例文档均补"自动化脚本"小节。

三、未完成工作（W6 三波成果全部丢失，需重做）

第六波并发三线（W6-A/B/C）的 subagent 报告完成，但改动未入库（工作区干净，代码核实无对应实现）。下个 agent 需重做。

W6-A：cmd AUTOEXEC 缓冲别名修复（BUG-011，P1）

  • 根因（已定位定案）：f32_read_root_file（CODE/tools/fat32_io.h）把文件读入共享静态缓冲 f32_data 并返回指针；run_autoexec（CODE/cmd/main.c L1232）跨 execute_command 持有该指针逐行执行；首行 pe HELLO32.EXE 加载 PE 文件覆盖缓冲中剩余 AUTOEXEC 脚本 → exit 行丢失 → cmd 落入交互主循环永远轮询键盘。
  • 影响：任何"读文件的 AUTOEXEC 命令 + 后续行"组合。历史上从无"真实 PE 执行后 [DSK] cmd.elf returned"。
  • 修法（W6-A 已设计未入库）：run_autoexec 先把脚本整体拷入私有缓冲 g_autoexec_snapshot[4096] 再逐行执行。CODE/cmd/main.c 当前 L1232 仍是原样，需重做。
  • 验证：修复后 x86emu32-coverage.ps1 末锚点 [DSK] cmd.elf returned 转绿（该用例硬断言已就位，W6-A 报告复跑 PASS 但成果丢失）。
  • 登记：Bug记录.txt 无 011 条目（W6-A 报告登记了但未入库），需补登。

W6-B：virtio_net MSI-X 中断驱动 RX/TX

  • 现状：virtio_net.c 有 virtqueue RX/TX（纯轮询），无 MSI-X 代码（Select-String 'msix|MSI-X' 无匹配）。
  • W6-B 设计（未入库）：legacy transitional + MSI-X 组合，三向量（cfg/RXQ/TXQ）编程，SPSC pending 环 IRQ 上下文收包，三级降级（MSI-X→INTx→轮询），FUCK vnet_msi=1 开关。参考 NVMe 的 nvme_msix_program 模式。
  • 需重做。QEMU 拓扑：e1000@net0 + virtio-net-pci@net1。

W6-C：用户态工具串口锚点增补 + 策划文档收尾

  • 现状：CODE/tools/editor.c / curl.c / ping.c / browser.c 无 [editor] saved / [curl] http status / [ping] reply / [browser] loaded 锚点（Select-String 无匹配）。
  • W6-C 设计（未入库）：为各工具补 1-3 个关键事件串口锚点，升级 userapps-matrix.ps1 / network-e2e.ps1 的 MANUAL 项为自动断言。
  • 需重做。

四、Bug 状态核对表（重要 — 文档与代码不符）

docs/RE/Bug记录.txt 中以下条目代码已修复并提交（a26866e）但状态仍标 [OPEN]，本次交接已修正为 [FIXED]。

Bug 登记状态 代码实际 本次处理
BUG-20260801-005 DSK 异常无法投递 [OPEN] ✅ idt_install_dsk_diag 已落地 改 [FIXED]
BUG-20260801-006 pe_shim longjmp UB [OPEN] ✅ g_exit_jmp 重构已落地 改 [FIXED]
BUG-20260801-007 shim fn32 guest 指针 [OPEN] ✅ g_emu_mem_base+gp() 已落地 改 [FIXED]
BUG-20260803-011 cmd AUTOEXEC 别名 未登记 ❌ 代码未入库 需补登 + 重做修复

其余已 FIXED 条目（001/002/003/004/008/010）状态正确。009 CLOSED（定论非缺陷）。

五、新出现的并行工作（8/5 下午，commit 6287513 + 4a62932）

这两批提交不是本轮多智能体推进的产物，是另一条线的工作，接手时注意区分：

  • Linux 预览后端（6287513）：CODE/tools/desktop_app_linux.h（跨平台后端抽象）、CODE/desktop/host_main.c/host_main.h（桌面宿主 Linux 预览）、ISO/run_desktop_host.sh、Notes 应用预览（CODE/tools/notes/，5x7 位图字体）。
  • PE DLL 管理器（4a62932）：CODE/UTSM/pe/pe_dll_manager.c/h（新模块，PE DLL 加载管理）。
  • FAT32 长文件名：CODE/tools/fat32_lfn.h。
  • 上下文目录重命名：docs/上下文/250729→260729、25072901→26072901（年份修正 25→26）。

接手者若推进这些方向，先读对应源码理解现状。

六、下一步优先级建议

优先级 任务 理由
P1 重做 W6-A：cmd AUTOEXEC 缓冲别名（BUG-011） 阻断 x86emu32-coverage 用例，影响所有 AUTOEXEC 多行场景；修法简单（私有快照缓冲）
P1 补登 BUG-011 条目 + 核对 Bug记录其余状态 文档与代码一致性
P2 重做 W6-B：virtio_net MSI-X NVMe MSI-X 已完成可参照；virtio_net 当前纯轮询，中断化收益明确
P2 M2 剩余：e1000 中断驱动收发（替代 polling） 策划 L134 仍空；e1000 走 legacy IRQ11 已通，MSI 切换成本低
P3 重做 W6-C：tools 串口锚点 + 测试断言升级 把 MANUAL 项回收为自动化
P3 M2 收尾：替换 arena 为真实页分配（L129）、DKM 工程化（ABI 头统一/零 warning，L136） 策划仍空
P3 真机冒烟：APIC/MSI-X 在真机验证（QEMU 无多 IOAPIC/非常规 GSI） W4-B/W5-B 均提遗留
P4 M3 兼容层验证推进（VMX 真机/KVM） B4 阻塞，需嵌套虚拟化环境

七、环境与协作约定（坑点合集，务必读完）

构建环境

  • Windows + PowerShell 5.1（不能用 &&/||/三元）。
  • make.exe 在 C:\mingw64\bin，clang/ld.lld 在 LLVM bin。
  • 全量构建：根目录 build.ps1。UTSM 编译：CODE/UTSM/MAKEFILE（-MMD -MP，零警告）。
  • 工具 MAKEFILE 普遍缺头文件依赖：改 desktop_app.h 等公共头不会触发工具重编，需手动删对应 .o。
  • 仓库内 .ps1 一律纯 ASCII：PS5.1 把无 BOM UTF-8 按 GBK 解码，CJK 注释第三字节（0x80-0xBF）被当 GBK lead byte 会吞掉紧跟换行符，把后续代码并进注释。编辑已有含 BOM 文件保留 BOM。

QEMU

  • ISO/run_qemu.bat（WHPX）。WHPX 在 PE 执行处会 VP exit 4，pe-compat/deaicup-e2e 已有 TCG 自动兜底。
  • -snapshot 必加（镜像只读，防 deshab.img 锁冲突，多代理并发必备）。
  • monitor TCP 端口分配：deaicup-e2e 固定 45454，测试套件 45501-45509，其他按需避让。
  • Start-Process 下 -serial file: 不生效（已知坑）：用临时 cmd 批处理 + -serial stdio 重定向到日志文件，计时按 PID 杀。
  • monitor screendump 路径必须正斜杠：反斜杠 \C 转义静默失败。
  • -d reset 非法（本版叫 cpu_reset）。
  • 并发时只杀自己启动的 QEMU（记 PID），绝不全局 Stop-Process qemu。

多智能体并发协议（若继续用多 agent）

  • 构建互斥：build.ps1 前检查 .build_tmp\BUILD.lock：存在且 30 分钟内则 Start-Sleep 15-30s 重试，不存在才创建（写名字+PID+时间），构建+打包完成立即删除。
  • 地盘划分：UTSM/DKM/desktop/cmd/tools/tests 分属不同 agent，不交叉改动。
  • subagent 改动落地风险：本轮 W6 三线 subagent 报告完成但改动未入库——接手者用 subagent 后务必核实改动是否落盘主仓库工作区（git status + Grep 代码），不能只信报告。建议关键修复由主会话直接 Edit/Write 落盘。

kernel_api ABI

  • 结构体 ABI 冻结：成员顺序/签名不可改，只允许尾部追加。本轮已追加 register_apic_eoi、irq_vector_alloc/free（dkm.h 尾部）。

八、关键文件索引

模块 关键文件
APIC/IOAPIC CODE/DKM/apic/apic.c、CODE/UTSM/arch/x86_64/idt.c（EOI 钩子+DSK diag+vector allocator）、CODE/UTSM/include/utsm/dkm.h（kernel_api 尾部追加）
NVMe CODE/DKM/nvme/nvme.c（写+MSI-X+CID 防御）、SYSTEM/system/deshab64/FUCK（nvme_msi 开关）
virtio_net CODE/DKM/virtio_net/virtio_net.c（virtqueue 轮询，无 MSI-X）
PE 兼容层 CODE/UTSM/pe/pe_shim.c（g_exit_jmp/g_emu_mem_base）、pe_service.c、pe_loader.c、CODE/UTSM/pe/pe_dll_manager.c（新）、CODE/tools/pe-samples/gen_pe.py
用户态 CODE/shell/main.c（Ctrl 跟踪+g_run_image 1MB）、CODE/cmd/main.c（run_autoexec 待修）、CODE/tools/desktop_app.h（da_mouse_init/poll）、CODE/tools/editor.c/curl.c/ping.c/browser.c（锚点待补）
测试套件 tests/qemu/Run-All.ps1、tests/qemu/lib/QemuTest.ps1、9 用例脚本
配置 SYSTEM/system/deshab64/FUCK（apic_route/nvme_msi/vnet_msi/dev_mode 等）
文档 docs/系统开发策划.md（M2 进度）、docs/RE/Bug记录.txt、docs/RE/test-cases/、docs/RE/桌面设计.md、LESSONS_LEARNED.md、CLAUDE.md

九、本轮提交时间线

commit 时间 内容
a26866e 8/4 18:08 大合并：B7 APIC stage1+2、NVMe 写+MSI-X、virtio_net virtqueue、PE 004-007、用户态 001-003/008、9 用例测试套件、文档
019585f 8/4 18:36 B7 阶段3：NVMe MSI-X 增强 + vector allocator + 幽灵 CQE 防御（BUG-010）
6287513 8/5 13:15 Linux 预览后端 + Notes 应用（并行工作，非本轮）
4a62932 8/5 13:58 PE DLL 管理器 + desktop host + fat32_lfn + 上下文目录重命名（并行工作）
Reference in New Issue View Git Blame Copy Permalink