Shuery/BakNRet
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
53 Commits 1 Branch 0 Tags
effc38fdd3aff35040854ea24b274a33e230d41d
Commit Graph
53 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
Shuery effc38fdd3 feat(tui): 名录编辑器循环 + 挂进 Edit-Config（第三轮第二块·完成） 
装配：Get-BakNRetCatalogField → 菜单选字段 → Read-BakNRetLine → Set-BakNRetCatalogField → Save-BakNRetConfigFile（校验通过才原子替换 + 时间戳备份）。

菜单里**只列可编辑的字段**（单行的 Encrypt / Description）：把只读的 Path / Exclude 也列出来再拒绝，会让每个只读项浪费用户一次回车。

校验用模块自己的 Import-BaknretDataFile：这份名录有 $( ) 动态表达式与跨行拼接，普通数据文件读取器读不了 —— 而正是它保证"改完整份文件还能被程序读回来"（值能读回来才算改成功）。定位用 (软件名, Slot, 字段名) 三元组，因为同一软件可以有多个 Slot。

Edit-Config 的三个界面（清单 / 设置 / 名录）至此全部完成。

判据 9 条：改一个值后只动一行、注释行数不变、改完能读回新值、留下时间戳备份且备份里是原文；取消时不写盘也不产生备份。

验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。
 2026-09-27 21:30:14 +08:00
Shuery 8c018533c9 feat(tui): 名录字段的读改核心（第三轮第一块） 
先侦察事实（232 行、71 个 Slot 级字段）：**可编辑面比预想的还窄，边界落在一条可判定的规则上** —— Encrypt 19 个全是单行（可编辑），Description 24 个单行 + 1 个跨行（Edge 那条多行说明，只读），Path / Exclude 一律只读（Scoop 三条带 $(if ($env:SCOOP_GLOBAL){...}) 表达式、Edge 的 Exclude 是跨行拼接）。

规则：**只有单行的 Encrypt / Description 可编辑** —— 与 ADR-0013 的"按能不能安全往返来定"一致："改一行"对动态表达式与跨行拼接没有明确含义。

扫描时跳过块注释：文件头部模板里有 SoftWareName = @{ ... } 示例，纯文本扫描会把它当成一个软件（实测踩到）。定位靠 (软件名, Slot, 字段名) 三元组且要求唯一命中，命中 0 个或多个都抛错。

实测五个事实：认出 70 个字段、可编辑 43 个（19+24）、往返**逐字节相同 = True**、真改一个只动一行、Edge 的跨行 Description 正确地只读。

过程里两处自己的坑都被门禁逮住：插入的测试代码带过一行手滑垃圾（Parse 层当场报），以及函数文档注释里写了块注释的闭合符号 —— 它提前结束了那段注释，后半句变成代码，而它是**合法语法**所以解析层抓不到、跑到才炸（与"左边空的赋值"同族）。

验收：test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 21:25:36 +08:00
Shuery 4aa44e8965 feat(tui): 配置编辑器循环 + 挂进 Edit-Config（第二轮第三块·完成） 
装配：Get-BakNRetConfigSetting（读）→ 菜单选设置 → Read-BakNRetLine（输入新值）→ Set-BakNRetConfigSetting（只改那一行）→ Save-BakNRetConfigFile（校验通过才原子替换 + 时间戳备份）。

输入行**从空开始**、当前值只作提示：预填当前值看着贴心，实际等于逼用户先删一遍（对 'Backups' 这种带引号的原文尤其别扭）。

校验用 Import-PowerShellDataFile：这份配置里没有动态表达式，能被它读回来是个**强校验** —— 比"语法能不能过"更强，它还能抓出"值是合法语法、但结构不对"。它只接受文件路径，所以先把候选文本写到临时文件再读。

Edit-Config 的 -Target Settings 与菜单里的"设置"都挂上了同一个编辑器；-Target Catalog 仍明确报"还没做（第三轮）"。

判据 9 条：改一个值后只动一行、注释行数不变、新值落盘、留下时间戳备份且备份里是原文；取消时不写盘也不产生备份。

验收：test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 21:10:15 +08:00
Shuery 92bbc995c4 feat(tui): 输入行控件（第二轮第二块） 
TUI 里唯一缺的控件：读一行文本（字符追加 / Backspace 删除 / Enter 确认 / Esc 取消）。

为什么不用 Read-Host：TUI 的所有输入都走同一个 -Driver，门禁才能用 -InputScript 把"输入一个值"这一步也驱动起来 —— Read-Host 无法脚本驱动，会在门禁里挂住，而挂起比变红糟得多。

为什么 Esc 返回 $null 而不是空串：空串是"把值改成空"这个**合法意图**，取消是另一个意思，两者必须能区分，否则调用方会把"用户取消"当成"用户要清空它"。

方向键等非字符键一律忽略（在输入行里按方向键不该有副作用）；字母按小写存（与键名归一化一致）。判据 8 条，全部按键序列驱动。

验收：test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 21:05:14 +08:00
Shuery 7733b1bf6d feat(tui): 配置标量的读改核心（第二轮第一块） 
先侦察事实：BackupConfig.psd1 共 99 行 —— 52 行注释、18 行单行标量、3 处嵌套哈希、1 处数组、1 处行内空哈希（SidMap = @{}）。所以"外科式改一个值"的边界很明确：**只认单行标量**。值跨行或本身是集合时，"改一行"这个动作没有明确含义 —— 那种就不该在界面上提供（如实显示为只读）。

