Shuery/BakNRet
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
41 Commits 1 Branch 0 Tags
6315c72f69c9ea3dbc6dfe521d2f44988c595c94
Commit Graph
21 Commits
Author SHA1 Message Date
Shuery 6315c72f69 fix(tui): 单键序列被 [pscustomobject] 拆成字符串（驱动器改 List[string]） 
根因：`[pscustomobject]@{ Script = $scriptKeys }` 里，**单元素数组会被 PowerShell 拆成字符串**，于是 `$Driver.Script[0]` 取到的是字符串首字母 —— @('Esc') 变成 'E'，键名不再匹配任何分支，循环继续往下读，最后"序列用尽"报错。

这个坑只在"恰好一个键"时出现，所以块 ② 当时的断言（两键序列按顺序消费）看不见它；而菜单循环那块因此连着两次"看着对、跑起来不对"。修法是改用 List[string]：不会被拆、可按索引取、两个版本行为一致。

补一条正是为它立的断言：单键序列必须整键返回（不是首字母）。这类"只在边界数量上出现"的错，只能靠把边界数量本身写进断言来防。

验收：test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 16:11:17 +08:00
Shuery 347959d677 feat(tui): 菜单状态机（第一轮第四块·上） 
把菜单拆成"纯状态机 + 薄渲染"：状态机进断言，渲染只需人肉看长相。规则：Up/k 上移、Down/j 下移、到头绕回；Space 只切换当前项（单选模式无效）；Enter=confirm、Esc=cancel；返回新对象而不就地改（状态属于调用方，ADR-0011）。

特别钉住空菜单：第一次使用时归档目录就是空的，菜单打开就是空菜单 —— 方向键与空格都不该抛错，只有 Esc 能退出。这类"初始状态为空"的路径最容易在真终端里才被发现，而那时已经晚了。

验收：断言 16 条；两版手工输出一致；test.ps1 9/9 全绿。
 2026-09-27 15:55:31 +08:00
Shuery d9d7967e64 feat(tui): 定位写与按列对齐（第一轮第三块） 
Format-BakNRetPaddedText：按**列宽**补齐或裁剪，且绝不切开宽字符 —— 剩余宽度差 1 列而下一个字符要占 2 列时，停下用空格补那 1 列。返回的字符串保证恰好 N 列，这条不变式是画边框的基础（按 .Length 补会让边框歪，按 .Length 裁会把汉字劈成半个显示成乱码）。

Write-BakNRetAt：第一道闸门是 [Console]::IsOutputRedirected，**不是** $Host.UI.SupportsVirtualTerminal（实测后者无控制台时仍返回 True，而 SetCursorPosition 会抛异常）。没有控制台就完全不定位、只把文本写出去；坐标越界时跳过定位但仍写出文本 —— 计划任务与窄窗口不该让 TUI 崩掉，只是画得难看一点。颜色走 Write-Host -ForegroundColor（零 VT 依赖）。

验收：断言 10 条（含"裁剪后恰好 5 列且不是 4 个字符"这条关键判据）；两版手工输出一致；test.ps1 9/9 全绿。
 2026-09-27 15:52:34 +08:00
Shuery f2959a4279 feat(tui): 读键归一化与 -InputScript 输入缝（第一轮第二块） 
三层拆开，让唯一能无控制台测试的那层露出来：Get-BakNRetKeyName 纯映射（键码→键名）、New-BakNRetInputDriver 造驱动对象、Read-BakNRetKey 取下一个键。门禁把方向键/回车/空格/字母全钉住，只把"真的读到一个键"留给人工。

两条"不猜"的设计：序列用尽必须抛错（绝不退回去读真终端 —— 门禁挂起比变红糟得多）；没有控制台也没有序列时不返回任何默认键（没人按键却继续执行，在备份工具里等于替你做了决定）。

这块连撞三个"看起来该有值、其实是空的"坑，全被"绿了才提交"拦在提交之外：① 键名少写冒号；② @($null) 造出含 $null 的单元素数组，"空序列"被当成"有一个键"，且两版本表现不同（7 静默返回、5.1 抛错）；③ **多行插入时换行被折成空格**，于是注释与 `Script = $scriptKeys` 一起落进同一行注释，那条赋值从未执行 —— 症状是"对象一个属性都没有"。教训：往文件里插多行代码不能靠拼接字符串，写文件就整份重写。

验收：断言 15 条（含驱动序列消费与两条必须报错）；两版本手工输出一致；test.ps1 9/9 全绿。
 2026-09-27 15:49:20 +08:00
