Matugen：从配色生成到应用刷新
本页目录
Matugen 根据图片或颜色生成调色板，再把颜色填入模板。应用是否立即变色，还取决于它怎样读取主题文件以及是否支持重载。排错时应把“生成”和“刷新”分开。
本文示例以 Matugen 4.1.0 为核对版本。先用独立目录完成实验，再接入正式桌面配置，避免生成过程覆盖正在使用的主题。
配色链的四个环节
| 环节 | 产物 | 常见问题 |
|---|---|---|
| 输入 | 壁纸路径、种子颜色、明暗模式 | 图片不存在，模式与外壳不一致 |
| 生成 | primary、surface、on_surface 等角色 | 选错 scheme 或角色 |
| 模板 | Ghostty、GTK、Waybar 等格式的文件 | 模板语法错误，输出路径不对 |
| 刷新 | 当前应用读取新配置 | 文件已更新，进程仍使用旧内容 |
surface 适合作为表面背景，on_surface 是对应前景角色，primary 用于强调。直接挑三个看起来好看的颜色，可能破坏文字与背景之间的关系；还应在应用中检查禁用、选中和警告状态。
先在独立目录生成
建立一个新的练习目录并进入，例如 matugen-lab。保存下面的 ghostty.template：
background = {{colors.surface.default.hex}}
foreground = {{colors.on_surface.default.hex}}
cursor-color = {{colors.primary.default.hex}}
同目录保存 config.toml：
[config]
[templates.terminal]
input_path = "ghostty.template"
output_path = "generated.theme"
从这个目录运行，显式指定配置文件：
查看生成结果：
应看到三项实际颜色，没有残留 {{...}}。4.1.0 的 .hex 值已经带 #，模板不能再手工加一个 #；否则 GTK CSS 等目标可能得到 ##...。升级模板引擎后，先在这里验证变量格式，再调整正式输出。Matugen
颜色作为输入便于复现。改成壁纸时，将命令换为 matugen -c ./config.toml image ./wallpaper.png，并确保图片存在。明暗模式可以通过 --mode light / --mode dark 指定。
为每个应用编写自己的模板
同一个角色需要转换成目标应用接受的语法。Waybar 使用 GTK CSS，模板可以是：
@}};
@}};
@}};
Ghostty 的主题使用 key = value，Zellij 使用 KDL，不能把同一份输出直接复制给所有应用。先让每个应用用静态颜色正常工作，再用模板生成相同结构。
正式配置中的每个模板应写明输入和输出路径。输出目录需要存在且可写，文件应只包含该应用需要的语法。对有配置校验器的应用，先校验临时输出，再将其发布到正式主题路径。
post_hook 与刷新策略
Matugen 的模板可以关联生成后的 hook。hook 负责通知应用重新读取配置，不应替代生成结果检查。最初接入时先不设置 hook，确认文件正确后再加刷新动作。
| 应用 | 建议验证方式 |
|---|---|
| Ghostty | 生成 themes 文件，执行配置检查，再测试其重载动作 |
| Waybar | 使用独立测试配置；正确后重载指定实例或对应服务 |
| GTK 应用 | 检查生成 CSS；部分应用需要新建窗口或重启 |
| Zellij | 检查 KDL 主题和所选主题名，区分新会话与现有会话 |
| 外壳 | 使用该外壳公开的主题接口与配置约定 |
不要把某个应用支持的 SIGUSR2 推广到所有程序。旧配置向终端广播 OSC 颜色序列是自定义脚本行为；它有终端实例选择、复用器转发和应用覆盖颜色等边界。需要热更新时，优先使用目标应用明确支持的机制。
当前 Caelestia 实例如何连接
当前本地流程由 Caelestia 选择壁纸、明暗模式和方案，再通过 caelestia-sync-app-theme 脚本映射到 Matugen 参数。脚本读取当前壁纸状态，对 scheme 名称做转换，并用文件锁避免并发生成。
Matugen 配置包含 Ghostty、Zellij、GTK、KDE、Fuzzel 和 Fcitx5 等输出。Caelestia 外壳本身有自己的主题状态，并不是继续读取 ii 时代的 Quickshell colors.json。
共同壁纸不保证每个界面像素颜色完全相同，因为外壳与模板可能使用不同角色和生成选项。应验证输入、模式与角色选择是否一致，再判断差异是否需要调整。
一处没有更新时怎样定位
- 确认此次使用的图片路径、模式和配置文件；不要只检查旧默认配置。
- 在独立目录运行同样的生成命令，检查退出状态和输出内容。
- 比较正式输出路径、修改时间与应用实际读取的路径。
- 单独执行应用支持的重载操作，检查其日志。
- 若新窗口正确、旧窗口不变，继续查运行时刷新能力；若二者都错误，回查模板与主题选择。
恢复时先还原主题文件和应用配置，再按应用支持的方式重载。多应用生成并不是天然的全局事务，某个模板失败后可能存在部分更新，应逐项核对。