路径用点号拼（Snapshot.Enabled）：同名键在不同嵌套里会出现（Enabled 有两处），只用键名会把它们混成一个。非标量（行内哈希、数组）显式排除。读出来的是**含引号的原文** —— 原样写回才逐字节等价。

判据 12 条，核心是往返：**把每个标量设成它当前的值，文本必须逐字节相同**（含键名对齐与全部注释）；真改一个时只有那一行不同、注释行数不变、改完还能读出新值；找不到路径或不是标量必须抛错而不是静默不动。

真实配置上的实测：认出 18 个标量（含 3 组嵌套的点号路径，排除了 SidMap 与 DefaultExcludes），**往返后逐字节相同 = True**。

过程里插入的测试代码带过一行手滑的垃圾（被 Parse 层当场抓住 —— 它是这个仓库最便宜的一道闸），以及一条期望值写错（忘了 Value 含引号）。

验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。
 2026-09-27 21:00:07 +08:00
Shuery c2bae35506 feat(tui): 主入口 Manage-Backup 与配置入口 Edit-Config（第一轮第六块·完成） 
Manage-Backup.ps1：不带参数进 TUI 主菜单（备份 / 恢复 / 配置）；带 -Action 直接做那个动作，可配 -Quiet 走无头。退出码原样传出（计划任务靠它）；只有两种情况由它自己给码：进不了交互界面（2）与菜单里按 Esc（0）。

动作目前仍是**子进程**：一份编排、两个前端是终局目标（ADR-0012），但那要求先把编排从入口脚本下沉进模块。先让 TUI 能用起来，等下沉做完把子进程调用换成进程内直调，界面层不受影响。

-Quiet 与交互两条路的输出处理**故意不同**：-Quiet 时调用方要拿输出（管道 / 日志 / 计划任务），所以捕获并转发；交互时让子进程继承控制台，输出实时、顺序正确、还能接键盘。这套转发收进模块函数 Invoke-BakNRetEntryScript（垫片与主入口共用同一处逻辑）。

Edit-Config.ps1：把已做好的清单编辑器挂上（外科式改写 + 校验通过才落盘 + 时间戳备份）；设置与名录两个界面明确报"还没做"并返回非零，而不是假装成功。

判据 7 条。过程中夹具又踩了"& 不传退出码"这个事实（我在垫片那层修过，却在测试夹具这一层又犯）—— 所以断言里改用 -File 调入口；输出检查走**文件重定向**而不是管道捕获（与 E2E 同一个理由：沙箱下给子进程建管道可能失败，写文件不会）。

验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。
 2026-09-27 20:41:39 +08:00
Shuery 4e3c0461c0 refactor: 入口改名（Backup/Restore -> Backup-Data/Restore-Data）+ 只留一轮的垫片 
git mv 保留历史。旧名字留薄垫片：入口脚本是**外部接口**（README 二十多处引用、使用者的肌肉记忆、注册脚本里的路径），内部实现改名断了会当场报错，外部接口改名断了是静默没用 —— 后者对备份工具尤其不能接受（ADR-0012）。

垫片踩到四个坑，全部由门禁报出（E2E 与 Pester 集成用例本来就是通过子进程调这两个入口的，于是它们原封不动成了垫片的验收）：① `& script.ps1` 里子脚本的 exit 不会把退出码传到父脚本的 $LASTEXITCODE —— 会把失败变成成功，而计划任务靠退出码判断成败；② 调用方传 -Verbose 时垫片里的 Import-Module 会多打一行加载信息，顶掉测试的输出断言；③ 不重定向时子进程的输出到不了调用方（父进程的 stdout 常常是管道，而 .NET 起的进程默认只继承控制台）—— 改成显式重定向 + 异步读转发（同步先读 stdout 再读 stderr 会在管道写满时死锁）；④ **`[CmdletBinding()]` 会把 -Verbose 当通用参数绑走，它不会落进 $Rest，于是没被转发给子进程** —— 而测试正是靠 -Verbose 拿那条 VERBOSE 级日志的。现在显式把 -Verbose / -Debug 加进转发参数。

参数引号化用模块自己的 ConvertTo-BakNRetNativeArgumentString（5.1 上 ProcessStartInfo.ArgumentList 不存在）。tools\Register-BackupTask.ps1 已同步改指 Backup-Data.ps1（4 处）。

门禁新增一条机械检查：**源码里不得出现"左边空的赋值"** —— 它是"用双引号拼代码导致 $变量 被插值成空"那个坑的指纹（合法语法、Parse 层抓不到、只有跑到才炸，同一块代码里出现过五次）。垫片全部用单引号 here-string 生成，零插值。

验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。
 2026-09-27 19:51:24 +08:00
Shuery 5df40d3341 feat(tui): 清单编辑器循环（第一轮第五块·装配完成） 
装配：选行 → 选新方向 → 逐行校验 → 校验后原子保存 + 时间戳备份。输入走 -Driver，所以门禁里能用 -InputScript @('Enter','Down','Enter') 走完整流程，断言看返回值与**文件内容**，不需要捕获控制台输出。