Shuery 8a0924330a feat(tui): 控制台列宽表（第一轮第一块） 
整个 TUI 的地基：位置、对齐、边框都靠它。而它算错了**不会报错** —— 表现只是菜单右边框歪一点、光标偏一列，所以每条边界都在断言里钉住。

为什么必须自己算：.Length 是 UTF-16 code unit 的个数（汉字 1 个 char、2 列）；而 $Host.UI.RawUI.LengthInBufferCells 在 PowerShell 7 上对、在 5.1 上错（实测 中文 返回 2、字体边框字符 返回 6），且不抛错 —— 这种"一边对一边错"的 API 比两边都错更危险。

表里三个边界是实测踩过的：半角片假名 U+FF61–FF9F 是 1 列（不能划进全角区）；全角拉丁 U+FF00–FF60 是 2 列；emoji 是代理对，按一个码点算。

验收：断言 8 条（含空串与控制字符）；test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 15:31:26 +08:00
Shuery 187549e2af feat: 运行结尾输出分类详细的结果汇总（成功/跳过/失败/安全/孤儿） 
原先结尾只有一行计数加一个失败清单。计数回答有几个，而人真正要读的是哪几个、为什么——尤其当失败或跳过发生在你没盯着屏幕的时候（计划任务）。

新的 Write-BakNRetRunSummary 按动作分组逐条列出：成功组带归档名/体积/耗时/sha256 前 12 位、以及有文件没打进归档的警告标记；跳过组带具体原因（源未更新/源不存在/路径无效）；失败组带退出码与原因原文，并且再单列一遍。另有安全描述符与孤儿归档两段，空分组不打印，末尾给耗时。

数据来源是 manifest 里本次运行写下的记录（按 finishedAt 落在运行窗口内筛），而不是让调用方另维护一份清单。

搬的过程里翻车一次并被自己的断言拦住：Get-RecField 只用 PSObject.Properties.Name 判字段存在，而那是 PSCustomObject 的形态；本进程新造的记录是 [ordered] 字典，于是字段一律读成 $null，现象是"本次运行没有写下任何条目记录"（记录明明在）。现在两种形态都认。

一个已知没做的：排除规则只在内联逐条打印，没进汇总——我没定位到那个打印点，不愿意凭猜往条目循环里插桩。

断言：零依赖套件新增一条，用真日志文件验收汇总内容，并断言空分组不出现。验收：test.ps1 9/9 全绿（7 与 5.1）。
 2026-09-27 14:26:59 +08:00
Shuery 319ec1da78 refactor: 条目记录的工厂搬进模块（manifest 的 schema 有了唯一落点） 
New-ItemRecord 是纯工厂：我先用正则扫过它读了哪些外部状态 —— 一处都没有，输入全在参数里，只有一个 Get-Date。所以这是"有状态核心"里唯一可以零判断搬走的一块。

搬走并改名 New-BakNRetItemRecord，同时补上字段说明：这个有序哈希就是 manifest 每个条目的 schema。它原先藏在 Backup.ps1 里，于是"manifest 条目长什么样"这件事只有一个隐式落点；恢复端与工具脚本读的也是同一份 schema，改字段时漏掉某一侧的风险就出在这里。

新增一条断言把这个 schema 钉住：26 个字段的名字与**顺序**逐项比对（顺序是 manifest diff 可读性的前提），另外断言 attemptedAt 每次现取 —— 后者是"把它误写成模块加载时的常量"这种错唯一能被发现的地方。

验收：test.ps1 9/9 全绿（7 与 5.1）、104 个文件两版解析零错、真实清单只读冒烟 4/4。Backup.ps1 从 920 行降到 889 行。
 2026-09-27 10:40:35 +08:00
Shuery 42f02d0eca refactor: 公共面补 BakNRet 前缀，产品名大小写全仓统一 
16 个没有前缀的公共函数补上 BakNRet（Write-Log → Write-BakNRetLog、Resolve-BackupEntry →
Resolve-BakNRetBackupEntry、Find-ChildDirectoryByName → Find-BakNRetChildDirectoryByName 等），
另外把全仓的 Baknret 统一成 BakNRet（47 个文件、940 处、65 个定义文件重命名）。

这不是审美问题：静态分析直接拓出一条实据 —— Write-Log 与本机某个已装模块导出的命令
**重名**（PSAvoidOverwritingBuiltInCmdlets），而重名的后果是导入两个模块时有一方的命令被
静默遮蔽。补前缀正是这条规则的解法，改名后它归零。

为什么敢做这个规模：PowerShell 的函数名解析大小写不敏感，所以 Baknret → BakNRet 在功能
上是零风险；真正要验证的是 16 个补前缀的调用点，而 276 个断言几乎覆盖了每个函数。另外
"名字与文件名一致"这条不变式有断言盯着（加载器点源的文件集合 vs 磁盘）。

