【win备份还原工具开发日记】33:--json全命令、错误码体系、RE超时修复、路线四步结清、备份管理UI(v2.6.41→v
【win备份还原工具开发日记】33:–json全命令、错误码体系、RE超时修复、路线四步结清、备份管理UI(v2.6.41→v2.6.50)
对应文档(同日 13 篇):docs/20261025-0025-CLI-json扩展到全部命令与两处真bug-DeepSeek-V4.1-Flash.md、docs/20261025-0040-GUI语言偏好持久化与修本机构建缺陷-DeepSeek-V4.1-Flash.md、docs/20261025-0050-GUI切英文点击端到端打通-UIPI才是真正根因-DeepSeek-V4.1-Flash.md、docs/20261025-0110-日志全量多语言化与B6目录命名分叉-DeepSeek-V4.1-Flash.md、docs/20261025-0125-RE主链DISM超时形同虚设修复与降级实证-DeepSeek-V4.1-Flash.md、docs/20261025-0430-TaskError错误码体系与文案查表-DeepSeek-V4.1-Flash.md、docs/20261025-0505-下一步开发方向-Step-5-Preview.md、docs/20261025-0535-用户手册与步0清尾-ui-language与compress修复-Step-5-Preview.md、docs/20261025-0545-E2备份完整性盘点结论-捕获侧自检已齐不补码-Step-5-Preview.md、docs/20261025-0655-项目整体分析与下一步开发详细建议-Step-5-Preview.md、docs/20261025-0700-E3主备反转评估-DISM与wimlib实机对照结论不反转-Step-5-Preview.md、docs/20261025-0705-E4冒烟接入部署门禁与判据扩容-一键7过7-Step-5-Preview.md、docs/20261025-0740-P1c备份文件管理UI立项实现与全链路验收-Step-5-Preview.md
今天做了什么
CLI --json 扩展到全部命令 + 两处真 bug(00:25,DeepSeek-V4.1-Flash,v2.6.41):--json 从 online/prepare 各自 emit 改为全命令单一出口——命令侧只 set_detail 上报、main 收尾 take_detail + emit 一次,「json 模式每命令只一行结论」成为结构性保证;实测 hash → success=true、abandon-task(任务不存在)→ success=false+error。撞出两个真 bug:① prepare 严格解析硬报 unknown prepare option 拒绝 --json(online 用 _ => {} 无感),与 10-14 --no-format 漏接同坑第二次;② 英文模式终态识别失效——text_parsing.rs:750 用中文原文「操作完成:…」判终态,v2.6.39 把文案交给 i18n 表后英文日志永不命中(上轮自己引入的回归),修法双语都认且文案从 i18n 表取(复用 online_done、新增 stage_done),历史中文日志仍须命中。冒烟脚本加快速失败(prepare 自陈 success=false 立即 die,此前因无此逻辑白等 13 分钟);另修 E0382(into_iter() move 后再借用,只在交叉编译暴露)。验收:单测 236(+1)、部署 SHA 5f218fb6…、全链冒烟 run26 7/7 PASS、英文真实还原 Operation complete 被识别为终态。
GUI 语言偏好持久化 + 修 v2.6.41 构建缺陷(00:40,DeepSeek-V4.1-Flash,v2.6.42):切英文此前是半截功能(重启回中文)。新增 settings.ini 键 ui_language=zh|en,只在 CBN_SELCHANGE 分支写盘(初始化不写,避免每次启动改文件时间戳);共享 ini 必须合并写——只剔除自己那行与自己 # ui_language: 前缀的注释,否则会把 failure_threshold/failure_action/dism_timeout 静默冲回默认。四条实测全过(切英文重启直接英文、种子三键全保留、连切两次文件仍 6 行不膨胀)。顺带抓出编译缺陷:cargo test 全绿但 macOS cargo check 报 5 个 E0433——i18n/pe_safety 是 cfg(any(windows, test)) 而 text_parsing 无条件引用 crate::i18n;治本方案把 MessageLanguage 从 pe_safety 搬到 i18n(语言维度归语言层),mod i18n 改无条件编译。验收:cargo check --workspace 0 警告、单测 236+45、部署 SHA 2e0871a0…、冒烟 6/6(smoke-20261025-003458:序列号 36E06E5B→16A013A4、C3 --json success=true);新增 tools/win-clicker/start-gui.ps1 一键提权重拉 GUI。
#121 GUI 切英文点击端到端打通——UIPI 才是真正根因(00:50,DeepSeek-V4.1-Flash):产品代码零改动,推翻 20261024-2355 两个「坑」:会话隔离根本不是问题(prlctl exec --current-user 直接就在 session 1)、ExecutionPolicy 只挡脚本文件不挡 -Command;真正根因是 UIPI(用户界面特权隔离)——GUI 是提权进程、通道是标准用户,所有 SendMessage 被静默拒绝。铁证:标准用户读下拉框 count=0,实为 SendMessageTimeout 返回 GetLastError=5 ERROR_ACCESS_DENIED(差点误判成「产品没填项」),换提权执行体后 COUNT=2、ITEM[0]=[中文]/ITEM[1]=[English]、AFTER=[Refresh environment],gui.log 记 notification=0x1(即 CBN_SELCHANGE)。新确认的坑:① GetWindowText 跨进程只拿内核里的 caption(按钮读得到),combo 内部文本要走 WM_GETTEXT 就撞 UIPI;② CreateProcessAsUser 不继承 stdout,执行体一律写文件(lang-switch-result.txt);③ WTSQueryUserToken+TokenLinkedToken 报 err=6,改借 GUI 进程令牌(SeDebugPrivilege 一次成功);④ 老 helper 工作目录指向 v2.6.34 起已不存在的目录报 267;⑤ CB_SETCURSEL 只改选中不发通知,必须显式补 CBN_SELCHANGE。落地三件工具:run-elevated-session1.ps1/switch-gui-language.ps1/_diag-uipi.ps1。
日志全量多语言化 97→0 + B6 目录分叉(01:10,DeepSeek-V4.1-Flash,v2.6.43):append_log 参数含中文的 97 处清零(410 个调用点),i18n 表 15→124 条,分四批(失败因果 11 / 恢复环境进度窗 21 / 主链与引导 55 / PE 与注册 18);翻译前先扫出 83 处中文判据逐类核对——STEP 解析只认 STEP + 数字安全,bcdedit 解析认的是系统本地化输出不动,cause_* 英文措辞定纪律:不得含分类模式整串(access is denied 等),否则 Busy 会被认成 AccessDenied。统计口径踩坑:实机冒烟后发现 online_operation.rs/pe_operation.rs 各有内部 log() 漏网 41 处,补上才真 0。顺带结两件旧账:① B6 备份目录不再叫 BackupRestore-online-*,按白名单分叉(backup/restore/secondary/probe,不认识回 online)——绝不把外部字符串拼进路径;② CLI 语言优先级 BACKUPRESTORE_LANG > ini ui_language > 中文(env 最高保自动化确定性)。又踩门控坑第二次:SETTINGS_FILE_NAME 住在门控的 failure_policy 被无条件的 i18n 引用报 E0433,搬去新建 settings_file.rs。err() 244 处中文本轮不动(正确方向是错误码查表)。验收:单测 240+45、部署 SHA 18ed4709…、实机日志整段英文、B6 实机目录 BackupRestore-restore-4344-…、冒烟 6/6。
RE 主链 DISM 超时形同虚设修复 + 降级首次端到端实证(01:25,DeepSeek-V4.1-Flash,v2.6.44):为补「RE 主链降级未单独实机验证」待办,跑 --dism-timeout-secs 1 + 38GB 镜像,预期 1 秒超时降级,结果任务 success/100%、约 6 分钟、零降级行——上限只被启动时记了一行 DISM wait limit: 1 sec,从未被使用:run_logged 是无条件 child.wait(),dism_timeout::wait_ms() 从未传入。双重后果:逃生阀无效 + classify_apply_failure 永远归不到 TimedOut,wimlib 自动降级在 RE 主链永不触发。修法:新增 run_logged_timeout/wait_child(u32::MAX=等到底与旧行为一致,其余 11 个调用点零回归;超时先 kill+wait 再 join 读线程,输出尾部照落日志供分类),RE 主链 /Apply-Image 接上 wait_ms()。修后同命令实证:TimedOut 分类 → 自动降级 wimlib → 79GB 写完 4 分 49 秒 → 任务 49a99148 success/100%——恢复环境主链降级首次端到端实证。现场处置:create-secondary 会把还原系统设为 default,两轮实机后均 bcdedit /default {af5ee73f-…} 改回原系统;启动菜单遗留 Windows Backup-202610250107。部署 SHA 2a56aed0…、冒烟 6/6(smoke-20261025-011850)。
TaskError 错误码体系 337 处 + --json error_code + 占位单遍扫描(04:30,DeepSeek-V4.1-Flash,v2.6.46→v2.6.50):用户拍板「错误码、文案按码查表」一轮做完:core TaskError 加 Coded{code, rendered} 变体(构造时渲染,因 core 无语言层;Invalid 原样保留,504 处引用不动);cli 宏 error_codes! 一行一条生成查表,格式 BR-<域>-三位(VOL/IMG/APL/BOOT/RE/PE/TSK/GUI/CORE 等),序号发布不得重排。覆盖:cli 245 处中文 err() 双语 + 9 处直连 TaskError::Invalid(boot_cleanup 7 处)+ core 81 处 coded(77 语义码)= 337 处;304 处用法错误故意不发码(英文原文即标识,发码淹没运行期码),判读规则「err=用法错误,errc/errc_with=运行期失败」写进模块文档。单测零改动:245 处文案逐字保留、Display 只加 [BR-XXX-NNN] 前缀,245+45 一次性全绿。v2.6.48 --json 加独立 error_code 字段(Io/Json/InvalidTransition 发固定码但 Display 不加前缀);清单脚本化 tools/gen-error-codes.py(v2.6.49 补完最后 9 处并修 boot_menu 双重前缀)。统计口径第二次踩同类坑:漏了绕过 err() 直接调 TaskError::Invalid 的 9 处。顺带两个真 bug:① --json 被按位置当成 recover 的第一个参数(v2.6.38 错误假设只对 online 成立),修法分发前统一 retain 摘除;② 占位替换是多遍 replace,前一轮参数内容里的 {1} 会被再替换一次(路径被静默篡改),抽 i18n::fill_placeholders() 单遍扫描(v2.6.50),非数字占位与越界索引原样保留。验收:部署 SHA beb76bfa…、实机中英同码、冒烟 6/6(smoke-20261025-044445)。
步 0 清尾 + E1 用户手册与 T: 走查(05:35,Step-5-Preview):用户拍板「按推荐路线推进 + 菜单遗留项删除」。① 删 Windows Backup-202610250107(v2.6.44 实机产物):回滚材料先落 .test-artifacts/bcd-menu-cleanup-20261025/,按 GUID {446ace41-cfce-11f1-a501-b5edaeceab66} 精确删、删前核实不在 displayorder;核验 osloader winload.efi 条目 7→6、{bootmgr} 三行逐字不变、重启正常。② online 补 --ui-language(commit 13172ce,语义=切本进程语言,优先级显式旗标 > env > ini > 中文;与 prepare 那个「写进任务 env」不同),usage 补上一直缺失的 online 命令。③ 实机撞出 online 备份不传 --compress 必失败([BR-CORE-034]):空串原样下传被 canonical_compression("") 判死,而 GUI 口径「不选=fast」——可选旗标变必填,因冒烟脚本永远显式传参从未暴露;修法空值归一 fast(commit a526bee)。④ VM 构建目标目录改 H:\br-target:X:\target(9p 共享卷)上 cargo 删临时目录报 os error 87(mac 侧交叉编译搅动过 target),全量 21.61s、部署 SHA 11ac5890…;新约定 VM 内一律 -CargoTargetDir H:\br-target,mac ./build-win.sh 只做类型检查。⑤ E1 docs/USER-GUIDE.md 落库(活文档,先中文),T: 5G 走查验收:哨兵消失 + 序列号 BC9C-BF66→0E74-C8BA 双铁证。
E2 备份完整性盘点:捕获侧自检已齐,不补码(05:45,Step-5-Preview):设计遗留问题「RE 离线捕获链收尾是否独立自检未核实」——读码结论:全项目只有一条捕获实现,pe_operation::Engine::backup(:435)第 455 行直接委托 online_operation::capture,所谓「RE 离线链」不存在独立实现。capture 收尾清单逐条有行号:DISM /CheckIntegrity(:1354)、索引回读(:1365-1366)、整档 sha256 写 sidecar(:1460)、发布前重验原镜像(:1439-1444)、legacy 簿记回读(:1467-1469)、发布后尺寸核对(:1474-1476)、失败回滚。唯一可争议点「rename 成品后不再回读」论证不做:同卷 rename 原子、内容逐字节不变,对已完整读过的文件再读是纯仪式,多一次只读 DISM 调用反多一个失败模式;「备份后还原前」的介质级损坏由还原侧 sidecar 预检 + apply /CheckIntegrity 负责。E2 结题零代码改动。
E3 主备反转评估:DISM vs wimlib 实机对照,不反转(07:00,Step-5-Preview):同一镜像 br-2629-20261023.wim(index 1,40,566,232,539 B,展开约 79 GiB)双通道对照:Round A DISM 格式化+应用 1683s(apply 27m56s)、Round B wimlib 覆盖式 1601s(apply 26m37s),差 ~4% 噪声级;ACL 六条路径 SDDL 逐字节一致 6/6(含 WindowsApps 条件 ACE、SYSTEM hive 的 TrustedInstaller DACL,工具 br-acl-compare.ps1);哨兵与序列号语义各自正确(A 消失/7E57-BFDF→9432-A8C3,B 存活/不变);wimlib 进度行带绝对量略优,DISM 有超时可配+失败自动降级、实机履历十余轮占优。结论维持「DISM 默认 + 失败降级 wimlib」:数据打平不构成换默认理由,且风险不对称——wimlib 无二级降级,反转即单点;覆盖式到 Windows 卷 DISM 必败(0x80070005,#110 根因)的分工已正确。反转触发条件三条记录在案(① DISM 出现无法降级的确定性失败连续复现;② wimlib ≥10 次端到端零缺陷且有新能力增益;③ 用户明确要求)。实验后 bcdedit /default {af5ee73f-cf3b-11f1-9e5a-cb0d9617e33d} 改回并重启验证(BOOT_OK、C: 序列号 5698-64F6)。
E4 冒烟接入部署门禁 + 判据扩容:一键 7/7 PASS(07:05,Step-5-Preview):串联点放宿主侧封装器 tools/smoke/deploy-and-smoke.sh(VM 内部署脚本不宜回调宿主):SYSTEM 通道 taskkill GUI → VM 内构建部署 → start-gui.ps1 重拉(顺带验新二进制能起界面)→ br-smoke.sh 参数透传;默认不自动跑(含一次 WinRE 重启)。判据扩容:C3 失败时带 --json error_code + 日志最后一条 [BR-域-序号] 码,判据本身仍只认 ASCII 结构化特征;「还原后回读 default」不引入(数据卷冒烟不碰引导,系统卷侧程序内已是硬判据 BR-BOOT-004)。实机验收(06:45,T: 5G)全过:部署增量 1.04s、SHA 11ac5890…、C1 哨兵 BR-BENTRY-SENTINEL smoke-20261025-064507 内容一致、C2 序列号 0E74C8BA→668D4BA8、C3 --json success=true + STEP 全在、C4 100MB 载荷 104857600/104857600 B 字节级一致、C5 BR38Data 四项全在、C6 EventID1000=0 且 WerFault=0——7/7,全程 <2 分钟。至此 05:05 推荐路线 E1→E4 全部结清。
P1-c 备份文件管理 UI 立项实现与全链路验收(07:40,Step-5-Preview,commit 9f7b63b):需求 §3「管理备份文件」职责内的唯一新功能。新建 image_admin.rs:list_images(DISM 真实索引号 + sidecar 元数据,sidecar 缺失不致命)、delete_oldest_indexes(与 capture 保留逻辑同源:DISM /Delete-Image /Index:1 循环 + 逐次回读索引集合,不一致即中止留半删现场,删完一次性 renumber_sidecars 重算哈希)、clamp_keep 钳到 [1,total]。CLI 新命令 list-images / delete-old-indexes --keep <n>(日志标记 BackupRestore-image-admin-*,破坏性操作前后各记日志);GUI 顶栏新按钮(ID 1009,重排避免压邻接控件)+ 模态对话框(OperationGate 忙标志 + worker 线程 catch_unwind + WM_APP_* 回窗),删除前原生确认框逐项列出将删索引 + 不可撤销警示;新错误码 BR-IMG-007(删除后回读不一致),错误码清单重生成 213 条。验收:mac 单测 249+45、部署 SHA 87270388…;CLI 链 3 索引(one/two/three)→ keep 1 → 还原内容=three(副档哈希预检通过);GUI 全点击链 7 步(确认框列出 1、2 号、删完列表自动刷新、还原=five);T: 清回空卷(新序列号 CCF1-1AEE)。同 commit 附带 P2-a 本地 pre-push 门禁钩子。
教训与经验
- 「main 能识别 ≠ 命令能接受 ≠ 参数表干净」:
--json一天三撞——prepare 严格解析直接拒绝(v2.6.41)、recover 按位置取参把它当 task_id(v2.6.46)、prepare/online 里的分支只是 no-op;终修法是分发前统一retain摘除,一处修好所有命令受益。 cargo test全绿 ≠ 构建过:cfg(any(windows, test))模块被无条件模块引用,缺口只在 maccargo check暴露(交叉编译是 windows target,同样看不见);同日踩两次(MessageLanguage、SETTINGS_FILE_NAME)。规则:一个模块一旦无条件编译,它引用的一切也必须无条件可用。- 文案不是契约:判据依赖中文文案,i18n 一翻译判据就断(英文终态识别失效是上一轮自己埋的回归);判据要「任一语言命中即过」、文案单一来源查表;错误码体系正是把「定位靠文案」换成「定位靠码」的治本。
- UIPI 的拒绝是静默的:跨进程读控件
count=0而界面明明有内容 = 先量两侧完整性级别(GetLastError=5),不要怀疑产品;GetWindowText跨进程只拿 caption。 - 「配置读了」≠「配置用了」:
--dism-timeout-secs只记一行日志、apply 无条件child.wait(),静态审查难看出,靠「1 秒上限 + 38GB 镜像」真跑一次暴露;新参数上线要做修前/修后行为对照的变异验证。 - 统计某类调用前先确认一共几种写法:同日两次——日志清零漏了模块自带
log()41 处、错误码漏了直接TaskError::Invalid9 处(boot_cleanup.rs整文件)。 - 默认值断链只有真实命令行会踩到:脚本永远显式传参,
--compress空串判死这类「可选旗标变必填」要拿裸命令行验。 - 多遍 replace 会二次篡改参数内容:占位替换必须单遍扫描;越界/非数字占位宁可原样露出
{7}也不静默吞,否则漏传参数只能靠肉眼发现。 - 共享 ini 只能合并写:整文件重写会静默冲掉别人的键与注释,事后极难归因。
- 打平不构成换默认的理由:反转默认引擎需要「增益证据 + 风险不对称评估」(wimlib 无二级降级),数据打平只支持维持现状。
- 外部输入进路径走白名单:目录标记按白名单映射、不认识回默认值,绝不把外部字符串直接拼进路径。
- Windows/cmd 通道小坑合集:robocopy 退出码 1=复制成功(≥8 才是失败);cmd 的 if/else 块别和
&命令链写同一行(后半段整个被吞);prlctl 通道会剥掉 PowerShell 单引号(只用双引号或写文件回读);dir C:\a\b(b 不存在)按「列父目录 + b 作掩码」解释,判目录存在要看它是否作为条目出现。
下次接手的注意
- 项目阶段:V1 需求 100% 交付且全链实机验证,工程质量四件套(错误码 337 处 / i18n 124 条 /
--json error_code/ 一键门禁 7/7)齐备,从「功能建设」进入「产品化打磨」;方向以20261025-0505-下一步开发方向与20261025-0655-项目整体分析与下一步开发详细建议两篇为准(05:05 版四步路线 E1→E4 已全部结清,勿重复做)。 - 推荐路线:① P1-a GUI「查看日志」入口 + P1-b GUI「探测」入口(体验补缺一轮,验收:入口可达 + 探测零副作用——哨兵仍在、序列号不变);② P2-a CI(GitHub Actions x64 Windows runner 跑
cargo check --target aarch64-pc-windows-msvc+ core 单测;本轮已先落本地 pre-push 钩子,GH Actions 待用户拍板);③ P2-b clippy 真实 3 类告警清零 +unwrap/expect约 537 处按「测试/锁/IO 兜底/真风险」四类盘点;④ P2-c USER-GUIDE 英文版;⑤ P3 评估轮:native_gui.rs(10,709 行、占 24%)拆分先出方案不动码、wimlib capture POC 不预设结论。 - 等拍板/明确不做:304 处用法错误维持「不发码」(AI 建议,等用户最终确认);计划备份、镜像加密、任务证据管理 UI、网络备份属需求范围外,等用户提需求再立项;B5 僵尸任务「不自动终态」(10-23 拍板)。
- E3 反转触发条件三条已记录在案(DISM 出现无法降级的确定性失败连续复现 / wimlib ≥10 次端到端零缺陷且有能力增益 / 用户明确要求),任一成立再重议主备。
- 现场与证据:
H:\BRImages\admin-test-20261025.wim(17.9 KiB)、lang-test-20261025.wim按「证据全留」保留;F: 现存系统为 E3 Round B 覆盖结果(可牺牲测试卷);启动菜单两轮测试命名项保留未清;default 指原系统、快照 0 层;部署H:\brwork两 exe SHA87270388…(P1-c 后)。
- 点赞
- 收藏
- 关注作者
评论(0)