四条"不猜"：取消时什么都不写也不产生备份；方向菜单**预选当前值**（不预选的话"连按两次回车"会把字段改成菜单第一项 —— 不是没改，是改错了）；方向没变直接返回"没有变化"；保存前逐行校验（每行都要能被 ConvertFrom-BackupListLine 解析）—— 这正是 TUI 编辑器比手改安全的地方。

这个函数我试了两次才落地，两次都栽在同一件事上：**用脚本做多行字符串替换时，换行被折成空格**，于是注释与赋值落进同一行、被整段注释掉（症状是"对象没有属性"/"流程莫名走取消分支"）。所以这条现在当硬约束执行：多行代码一律整份写文件，不做插入+删除式的拼接。

判据 12 条，覆盖保存 / 取消 / 无变化三条路径，并逐条断言注释行与未编辑行一字不动、备份里存原文、取消时不新增备份。

验收：test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 16:40:38 +08:00
Shuery e1fe99671b feat(tui): 改方向（第一轮第五块·编辑动作） 
清单上最常改的就是方向，而它**能在文本层精确完成**：加/去一个行首标记即可，不需要把整行拆成字段再拼回去。后者要在 Overrides / Flags / 引号 / 转义之间做逆向，任何一处不精确都会把用户的清单改花 —— 外科式改写的底线是"只动我要动的那一处"（ADR-0013）。

**保留用户的写法风格**：仓库的真实清单里同时存在贴着写（+WindowsTerminal）与留空格（+ WindowsTerminal）两种，统一成一种意味着顺带改动了本不该碰的行。这就是"改一个字段却多出几十行 diff"的来源。断言里两种风格都钉住了。

注释行没有方向可改，直接抛错：静默返回原样会制造"改了但没变"。

判据 12 条，其中往返那条最强：**把一行设成它当前的方向，必须原样返回**（含带注释与修饰符的行）。

验收：test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 16:25:38 +08:00
Shuery 59ec5a21d4 feat(tui): 校验后原子保存 + 时间戳备份（第一轮第五块·地基） 
三个配置编辑器共用的这块地基（ADR-0013）。顺序是刻意的：① 先校验（调用方给的 -Validate 回调）；② **只有校验通过才备份与写盘** —— 校验没过还留下备份会让人以为"动过了"；③ 原子替换走 Write-BaknretAtomicText。返回结果对象而不是抛异常：TUI 要把错误显示出来让人继续改，而不是把界面炸掉（"TUI 异常不改退出码"这条同样适用）。

给 Write-BaknretAtomicText 加了一个可选 -Encoding（不传时沿用原行为，现有调用点不受影响）。原因：它原先固定用日志编码（无 BOM），而三个配置文件都是带 BOM 的 —— 丢掉 BOM 会让 5.1 把整个文件按 GBK 读，中文全成乱码。这类"编码悄悄变了"的错不会报错，只会让文件在某一个 PowerShell 版本上读出来是乱码。

判据（断言 10 条）：校验不过时不写盘、不产生备份、错误原文能带回去；校验通过后新内容落盘、备份里是**原文**、且写回**保留 UTF-8 BOM**（逐字节验 EF BB BF）。

验收：test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。
 2026-09-27 16:22:21 +08:00
Shuery 54972ab341 feat(tui): 清单行表与单行替换（第一轮第五块·核心） 
外科式改写的地基（ADR-0013）：Get-BakNRetBackupListRow 把清单文本拆成带**行号**的行表，Get-BakNRetBackupListRow 之外的行一字节不动。行表刻意保留注释与空行 —— 只在表里放"真正的条目"会让行号错位，改一行就会连锁改掉别处。

解析器给的 Record.Raw 就是原始行文本，所以"没被编辑的行写回原样"是天然的：注释、对齐、$( ) 表达式、跨行拼接都不会被碰到。这也是它比"解析成对象再序列化"安全的地方。

行号越界**抛错**而不是静默不动：静默不动会制造"保存成功但其实没改"，而用户看到的是一份以为改过、其实没改的配置。

判据是 spec 里那条往返断言的文本层形式：每行原样写回后**文本逐字节相同**；改一行时只有那一行不同、注释行数不变、原文本不被就地改动。

验收：断言 13 条；test.ps1 9/9 全绿（5.1 与 7）。
 2026-09-27 16:18:27 +08:00
Shuery 835fb0cf2b feat(tui): 菜单渲染与循环（第一轮第四块·下） 
形态是行内（ADR-0010）：菜单按普通行往下打，之后每次按键只把那几行原地重画（记下起始行再定位回去）。不做全屏、不切备用缓冲区 —— 崩了的时候滚屏里还留着上文，而"终端被 TUI 弄乱"是这类代码最难排查的故障。

没有控制台时只打一次、不重画、不抛错，靠 -Driver 里的 -InputScript 驱动 —— 同一个循环在真终端与门禁里走**同一条代码路径**，断言看的是返回值（Action/Index/Chosen/Checked），不需要捕获控制台输出。

两处刻意的不猜：空菜单直接返回 cancel 并说明原因（没有可选项时不该等按键 —— 第一次使用时归档目录就是空的，在计划任务里等按键等于挂起）；绝不 exit、绝不碰退出码（TUI 的异常不该污染备份结果）。