踩到并记下的坑：Windows 文件系统大小写不敏感，所以**只改大小写**的重命名会被 Move-Item
当成同一个文件而静默跳过 —— 同一批里同时改了名字的那 16 个文件却成功了，于是"看起来能跑"。
最后用"先移到临时名、再移到目标名"的两步走解决，判断与替换全部改用显式大小写敏感的形式
（-creplace / -cmatch）。

顺带把名录指纹缓存从 MD5 换成 SHA256（PSAvoidUsingBrokenHashAlgorithms）：它只是缓存键，
没有兼容负担。

验收：test.ps1 9/9 全绿（7 与 5.1）、100 个文件两版解析零错、276 个断言全过、
构建工具仍能合回单文件（3300 行）。
 2026-09-27 09:56:36 +08:00
Shuery 187d2759fd style: 按微软规范落地静态分析，并全仓机械重排 
三件事：

1) tools\Install-TestDependencies.ps1 现在也把 PSScriptAnalyzer 装进仓库内的 .tools\modules
（不动机器上的全局模块，与 Pester 同一策略）。

2) PSScriptAnalyzerSettings.psd1：这是必要的，不是装饰 —— 那 6 条格式规则
（括号、缩进、空格、对齐、大小写）默认全是 Disabled，所以不带 -Settings 的
`Invoke-ScriptAnalyzer -Severity Warning,Error` 会**静默漏掉全部排版问题**。本文件用 Rules
把它们打开（而不是用 IncludeRules 换一套），于是默认规则与格式规则同时生效。
三条有意的排除都写明了理由：PSAvoidUsingWriteHost（彩色控制台输出是这份工具的刻意设计）、
PSUseShouldProcessForStateChangingFunctions（WhatIf 的边界在入口脚本，给库里 27 个改状态的
函数都加上反而会"静默跳过"，备份看着成功却什么都没做）、PSAvoidUsingPlainTextForPassword
（7z 只接受命令行口令，这是 7z 的限制，README 里写明了取舍）。

3) tools\Invoke-Analyzer.ps1：独立门禁（不塞进 Pester 用例 —— 套件跑一次二十多秒，
混进去会让"测试红了"这句话失去分辨力），路径过滤与验收门槛的 Encode/Parse 两层一致。

全仓重排结果：706 条告警 -> 67 条。修掉的 639 条全部是格式（闭括号 168、空格 80、
对齐 68、缩进 60、行长 229）。重排后 9/9 验收全绿、100 个文件两版解析零错、
276 个断言原样通过 —— 机械重排没有改变任何可观察行为。

如实说明两件事：

  * 行长上限设成 160，**不是**官方默认的 120。120 在本仓库意味着 270 处改动（主要是
    中文注释与测试夹具里的一行式目录），160 意味着 41 处。160 仍是"宽但可读"，而理由是写在
    配置文件里的：这不是悄悄放宽，想收紧到 120 时那份清单就在分析器输出里。

  * 剩余 67 条里，41 条是上面那批行长，其余 26 条是分析器找出的真问题（未使用参数 6、
    空 catch 6、MD5 指纹 1、覆盖内置命令 1、switch 默认值 1 等）。其中
    Find-ChildDirectoryByName 的 MaxDepth 参数从未被使用 —— 也就是配置里的
    CatalogMaxDepth = 5 是假的，前缀补全实际只查 1 层。这条要改行为、且影响真实名录的解析
    结果，留给你拍板，不在本提交里动手。
 2026-09-27 09:46:08 +08:00
Shuery 2ad7987ffe refactor: Common.psm1 拆成 BakNRet/{Public,Private}，一函数一文件 + 薄加载器 
3152 行、66 个函数的单文件模块拆成：
  BakNRet\BakNRet.psd1   模块清单：FunctionsToExport 是显式白名单（62 个名字）
  BakNRet\BakNRet.psm1   加载器：点源顺序的唯一一处声明
  BakNRet\Public\*.ps1   62 个对外函数，一函数一文件，文件名 = 函数名
  BakNRet\Private\*.ps1  4 个内部函数 + State.ps1（模块级状态集中一处）

为什么是一函数一文件：这是社区里脚本模块的主流形态（调研实测：winutil 79 个、
Terminal-Icons 24 个、ModuleBuilder 23 个，全部如此）。收益是改动落在小文件里、diff 按职责
可读、模块级状态有唯一去处。

