Caelestia 提供的元件

手動拼裝的桌面需要 6-8 個獨立工具各自配置。Caelestia 把這些元件用 Quickshell 統一實作：

Quickshell 框架

Quickshell 是一個 Qt6/QML 的 shell framework，用來在 Wayland compositor 上渲染 UI 元件。它的角色是 Caelestia 跟 Hyprland 之間的中介層：

• 用 QML（Qt 的宣告式 UI 語言）描述介面元件
• 透過 wlr-layer-shell 協議把元件渲染成 Wayland layer surface（這是狀態列、啟動器能「黏在」螢幕邊緣的原因）
• 直接存取 Hyprland IPC，可以即時讀取工作區狀態、視窗資訊
• 配置檔修改後自動 reload，不需要重啟

跟其他桌面 shell 框架的差異主要在底層渲染引擎和配置語言。

跟 AGS / Eww 的比較

選型判讀：想要開箱即用的華麗桌面 → Caelestia（Quickshell）。想要自己一個個拼、有前端經驗 → AGS。想要最簡單輕量 → Eww。想要完全控制每個細節 → 手動拼裝 waybar + wofi + mako。

跟手動拼裝的 Trade-off

Caelestia 的優勢是省去「挑工具 + 各自配置 + 統一視覺風格」的大量前期功夫。Material Design 3 的動態取色（從桌布自動提取配色方案套用到所有元件）是手動拼裝很難做到的。

代價是兩個：

第一，鎖定在 Caelestia 的設計決策裡。你可以調配色、改模組顯示、換桌布，但桌面的整體結構和行為邏輯是 Caelestia 決定的。想要「狀態列放底部 + 用不同的 launcher」這種結構性改動，比手動拼裝困難得多。

第二，穩定性風險。Caelestia 的 README 明確寫：「Configs, and internal tokens used in them, may be changed or removed without notice」。這表示一次更新可能靜默破壞你的自訂設定。這跟 Hyprland 本身的 breaking changes 疊加，等於你的桌面有兩層快速移動的依賴。

三個 GitHub Repo 的分工

完整安裝（caelestia install）會同時部署三者。也可以只裝 shell（caelestia-shell AUR package），保留自己的 Hyprland config 和應用程式設定。

定位認知

Caelestia 的本質是一套社群維護的 rice dotfiles，不是有 release cycle 和 backward compatibility 承諾的軟體產品。用它的心態應該接近「fork 別人的 dotfiles 來改」而不是「安裝一個桌面環境」。這個定位決定了它適合什麼人：享受折騰和客製化的人會從中得到很好的起點，想要穩定日用的人應該考慮 GNOME 或 KDE Plasma。

配置檔路徑

shell.json 不會在安裝時自動產生——預設行為由 Caelestia 內建值決定。你只需要建立這個檔案、寫入你想覆寫的 section。未寫的 section 使用預設值。

shell.json 結構

shell.json 的 top-level section 對應桌面 shell 的各個元件和全域設定：

全域設定

元件設定

範例：常見客製化

 1{
 2    "bar": {
 3        "persistent": true,
 4        "workspaces": {
 5            "shown": 9
 6        },
 7        "clock": {
 8            "format": "%H:%M"
 9        }
10    },
11    "notifs": {
12        "expiration": 8000
13    },
14    "paths": {
15        "wallpapers": "~/Pictures/MyWallpapers"
16    },
17    "services": {
18        "gpu": "amd",
19        "time": {
20            "format24h": true
21        }
22    }
23}

Key 要對著實際版本驗：caelestia-shell 啟動時會改寫 shell.json、丟掉 schema 不認得的 key、只留有效子集（VM 實測 2.1.0：bar.clock.format、notifs.expiration、services.* 都被丟掉、只有 bar.persistent 與 workspaces.shown 留下）。寫覆寫檔後啟動 shell、再回頭看檔案剩什麼，就是這個版本的有效 schema——被丟掉的 key 代表該功能在這版不存在或搬了位置，去 token 或別的 section 找。schema 的權威來源是安裝進來的 /usr/lib/qt6/qml/Caelestia/Config/caelestia-config.qmltypes（config 編在 C++ plugin 裡、QML 原始碼查不到）。

一個經 2.1.0 驗證的實用例——idle 鎖屏時間（預設 3 分鐘鎖、10 分鐘關螢幕）延長到 2 小時：

 1{
 2    "general": {
 3        "idle": {
 4            "timeouts": [
 5                {
 6                    "timeout": 7200,
 7                    "idleAction": "lock"
 8                }
 9            ]
10        }
11    }
12}

Token 系統

shell-tokens.json 控制的是比 shell.json 更細粒度的視覺數值：

• 每個元件的 rounding（圓角半徑）
• 各區域的 spacing 和 padding
• 各類別文字的 font size
• 動畫的 duration 和 easing curve
• 元件的固定尺寸

官方的說法是：「Do NOT change any of these options if you do not know what you are doing.」這個警告的實際意義是——token 之間有隱含的依賴關係（某個 padding 值跟某個 rounding 值配合才好看），隨意改一個可能讓整體視覺走樣。而且 token 的名稱和結構可能在版本更新時變動，沒有向後相容承諾。

務實的做法是先不動 token，用 shell.json 做功能層面的客製化。等到你有明確的視覺需求（例如想把所有圓角改更大），再查 token 文件做精確調整。

自定義 Hyprland 設定