这块的断言按**数量分档**写（0 项 / 1 项 / 3 项）——上一块的单键 Bug 正是藏在"1 项"这个档位里，而当时只跑了 3 项的序列。

验收：断言 10 条；test.ps1 9/9 全绿（5.1 与 7）；真实清单只读冒烟 4/4。
 2026-09-27 16:13:57 +08:00
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 60f2ae3e0f docs: TUI 与入口重组的设计记录（4 条 ADR + 验收锚点） 
grilling 三轮把设计树走完了，这里把它落成文件，避免决策只活在对话里。

ADR-0010 零依赖自研 TUI：三个候选库全部实测排除 —— ConsoleGuiTools 的 PSGallery 元数据声明最低 7.2（5.1 装不上）；Spectre.Console 0.49.1 能在 5.1 加载但要塞 4 个第三方 DLL 且不支持鼠标；Terminal.Gui 1.15.0 能反射接线到真的渲染出窗口，但 Application.Shutdown() 在两端都抛 NRE。同时记下两条实测坑：无控制台时 $Host.UI.SupportsVirtualTerminal 会撒谎返回 True（第一道闸门必须是 [Console]::IsOutputRedirected），以及 5.1 的 RawUI.LengthInBufferCells 对中文返回 2、对边框字符返回 6（都不能用来排版）。

ADR-0011 进度回调这个例外：它是注入点不是状态，无头路径为 $null 时行为与今天完全一致。

ADR-0012 入口改名与垫片：这次留垫片而 Common.psm1 直接删，是因为前者是外部接口（断了是静默没用）后者是内部实现（断了当场报错）。并纠正了自己的一个伪前提 —— 本机实测没有注册任何 BakNRet 计划任务。

ADR-0013 TUI 写配置：外科式改写 + 校验通过才原子替换。硬事实是 SoftwareCatalog.psd1 根本不能被 Import-PowerShellDataFile 读入（动态表达式），任何"解析成对象再序列化"的方案都会毁掉表达式与注释。

.scratch/tui/spec.md 是这次改造的验收锚点：9 条已定决策 + 三轮的判据 + 风险表。

验收：Parse 两版仍绿。
 2026-09-27 15:27:01 +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 e8f0a5ae19 docs: 更新 README（口令一节、测试计数、虚拟机验证）并修掉拆文档时留下的重复标题 
README 是被人真读的那份文档，而这一路改动让它有三处不再准确：

  1. 「口令放在哪里」整节是错的：它写着"默认留空、必须放在仓库之外"，而按你的决定，出厂默认值就是仓库根的 baknret.key（靠 .gitignore 兜住不被提交）。整节重写：如实写明这是一次取舍（省事 vs "不提交"依赖一个规则文件），并补上"相对路径按仓库根解析、不按工作目录"这条 —— 计划任务的工作目录是 C:\Windows\System32，按工作目录解析会让加密条目以"拿不到口令"失败而配置看上去没问题。关键提醒也改了：已经在仓库根的人什么都不用做，想搬走才需要动。

  2. 测试项数过期：Pester 150 -> 183（含安全描述符套件）、零依赖 101 -> 111。

  3. 新增「在 Hyper-V 虚拟机里验证」：这一层本机跑不到，而它覆盖的正是最需要真环境的那条路径 —— 安全描述符回放（把属主改成 NT AUTHORITY\SYSTEM、再靠 CREATOR OWNER 判断恢复后归谁）。附最近一次四步的结果与命令。

另修一个我在拆分 README 时留下的缺陷：4 个二级标题各重复了一次（块替换保留了原标题、又插入了带同名标题的指针行）。markdown 不经过 test.ps1，所以当时没被拦住 —— 现在按"相邻同标题只留一行"折掉，并复查为 0。

验收：test.ps1 9/9 全绿（7 与 5.1）。
 2026-09-27 14:10:04 +08:00
Shuery 2446c7c5c7 docs: 把"前缀补全只搜一层、且不提供深度开关"写成决策记录 
深度递归不是"补上一个没实现的功能"，而是引入一个具体的错。写成 ADR-0009 连同实测数据：26 条真实 Path 里 19 条直接命中、3 条补全救不了（软件没装）、1 条（%UserProfile%\fnm）在 5 层内会命中 AppData\Local\fnm_multishells 这个临时目录 —— 静默备份错的东西还报成功。

同时在 Find-BakNRetChildDirectoryByName 的注释里指回 ADR，免得下一个人把它当"漏了的功能"补回去。

顺带修掉 README 里一句与实现不符的话：原先写"前缀补全命中多个候选（同名目录分散在多处）"，而只搜一层时多个候选只可能来自同一个父目录（既有 X 又有 X_后缀）。

全仓复查：MaxDepth / CatalogMaxDepth / 最大深度 / 向下找几层 除 ADR-0009 的历史叙述外 0 处。

验收：test.ps1 9/9 全绿（7 与 5.1）。
 2026-09-27 11:34:34 +08:00
