Quickshell 与 Caelestia：组件、服务与本地修改

Quickshell 提供用 QML 编写桌面组件的运行环境。Caelestia 和 illogical-impulse 是基于它组织起来的完整外壳，各自有配置格式、目录和服务约定。选择了某个外壳，并不意味着另一套外壳的 colors.json 或模块路径也会生效。

当前实例使用 Caelestia Shell v2.4.0。旧文的 ii 目录说明保留为历史背景，本篇先讲 Quickshell 的基本机制，再说明如何维护当前外壳。

一个独立的时钟组件

在已安装 Quickshell、QtQuick 且运行于兼容 Wayland 合成器的环境中，建立 ~/.config/quickshell/doc-clock/shell.qml：

import Quickshell
import QtQuick

PanelWindow {
    anchors {
        top: true
        left: true
    }
    implicitWidth: 240
    implicitHeight: 48
    exclusiveZone: 0
    color: "#1e2530"

    SystemClock {
        id: clock
        precision: SystemClock.Seconds
    }

    Text {
        anchors.centerIn: parent
        text: Qt.formatDateTime(clock.date, "hh:mm:ss")
        color: "#f1f4f8"
        font.pixelSize: 22
    }
}

从桌面终端启动这份独立配置：

qs -c doc-clock

窗口位于左上角，exclusiveZone: 0 表示不为它保留平铺空间，因此可能覆盖其他界面。测试时选择不会干扰操作的位置，完成后在启动它的终端按 Ctrl+c 退出。Quickshell 入门

clock.date 改变后，绑定它的 text 自动重新求值。这里没有手写轮询文本控件的逻辑，数据变化由属性绑定传递到界面。

从时钟推广到系统服务

完整外壳中的音量、网络和播放器一般有一层服务对象。服务负责连接系统接口并暴露状态，界面模块负责把状态画出来，用户操作再调用服务的方法。

不要看到一个音量条就直接猜属性是 defaultSink.volume。Quickshell 原始服务与 Caelestia 包装后的对象可能不同，还需要处理“尚无默认设备”的情况。先找组件当前引用的服务类型，再查该版本的 API。

Caelestia 的三种配置来源

当前实例可以分成三个层次：

1. ~/.config/caelestia/shell.json：字体、应用入口、空闲策略、显示器选择等用户设置。
2. 安装的 quickshell/caelestia/：QML 模块、服务、资源与编译插件。
3. 上游源码与本地补丁：需要改变外壳实现时，保存可审阅的差异和对应版本。

优先用公开用户设置，只有它不能表达需求时才修改源码。直接改包管理器安装的文件，更新时可能被覆盖；具体安装和定制位置以 Caelestia 上游说明为准。

本地实例的改动包括多屏外壳显示范围、竖屏锁屏布局和壁纸加载尺寸。这些属于特定桌面的适配，不是所有 Caelestia 用户都需要的补丁。

启动与日志

命令行可使用 qs -c caelestia -n 启动已安装的配置；-n 避免重复运行同名配置。若已经由用户服务管理，不应再从其他启动器重复拉起。

当前实例的服务名是 caelestia-shell.service：

systemctl --user status caelestia-shell.service
journalctl --user -u caelestia-shell.service -b -n 80 --no-pager

其他安装方式可能使用不同服务名。日志中的 QML import 错误通常指向运行时或编译插件路径；属性不存在则先核对外壳和 API 版本；实例正常但控制命令无效时，再查 IPC 是否连接到预期实例。

更新时保留修改的来历

更新前记录上游版本、源码提交和本地 diff，并保存用户配置。更新后先验证启动、顶栏、通知、锁屏和多屏选择，再检查主题 hook。

当前外壳调用额外脚本让 Matugen 同步应用颜色，它不是 ii 的旧 colors.json 链路。完整流程见 Matugen 配色。如果外壳在重启后连接了失效会话，则继续查会话环境。