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
1 parent 187549e2af
commit 60f2ae3e0f
@@ -0,0 +1,109 @@
+param([Parameter(Mandatory=$true)][string]$OutFile, [Parameter(Mandatory=$true)][string]$Work, [int]$HoldSeconds = 5)
+$lines = New-Object System.Collections.Generic.List[string]
+function L($s) { $lines.Add($s); [System.IO.File]::WriteAllLines($OutFile, $lines, (New-Object System.Text.UTF8Encoding($false))) }
+function Braino([string]$m) { return $null }
+L ("PSVersion: " + $PSVersionTable.PSVersion + "   CLR " + [System.Environment]::Version + "   Redirected=" + [Console]::IsOutputRedirected)
+$nstack = Join-Path $Work 'nstack111\lib\netstandard2.0\NStack.dll'
+$tg     = Join-Path $Work 'tg115\lib\net472\Terminal.Gui.dll'
+$sc     = Join-Path $Work 'sc049\lib\netstandard2.0\Spectre.Console.dll'
+function A([string]$fullName, [string]$asmName) { return ([AppDomain]::CurrentDomain.GetAssemblies() | Where-Object { $_.GetName().Name -eq $asmName }).GetType($fullName) }
+function GetT([string]$fullName) { return ([AppDomain]::CurrentDomain.GetAssemblies() | Where-Object { $_.GetName().Name -eq 'Terminal.Gui' }).GetType($fullName) }
+function GetS([string]$fullName) { return ([AppDomain]::CurrentDomain.GetAssemblies() | Where-Object { $_.GetName().Name -eq 'Spectre.Console' }).GetType($fullName) }
+
+L ""
+L "############ QUESTION: after Add-Type -Path, do PS type literals work? ############"
+Add-Type -Path $nstack -ErrorAction Stop
+Add-Type -Path $tg -ErrorAction Stop
+L ("  [bool]([Type]::GetType('Terminal.Gui.Application, Terminal.Gui'))  = " + [bool]([Type]::GetType('Terminal.Gui.Application, Terminal.Gui')))
+L ("  [bool]([Type]::GetType('Terminal.Gui.Application, ' + full))     = " + [bool]([Type]::GetType('Terminal.Gui.Application, ' + (GetT 'Terminal.Gui.Application').AssemblyQualifiedName)))
+L ("  script GetT('Terminal.Gui.Application')                          = " + [bool](GetT 'Terminal.Gui.Application') + "   <-- reliable in BOTH hosts")
+$litOk = $false
+try { $litOk = [bool]([Terminal.Gui.Application] -is [Type]) } catch { $litOk = "THREW: " + $_.Exception.Message }
+L ("  PS type literal [Terminal.Gui.Application]                        = " + $litOk)
+
+L ""
+L "############ A) Terminal.Gui 1.15.0 (net472) DRIVER-WIRED RUN ############"
+$tgResult = 'not-attempted'
+try {
+  $appT = GetT 'Terminal.Gui.Application'
+  $netT = GetT 'Terminal.Gui.NetDriver'
+  L ("  Application type : " + [bool]$appT + "    NetDriver type: " + [bool]$netT)
+  $initM = $appT.GetMethod('Init', [Type[]]@($netT, ($netT.GetInterfaces() | Where-Object { $_.FullName -eq 'Terminal.Gui.IMainLoopDriver' })[0]))
+  L ("  Init(NetDriver, IMainLoopDriver) overload: " + [bool]$initM)
+  if ([Console]::IsOutputRedirected) {
+    L "  stdout redirected -> Terminal.Gui CANNOT paint; skipping the live run (documented limitation)"
+    try { $initM.Invoke($null, @([Activator]::CreateInstance($netT), $null)) | Out-Null; L "  unexpectedly Init'ed" } catch { L ("  expected failure: " + $_.Exception.InnerException.Message.Split([char]10)[0]) }
+    $tgResult = 'blocked-by-redirect'
+  } else {
+    $drv = [Activator]::CreateInstance($netT)
+    $initM.Invoke($null, @($drv, $null)) | Out-Null
+    L "  Application.Init(NetDriver) -> SUCCEEDED *** Terminal.Gui 1.15.0 is LIVE inside PowerShell " + $PSVersionTable.PSVersion + " ***"
+    $winT = GetT 'Terminal.Gui.Window'; $lblT = GetT 'Terminal.Gui.Label'; $btnT = GetT 'Terminal.Gui.Button'
+    $w = [Activator]::CreateInstance($winT, [object[]]@('BakNRet / Terminal.Gui - PS ' + $PSVersionTable.PSVersion))
+    $l1 = [Activator]::CreateInstance($lblT, [object[]]@('Terminal.Gui 1.15.0 net472 - running on .NET Framework ' + [System.Environment]::Version))
+    $l2 = [Activator]::CreateInstance($lblT, [object[]]@('CJK cell-width check:'))
+    $l3 = [Activator]::CreateInstance($lblT, [object[]]@('  2 CJK chars -> 4 columns'))
+    $b1 = [Activator]::CreateInstance($btnT, [object[]]@('OK'))
+    $w.Add($l1); $w.Add($l2); $w.Add($l3); $w.Add($b1)
+    $w.X = 1; $w.Y = 1; $w.Width = 70; $w.Height = 9
+    $l1.Y = 1; $l2.Y = 3; $l3.Y = 4; $b1.Y = 6; $b1.X = 2
+    $homeT = GetT 'Terminal.Gui.Toplevel'
+    ($appT.GetProperty('TopLevel')).SetValue($null, $w)
+    $w.SetFocus()
+    $w.Redraw($w.Bounds)
+    $appT.GetMethod('Refresh', [Type[]]@()).Invoke($null, @()) | Out-Null
+    L "  Window(70x9) + 3 Labels + Button painted. Holding " + $HoldSeconds + "s..."
+    Start-Sleep -Seconds $HoldSeconds
+    $appT.GetMethod('Shutdown', [Type[]]@()).Invoke($null, @()) | Out-Null
+    L "  Application.Shutdown() -> clean"
+    $tgResult = 'WORKS'
+  }
+} catch {
+  L ("  Terminal.Gui FAILED: " + $_.Exception.GetType().Name + ': ' + $_.Exception.Message)
+  $ie = $_.Exception.InnerException; while ($ie) { L ("     inner: " + $ie.GetType().Name + ': ' + ($ie.Message -split "`n")[0]); $ie = $ie.InnerException }
+  $tgResult = 'FAILED'
+}
+
+L ""
+L "############ B) Spectre.Console 0.49.1 (netstandard2.0) REAL RENDERING ############"
+$scResult = 'not-attempted'
+try {
+  Add-Type -Path $sc -ErrorAction Stop
+  $ansiT = GetS 'Spectre.Console.AnsiConsole'
+  $tableT = GetS 'Spectre.Console.Table'
+  $extT = GetS 'Spectre.Console.TableExtensions'
+  L ("  AnsiConsole/Table/TableExtensions types: " + [bool]$ansiT + "/" + [bool]$tableT + "/" + [bool]$extT)
+  # Build a table WITHOUT AddRow extension methods (instance API only) to isolate extension-call support
+  $t = [Activator]::CreateInstance($tableT)
+  $colT = GetS 'Spectre.Console.TableColumn'
+  $t.AddColumn([Activator]::CreateInstance($colT, [object[]]@('项目 Item')))
+  $t.AddColumn([Activator]::CreateInstance($colT, [object[]]@('大小 Size')))
+  L "  2 columns added via INSTANCE AddColumn(TableColumn) -> OK"
+  # extension method called the PowerShell way
+  $addRow = $extT.GetMethod('AddRow', [Type[]]@($tableT, [string[]]))
+  L ("  found extension TableExtensions.AddRow(Table, string[]): " + [bool]$addRow)
+  $addRow.Invoke($null, [object[]]@($t, [string[]]@('中文备份 alpha', '1.2 GB'))) | Out-Null
+  $addRow.Invoke($null, [object[]]@($t, [string[]]@('beta', 'OK'))) | Out-Null
+  L "  2 rows added via reflection-invoked EXTENSION method -> OK"
+  $ansiT::Write($t)
+  L "  >>> AnsiConsole.Write(Table) with mixed-width CJK content rendered above <<<"
+  try { $ansiT::Markup('[red]red[/] [green]green[/] [bold]bold[/] [yellow]yellow[/]') ; L "  AnsiConsole.Markup color test -> OK" } catch { L ("  Markup FAILED: " + $_.Exception.Message) }
+  Write-Host ""
+  Write-Host "  -- Spectre.Console table rendered from PowerShell $($PSVersionTable.PSVersion) --" -ForegroundColor Cyan
+  $ansiT::Write($t)
+  Start-Sleep -Seconds 3
+  # Progress demo (bounded)
+  try {
+    $progT = GetS 'Spectre.Console.Progress'
+    L ("  Progress type: " + [bool]$progT)
+    $act = { }
+    L "  (Progress/Status need a script-block -> Action`1 delegate; skipped live run to stay bounded)"
+  } catch { L ("  progress probe failed: " + $_.Exception.Message) }
+  $scResult = 'WORKS'
+} catch {
+  L ("  Spectre FAILED: " + $_.Exception.GetType().Name + ': ' + $_.Exception.Message)
+  $ie = $_.Exception.InnerException; while ($ie) { L ("     inner: " + $ie.GetType().Name + ': ' + ($ie.Message -split "`n")[0]); $ie = $ie.InnerException }
+  $scResult = 'FAILED'
+}
+L ""
+L "RESULT: TerminalGui=$tgResult   SpectreConsole=$scResult"