 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
|
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
|
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
|
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
|
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
|
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 |
|