企业官网建设流程全解析

如何开发FluentTweaker扩展：元数据、Host模式与参数传递完整参考

【免费下载链接】FluentTweakerWindows Slop Remover项目地址: https://gitcode.com/gh_mirrors/wi/FluentTweaker

FluentTweaker（Windows Slop Remover）是一款开源的 Windows 系统优化工具，它的扩展系统非常友好：你只需要把一个 PowerShell 脚本放进scripts文件夹，就能自动出现在Tools（工具）页面中。本文是面向新手的 FluentTweaker 扩展开发完整参考，讲清楚三件最核心的事：脚本头部的元数据怎么写、Host 运行模式怎么选、以及程序如何把参数传给你的脚本。读完你就能独立写出第一个扩展 🚀

一、FluentTweaker 扩展系统是什么？

FluentTweaker 的扩展（Extensions）本质上就是带注释头部的.ps1PowerShell 脚本：

• 你把脚本放进安装目录下的.\scripts\文件夹（支持子文件夹）；
• 程序会解析脚本前 15 行左右的头部注释，读取Description、Category、Host、Options、Input等元数据；
• 满足条件的脚本会自动出现在 Tools 页面，并根据文件名的关键字（如 update、debloat、network）智能匹配图标。

官方技术指南在仓库中有完整文档：docs/extensions.md，本文的内容就是基于它整理的新手版。

💡 扩展（Extensions）和插件（Plugins）是两套不同的脚本系统，区别见文末第四节。

二、快速上手：三步写出第一个 FluentTweaker 扩展

第 1 步：新建一个.ps1文件，写好头部元数据：

# Description: 清理临时文件 # Category: Post # Host: embedded

第 2 步：在下面写你的 PowerShell 逻辑，例如：

Write-Output "Cleaning temp..." # 你的清理逻辑写在这里

第 3 步：把文件放进.\scripts\文件夹，重启 FluentTweaker，脚本就会出现在 Tools 页面。就是这么简单 ✅

如果没有声明# Options:和# Input: true，脚本就以零参数直接运行，不需要param()块。

三、FluentTweaker 扩展元数据完整清单

所有元数据都写在.ps1文件顶部的注释里，格式统一为# 键名: 值：

3.1 Category 分类怎么选？

分类决定了扩展在"安装前 / 配置中 / 安装后"哪个阶段的工具集中展示：

分类的定义可见源码 ExtensionsCategory.cs。

四、FluentTweaker Host 模式详解：embedded / console / log 怎么选

# Host:决定脚本以什么方式运行，这是扩展开发里最影响用户体验的设置：

1️⃣ embedded（嵌入式，默认）脚本在程序内部无头运行，stdout/stderr被捕获并显示在 UI 控件中，适合大多数"静默执行"的脚本。 写法：# Host: embedded或直接不写。

2️⃣ console（外部控制台）启动一个外部 PowerShell 窗口并加-NoExit，用户可以交互输入，适合需要人工确认的操作。 写法：# Host: console。

3️⃣ log（实时日志）同样在内部运行，但额外打开一个 Live Log 窗口实时滚动输出，适合耗时较长、需要盯进度的脚本。 写法：# Host: log。

4.1 单个选项的 Host 覆盖后缀

除了全局# Host:，还可以给# Options:里的单个选项加后缀，覆盖默认模式（后缀在传给脚本前会被自动剥掉）：

例如：

# Options: 隐藏扩展名; 显示扩展名; 打开此电脑 (console)

这样"打开此电脑"这一项就会弹出交互控制台，而其他选项仍走默认模式。

五、FluentTweaker 参数传递机制：位置参数详解

这是新手最容易踩坑的一点。FluentTweaker 用位置参数调用脚本：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<脚本.ps1>" "<Option>" "<ArgsText>"

也就是说：

• 位置 0→ 下拉框选中的# Options:值，读作$Option或$args[0]；
• 位置 1→ 输入框里的文本，读作$ArgsText或$args[1]。

推荐在脚本开头显式声明param()，可读性最好：

param([string]$Option, [string]$ArgsText) # 位置 0 和位置 1

如果脚本没有param()块，也可以直接通过$args[0]、$args[1]读取。两种方式完全兼容，不需要定义-Option/-ArgsText这类命名参数。

六、三个典型扩展脚本范例

范例 1：带选项 + 输入的完整扩展

# Description: 通过 ViVeTool 管理功能 ID # Category: Post # Host: log # Options: 启用 ID; 禁用 ID; 查询 ID # Input: true # InputPlaceholder: 输入逗号分隔的 ID（如 123,456） param([string]$Option, [string]$ArgsText) switch ($Option) { '启用 ID' { $ids = $ArgsText -split ',' | ForEach-Object { $_.Trim() } # 调用 ViVeTool.exe 的逻辑…… } default { Write-Error "未知选项：$Option" } }

范例 2：利用选项后缀切换 Host 模式

# Description: 文件资源管理器小工具 # Category: Post # Host: embedded # Options: 显示扩展名; 隐藏扩展名; 打开此电脑 (console) param([string]$Option) # "打开此电脑" 会自动弹出可交互的控制台窗口

范例 3：静默后台任务

# Description: 清理系统临时文件 # Category: Post # Host: embedded Write-Output "Cleaning temp..." Remove-Item "$env:TEMP\*" -Recurse -Force -ErrorAction SilentlyContinue

仓库中 plugins/DemoPluginPack.ps1 和 plugins/File Extensions Visibility (NX).ps1.ps1) 等文件是很好的真实参考（注意它们是插件格式，结构略有不同）。

七、扩展（Extensions）与插件（Plugins）的区别

FluentTweaker 里其实有两套脚本体系，别搞混了：

插件的执行模型是：先跑Check读取当前状态，用[Expect]校验输出，需要修复时执行Do，并可选提供Undo回退。完整格式说明见 docs/plugins.md。

插件的远端清单由 plugins/plugins_manifest.txt 维护，程序按其中的名称与描述下载对应脚本。

八、FluentTweaker 扩展开发最佳实践

• ✍️描述要短、要有动作感：Description直接决定用户在界面里看到的说明文字；
• 🎛️善用 Options 减少重复脚本：一个脚本 + 下拉框，胜过五个几乎一样的脚本；
• 🧪尽早校验输入：输入不合法时用Write-Error报错，UI 会把错误直观展示给用户；
• 🛡️避免破坏性默认值：危险操作一定要让用户明确选一个Option才执行；
• 📦按语义命名文件：文件名含 update / debloat / network 等词会帮助程序自动挑选合适的图标；
• 🔗 了解脚本如何被装载和管理的，可以看看源码 ExtensionsHelper.cs 和 ExtensionsDefinition.cs。

九、参考资料

• 扩展官方技术指南：docs/extensions.md
• 插件格式文档：docs/plugins.md
• 内置功能（注册表开关）清单：docs/features.md
• 插件示例目录：plugins/

把.ps1脚本写对头部元数据、选对 Host 模式、按位置参数接收选项和输入——这就是开发 FluentTweaker 扩展的全部核心。动手写一个，放进scripts文件夹，Tools 页面见分晓 🎉

【免费下载链接】FluentTweakerWindows Slop Remover项目地址: https://gitcode.com/gh_mirrors/wi/FluentTweaker