Wayle 是一个不依赖特定合成器的 Wayland Shell（面板/桌壳），除了丰富的可定制模块外，它最吸引眼球的功能之一就是动态颜色提取：只需把theme-provider切换为 matugen、pywal 或 wallust，整个界面就会自动从壁纸中提取配色，实现类似 Material You 的全局换肤。本文带你彻底搞懂这三套提取算法在 Wayle 中各自是怎么工作的，帮你选到最适合自己的那一款。

一、颜色提取在 Wayle 中的整体位置

Wayle 的配色体系由一套统一的 10 色调色板（Palette）驱动：bg（基础背景）、surface（卡片背景）、elevated（抬升元素背景）、fg（主文字）、fg_muted（次要文字）、primary（强调色）以及red、yellow、green、blue四个功能色。

整套流程分三步：

1. 提取：由壁纸服务调用外部工具（matugen / pywal / wallust）从指定显示器（theming-monitor）的壁纸中抽取主色，输出一个 JSON 文件；
2. 解析：Wayle 内置的 palette provider 读取该 JSON，映射到上述 10 色调色板；
3. 重编译：颜色变化触发样式表重编译，界面即时换肤。

三个引擎的解析实现分别位于 matugen.rs、pywal.rs 和 wallust.rs，而引擎参数（scheme、对比度、调色板模式等）全部集中在 styling 配置中，文档见 styling.md。

二、matugen：Material You 风格，参数最多

matugen 基于 Material Design 3 的动态取色算法，生成的是一组语义化颜色（primary / secondary / tertiary / error / background 等），并且每个颜色都同时提供深色和浅色两套变体。

工作方式

• 解析器读取 matugen 输出的 JSON，根据matugen-light开关决定取dark还是light分支（见 matugen.rs 的pick逻辑）；
• 颜色映射关系：primary→ 强调色与蓝色，on_background→ 主文字，on_surface_variant→ 次要文字，error→ 红色，tertiary→ 黄色，secondary→ 绿色；
• 兼容新旧两种 JSON 格式：旧版直接是"#4090ff"，新版嵌套为{"color": "#4090ff"}，解析器用非标签枚举同时兼容（matugen.rs）。

可调参数

方案类型定义在 extractor.rs，每种方案对应 matugen CLI 的--type参数。想要"跟随壁纸内容"选content，想要强烈视觉冲击选expressive，想要还原壁纸原色选fidelity。

三、pywal：经典终端取色，简单直接

pywal 是最早流行的壁纸取色工具，思路非常"终端原教旨"：从壁纸提取 16 色 ANSI 调色板，再从中挑选常用角色色。

Wayle 的解析器（pywal.rs）只读取其中几个关键字段：

可调参数

其中对比度校验逻辑见 PywalContrast，默认 3.0 恰好满足 WCAG AA 级正文对比标准。

四、wallust：现代 Rust 实现，选项最丰富

wallust 是 pywal 的"精神继任者"——同样面向 16 色终端调色板，但用 Rust 重写，性能更好、可选项更多，也是 Wayle 中参数维度最宽的引擎。

调色板模式（21 种）

wallust-palette提供 21 种预设，覆盖深色/浅色、柔和/强硬、互补色、16 色技巧等组合，默认dark16。名称带comp的会额外生成互补色；带16后缀的启用"16 色技巧"扩展亮度层次；soft*系列更柔和，harddark*更硬朗。完整的枚举及浅色判定逻辑见 WallustPalette。

采样后端与色彩空间

• 采样后端wallust-backend：full（逐像素）、resized（先缩放）、wal（ImageMagick）、thumb（512x512 缩略图）、kmeans（K 均值聚类）、默认fastresize（SIMD 加速缩放，速度最快）；
• 色彩空间wallust-colorspace：lab、lch等感知均匀色空间，默认labmixed（LAB + 稀疏图像混合），用于更"像人眼"地选出主导色。

颜色映射

与 pywal 类似但取色位不同：primary/blue来自color6，red/yellow/green来自color3/color5/color4，fg_muted来自color7，fg直接用提取的foreground（wallust.rs）。

五、共同的"三层背景"派生算法

三个引擎都只给出一个基础背景色，Wayle 需要三层背景（bg / surface / elevated）来做层次感。这一步由统一的derive_layers完成（color.rs）：

1. 把背景色从 HEX 解析为 sRGB，再转换为 HSL；
2. 在 HSL 的明度（lightness）通道上叠加固定偏移量0.04，并钳制在 0-1；
3. 深色模式：bg = 变暗 0.04，surface = 原色，elevated = 变亮 0.04；
4. 浅色模式：方向相反，bg 变亮、elevated 变暗。

这样保证了无论壁纸提取出什么颜色，"基础背景 → 卡片 → 抬升元素"的明度梯度始终成立，相关正确性由 color.rs 内的测试 覆盖（包括黑白边界钳制与 HSL 往返精度）。

六、三大引擎横向对比

七、热重载与容错设计

• 配置热更新：color_extractor.rs 中有一个专门的任务，持续监听theme-provider及全部引擎参数（scheme、对比度、调色板模式……）的变更流，任何一项改动都会立即重建提取器配置，无需重启 Wayle；
• 失败回退：若对应 JSON 文件不存在或解析失败，resolve_palette会记录错误并静默回退到内置调色板，界面不会白屏（lib.rs）；
• 手动主题不受影响：你也可以不依赖提取，直接把.toml主题文件放进~/.config/wayle/themes/使用，两种方式可自由切换，详见 themes.md。

八、如何快速上手

1. 用wayle panel settings打开设置，进入 Appearance → Theme；
2. 将theme-provider从默认的wayle（内置主题）切换为matugen、pywal或wallust；
3. 确保系统已安装对应工具（三者均为外部 CLI），壁纸服务会在换壁纸时自动重新提取；
4. 按口味微调参数：想要 Material You 感选 matugen +vibrant，想要经典终端风选 pywal 调高pywal-contrast，想要精细控制选 wallust +fastresize+labmixed。

一句话总结：matugen 赢在风格化、pywal 赢在简单经典、wallust 赢在参数深度——三者共用同一套"解析 + 三层背景派生 + 热重载"管线，切换零成本，放心试。