WinUtil 项目契约深度解析：从 SPEC.md 看单脚本 PowerShell 工具包的构建、运行与安全模型

SPEC.md 是 WinUtil（Chris Titus Tech's Windows Utility）仓库根目录下的"项目契约"（Project contract），它定义了项目是什么、如何构建、如何运行，且对任何人类或 AI 读者一视同仁。本文以 SPEC.md 的原始骨架为主线——项目上下文、构建模型、运行时模型、UI 事件契约、配置契约、安全要求、文档站与测试 CI——并结合 Compile.ps1、scripts/start.ps1、scripts/main.ps1 等真实源码逐项印证，帮助开发者与 AI Agent 在动手修改之前完整掌握这个"源码模块化、产物单文件"的 WPF 工具包工程约束体系。

1. 项目上下文（Project Context）

SPEC.md 开宗明义：

WinUtil is a Windows PowerShell utility with a WPF interface. The repository is maintained as modular source, but the distributed artifact is one compiled PowerShell script.

这句话点出了整个仓库最重要的架构张力：源码是模块化的（按函数、配置、UI 分文件维护），但分发的产物只有根目录下一个编译生成的 winutil.ps1。SPEC.md 同时声明了它与 AGENTS.md 的分工：AGENTS.md 指向 SPEC.md 获取项目事实，并单独规定 Agent 在本仓库中的行为准则；SPEC.md 本身不随读者身份变化。

1.1 技术栈（Stack）

SPEC.md 列出的技术栈及各要素在仓库中的实际落点如下：

技术栈要素	说明	仓库落点
语言	Windows PowerShell / PowerShell	全仓库 .ps1
UI	WPF，标记语言定义在 XAML	xaml/inputXML.xaml
配置	config/ 下的 JSON 文件	config/applications.json、config/tweaks.json 等 8 个文件
测试	pester/ 下的 Pester 测试	pester/configs.Tests.ps1 等 29 个测试文件
Lint	PowerShell Script Analyzer	lint/PSScriptAnalyser.ps1
文档	Astro + Starlight 站点	docs/（独立 package.json，构建与 Compile.ps1 无关）
发布产物	根目录生成的 winutil.ps1	由 Compile.ps1 生成，属于被忽略的构建输出

1.2 仓库布局（Repository Layout）

SPEC.md 给出的目录契约与真实仓库一一对应：

• Compile.ps1：构建脚本，产出 winutil.ps1（见 Compile.ps1）。
• scripts/start.ps1：启动/引导段，位于编译脚本开头。
• scripts/main.ps1：主入口，追加在编译脚本末尾。
• functions/public/：面向 UI 的公共函数（Invoke-WPF* 系列）。
• functions/private/：内部辅助函数（Initialize-*、Get-WinUtil*、Set-WinUtil* 系列）。
• config/：JSON 配置，在编译期被消费并内嵌进 $sync.configs。
• xaml/inputXML.xaml：WPF UI 标记，内嵌进编译脚本。
• tools/autounattend.xml：无人值守安装 XML，为 Windows ISO 工作流内嵌。
• pester/：针对配置与函数行为的 Pester 测试。
• lint/PSScriptAnalyser.ps1：Script Analyzer 设置。
• docs/：独立的 Astro + Starlight 文档站。
• winutil.ps1：被忽略的生成产物，禁止手工维护。

2. 目标与非目标（Goals / Non-Goals）

SPEC.md 明确列出了 5 条目标与 4 条非目标，后者对避免误操作尤其重要：

目标：

• 提供一个可以从 PowerShell 直接启动的单脚本 Windows 工具；
• 保持模块化开发边界，让贡献者可以独立地改函数、配置、UI、文档和工具链；
• 让安装、调优（tweak）、特性（feature）、修复、更新、ISO 工作流都能从 WPF UI 中发现；
• 常见的列表与选项尽量以 JSON 声明式配置承载；
• 保证编译过程可重复：本地构建与 GitHub Actions 构建从相同输入产出可分发的脚本。

非目标（Non-Goals）：

• winutil.ps1 不手工维护；
• 项目不是一个运行时 PowerShell 模块（没有 Import-Module 式的模块结构）；
• GUI 不是本仓库常规发布路径中独立打包的桌面应用；
• 生成的文件不应按源码变更来评审。