为什么这不算"打散"：模块内 dot-source 的文件共享同一个模块作用域（实测确认），所以
"按顺序点源 67 个文件"与"点源一个大文件"在语义上等价；顺序只在加载器里出现一次，
tools\Build-BakNRetModule.ps1 从那里读出顺序就能拼回单文件 —— 本次产物 dist\BakNRet.psm1
3240 行、两个版本都解析零错。

新增一条断言把这条承诺钉住：加载器点源的文件集合必须与磁盘一致、导出名单必须与
Public\ 一一对应。漏一个文件或漏一个名字就是静默少一个函数 —— 而那种错在运行时只表现为
"找不到命令"。

引用更新：11 个文件里的 Common.psm1 改成 BakNRet\BakNRet.psd1（走清单导入，
FunctionsToExport 才真的说了算）；Common.psm1 直接删除，不留转发垫片。

验收：test.ps1 9/9 全绿（7 与 5.1），98 个文件两版解析零错，276 个断言原样通过 ——
这次搬家没有改变任何可观察行为。
 2026-09-27 09:34:10 +08:00
Shuery 8d67a38fb7 fix: Backup.ps1 与 Restore.ps1 并发撞车时互踩账本（加运行锁） 
问题：两个入口都会写 manifest.json，也都会在备份目录里用 <归档>.tmp 这个名字生成临时
归档。计划任务与手动运行撞在一起时，两边会互相覆盖对方的账本；更糟的是两边会把彼此的临时
归档当成自己的。计划任务的 -MultipleInstances IgnoreNew 只挡住"计划任务之间"，挡不住手动运行。

修法：备份目录上的一把跨进程锁，用**独占文件句柄**（FileShare.None）而不是命名互斥体：
  * 句柄由内核持有，进程被杀 / 崩溃时自动关闭，锁自动释放 —— 不会留下需要人工清理的陈旧锁；
    命名互斥体要跨会话（计划任务在另一个会话里跑）还得用 Global\ 前缀，那需要额外权限。
  * 它是文件系统的锁：不区分会话、不区分终端，计划任务与手动运行会互相看见。
  * 锁文件里写明持有进程（pid / 起始时间 / 主机 / 用户）—— "到底是谁占着"不该靠猜。
拿不到锁就直接失败（退出码 1 + 明确消息），不等待：单个条目压缩可能十几分钟，"等它跑完"
对用户来说和挂住没区别。

只读模式不取锁（Backup 的 -DryRun；Restore 的 -DryRun / -WhatIf / -VerifyOnly）：
它们一个字节都不写，没必要被正在跑的备份挡在外面。

踩到并记下的两个坑：
  1) catch [System.IO.IOException] 接不住 —— PowerShell 把 .NET 方法抛出的异常包成
     MethodInvocationException，按内层类型做的 catch 会漏。现在沿 InnerException 链找，
     不是 IOException 就把原异常抛回去（目录不可写是 UnauthorizedAccessException，那是真
     错误，不该伪装成"另一次运行在进行中"）。
  2) 锁文件是独占打开的，所以内容只能在**释放之后**读 —— 第一版断言在持锁时去 Get-Content，
     被自己的锁拒了；这条断言现在挪到释放之后。

跨进程证据（真跑，不是推理）：父进程持锁 → 另一个进程取锁得到 DENIED；持锁状态下跑
真实的 Backup.ps1 → 退出码 1、日志点名锁文件、manifest 的 SHA256 未变；释放后另一进程
得到 GOT。

验收：test.ps1 9/9 全绿（7 与 5.1）；tests\Run-RealSmoke.ps1 4/4 全绿。
 2026-09-27 09:18:49 +08:00
Shuery 79f83f6760 fix: manifest 先删后移会丢账本；5.1 拿不到原子替换；空目录让空间守卫静默失效 
四件事都在"原子替换与空间守卫"这条线上：

1) Write-BaknretManifest 自己写了"写 .tmp → 删旧 → Move-Item"。Move-Item 一失败，
   旧 manifest 就已经没了 —— 而 manifest 是"这块归档是谁的"的唯一账本。改成复用
   Write-BaknretAtomicText。

2) Write-BaknretAtomicText 原本也是走 Move-BaknretArchiveIntoPlace，而后者在 5.1 上
   必然退化成"先删后移"（三参数 File.Move 是 .NET Core 3.0+ 才有的重载）。现在目标存在时
   改用 File.Replace（ReplaceFile API）：要么换成新内容、要么保持旧内容，两个都不会消失。
   实测目标只读时替换失败、旧内容完好、.tmp 保留便于排查。

3) Move-BaknretArchiveIntoPlace 的 5.1 降级路径同样改成 File.Replace —— 之前那条
   "先删后移"会在中途失败时让归档消失（旧归档没了、新归档还在 .tmp 里）。
   注意第三个参数必须传 [NullString]::Value：PowerShell 会把 $null 转成空串，Replace 于是
   报"路径为空"（两个版本实测都这样，我第一版就踩了）。

