Omarchy 的 Shell 插件体系bar 布局、插件定制与 idle 锁定机制实战指南【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy本文基于 Omarchy 官方的 Agent 技能文档 plugins.md 展开讲解 Omarchy 状态栏bar、shell 插件与空闲锁定idle/lock的运行模型与定制方法。读完你将掌握三件事如何理解「单一 Quickshell 进程托管一切」的 shell 架构如何用omarchy bar命令和shell.json调整 bar 布局以及为什么定制内置插件必须走omarchy plugin clone克隆路线并会结合源码弄明白 idle 守屏/锁屏的触发机制。架构前提bar、通知、面板全部运行在同一个 omarchy-shell 进程里Omarchy 桌面上的状态栏、通知守护进程、设置面板以及各类 overlay 浮层都运行在同一个长期存活的 Quickshell 进程omarchy-shell内部。官方 skill 文档的开篇就强调在改动状态栏、通知、shell 插件、widgets 或 idle/lock 行为之前必须先理解这个前提The bar, notification daemon, settings panel, and assorted overlays all run inside a single long-running Quickshell process (omarchy-shell).单一进程带来的直接收益见 shell/README.md共享服务与单例只存在一份而不是每个进程一份「召唤」一个面板是对一个已在运行的进程发起 IPC 调用而不是冷启动一个全新的 Quickshell 实例第三方插件可以直接从磁盘加载无需改动 Omarchy 的任何源码。三个关键路径与 bar / 插件 / idle 相关的文件布局如下路径归属用途~/.config/omarchy/shell.json用户用户覆盖配置bar 布局、插件开关、idle 超时~/.config/omarchy/plugins/plugin-id/用户用户自有的 shell 插件目录含克隆出来的内置插件$OMARCHY_PATH/config/omarchy/shell.json系统出厂默认配置用户没有自己的shell.json时由 shell 原样使用出厂默认值可以在仓库的 config/omarchy/shell.json 中查看内容完整保留了文档所述的全部结构{ version: 1, idle: { screensaver: 150, lock: 300 }, bar: { position: top, transparent: false, centerAnchor: omarchy.clock, layout: { left: [ { id: omarchy.menu }, { id: omarchy.workspaces } ], center: [ { id: omarchy.indicators }, { id: omarchy.clock, format: dddd HH:mm, formatAlt: d MMMM Www yyyy, verticalFormat: HH\n—\nmm }, { id: omarchy.keyboard-layout }, { id: omarchy.weather }, { id: omarchy.system-update } ], right: [ { id: omarchy.tray }, { id: omarchy.agents }, { id: omarchy.bluetooth }, { id: omarchy.network }, { id: omarchy.audio }, { id: omarchy.monitor }, { id: omarchy.power } ] } }, plugins: [] }两个重要行为约束热重载shell 监听shell.json保存即生效——布局类改动不需要重启进程。无深合并一旦你定制过任何内容~/.config/omarchy/shell.json就成为权威文件shell 不会把出厂默认值深合并回你的文件。如果热重载没有兜住比如插件代码加载异常skill 文档给出的两个恢复命令是omarchy restart shell # 重启整个 shell 进程 omarchy refresh shell # 刷新底层原理上refresh对应的是 shell IPC 的rescanPlugins/reloadConfig。IPC 处理逻辑位于 shell/shell.qmlfunction rescanPlugins(): void { shell.reloadPlugins() } function reloadConfig(): string { userConfigFile.reload() return ok }完整的 shell IPC 契约ping、summon、hide、toggle、rescanPlugins、reloadConfig、setPluginEnabled、listPlugins等记录在 shell/README.md 的 IPC contract 一节。Bar 布局用omarchy bar管理 widget用 shell.json 做精细调整skill 文档给出的标准操作是使用omarchy bar命令组来移动和管理 bar 上的 widget例如把时钟移动到右侧区omarchy bar move omarchy.clock --section rightomarchy bar move与omarchy bar set实际编辑的是持久化的shell.json中的 widget 布局对应 shell IPC 的moveBarWidget/setBarWidget实现同样在 shell/shell.qml。当命令覆盖不到的布局需求出现时直接编辑~/.config/omarchy/shell.json的bar:子树保存后自动热重载。bar:子树的各字段含义结合 config/omarchy/shell.json 默认值与 shell/plugins/bar/README.mdpositiontop | bottom | left | right所有 widget 在四个方向上均可工作垂直方向 bar 宽 28px文本类 widget 会自动退化为图标形态transparent是否透明也可以双击空的中栏区域切换centerAnchor把中栏里的某一个 widget 钉在屏幕精确的横纵中心位置其余中栏模块围绕它排布默认是omarchy.clock置空字符串则取消锚定整个中栏列表作为一个组居中layout.left / center / right三个分区每个分区是一个 widget 实例数组widget 的配置项如 clock 的format、formatAlt、verticalFormat直接内联在条目上没有单独的 per-plugin 设置文件。此外bar 支持在布局里插入type: commandshell 驱动输出脚本可打印纯文本或 Waybar 风格 JSON和type: qml自定义 QML 组件文件放在~/.config/omarchy/bar/modules/id.qml的自定义模块完整示例见 shell/plugins/bar/README.md 的 Custom user modules 一节。widget 的完整目录omarchy.menu、omarchy.workspaces、omarchy.clock、omarchy.media、omarchy.audio等各自的交互行为也在同一份文档的 Module catalogue 表格中。定制内置插件克隆而不是修改发行目录这是 skill 文档中规则性最强的一条定制内置 bar widget 时永远不要编辑$OMARCHY_PATH/shell/plugins/。正确做法是把它克隆到用户插件目录omarchy plugin clone omarchy.workspaces # 之后编辑 ~/.config/omarchy/plugins/username.workspaces/保存的改动会自动重载。克隆后 bar 会切换到克隆副本例如username.workspaces这个副本归你所有、可以随意编辑并且在系统更新后依然存活发行目录里的原文件会在更新时被覆盖改它等于白改。克隆命令做了什么源码级拆解克隆逻辑的完整实现在 bin/omarchy-plugin-clone其行为比文档描述更细id 命名新插件 id 为用户名.原id去掉omarchy.前缀例如用户dhh克隆omarchy.clock得到dhh.clock显示名改为My 原名。用户名前缀保证多人共享环境下的克隆副本互不冲突完整拷贝整个插件目录含 manifest 声明的所有 entryPoints 与omarchy.clonePaths映射的本地依赖被复制到临时 staging 目录如果源/目标路径不同还会用sed批量改写文件内对旧路径的引用manifest 重写新的manifest.json里写入omarchy.clonedFrom: 原id。这一字段是关键——内置 id如omarchy.clock在插件代码内部是稳定的 IPC 目标地址shell 会依据clonedFrom把针对内置 id 的调用路由到已启用的克隆副本。所以现有的快捷键和 shell IPC 调用方完全不需要改动见 bin/omarchy-plugin-clone 中的注释Keep built-in ids inside the plugin code as stable IPC targets原子性与验证拷贝先落在~/.config/omarchy/plugins/.clone.XXXXXX暂存目录成功后才mv到位随后自动触发omarchy-shell shell rescanPlugins并以 0.05 秒间隔轮询最多 40 次确认新 id 已被发现确认失败则整体回滚收尾自动omarchy plugin enable 新id保持原有 bar 位置与设置发送「Original plugin has been replace by clone.」通知并回显Cloned omarchy.workspaces to ~/.config/omarchy/plugins/user.workspaces and switched to user.workspaces。附加选项--edit会在克隆完成后直接用$EDITOR打开新目录交互式入口在 Setup 面板的 Plugins Clone对应菜单项定义在 default/omarchy/omarchy-menu.jsonc 的setup.plugin.clone。保存即重载rescanPlugins 强制重载文档明确的另一条热重载规则在~/.config/omarchy/plugins/下任意位置保存文件都会自动重载插件代码。如果某次改动因异常未生效强制重载命令为omarchy-shell shell rescanPlugins该命令通过omarchy-shell包装器转发到运行中 shell 的shellIPC 目标omarchy-shell只转发、不启动进程shell 本身由 Hyprland autostart 用quickshell -p $OMARCHY_PATH/shell拉起见 shell/README.md 的 IPC contract 一节。顺带说明插件的 manifest 契约每个插件含第一方都带manifest.json声明kindsbar、bar-widget、panel、overlay、menu、service、entryPoints与barWidget元数据第一方与第三方的唯一区别是 shell 给前者打上__isFirstParty: true标记。第一方插件的完整清单id、kind、入口文件列在 shell/plugins/README.md。Idle 与 Lock两个以「空闲开始」为起点的秒级阈值skill 文档对 idle/lock 的定义非常明确idle.screensaver和idle.lock设置在~/.config/omarchy/shell.json中单位是从用户开始空闲起经过的秒数。例如「空闲十分钟后锁定」对应把idle.lock设为600{ version: 1, idle: { screensaver: 150, lock: 600 } }出厂默认是screensaver: 150、lock: 300见 config/omarchy/shell.json。从源码看触发时序idle 的实际执行者是omarchy.idle这个 service 插件实现位于 shell/plugins/services/idle/Service.qml。关键逻辑readonly property int defaultScreensaverSeconds: 150 readonly property int defaultLockSeconds: 300 readonly property int screensaverTimeoutSeconds: secondsFromConfig(idleConfig.screensaver, defaultScreensaverSeconds) readonly property int lockTimeoutSeconds: secondsFromConfig(idleConfig.lock, defaultLockSeconds) readonly property int firstIdleTimeoutSeconds: Math.min(screensaverTimeoutSeconds, lockTimeoutSeconds) readonly property int screensaverDelaySeconds: Math.max(0, screensaverTimeoutSeconds - firstIdleTimeoutSeconds) readonly property int lockDelaySeconds: Math.max(0, lockTimeoutSeconds - firstIdleTimeoutSeconds)这段代码印证并补充了文档的语义两个阈值都以同一次空闲开始时刻为原点IdleMonitor的timeout取两者最小值一旦进入空闲即同时武装「守屏定时器」和「锁定定时器」两个相对延迟Service.qml所以默认配置下空闲 150s 先拉起守屏omarchy-launch-screensaver继续空闲到 300s 执行omarchy-system-lock。即使守屏先启动锁定仍按 300s 触发——与文档「lock after N seconds since idle began」的语义一致有个容易忽略的细节如果用户在锁屏到期前主动关掉了守屏窗口shell 会把它视为活动事件、取消本次锁定Service.qml 中的screensaver-dismissed分支服务还维护一个stay-awake状态文件~/.local/state/omarchy/indicators/stay-awake置位后整个 idle 周期被抑制可通过 shell 暴露的idleIPC 目标status/enable/disable/toggle查询和控制锁屏界面本身是独立的omarchy.lockservice 插件shell/plugins/lock/Service.qml基于 Quickshell 原生WlSessionLock密码走omarchy-lock-passwordPAM 服务录入指纹后才启用omarchy-lock-fingerprint。小结一张可复制的操作速查目标操作移动 widgetomarchy bar move omarchy.clock --section right精细调整布局编辑~/.config/omarchy/shell.json的bar:子树保存即热重载定制内置 widgetomarchy plugin clone omarchy.id编辑~/.config/omarchy/plugins/user.id/强制重载插件omarchy-shell shell rescanPlugins重启 / 刷新 shellomarchy restart shell/omarchy refresh shell空闲 10 分钟锁定shell.json中idle.lock: 600单位自空闲开始的秒数整个体系的设计核心可以概括为出厂代码只读$OMARCHY_PATH下的插件在更新时会被覆盖用户定制全部收敛到~/.config/omarchy/shell.jsonplugins/变更通过文件监听与 IPC 热生效clonedFrom路由机制则保证克隆后的 IPC/快捷键契约零改动。更多细节可继续查阅 shell/README.mdmanifest 契约、第三方插件安装、IPC 表、shell/plugins/README.md第一方插件清单与 shell/plugins/bar/README.mdbar 引擎与自定义模块。【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考