Shuery 520257b5e5 fix: 口令文件默认值回到仓库根（按你的决定），并让相对路径与工作目录无关 
你的决定：口令文件继续放在仓库根，靠 .gitignore 的 *.key 兜住"不被提交"。我把出厂默认值改回 baknret.key，并把配置注释从"必须放在仓库之外"改成如实说明这是一次取舍：省事 vs 「不提交」依赖一个规则文件（git add -f、或整目录复制到别处再初始化仓库时，口令会跟着走）。

顺手修掉一个潜在陷阱：口令文件写相对路径时，原先的 Test-Path 是按**当前工作目录**找的。计划任务的工作目录通常是 C:\Windows\System32，在那里 Test-Path baknret.key 为假，加密条目就会以"拿不到口令"失败 —— 而配置看上去毫无问题。现在相对路径按仓库根解析（复用上一轮抽出来的 Resolve-BakNRetRootedPath）。

证据：把工作目录切到 C:\Windows\System32 再跑真实清单只读冒烟，仍然 4/4 通过（那份真实配置里有 5 个加密条目、口令文件就是仓库根的 baknret.key）。

验收：test.ps1 9/9 全绿（7 与 5.1）。
 2026-09-27 11:21:43 +08:00
Shuery 120cf3584b fix: 清掉改造过程留下的陈旧引用（代码改了、文档还写着旧的） 
这一轮做的是交付一致性检查：把这一路改掉/移走/删掉的每个符号在全仓（含文档）扫一遍。42 处命中里 38 处是正当的 —— CHANGELOG 与 ADR 里讲“原来是什么”属于历史叙述，test 里的 Assert-FileExists 是因为我只抑制了误判而没有改名。剩下的 4 处是真陈旧：

  * README 还在配置表里写着 CatalogMaxDepth，而那个配置项上一轮已经整条移除；

  * Get-BakNRetItemArchiveName 的 param 里还留着一个内联的 [int]$MaxDepth = 5（上一轮的删除按行匹配，没覆盖到这种写在同一行的参数），它已经没有任何调用方传值；

  * tools\lab\README.md 与 docs\agents\domain.md 还写着模块叫 Common.psm1。

这正是这次改造从头到尾在抓的毛病：文档承诺的东西，代码已经不做了。区别是多了一个可执行的检查 —— 符号改名/删除之后，全仓扫一遍旧名字。

验收：test.ps1 9/9 全绿（7 与 5.1）、真实清单只读冒烟 4/4。
 2026-09-27 10:49:21 +08:00
Shuery c4452a749c refactor: manifest 的写入收进模块函数，依赖写在签名上 
Save-ItemRecord 原先直接用脚本级的 $manifest —— "这个函数会改全局账本"这条事实只存在于读代码的人的注意力里。搬进模块后 Manifest 是必填参数，13 个调用点每一个都能看出自己在动账本。

关键判断：**不需要接返回值**。$Manifest.items 是哈希表，传参是引用语义，函数里的写入直接落在调用方那份 manifest 上，所以调用点的形状只是"多了一个 -Manifest $manifest"，行为一字不改。这是"有状态依赖该做成什么"的答案里最省的一种：显式参数 + 引用语义。

两条刻意保留、容易被改错的语义也写进了注释并原样搬过来：warnings 与 security 描述的是"当前在位的归档"而不是"这次尝试"，只有真的换掉归档才更新 —— 否则"因不完整而保留旧归档"之后，下一次就失去保护了。

搬的过程里把 $Record.finishedAt 那行写坏了（外层双引号把 $Record 提前插值成空，文件里变成 ".finishedAt = ..."）。**注意这是上一轮刚记下的同一个坑**：往文件里写 PowerShell 代码时外层一律用单引号。这次是"绿了才提交"把它拦在提交之外 —— 流程修正当场生效。

验收：test.ps1 9/9 全绿（7 与 5.1）、真实清单只读冒烟 4/4。Backup.ps1 从 889 行降到 846 行。
 2026-09-27 10:45:57 +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 67ee2af006 refactor: 两个入口统一 7z 的查找方式（消除“备份找得到、恢复找不到”的隐患） 
原先同一段查找逻辑有两份：模块的 Resolve-BakNRetCompressionTool 里一份，Restore.ps1 自带的 Get-7zExecutable 里又一份（PATH → Program Files → Program Files (x86)）。两套写法哪怕只差一个候选路径，就会出现“备份找得到、恢复找不到”这种最难看的不一致。

抽成 Find-BakNRet7zExecutable，两边都改用它。**保持策略不同**：备份可以退到 RAR 或内置 ZIP（能打包就行），恢复必须真能解压 7z、找不到就明确报错 —— 所以抽出来的只负责“找 7z”，不负责“找不到怎么办”。我自己在抽之前差点把它当成顺手删的重复代码，看清楚才发现策略差异是刻意的。

验收：test.ps1 9/9 全绿（7 与 5.1）、103 个文件两版解析零错、真实清单只读冒烟 4/4、构建工具仍能合回单文件。当前查找器在本机解析到 C:\Programs\Scoop\shims\7z.exe，备份侧解析器仍返回 7z。
 2026-09-27 10:31:05 +08:00
Shuery fcf83ecb74 refactor: Restore.ps1 的条目筛选改用模块函数（去掉第二份副本） 
Test-EntrySelected 与上一个提交搬进模块的 Test-BakNRetItemSelected 是同一段逻辑：我在删之前先逐行比对过（把 $Only/$Skip 归一化后两边 7 行逻辑完全相等），确认是重复才删。

