企业官网建设流程全解析

• 桌面应用
• 操作系统

本文围绕 Flyoobe 项目中的Setup Actions（可选动作包）机制展开：首先说明如何在官方 Actions/README.md 指引下安装、启用并安全使用这些动作，然后以完整指南 docs/setup-actions.md 为核心脉络，深入讲解单脚本动作、带action.ini清单的动作包、Prepare/Finish/Utility三种相位、下拉选项参数、配方（Recipe）集成规则以及故障排查方法。读完本文，你将能够在自己的 Windows 11 部署流程中编写、打包、导入并安全运行 Flyoobe 动作，并判断哪些动作适合交给自动化配方。

一、Setup Actions 是什么：核心定位与设计哲学

Flyoobe 是一个面向 Windows 11 安装流程（OOBE/Setup）的配置工具，其核心功能（广告、Edge、隐私、系统优化等）都通过内置的设置数据库管理。但总有不适合放进设置数据库的一次性操作——例如重建图标缓存、创建系统还原点、打开某个 Windows 工具、执行一条安装后的收尾命令。

Setup Actions 正是为此设计的"逃生舱"（escape hatch）。它的刻意设计目标是保持"无聊"且透明：

• 没有隐藏在背后的插件框架：动作就是一个 PowerShell 脚本 + 一个可选的 INI 文件；
• 不自动运行：动作存在≠动作执行。要么你手动点选启动，要么显式地把配方安全（recipe-safe）的动作加入配方（Recipe）；
• 保持小巧可控：整个机制只有一个执行模型，没有外部控制台模式、特殊日志宿主、任意输入框、分类过滤器，也没有(console)、(silent)这类魔法后缀（见 docs/setup-actions.md 的"What I deliberately left out"一节）。

动作被刻意放在 Flyoobe 核心功能集之外。仓库中 Actions/ 目录下的每个子目录（default-power-plan、clear-icon-cache、create-restore-point、christitus-winutil等）都是构建可选Actions发布资产的包，方便用户按需取用。

二、安装与目录布局

2.1 安装步骤

根据 Actions/README.md 的安装说明：

1. 从 Flyoobe 发布页（Release page）下载Actions资产包；
2. 把其中的Actions文件夹解压到应用程序的Data文件夹内；
3. 在Settings > Advanced（设置 > 高级）中启用Setup Actions。

2.2 最终目录结构

Flyoobe/ |- Flyoobe.exe `- Data/ `- Actions/ `- <action-id>/ |- action.ini `- run.ps1

安装完成后，你可以在Setup Actions 页面导入动作，也可以打开本地的 Actions 文件夹（见 docs/setup-actions.md 的开启方式说明）。这与 docs/setup-actions.md 中"单个.ps1导入后被 Flyoobe 复制进Data\Actions，包则整体复制进Data\Actions\<Id>"的行为一致。

2.3 运行安全模型：不自动、需确认

仓库 Actions/README.md 明确强调：该文件夹中的任何内容都不会自动运行。手动动作必须经过明确的点击与确认；动作只有在清单中显式声明RecipeAllowed=true，并且使用Prepare或Finish相位时，才能参与配方。

2.4 运行前的安全检查清单

在运行任何动作之前，Actions/README.md 建议至少确认：

• 阅读action.ini和run.ps1的内容；
• 特别注意RequiresAdmin（是否需要管理员权限）与Warning（额外警告文本）字段；
• 把会下载变化中的远程代码的动作视为外部软件（参见仓库中的 christitus-winutil 动作：它会从https://christitus.com/win拉取并执行当前版本的 WinUtil 脚本，Warning字段明确声明"代码在 Flyoobe 之外维护、可能独立变化"）；
• 在对系统做大面积修改前保留备份。

三、编写动作：从单脚本到动作包

3.1 快速方式：单个 PowerShell 文件

对于个人使用的小型动作，一个.ps1就足够了。官方推荐模板如下（摘自 docs/setup-actions.md）：