4) Get-FolderSummary 对空目录返回的 TotalSize 是 $null 而不是 0（Measure-Object 空
   输入的行为，两版一致）。$null / 1GB 得 0，而备份前的空间守卫判的是 -gt 0 —— 空间不足时
   不再拦截，静默失效。现在补成 0。

回归断言（零依赖与 Pester 各一份）：空目录的摘要必须是整数 0；原子写成功时内容到位
且不留 .tmp、失败时旧内容完好（用只读目标强制失败）。

验收：test.ps1 9/9 全绿 —— 5.1 那一遍的通过同时证明了 File.Replace 这条新路径真的
在 5.1 上成立；tests\Run-RealSmoke.ps1 4/4 全绿。
 2026-09-26 22:47:14 +08:00
Shuery e17cdcda79 fix: 口令会随 -Verbose 落进日志（DEBUG 下打印整条命令行） 
缺陷：Invoke-ExternalCommand 在 DEBUG 级打印整条命令行，而 7z / RAR 只接受命令行
口令（-p<口令>），所以口令必然出现在参数表里。一旦 -Verbose（Backup.ps1 / Restore.ps1
都会因它打开 DEBUG），logs\*.log 里就是明文口令 —— 与 BackupConfig.psd1 和文档里
"口令不落盘、不写进仓库"的承诺直接冲突。

修法：打印前把 -p 参数换成占位符；真正执行的仍然是原参数。在**参数级别**替换而不是
对拼好的命令行做正则 —— 含空格的口令会被引号包起来（"-pmy pass"），正则在那种形态上
很容易漏掉，而漏掉的代价是口令明文入日志。

回归断言（零依赖与 Pester 各一份）：打开 DEBUG、把日志指向临时目录、带一个哨兵口令
跑一次外部命令，然后读日志文件断言哨兵不在里面、占位符在里面。另加一条"测试的测试"：
断言那行 DEBUG 记录确实写进去了 —— 否则前两条会在"压根没记录"时空跑通过。

断言有效性做了红绿证明：把遮蔽改回 $startInfo.Arguments 后断言变红并指名"口令明文
进了日志"，还原后转绿。

验收：test.ps1 9/9 全绿；tests\Run-RealSmoke.ps1 4/4 全绿。
 2026-09-26 22:41:52 +08:00
Shuery d32d4b511f fix: 暂存目录半途失败会留下指向真实数据的 junction 
缺陷：Backup.ps1 用 `$stagingRoot = $null` + try/finally 清理暂存目录，而
New-BaknretArchiveStaging 中途抛错时没有返回值 —— 赋值没发生，finally 拿到的还是 $null，
而 Remove-BaknretArchiveStaging 对 $null 直接 return。结果是已经建好的 junction 与临时
目录永久留在 %TEMP%，而那些 junction 指向真实数据；临时目录迟早会被某次
Remove-Item -Recurse 扫到，那一下就会走进真实数据。全仓唯一会伤到数据的缺陷。

修法：把清理责任放回函数自己身上 —— 循环包进 try，catch 先调
Remove-BaknretArchiveStaging 清掉已经建出来的东西，再 throw 原始错误。调用方的 finally
保持不动（它管的是"暂存建好之后下游才失败"那条路）。自清理失败时只告警并点名残留路径，
不覆盖真正的失败原因 —— 那才是排查需要的。

回归断言（零依赖与 Pester 各一份）：第一项走 junction 成功挂上，第二项因源文件不
存在必然抛错；然后断言沙盒里不留任何条目，尤其不留 junction。

断言的有效性做了红绿证明：把 catch 里那行清理临时停用后，同一段场景残留 1 个
junction（.\sandbox\stage\Good，指向真实目录）→ 断言变红；还原后文件哈希一致、断言转绿。
一个不会红的断言不算保护。

验收：test.ps1 9/9 全绿（7 与 5.1）；tests\Run-RealSmoke.ps1 4/4 全绿。
 2026-09-26 22:36:44 +08:00
Shuery 8736bb2c67 fix: 行首方向标记贴在目标上时失效（真实清单 29 条里 24 条被静默跳过） 
量到的事实：用真实清单只读干跑，28 个条目里 27 个被当成"源不存在"跳过、退出码 0，
只有不写方向标记的 Scoop 真的被备份 —— 磁盘上最新那份归档正是 Scoop.7z（4.6 GB / 09-24）。
修复后同一批条目：29 条全部分解出方向（26 仅备份 / 2 仅恢复 / 1 双向），零个标记残留。