这是"入口下沉"里少见的零风险一块：不新增代码，只是让两份实现变成一份。Restore.ps1 从 884 行降到 870 行。

验收：test.ps1 9/9 全绿（7 与 5.1）、无解析错误、真实清单只读冒烟 4/4。
 2026-09-27 10:27:44 +08:00
Shuery bbfece10b6 refactor: 入口逻辑下沉第一块（路径解析与条目筛选） 
把两个内联函数从入口脚本搬进模块，它们正好覆盖下沉时最容易出错的三类依赖：

  * Resolve-BakNRetRootedPath（原 Backup.ps1 与 Restore.ps1 各一份同名副本）靠 $PSScriptRoot 找仓库根 —— 搬进模块之后 $PSScriptRoot 会变成**模块目录**，语义就悄悄变了。所以根目录改成显式参数，由调用方传 $PSScriptRoot。

  * Test-BakNRetItemSelected（原在 Backup.ps1 里）直接读脚本级的 $Only / $Skip。那种闭包依赖让它没法单独测：要测它就得先构造一个入口脚本。现在两个清单是显式参数。

  * 第三个函数 Get-7zExecutable 我**没有**动：它和模块里已有的 7z 定位功能重复，但两者返回的东西不同（一个路径字符串、一个带 Name/Command/Extension 的对象），合并要先确认语义，不能顺手删。记在下面待办里。

过程里翻车一次并当场修好：给调用点补参数时我是按"行尾追加"做的，结果 3 处把参数甩到了 `)` 或 `}` 外面（例如 `if (...) { continue } -Only $Only`）。**解析是零错的** —— 又一次"绿着但是错的"。修法不是继续追加，而是按内容精确定位那 4 行、把参数插到括号里面；修完先用 5 个即时探针确认两个函数真的能调起来（含 -Only 命中、-Skip 否决、绝对路径不被拼根），再跑全套。

验收：test.ps1 9/9 全绿（7 与 5.1）、102 个文件两版解析零错、构建工具仍能合回单文件。
 2026-09-27 10:25:05 +08:00
Shuery 60ecbc2933 docs: README 拆出四篇主题文档，本文件留总览与操作 
拆出软件名录（67 行）、清单语法（114 行）、归档布局与迁移（47 行）、安全描述符（69 行），共 297 行；README 从 653 降到 360 行，每节原位留一句摘要加链接。

为什么拆：这四块是「要查的资料」，README 剩下的是「要读的流程」。混在一起时，想查清单语法的人得先滚过一百多行总览；拆开后每篇也能被单独引用与单独评审。

搬运按标题抽取原文、不重打，并在写之前断言正文长度、写之后再读回断言一次（第一次尝试就是栽在没有断言上：@(a, b, $arr) 不会展开数组，而是把 $arr 拼成一行，结果四篇各只有 5 行、正文却已从 README 删除。那次已回滚）。
 2026-09-27 10:20:08 +08:00
Shuery fb0d93a25f Revert "docs: README 拆出四篇主题文档，本文件留总览与操作" 
This reverts commit 35aade63bc.
 2026-09-27 10:19:34 +08:00
Shuery 35aade63bc docs: README 拆出四篇主题文档，本文件留总览与操作 
拆出去的是最大且自成体系的那四块参考资料：软件名录（67 行）、清单语法（114 行）、归档布局与迁移（47 行）、安全描述符（69 行），共 297 行。README 从 653 行降到 360 行，每一节原位留一句摘要加链接。

为什么拆：这四块是"要查的资料"，而 README 剩下的（快速开始、文件说明、恢复语义、manifest、配置、加密、口令、计划任务、测试、验收、设计取舍、已知限制）是"要读的流程"。混在一起时，想查清单语法的人得先滚过 130 行总览。拆开之后每篇也能被单独引用与单独评审。

搬运用脚本按标题抽取原文，不重打，所以不存在抄漏的风险；拆完校验了每一条指向新文件的链接目标都存在。
 2026-09-27 10:17:19 +08:00
Shuery 232a82cd3c style: 逐条修静态分析告警（706 → 44），并把 MaxDepth 这条假承诺删掉 
修掉的：空 catch 5 处；名词白名单 7 处；default-value 开关、自带 -WhatIf、lab 的明文口令与 irm|iex 各挂抑制并写明理由。

MaxDepth：它是分析器拓出来的真 bug —— 参数声明了却从未使用，也就是配置里的 CatalogMaxDepth 是假的，前缀补全实际只查 1 层，而配置注释与 README 都承诺「向下找几层」。按确认过的原则处理：**先让文档不撒谎**，所以把整条链路去掉（配置默认值、三个函数的参数、70 处实参、配置注释），而不是留一个假旋钮。零行为变化。想真的支持多层补全时，那是一个独立决定。

剩下 3 条都是分析器的误判，而且我实测确认过其中一条：$sourcePath 被报「赋值后从未使用」，我照着改成 $null = 之后，Set-StrictMode -Version 3.0 下读未定义变量直接抛错，Security 套件的 BeforeAll 挂掉、4 条用例连带失败。恢复后才绿。