这些非目标与 AGENTS.md 的"Non-Negotiables"完全互相咬合：直接编辑 winutil.ps1、提交它、手改自动生成文档目录都是被明令禁止的。

3. 构建模型（Build Model）：Compile.ps1 的 8 步拼接

SPEC.md 给出的编译顺序是：

1. 读取 scripts/start.ps1，把 #{replaceme} 替换为当前 yy.MM.dd 构建日期；
2. 递归追加 functions/ 下所有文件；
3. 把每个 config/*.json 转换为内嵌的 $sync.configs 对象；
4. 特判 config/applications.json，让其键名带上 WPFInstall 前缀；
5. 把 xaml/inputXML.xaml 内嵌到 $inputXML；
6. 把 tools/autounattend.xml 内嵌到 $WinUtilAutounattendXml；
7. 追加 scripts/main.ps1；
8. 写入根目录 winutil.ps1。

对照 Compile.ps1 源码，上述 8 步全部有精确对应实现（全文仅 46 行）：

• 第 1 步（Compile.ps1#L11）： $script = (Get-Content -Path scripts\start.ps1) -replace '#{replaceme}', (Get-Date -Format 'yy.MM.dd')。占位符同时出现在 scripts/start.ps1 的注释头 Version : #{replaceme}（scripts/start.ps1#L6）和运行时的版本赋值 $sync.version = "#{replaceme}"（scripts/start.ps1#L60），编译后二者都被替换为同一构建日期，窗口标题里的版本号即来自这里（scripts/main.ps1#L183：$sync["Form"].title = $sync["Form"].title + " " + $sync.version）。
• 第 2 步（Compile.ps1#L13-L15）：Get-ChildItem -Path functions -Recurse -File 递归读取并按原始文本拼接全部函数文件。
• 第 3 步（Compile.ps1#L17-L32）：每个 JSON 先 ConvertFrom-Json 校验合法性，再 ConvertTo-Json -Depth 10 序列化，生成形如 $sync.configs.<BaseName> = @'...'@ | ConvertFrom-Json 的 here-string 赋值追加到脚本中。也就是说，配置在编译期被"冻结"为字面量嵌进单文件脚本，运行时不再读取磁盘 JSON。
• 第 4 步（Compile.ps1#L20-L26）：仅 applications.json 被重新构造为有序对象，键名改写为 WPFInstall$($p.Name)（例如 7zip → WPFInstall7zip）。这个前缀正是 UI 侧 Install 页签复选框控件的命名空间，也是 pester/configs.Tests.ps1 校验 preset 引用时 applications 键加前缀的依据。
• 第 5、6 步（Compile.ps1#L34-L38）：XAML 与 autounattend XML 均以原始文本 here-string 内嵌到 $inputXML 与 $WinUtilAutounattendXml。
• 第 7、8 步（Compile.ps1#L40-L42）：追加 scripts/main.ps1 原文后 Set-Content -Path winutil.ps1。

编译脚本还接受一个 -Run 开关（Compile.ps1#L1-L3）：.\Compile.ps1 -Run 会编译后直接执行生成的 .\Winutil.ps1，用于手动 GUI 验证——这正对应 SPEC.md"Testing And CI"一节提到的两种本地验证方式。

SPEC.md 在 Build Model 结尾给出了一条关键推论：

由于最终脚本是拼接而成的，代码不能依赖运行时模块导入或基于源码相对路径的 dot-sourcing，除非编译脚本中同样包含了所需的代码/数据。

这解释了为什么 functions/ 下所有函数在编译后都是同一作用域内的顶层函数：运行时根本不存在"文件"，只有这一个大脚本。

4. 运行时模型（Runtime Model）

SPEC.md 定义了四条运行时规则，每一条都能在 scripts/start.ps1 和 scripts/main.ps1 中找到实证：

4.1 $sync 是唯一的共享可变状态

共享可变状态存放在 $sync，包括配置、UI 元素引用、runspace 状态、选择项和进度。

scripts/start.ps1#L59-L71 初始化了这个结构：

$sync = [Hashtable]::Synchronized(@{})
$sync.version = "#{replaceme}"
$sync.configs = @{}
$sync.Buttons = [System.Collections.Generic.List[PSObject]]::new()
$sync.preferences = @{}
$sync.ProcessRunning = $false
$sync.Win11ISOProcessRunning = $false
$sync.selectedAppx = [System.Collections.Generic.List[string]]::new()
$sync.selectedApps = [System.Collections.Generic.List[string]]::new()
$sync.selectedTweaks = [System.Collections.Generic.List[string]]::new()
$sync.selectedToggles = [System.Collections.Generic.List[string]]::new()
$sync.selectedFeatures = [System.Collections.Generic.List[string]]::new()
$sync.currentTab = "Install"

注意 [Hashtable]::Synchronized() 包装——这是 PowerShell 官方 GUI 脚本模式中让 hashtable 支持跨 runspace/线程并发读写的标准手段，与 AGENTS.md 学习记录中提到的 $global:sync、多线程 UI 辅助函数要求（Invoke-WPFUIThread 等必须可安全跨线程调用）相呼应。编译脚本 Compile.ps1#L8-L9 在编译时也创建了一个同构的 $sync.configs 用于收集配置对象。

4.2 长任务走 Runspace，UI 保持响应；结果经 UI 线程分发

SPEC.md 规定"长耗时操作使用 runspace 或既有异步模式，UI 更新从后台工作调度回 WPF UI 线程"。源码实证：

• scripts/main.ps1#L317 在表单 ContentRendered 事件中以 DispatcherPriority::Background 延迟初始化 runspace 池（Initialize-WinUtilRunspacePool），避免阻塞首帧绘制；
• functions/public/Invoke-WPFRunspace.ps1、functions/private/Initialize-WinUtilRunspacePool.ps1、functions/private/Close-WinUtilRunspacePool.ps1 构成池的完整生命周期；
• scripts/main.ps1#L185-L188 窗口关闭时调用 Close-WinUtilRunspacePool 并强制 GC；
• -Preset/-Config 无界面路径（scripts/main.ps1#L37-L65）也显式走 Initialize-WinUtilRunspacePool → Invoke-WinUtilAutoRun → Close-WinUtilRunspacePool 的同一套生命周期。

4.3 声明式优先：应用、tweaks、preset、DNS、导航留在 JSON

SPEC.md："除非必须写代码，apps、tweaks、presets、DNS providers、导航等声明式特性留在 config/*.json"。这一点在 scripts/main.ps1#L25-L33 可见一斑：启动时把 $sync.configs.applications、$sync.configs.appx 逐项展开成 hashtable（applicationsHashtable、appxHashtable）供 UI 渲染代码以属性名直接取用；$sync.preferences 默认 theme = "Auto"、packagemanager = "Winget"（scripts/main.ps1#L34-L35）。

4.4 参数与管理员提权

scripts/start.ps1#L9-L14 的参数块定义了脚本对外契约：

param (
    [string]$Config,
    [ValidateSet("Standard", "Minimal", "Advanced", "")]
    [string]$Preset,
    [switch]$Offline
)

• $Preset 被 ValidateSet 约束为 Standard/Minimal/Advanced 三种（与 config/preset.json 的三个顶层键一一对应）；
• $Config 触发无界面导入工作流：Invoke-WPFImpex -type "import" 后自动执行（scripts/main.ps1#L53-L65）；
• $Offline 使 UI 禁用 Install 页签并提示离线（scripts/main.ps1#L287-L307）。

scripts/start.ps1#L21-L56 还包含两个运行前置检查：PowerShell 语言模式必须为 FullLanguage，否则直接退出；若非管理员运行，则自动收集 $PSBoundParameters（保留 -Preset/-Config/-Offline 原参数）并以 RunAs 重新拉起一个 wt.exe/pwsh/powershell 进程。此外日志通过 Start-Transcript 落到 %LocalAppData%\winutil\logs\winutil_<时间戳>.log（scripts/start.ps1#L73-L80），窗口标题固定为 "WinUtil"。

5. UI 与事件契约（UI And Event Contract）

SPEC.md 的 UI 契约是三句话的硬约定：

1. UI 布局在 xaml/inputXML.xaml；
2. 具名 WPF 控件被发现后存入 $sync；
3. 按钮/动作接线遵循命名约定：名为 WPFThingButton 的元素映射到名为 Invoke-WPFThingButton 的函数。

其运行时实现链条在源码中非常清晰：

控件发现（scripts/main.ps1#L135）：

$xaml.SelectNodes("//*[@Name]") | ForEach-Object {
    $sync["$("$($psitem.Name)")"] = $sync["Form"].FindName($psitem.Name)
}

XAML 中每个带 Name 属性的节点都会以名字为键存入 $sync，这就是"named WPF controls are discovered and stored in $sync"的逐字实现。

通用按钮分发（scripts/main.ps1#L149-L172）：对 $sync 中每个 ToggleButton/Button 类型控件，注册同一个 Click 处理程序——Invoke-WPFButton $Sender.name。真正的路由发生在 functions/public/Invoke-WPFButton.ps1，它分两级：

• 配置驱动优先（Invoke-WPFButton.ps1#L22-L43）：若按钮名存在于 $sync.configs.feature（即 config/feature.json），则优先调用其 function 字段指向的函数，或逐条执行其 InvokeScript 数组；
• 硬编码 switch 兜底（Invoke-WPFButton.ps1#L46-L97）：对未进 feature 配置的按钮（如 WPFInstall、WPFUninstall、WPFStandard、WPFundoall、WPFUpdatesdefault、窗口控制按钮等）用通配符 switch 直接映射到对应函数。

测试侧对这条契约有机器校验：pester/configs.Tests.ps1#L109-L114 用正则 "(WPF[A-Za-z0-9_]+)"\s*\{ 从 Invoke-WPFButton.ps1 中提取 switch 中声明的所有按钮名（Get-WinUtilButtonSwitchNames），并要求 config/appnavigation.json 中每个 Type = "Button" 条目必须能被 switch 或 feature 配置处理（pester/configs.Tests.ps1#L303-L305）。这意味着新增 UI 按钮必须同时满足 XAML 命名、switch/feature 处理三处约定，否则 Pester 会失败。

其他值得注意的 UI 行为（scripts/main.ps1）：

• 懒加载页签：首帧前只构建默认 Install 页签（Initialize-WinUtilTabContent -TabName "Install"，scripts/main.ps1#L127-L129），其余页签在首次激活时初始化；
• 键盘导航：Alt+I/T/C/U/W 切换到 Install/Tweaks/Config/Updates/Win11ISO 五个页签（scripts/main.ps1#L213-L223），Ctrl+F 聚焦搜索框，Ctrl+Q 退出，Ctrl+滚轮或 Ctrl+加减号做 75%–200% 字体缩放；
• 搜索防抖：DispatcherTimer 300ms 延迟，停止输入后才按当前页签调用 Find-AppsByNameOrDescription/Find-TweaksByNameOrDescription 过滤（scripts/main.ps1#L321-L355）；
• XAML 加载失败有明确降级路径：XamlReader.Load 异常时给出红色错误提示并 exit 1（scripts/main.ps1#L71-L93）。

6. 配置契约（Configuration Contract）

SPEC.md 给出三条配置规则，仓库用测试把它们全部固化成了可执行断言：

规则一：配置必须是合法 JSON 且能干净通过 ConvertFrom-Json。 pester/configs.Tests.ps1#L117-L129 遍历 config/ 下全部 JSON（applications、appnavigation、appx、dns、feature、preset、themes、tweaks）逐一 ConvertFrom-Json。而 Compile.ps1#L18 中同样的 ConvertFrom-Json 意味着任何 JSON 语法错误都会直接让编译失败——测试与编译器守同一道门。

规则二：applications.json 每个条目须包含测试与 UI 期望的字段。 pester/configs.Tests.ps1#L145-L176 强制要求每个应用条目具备非空的 category、content、description、link 四个字段，且至少声明一个安装源（winget 或 choco）。真实条目（config/applications.json）：

"7zip": {
    "category": "Utilities",
    "choco": "7zip",
    "content": "7-Zip",
    "description": "7-Zip is a free and open-source file archiver utility. ...",
    "link": "https://www.7-zip.org/",
    "winget": "7zip.7zip",
    "foss": true
}

编译期第 4 步会把键改写为 WPFInstall7zip（Compile.ps1#L20-L26），这正是 Install 页签上复选框控件名的来源。

规则三：tweaks 的注册表/服务变更须携带原始值或原始状态，保证 undo 可还原。 pester/configs.Tests.ps1#L179-L229 逐条断言：每个 registry 条目必须有非空 OriginalValue（多状态 Values 场景须有 DefaultValue），每个 service 条目必须有非空 OriginalType。以 config/tweaks.json 中的"禁用休眠"为例，其完整结构展示了契约的全部维度：

"WPFTweaksHiber": {
    "Content": "Hibernation - Disable",
    "Description": "Hibernation is really meant for laptops as it saves what's in memory ...",
    "category": "Essential Tweaks",
    "panel": "1",
    "registry": [
      { "Path": "HKLM:\\System\\CurrentControlSet\\Control\\Session Manager\\Power",
        "Name": "HibernateEnabled", "Value": "0", "Type": "DWord", "OriginalValue": "1" }
    ],
    "InvokeScript": [ "powercfg.exe /hibernate off" ],
    "UndoScript": [ "powercfg.exe /hibernate on" ],
    "link": "https://winutil.christitus.com/code-reference/tweaks/essential-tweaks/hiber"
}

注册表项带 OriginalValue 供撤销恢复，命令行动作带对称的 UndoScript。测试还进一步要求所有 InvokeScript/UndoScript 文本必须能通过 [scriptblock]::Create 解析（pester/configs.Tests.ps1#L586-L619）。

规则四（Preset 与导航引用完整性）：preset 和导航文件引用的必须是有效配置键；重命名一个配置键，必须同步更新所有 preset、UI 引用、文档与代码路径。 pester/configs.Tests.ps1#L232-L261 把 tweaks、feature、appx、加前缀的 applications 以及 Invoke-WPFButton switch 名合并为合法引用集合，逐条校验 config/preset.json 中 Standard/Minimal/Advanced 三组列表（例如 Standard 含 WPFTweaksActivity、WPFTweaksTelemetry、WPFTweaksRestorePoint 等 12 项）不允许出现悬空引用。这条规则使"改名"从一个危险操作变成被 CI 拦截的操作。

此外，测试还覆盖了配置契约的更外围部分：config/appx.json 必填 Category/Content/Description/Panel/PackageId 且 StoreId 须匹配 12 位微软商店 ID 格式；config/dns.json 四个 IP 字段须可被 [System.Net.IPAddress]::Parse 解析，且每个 DNS 提供商必须出现在 tweaks 中 WPFchangedns 的 ComboItems 里；config/feature.json 中声明的 function 必须真实存在于 functions/ 的顶层函数中（测试用 AST 解析全部函数文件收集函数名，见 pester/configs.Tests.ps1#L94-L107）；config/themes.json 的 Light/Dark 键必须对称，且 XAML 中每个 DynamicResource 必须能在 themes.json 或 XAML 资源里找到定义（pester/configs.Tests.ps1#L527-L583）。

7. 安全要求（Safety Requirements）

SPEC.md 的安全章节给出三条硬约束：

1. 高风险操作清单：注册表、服务、包管理器、Windows Update、AppX 移除与 ISO 操作都会影响宿主系统，一律按高风险对待；
2. 可逆性：tweaks 变更在 schema 支持时必须包含 undo 元数据（如第 6 节所示的 OriginalValue/OriginalType/UndoScript）；
3. ISO 工作流绝不修改用户原始 ISO 文件，只在拷贝/挂载的内容上工作。

第 3 条在代码层有专门保障：config/tweaks.json 的 Win11 Creator 相关流程与 functions/private/Invoke-WinUtilISO.ps1、functions/private/Invoke-WinUtilISOUSB.ps1 等遵循"拷贝/挂载/导出"模式；AGENTS.md 的学习记录进一步明确每次新的 ISO 修改都在全新 WinUtil_Win11ISO_* 临时目录中开始。日志与进度反馈也属于安全契约的一部分：长耗时操作通过 functions/private/Write-WinUtilLog.ps1、Set-WinUtilTweaksProgressIndicator 等保留既有反馈模式。

8. 文档站（Astro + Starlight）

SPEC.md 对 docs/ 的约定：

• 独立于 Compile.ps1 构建：自带 package.json/node_modules，经 docs.yaml GitHub Actions 工作流部署到 GitHub Pages；
• 页面位于 docs/src/content/docs/（.mdx），组织为 guides/、code-reference/ 及 faq.mdx、knownissues.mdx、contributing.mdx、index.mdx 等顶层页；
• code-reference/tweaks/ 与 code-reference/features/ 由 tools/devdocs-generator.ps1 从 config/tweaks.json/config/feature.json 及相关 PowerShell 函数文件自动生成，其余 code-reference/ 页面（如 architecture.mdx）为手写，生成器不触碰；
• docs/astro.config.mjs 中的侧边栏条目必须与实际页面 slug 一致；
• docs/public/ 是受版本跟踪的静态资源源（favicon 等），而非生成输出；dist/、.astro/、node_modules/ 等生成路径由 docs/.gitignore 忽略；
• docs/Dockerfile 与 docs/docker-compose.yml（服务名 winutil-astro）容器化了站点 npm 工具链——AGENTS.md 要求 Agent 必须经 Docker 运行 npm 命令而非在宿主上直接跑 npm。

这一节的工程含义是：改一个 tweak 的名称或字段，正确动作是改 JSON 与函数文件，然后跑生成器重新产出 mdx，手改生成目录会破坏"单一事实来源"链条。

9. 测试与 CI（Testing And CI）

SPEC.md 定义的验证矩阵：

检查	命令/机制	作用
编译验证	.\Compile.ps1	验证编译器能从源码生成 winutil.ps1
GUI 手动验证	.\Compile.ps1 -Run	编译后启动生成的工具
单元测试	Pester 5.8.0，pester/*.Tests.ps1，GitHub Actions 用 unittests.yaml 全新安装 Pester 5.8.0 并以 -CI 运行，产出 testResults.xml，失败则非零退出	见 pester/ 下 29 个测试文件
静态分析	GitHub Actions 每次 push 用 lint/PSScriptAnalyser.ps1 运行 Script Analyzer	设置文件仅排除 PSAvoidUsingWriteHost 一条规则（lint/PSScriptAnalyser.ps1#L24），其余默认规则全开
产物纪律	本地编译后可能出现 winutil.ps1，但它始终是被忽略的构建输出（根 .gitignore），不得提交	防止生成物混入源码评审

AGENTS.md 补充了两个实操细节：本地安装 Pester 5.8.0 需要 -SkipPublisherCheck（Windows 自带 inbox Pester 3.4.0 为 catalog 签名，Gallery 的 5.8.0 为 Authenticode 签名，不跳过会拒绝升级），且运行前必须 Import-Module Pester -RequiredVersion 5.8.0 防止回落到 3.4.0；另外因为 lint/PSScriptAnalyser.ps1 只排除规则不排除文件，-Recurse 会顺带 lint 本地生成的 winutil.ps1 产生噪声，所以 lint 前应先删掉本地编译产物。

pester/ 中除 configs.Tests.ps1 外，还有围绕本契约其他章节的专项测试，可作延伸阅读：pester/runspace.Tests.ps1（runspace 生命周期）、pester/tweaks.Tests.ps1（tweaks 执行）、pester/tooltip-key.Tests.ps1（UI 契约）、pester/win11creator.Tests.ps1（ISO 工作流）、pester/logging.Tests.ps1（日志契约）等。

10. 发布产物（Release Artifact）

SPEC.md 最后一段划定了发布有效性的边界：

GitHub Actions 负责从仓库源码产出发布版 winutil.ps1。只有当生成的脚本来自编译流程、而非对 winutil.ps1 的直接手工编辑时，一个 release 才被视为有效。

结合前文即得完整闭环：贡献者只改 scripts/、functions/、config/、xaml/、tools/ 这些"输入面"；Compile.ps1（或 CI 中的等效流程）把它们按固定 8 步拼成单文件；Pester 保证配置与 UI 契约不被改坏；Script Analyzer 保证代码风格；产物 winutil.ps1 自身是只读结果，被 .gitignore 排除在版本控制之外。

11. 结语：把 SPEC.md 当作可执行的架构文档来读

SPEC.md 的价值在于它把 WinUtil"源码模块化、产物单文件"这一核心决策翻译成了逐条可验证的约束：构建顺序写在 Compile.ps1 里、$sync 状态模型写在 scripts/start.ps1 里、UI 命名契约由 scripts/main.ps1 与 functions/public/Invoke-WPFButton.ps1 执行、配置 schema 由 pester/configs.Tests.ps1 断言。对开发者而言，改任何一处之前先读对应章节即可预判影响面——例如新增一个 tweak 需要同时满足：JSON 必填字段（Content/category/panel/link）、undo 元数据（OriginalValue/UndoScript）、（若暴露为按钮）XAML 命名与 switch/feature 处理、（若进入 preset）preset 引用完整性；新增一个应用则需要 winget/choco 至少其一与四个展示字段齐备。这套"文档—源码—测试"三向一致的契约，正是单脚本分发形态下仍可多人并行协作的根基。