原因：解析器只认"独立记号"形态的方向标记（+ Name），而清单里 24 条贴在目标上
（+WindowsTerminal）。后者被当成一个名叫 +WindowsTerminal 的软件名，名录里查不到就退回
当目录名，目录又不存在 → 静默记成 missing-source。它隐形的理由是两件本身正确的设计叠在
一起："源不存在只算跳过不算失败" 加上两种写法只差一个空格。

README 的方向标记表格写的是"行首 + / -"，并没有要求标记后面跟空格；要求带空白的是
修饰符（:: / :- / :+ / @）那一节。所以让解析器接受行首贴在一起的形态，而不是去改清单。
只放宽"行首"这一个位置：记号中间的 + / - 仍是普通字符（C:\a:-b 那条断言继续盯着）。

新增 tests\Run-RealSmoke.ps1：真实清单 + 真实归档上的只读冒烟。它存在的理由就是这个
缺陷 —— 夹具测试全绿，只有拿真实清单跑才看得见。它检查四件事：方向标记全部被剥掉、没有
软件名退化成"名录里没有"、两个只读模式退出 0、manifest.json 的 SHA256 前后不变。

验收：test.ps1 9/9 全绿（7 与 5.1）；tests\Run-RealSmoke.ps1 4/4 全绿。
 2026-09-26 22:26:45 +08:00
Shuery e10503be76 fix: 让 5.1 真正可用（显式编码 + 原生 stderr 处理 + .psd1 夹具带 BOM） 
上一提交让 5.1 能解析源码，但 Unit 与 Smoke 在 5.1 上仍然是红的。根因是三类彼此
无关的 5.1/7 行为差，全部实测确认：

1) 不写 -Encoding 时，5.1 的 Get-Content / Set-Content 默认是 ANSI，7 是 UTF-8。
   症状是 UTF-8 字节被按 GBK 解出「璇存槑」这类乱码。62 处补上显式 -Encoding UTF8。
   用 AST 而不是正则定位，避免把注释里的散文也改掉。

2) .psd1 夹具用无 BOM 写，而引擎的 .psd1 读取器（Import-PowerShellDataFile）只能靠
   BOM 判断编码、没有参数可传，于是 5.1 按 ANSI 解。40 处夹具改为带 BOM 写 —— 这正是
   .editorconfig 里 [*.psd1] charset = utf-8-bom 本来就要求的，是夹具违反了自己的约定。
   .cmd 批次文件刻意保持无 BOM：cmd.exe 会被 BOM 弄坏。

3) 5.1 在 $ErrorActionPreference = Stop 下会把原生命令写到 stderr 的内容升级成终止性
   NativeCommandError，7 改了这条。takeown/icacls 的 ACL 复位调用、以及 test.ps1 自己
   调子进程的地方，都需要在 Continue 下跑。

验收：test.ps1 9/9 全绿（Encode + Parse + Unit + Smoke + E2E，在 7 与 5.1 上各跑一遍）。