这一类误判有共同成因：静态分析看不到「在传给 Test-Case / It / Where-Object 的 scriptblock 里被使用」。所以我只对能证明是误判的挂抑制并写明理由，不为了数字好看去改代码。

验收：test.ps1 9/9 全绿（7 与 5.1）、100 个文件两版解析零错、Run-RealSmoke 4/4。
 2026-09-27 10:16:10 +08:00
Shuery 3a3a57a6a1 docs: 决策记录 8 条、变更日志、README 的验收与口令两节 
0007 与 0008 是本次改造新产生的决策（原计划 6 条）。它们同样满足「后人会问为什么」：把运行锁改成互斥体、或给库里 27 个函数补上 SupportsShouldProcess，都是看起来更规范的错法。

CHANGELOG.md：把 README 里那 33 行「相对旧版修了什么」整节搬过去，并补上本次改造的记录（11 条修复 + 6 条结构与规范，每条修复都写明现象与现状）。README 那一节换成指针。

README 新增两节：「验收与静态分析」（六个层次、Run-RealSmoke 为什么独立存在、以及那 6 条格式规则默认 Disabled 这个容易漏掉的事实）；「口令放在哪里」（默认留空不是遗漏，附迁移与验证命令）。

.markdownlint.json 照 PowerShell 主仓库的实践（default true、行长 240），只把 MD024 从关闭改成「仅同级不重复」，因为变更日志需要重复标题。顺带按 .editorconfig 把 .md 的 BOM 去掉。
 2026-09-27 10:01:54 +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 102a3e038d fix: 口令文件的出厂默认值不再指向仓库内的文件 
BackupConfig.psd1 原来写的是 PasswordFile = 'baknret.key' —— 相对路径，解析到仓库根，
而根目录真的有这个文件（实测它在服役：用它跑 7z t 得到 0，manifest 里 5 个条目标着
encrypted = true）。也就是说"出厂默认值"在教人把口令放进版本库，而同一份配置的注释却写着
"文件必须在仓库之外"。

现在默认留空，并把注释改成明确的约束：口令只能来自 -Password / $env:BAKNRET_PASSWORD /
仓库之外的 PasswordFile / 交互式询问（仅交互式会话）。取不到口令时加密条目**明确失败**，
绝不退化成明文归档 —— 这条行为没变，也没有放宽。

配套：.gitignore 早已加上 *.key；密钥文件本身怎么搬是使用者的动作（我不会自动搬你的
密钥），迁移命令见 README 与本次改造的收尾说明。
 2026-09-27 09:34:43 +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 78f43c8cc9 docs: 建立 CONTEXT.md 术语表 
13 个词，按「输入 / 归档布局 / 产物与审计 / 名字」四组，每词带 _Avoid_ 同义词。它是本次改造落定的用词记录：清单 / 条目 / 方向 / 软件名录 / Slot / 覆盖 / 排除模式 / 前缀补全 / 归档 / 归档项 / 旧布局 / manifest / 安全描述符旁挂 / 孤儿归档 / BakNRet。
 2026-09-27 09:23:48 +08:00
Shuery 10f97246c8 fix: lab 的 ACL 场景在 5.1 上会被原生命令的 stderr 中断 
tools\lab\payload\run-acl-scenario.ps1 是 $ErrorActionPreference = Stop，而它要大量调用
rmdir / takeown / icacls / scoop / code —— 其中 rmdir 与 takeown 在"对象已经处理过"或
"连接点已经悬空"时就会往 stderr 写字。Windows PowerShell 5.1 会把那升级成终止性的
NativeCommandError（7 改了这条规矩），于是清理函数在设计要处理的**恰恰那个场景**里直接崩掉。

修法：新增 Invoke-NativeTolerant，在进入原生命令时把 EAP 放到 Continue、退出时还原，
把 stdout 与 stderr 合并返回；12 处调用全部收进它。判断"删掉了没有"本来就该用 Test-Path，
不需要让 stderr 变成异常。这与 tests\BakNRet.Security.Tests.ps1 里对 takeown / icacls
用的是同一招（那里已被 5.1 的失败实测逼出来过）。

范围说明：只改了 run-acl-scenario.ps1。provision.ps1 的同类写法**不需要**改 ——
它是 $ErrorActionPreference = Continue，那两处本来就不会踩。

验证边界（如实说明）：这个文件要 Hyper-V + 一台 VM 才跑得到，本会话无法执行它。
所以这一步的证据是：两个版本上解析零错（Parse 层覆盖）、12 处替换逐条断言命中、以及
diff 逐行复核。它是"降低风险"，不是"已验证修复"。

验收：test.ps1 9/9 全绿（7 与 5.1）；Run-RealSmoke 4/4 全绿。
 2026-09-27 09:22:45 +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 dda36cfae5 docs: 记录改造 spec（验收锚点） 
四件事的目标、9 条验收门槛、30 条已确认决策、十步执行顺序与回滚控制。每项改动都要能被其中某一条判成通过或失败。
 2026-09-26 21:47:29 +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 7173e8ae10 备份前空间预估；manifest 的 archive 字段只在文件真的存在时才写 
需求
- 写满盘这件事只做一件事：**备份前预测本次所需大小，并提示用户存储够不够**，
  不再往"更复杂的占用控制"方向做。