Caelestia 管理自己的 Hyprland 配置。你的自訂設定放在 hypr-user.lua（不是直接改 hyprland.lua）：

 1-- ~/.config/caelestia/hypr-user.lua
 2
 3-- 額外的 keybind
 4hl.bind("SUPER", "Return", "exec", "foot")
 5
 6-- monitor 配置
 7hl.config({
 8    monitor = {
 9        "DP-1, 2560x1440@144, 0x0, 1",
10        "HDMI-A-1, 1920x1080@60, 2560x0, 1",
11    },
12})
13
14-- 額外的 window rules
15hl.config({
16    windowrule = {
17        "workspace 8, class:^(firefox)$",
18    },
19})

Hyprland Lua 格式：Caelestia 已經遷移到 Lua 配置（對應 Hyprland v0.55+ 的格式變更）。如果你手上有舊的 hypr-user.conf，需要轉換成 Lua。轉換工具：hyprlang2lua（Go）或 hyprconf2lua（Python pip）。

配色與主題

Caelestia 的配色系統用 Material Design 3 的動態取色——從桌布圖片自動提取色彩，產生一套 primary / secondary / surface / error 色系，套用到所有元件。

1# 設定桌布並觸發動態取色
2caelestia wallpaper -f ~/Pictures/Wallpapers/mountain.jpg
3
4# 手動切換配色方案
5caelestia scheme set -n dynamic    # 動態（從桌布取）
6caelestia scheme set -n catppuccin # 如果有對應 template

自定義配色模板放在 ~/.config/caelestia/templates/，用 {{ primary.hex }}、{{ surface.hex }} 等變數。Caelestia 會在切換桌布時用新的色系填入這些變數，產生對應的配置檔。

Scheme 熱套用的啟動時序前提（兩台 VM 各實測一次、行為一致）：shell 對 ~/.local/state/caelestia/scheme.json 的 file watcher 只在啟動當下檔案已存在時建立。首次安裝、從未 scheme set 過的機器上，第一個 shell 實例啟動時 state 檔還不存在——之後下 scheme set 會寫入 state、CLI 回報也正確，但跑著的 UI 不變色。修法：scheme set 建好 state 檔後重啟一次 shell；那之後同一實例的配色切換都即時生效、不用再重啟。

重啟 shell 用 pkill -x qs：caelestia shell -k 可能靜默失敗（實測 CLI 1.1.1：指令回傳正常但 process 沒死、新起的實例偵測到舊實例就自行退出——看起來重啟了、實際同一個實例一直活著）。驗證重啟是否真的發生，比對 ps -o pid,lstart -p $(pgrep -x qs) 的 pid 與起始時間，別只看指令沒報錯。process 名是 qs（/usr/bin/qs 是 quickshell 的 symlink）、pgrep caelestia 找不到它。

不要改 AUR 安裝的檔案

AUR package（caelestia-shell）安裝的檔案在系統路徑下，更新時會被覆蓋。所有客製化都應該放在 ~/.config/caelestia/，Caelestia 會優先讀取使用者路徑的配置，沒有的才 fallback 到系統預設。

已知問題

Config 靜默破壞：Caelestia 的 token 名稱和配置結構可能在版本更新時變動，不會事先通知。更新後如果 shell 行為異常，先檢查 shell-tokens.json 裡的 key 是否還存在。

Notification backlog：Shell 可能因為積累大量通知而變卡。清除：

1caelestia shell notifs clear

quickshell-git 必須：穩定版的 quickshell 缺少 Caelestia 需要的 API。如果裝了穩定版，shell 會啟動失敗或功能不完整。確認用的是 quickshell-git：

1pacman -Q quickshell-git

工作區切換卡頓：在某些 GPU / 驅動組合下報告過隨機卡頓。排查方向：關閉 VRR（vrr = 0）、減少 blur passes、檢查 GPU 驅動版本。

Dotfile Repo 結構對應

Caelestia 的配置只追蹤覆寫用的檔案（shell.json、cli.json、hypr-user.lua），AUR package 安裝的原始檔案不進 repo：

 1~/dotfiles/
 2└── caelestia/
 3    └── .config/
 4        └── caelestia/
 5            ├── shell.json
 6            ├── shell-tokens.json   # 如果有自訂
 7            ├── cli.json
 8            ├── hypr-user.lua
 9            ├── hypr-vars.lua       # 如果有自訂
10            └── templates/          # 如果有自訂配色模板

monitor 專屬的覆寫（monitors/<name>/）是硬體相關的，跟 Hyprland 的 monitor 設定一樣，可能需要排除在 Git 外或用 template/local 機制處理。

Runtime 寫入會穿透 stow 的目錄 symlink 弄髒 repo：用 stow 部署時 ~/.config/caelestia 常是折疊的目錄 symlink、指向 repo 裡的 package 目錄，而 caelestia-shell 會在執行期往自己的 config 目錄寫（啟動時建 monitors/、改寫 shell.json）——這些寫入直接落進 dotfiles repo、git status 變髒（btop 往 themes/ 寫也是同一型）。配套：repo 的 .gitignore 把「app 會自己寫的路徑」列入（caelestia/.config/caelestia/monitors/ 等），shell.json 被改寫後 diff 一下、把有效 schema 的版本 commit 回去。

VM 測試 vs 實機測試

[VM 可測試] shell.json 配置語法、各 section 的效果（bar 模組顯示、launcher 搜尋行為、通知過期邏輯）、CLI 指令執行、hypr-user.lua 載入、配色方案切換指令。

[需實機測試] token 微調的視覺效果（間距和圓角的差異在軟體渲染下難以判讀）。動畫流暢度、blur 效能、動態取色品質、多螢幕佈局、日常穩定性等視覺與效能項目見 Caelestia 安裝的對應段落。