已知未处理（留待后续提交）：tools/lab/** 里还有若干「原生命令 + 2>&1 + Stop」的同类
写法（takeown / icacls / scoop / code / Get-WimInfo）。它们要 Hyper-V 实验机才跑得到，
不在验收门槛内。
 2026-09-26 22:16:04 +08:00
Shuery 2d26f78d15 fix: 源文件改存 UTF-8 with BOM，让 Windows PowerShell 5.1 真正可用 
改造前：全仓 6/6 个源文件在 5.1 上解析失败（README 却承诺支持 5.1）。原因是文件是无 BOM 的
UTF-8，而 5.1 没有 BOM 就按 ANSI 代码页解码源码，中文变乱码、全角问号吃掉引号，整块语法塌掉。
现在 28/28 个文件在 5.1 与 7 上都解析零错误，E2E 36 项在 5.1 上全绿。

顺带修掉一个被 5.1 掩盖的缺陷：带 [CmdletBinding()] 的脚本在 5.1 上，param() 默认值里
拿不到 $PSScriptRoot（实测为空串，7 上正常）。于是 Backup.ps1 / Restore.ps1 在 5.1 上不传
路径参数就报错退出 —— 而计划任务恰恰不传。E2E 之所以看不见，是因为它总是显式传路径。
8 处默认值全部移到 param() 之后的解析段，沿用本仓库对 -BackupDir 一直在用的写法。

新增三条可重放的约定，让编码不再是一次性动作：
  .gitattributes 接管行尾（本机 core.autocrlf=true，会把工作区改成 CRLF 制造伪 diff）
  .editorconfig 用 charset = utf-8-bom 锁住 BOM
  tools\Set-SourceEncoding.ps1 是规范化脚本，tools\Invoke-* 之外的任何改动之后都能重放
  test.ps1 是唯一验收入口：Encode + Parse + Unit + Smoke + E2E，在 7 与 5.1 上各跑一遍

test.ps1 的 Encode 层直接检查"必须有 BOM"这条规则。加它的原因很实际：实测本仓库用的
编辑工具在保存时会悄悄去掉 BOM，而丢了 BOM 的文件只在 5.1 上出错、在 7 上完全正常，
没有这条检查就会一直漏过去。

已知未修（下一步处理）：5.1 上 Unit 有 6 项、Smoke 有 1 项失败，全部源于测试夹具写
临时文件时没指定编码（5.1 的 Set-Content 默认 ANSI），与产品代码无关。
 2026-09-26 22:05:42 +08:00
Shuery 2937eb6652 chore: 记录改造前基线 
改造开始前的完整状态，作为可回退的基点。此提交之后：Pester 175 项、零依赖套件 101 项全绿；PowerShell 5.1 尚不可用（源文件无 BOM）。

包含此前未提交的在制品：安全描述符套件、Hyper-V 实验环境（tools/lab）、agent 约定（AGENTS.md 与 docs/agents）。

.gitignore 增加 *.key / *.pfx：BackupConfig.psd1 的 PasswordFile 此前默认指向仓库内的 baknret.key，一次 git add -A 就会把口令提交进版本库。默认值在后续提交中改为空。
 2026-09-26 21:46:55 +08:00
Shuery e114cae8c8 P0-P3 全量重构：退出码 / 解析修复、manifest 与 7z t 校验、干跑、排除规则、日志、测试与计划任务 
P0 正确性
- 退出码：改用 .NET Process 直接启动、让子进程继承控制台，不再用 Start-Process -PassThru
  （在 7.7.0-preview.4 上 ExitCode 恒为 $null，会把成功的压缩判成失败）；
  7z / RAR / tar 三条解压分支统一走同一个取退出码的封装。
- BackupList 解析：先按第一个 :: 切段再处理引号（整行被一对引号包住的写法不再把排除表
  吞进路径）；排除表同时接受 , 与 ;（旧实现只认 ;，导致排除从未生效）；支持 :- / :+ / @flag。
- 补回 .ssh 与孤儿归档：.ssh 进清单；孤儿归档在备份端也做审计并点名；
  带 -Only / -Skip 时不再把未选中的归档误报成孤儿。
- Resolve-BackupEntry 里 $rootName 在赋值前被引用（会读到外层作用域残留值），已提前赋值。

P1 归档可靠性
- 每个条目写进 manifest.json：源、归档、时间、退出码、校验结果、失败原因，
  并区分 warnings（在位归档）与 attemptWarnings（本次尝试）。
- 归档后做 7z t 内容校验，先写 .tmp、校验通过再原子替换（File.Move overwrite）。
- manifest.roots 记录归档内**真实**的顶层条目名（原先记的是软件名，Edge 实际是 "User Data"）。

P2 可用性
- Restore 支持 -WhatIf / -DryRun / -VerifyOnly / -Only / -Skip；
  这三种"只看不写"的模式一个字节都不写（原先会写回 manifest.json）。
- Edge 等高缓存条目加排除规则并实测：1781 MB / 27961 项 -> 72 MB / 2294 项；
  书签、密码、Cookies、偏好、历史、IndexedDB、Local Storage 全部保留。
  普通模式是相对归档根目录锚定的，嵌套的那些（如 OneAuth\WebView2 里的 Crashpad）
  改用 ! 组件形式才会命中。
- 日志落盘 logs/<backup|restore>-<时间戳>.log；退出码按失败数返回。
- tools/Register-BackupTask.ps1 注册每日计划任务；tools/Rename-Archives.ps1 迁移旧归档名。
- root= 标记此前静默失效，现在明确告警（该功能尚未实现）。

P3 测试与验证
- tests/BakNRet.Tests.ps1：Pester 5 套件 62 项（含用子进程跑 Backup.ps1 / Restore.ps1
  的端到端与针对上述缺陷的回归）。
- tests/Run-Pester.ps1 + tools/Install-TestDependencies.ps1：把 Pester 装到仓库内 .tools/，
  不动机器上的全局模块（系统自带的 3.4.0 缺 Should -Be）。
- tests/Restore-Drill.ps1：真实归档恢复演练，明确区分"源在备份后变过"与"归档/解压有问题"。
- tests/Run-Tests.ps1（49 项，零依赖）与 tests/Run-E2E.ps1（23 项）继续可用；三套共 134 项全通过。

真实机器验证
- 生产归档 22/22 通过 7z t；-VerifyOnly 不再改动 manifest.json（SHA256 前后一致）。
- 真实恢复演练 12/12 通过，27,670 个文件与活源逐字节一致。
- 修复了生产 scoop-persist.7z：原先只有 90 字节（空归档）而源有 1.3 GB，
  重打包后 233 MB，恢复演练 26981/26981 全部一致。
 2026-09-21 23:02:47 +08:00
Shuery 045d51ac9c 引入软件名录：清单写软件名，归档名也用软件名 
新功能
- 新增 SoftwareCatalog.psd1 —— "软件名 -> 目录"映射表，BackupList.txt 里
  直接写软件名即可，归档名也就是软件名（FooClolor.7z），
  不再是 FooClolor_from_C_+Programs.7z 这种由路径拼出来的名字。
- 三种写法可混用：软件名、字面路径（现有清单无需改写）、软件名 @pathname。
- 名录支持前缀补全（legendary -> legendary_2.0.4，只认 <名>_* / <名>-*）、
  Variants（同名目录在多处）、Includes（分文件维护）。
- tools/Rename-Archives.ps1：存量归档重命名，默认试运行，逐份大小校验并重建 manifest。
- 归档名重复直接报错，不再静默互相覆盖。

两套测试全绿：单元 42 项、端到端 23 项（新增名录命名/解析/迁移用例）。

过程中修掉的缺陷
- Resolve-BackupEntry 里 @pathname 与 Unresolved 分支顺序错误，
  @pathname 会被静默吃掉（改名后仍用软件名）。
- 源目录被删除时解析器丢掉 Sources，导致恢复端把软件名当路径、
  报 "Cannot bind argument to parameter 'Path' because it is an empty string"。
  恢复的语义恰恰是"源不存在就要还原回去"，现在 Sources 照旧给出。
- 源存在性检查曾被漏掉，Get-Item 对不存在路径抛异常会中断整轮备份；
  且不能用 Join-Path 探测——目标盘符不存在时它会直接抛异常。
- 计划任务脚本外的 Caller 需要 -DryRun 才能验，已实跑确认。
 2026-09-21 20:55:19 +08:00
Shuery dbc0c00554 重构为可核对、可恢复的备份工具（P0-P3） 
修复（P0）
- 退出码：改用 .NET Process 继承控制台启动外部命令。Start-Process -PassThru 的
  ExitCode 在 PowerShell 7.7.0-preview.4 上恒为 $null，会把成功的压缩判成失败，
  并让 "exit 2 -> 删档重试" 的自愈分支永远不可达。
- BackupList.txt 解析：先按第一个 :: 切开再处理引号，修正整行被引号包住时
  排除表被吞进路径的问题（该条目此前被静默跳过，其 2.8 GB 归档成了孤儿）。
- 排除分隔符同时接受 , 与 ;：此前解析器只认 ; 而清单里写的是 ,，
  等于所有排除规则都没生效。
- 7z 排除参数不再嵌引号，含空格的模式自动转成 ?：旧写法 -x!"路径" 会让引号
  成为模式的一部分，导致排除对所有条目都失效。

加固（P1）
- 先写临时归档 -> 7z t 校验 -> 原子替换，中断不再污染正式归档。
- 放弃 7z 的更新模式 u：固实压缩下收益极小，却让排除规则改动与已删文件
  永远进不了归档。
- 新增 Backups/manifest.json 与 logs/*.log，跳过/失败有据可查。
- 结尾按失败数 exit；恢复支持 -WhatIf / -DryRun / -VerifyOnly / -Only。
- 恢复优先用 manifest 定位归档，并精确比较 BaseName（不再用 -Filter 通配）。
- 修正 tar 分支用 $LASTEXITCODE 判断成功与否的缺陷。
- 有警告（文件被占用）时拒绝用不完整的归档覆盖完整归档，需显式 -AcceptWarnings。

策略与安全（P2）
- Edge 条目加排除规则：解压后 4.22 GB 中 3.79 GB 是可再生的缓存/遥测/扩展本体，
  保留书签、密码、偏好、历史与站点数据。
- 可选 7z 加密（@encrypt 标记或全局开关），取不到口令时明确失败，绝不写明文。
- 磁盘空间守卫：放不下就跳过该条目，低于阈值告警。

工程化（P3）
- 新增 BackupConfig.psd1、README.md、.gitignore。
- tests/Run-Tests.ps1（32 项）与 tests/Run-E2E.ps1（16 项端到端验收）。
- tools/Register-BackupTask.ps1 注册每日计划任务。
- 归档命名算法保持不变，已有归档不会失联。
 2026-09-21 20:10:18 +08:00