# Description: Clears my application's local cache. # Author: Your name $ErrorActionPreference = 'Stop' try { Remove-Item "$env:LOCALAPPDATA\MyApp\Cache\*" -Recurse -Force Write-Output 'Cache cleared.' exit 0 } catch { Write-Error $_ exit 1 }

导入时 Flyoobe 会把它复制到Data\Actions，并把文件名用作动作的显示名称。如果没有额外的元数据，它就是一个仅可手动运行的Utility动作。

单脚本支持以下可选头注释（必须放在前 40 行内，每个字段使用一行#注释）：

# Id: clear-my-cache # Description: Clears my application's local cache. # Version: 1.0 # Author: Your name # Phase: Utility # RequiresAdmin: false # RecipeAllowed: false # Warning: This closes MyApp before clearing its cache. # Options: Clear cache; Show cache folder

这些头注释字段与action.ini中的字段一一对应（见下文清单字段表）。如果你需要翻译或者打算分享动作，官方建议改用动作包形式。

3.2 标准方式：动作包（action.ini + run.ps1）

官方自带的动作都采用如下包结构：

my-action/ |- action.ini `- run.ps1

导入时选中action.ini，Flyoobe 会验证包并把整个文件夹复制进Data\Actions\<Id>。包里可以包含辅助文件，脚本通过$PSScriptRoot定位它们。

完整的action.ini示例（与仓库中 default-power-plan 包 一致）：

[Action] Id=default-power-plan Name=Default power plan Name.de=Standard-Energieplan Description=Choose one of the built-in Windows power plans. Description.de=Wähle einen der integrierten Windows-Energiepläne. Version=1.0 Author=Your name Phase=Finish RequiresAdmin=false RecipeAllowed=true Script=run.ps1

3.3 清单字段详解

安全约束：脚本必须留在自己的包文件夹内。Flyoobe 会拒绝试图逃逸该目录的路径（"The script must stay inside its package folder. Flyoobe rejects paths that try to escape it."）。

四、动态 UI：# Options:下拉选项

这是整个机制中唯一刻意保留的动态 UI 特性。在脚本靠前位置放一行Options，用分号分隔选项：

# Options: Balanced; High Performance; Power Saver param([string]$choice) $ErrorActionPreference = 'Stop' try { switch ($choice) { 'Balanced' { powercfg.exe -setactive SCHEME_BALANCED } 'High Performance' { powercfg.exe -setactive SCHEME_MIN } 'Power Saver' { powercfg.exe -setactive SCHEME_MAX } default { throw "Unknown option: $choice" } } if ($LASTEXITCODE -ne 0) { throw "powercfg failed with exit code $LASTEXITCODE." } Write-Output "Selected: $choice" exit 0 } catch { Write-Error $_ exit 1 }

关键行为：

• Flyoobe 会把选中的文本作为第一个位置参数传给脚本，参数名由你自己决定，所以param([string]$choice)与param([string]$Option)都合法；
• 选项文本会写入配方。请把选项文本当作稳定的 ID：如果重命名了某个选项，那么包含旧文本的配方将变为无效——这是刻意的设计，新的 Setup Actions 核心不会去猜测旧值可能代表什么；
• Options行必须放在前 40 行内，选项之间用分号分隔。

对照仓库真实实现： default-power-plan 的 run.ps1 在头部声明# Options: Balanced; High Performance; Power Saver并接收$choice，通过powercfg -setactive切换电源计划；christitus-winutil 的 run.ps1 则声明# Options: Run utility并对非预期选项直接throw。可以看出这一机制的典型用法。

五、相位机制：Prepare、Finish 与 Utility

要让动作进入配方，必须同时具备配方相位与显式许可：

Phase=Finish RecipeAllowed=true

配方只存储动作 ID 和（如果有下拉框）选中的选项。配方里永远不会包含 PowerShell 代码或本地脚本路径。这也意味着：导入配方的那台 PC 上必须先安装好同一个动作。

官方强烈建议：只有当动作是可预测、非交互、且作为已确认的批处理一部分运行时安全，才把它标记为配方安全（recipe-safe）。

仓库中各内置包正好覆盖了三种相位：default-power-plan与clear-icon-cache均为Finish+RecipeAllowed=true（适合作为安装收尾的配方步骤），而christitus-winutil是Utility+RecipeAllowed=false（需管理员、下载执行外部代码，绝不能自动进配方）。

六、执行模型：实时输出与真实错误

Flyoobe 以如下参数启动 Windows PowerShell：

-NoProfile, -NonInteractive, -ExecutionPolicy Bypass, -File

标准输出（stdout）与标准错误（stderr）会实时显示在动作页面上。

官方推荐的模式是：

• 用Write-Output输出有意义的进度，避免向日志灌入噪音；
• 失败时返回非零退出码。仅仅打印一行红色的错误文本是不够的——Flyoobe 只能信任进程结果。

$ErrorActionPreference = 'Stop' try { Write-Output 'Starting...' # Do the work here. Write-Output 'Finished.' exit 0 } catch { Write-Error $_ exit 1 }

调用原生.exe时，必须自己检查$LASTEXITCODE：一个失败的原生命令不会自动让 PowerShell 失败。

仓库中 clear-icon-cache 的 run.ps1 是该模式的完整示范：它用& ie4uinit.exe -ClearIconCache通知系统清缓存、强杀并重启 explorer、删除%LOCALAPPDATA%\IconCache.db及 Explorer 目录下的iconcache*文件，成功路径exit 0，异常路径重启 explorer 兜底后Write-Error并exit 1。

七、编写动作时应当遵守的规则

官方总结的经验法则（见 docs/setup-actions.md 的"A few rules I would stick to"）：

• 让脚本足够小，确保别人能够真正审阅它；
• 不要把命令隐藏在编码字符串里；
• 不要下载并执行会变化的远程代码，除非这就是动作的全部意义；如果是，必须在Warning中明确说明；
• 只在确实必要时设置RequiresAdmin=true。Flyoobe 不会静默提权脚本；
• 把交互式工具、启动器、用户驱动的工具挡在配方之外；
• 路径要加引号，包内自带文件用$PSScriptRoot定位；
• 失败路径用throw或exit 1，不要依赖看起来吓人的输出文本来表达失败。

八、故障排查速查表

动作包没有出现

• 检查action.ini中是否包含Id、Name、Phase、Script；
• 确认Script指向包文件夹内真实存在的.ps1；
• 确认已在Settings > Advanced中启用 Setup Actions。

下拉框没有出现

• 把# Options:放在前 40 行内；
• 选项之间用分号分隔。

Flyoobe 报告动作成功，但其实出错了

• 在失败路径末尾使用exit 1；
• 调用原生命令后检查$LASTEXITCODE。

配方找不到某个动作

• 先在那台 PC 上安装相同 ID 的动作；
• 保持选项文本不变；
• 确认相位是Prepare或Finish且RecipeAllowed=true。

九、从实战角度理解内置动作包

Actions/目录下的内置包可以直接当作学习范本与开箱即用的工具：

• default-power-plan：通过powercfg -setactive在 Balanced / High Performance / Power Saver 之间切换，Finish相位适合配方收尾；
• clear-icon-cache：重建当前用户的图标缓存并重启一次 explorer；
• christitus-winutil：从官方端点下载并启动 Chris Titus Tech 的 WinUtil，RequiresAdmin=true、RecipeAllowed=false，是"外部软件型动作"的标准安全范式。

此外Actions/还包含create-restore-point、defender-maintenance、explorer-tweaks、post-install-essentials、repair-built-in-apps、setup-preflight等包，覆盖了还原点、Defender 维护、资源管理器微调、安装后必备项、内置应用修复、安装前预检等典型场景——你可以对照其action.ini与run.ps1观察相位、管理员需求与配方开关的取舍。

要创建你自己的动作包，完整的官方写法请阅读 docs/setup-actions.md（即仓库根目录下的完整 Setup Actions 指南），本文已完整继承了其中全部配置字段、示例代码与排查条目，可作为该文档的速查解读版本使用。

• 桌面应用
• 操作系统