实现
- Backup.ps1 新增只读的"备份前空间预估"，在动手之前按清单顺序模拟一遍：
  * 逐个条目枚举源目录得到真实源大小/文件数，并读取现有归档大小；
  * 沿用主循环那套"源未更新就跳过"的判断，所以列出来的就是**本次真的会重打**的条目；
  * 估算模型：临时归档写完时旧归档还在，那一刻占用 = 当前累计净增量 + 本次预估；
    原子替换后净增量 = 预估 − 旧归档大小；峰值取整个过程的最大值；
  * 预估归档大小：有历史归档取 min(源大小, 旧归档 × 1.3)，没有则按"不压缩"的悲观值；
  * 打印：可用空间、要重打的条目数（及跳过/缺源的数量）、逐条目明细（前 15 条）、
    预计峰值新增与净增量，最后给一句结论——"空间足够"或"空间可能不够！…差 Z GB"。
  * 不够时**只告警、不中断**：真正放不下的条目仍由逐条目守卫跳过。
- 新增 Sync-BaknretManifestArchive（Common.psm1，Backup/Restore 都在写 manifest 前调用）：
  维持不变式"manifest 里写了 archive 的记录，磁盘上就一定有那个文件"，
  把指向不存在归档的 archive 字段清空，但保留 source / action / 历史计数。
  这样"源不存在的条目"不会再让 Restore 反复报"manifest 记录的归档不存在"，
  人工删掉归档（例如把它并进别的条目）之后记录也会自我纠正。

整理（本机备份集）
- 按用户确认，删除了已被 scoop.7z 覆盖的 scoop-config.7z 与 scoop-persist.7z
  （删除前先 7z t 复验 scoop.7z：233 MB / 29478 项 / 顶层 [persist, scoop]），
  并清掉 manifest 里这两条历史记录；24 条记录的 archive 现在全部存在于磁盘上。

测试
- Pester 88 项、零依赖单元 49 项、端到端 23 项，全部通过。
  新增覆盖：对象数组名录、两种写法 × :+/-、同名目录拒绝执行、行尾 # 说明、
  孤儿审计（含"manifest 里还有历史记录"的说明）、archive 字段一致性、空间预估输出。
 2026-09-22 08:26:09 +08:00
Shuery 43fa4e52dd 清单格式：两种写法（软件名 / 手写目录）都支持 :+ 追加与 :- 排除；名录改用对象数组并逐条介绍目录 
需求
- 支持两种条目写法：1) 直接写软件名录里的软件名；2) 用户手写目录。
- 两种写法都必须支持追加（:+）与排除（:-）。
- 软件名录要改进：scoop 合并成"一个软件 + 一个目录数组"。
- 运行时要把"分别是哪些目录、每个目录是干什么的、排除/追加的理由"讲清楚。

实现
- 名录（SoftwareCatalog.psd1 / Get-SoftwareCatalog）
  * 一个软件挂多个目录时写成**对象数组**：@{ Path = '...'; Description = '...' }；
    也接受纯字符串数组与旧的 @{ Dirs = ... } / @{ Variants = ... }。
  * 目录说明（Description）一路带到运行日志里。
  * "声明了但当前不存在"的目录不再被丢掉：备份跳过，恢复仍然知道它该回到哪个位置。
  * scoop 合并成一个数组条目（%UserProfile%\scoop\persist + %UserProfile%\.config\scoop）；
    ScoopApps-persist 保持独立条目 —— 它和前者末级名同为 persist，并进同一个归档会在包里撞名。
- 解析与解析结果（ConvertFrom-BackupListLine / Resolve-BackupEntry）
  * `:+` 以前只对"软件名且能解析出目录"的写法生效，**手写目录的 :+ 会被整段丢掉**；
    现在统一生效，且 :+ 后面写软件名会按名录展开。
  * 行尾 `# 说明` 解析成 Comment，运行时打印。
- 归档与恢复
  * 同一条目里两个同名目录：打包前明确报错（退出码 1），不再静默混成一棵树。
    （7z 命令行没有"入库改名"的能力，归档内顶层名只能是文件系统上的那个名字。）
  * 恢复时每个源只解出**它自己那棵子树**，不会再往别的父目录里复制兄弟目录。
- 可解释性
  * 新增 Write-BackupEntryPlan：打包前打印条目的目录（含来源与介绍）以及排除/追加的出处；
    Restore.ps1 同样打印"哪棵子树还原到哪、会新建还是覆盖"。
- 孤儿归档审计修正：判据只看当前清单，不再把 manifest 的历史记录当成"已知"。
  否则"条目被合并/改名后留下的旧归档"会被历史记录遮住，永远不会报警。

验证
- Pester 84 项、零依赖单元 49 项、端到端 23 项，全部通过。
- 真实机器：合并后的 scoop.7z 233 MB / 29478 项 / 7z t 通过，manifest.roots=[persist|scoop]；
  恢复演练 26982/26982 逐字节一致（.ssh、legendary、Aria 同批通过）。
- 迁移提醒：scoop-config.7z 与 scoop-persist.7z 已无清单条目指向，会出现在孤儿审计里；
  确认 scoop.7z 无误后可以自行删除。
 2026-09-22 08:18:16 +08:00