Omarchy 桌面 Shell 插件体系完全指南发现、安装、克隆与自研【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchyOmarchy 是一个把整个桌面都装进单一长驻 Quickshell 进程omarchy-shell的 Linux 发行版顶栏、下拉面板、emoji 选择器、剪贴板管理、菜单、锁屏、polkit 对话框乃至监控电量与夜间暖屏的后台服务全部是壳内运行的插件。这意味着你不用改动 Omarchy 任何一行源码就能关掉某块桌面、换成替代品甚至从零编写一个自己的插件挂上去。本指南以 manual/32-shell-plugins.md 为主体结合 shell/README.md、shell/plugins/README.md 与真实插件清单系统讲解插件模型、生命周期、命令行管理、manifest 规范、shell.json持久化状态与 IPC 契约读完你既能熟练增删改查插件也能动手写出并发布一个规范的第三方插件。一切皆插件先理解桌面是怎么住进一个进程的Omarchy 桌面的核心是单个长驻的 Quickshell 实例omarchy-shellHyprland 在每个图形会话启动时拉起它一次其余所有东西——状态栏、背景切换器、面板、全屏浮层——都以插件形式运行在壳内而非各自 fork 独立进程。shell/README.md 总结了这种单壳承载的收益共享服务与单例只存在一份而非每进程一份唤起一个面板只是一次对已经在跑的进程的 IPC 调用而不是一次quickshell -p ...冷启动第三方插件可以从磁盘加载完全不需要改动 Omarchy 自身源码。这也是插件化不只是实现细节的原因桌面上的每一块 UI 都可以被单独关闭、替换或复写。runtime 目录布局 中shell/shell.qml是入口ShellRootshell/services/PluginRegistry.qml负责插件发现、校验以及在shell.json里查询启用状态shell/services/BarWidgetRegistry.qml是顶栏 widget第一方 第三方的统一注册表而shell/plugins/下则是每一个第一方插件的家。两类插件两种信任边界来源磁盘位置信任级别第一方插件内置$OMARCHY_PATH/shell/plugins/仓库中即 shell/plugins/可获得受信任的宿主接口对象第三方插件用户自装~/.config/omarchy/plugins/id/受限接口只能控制自己的 service 与生命周期二者在启动时用完全相同的方式被发现区别在于壳注入的宿主对象范围内置插件拿到完整受信对象第三方插件拿到的是能力受限的 facade详见后文安全边界克隆自内置插件的副本则保留仅与该来源行为和配置 UI 相关的窄接口。插件 id 是带命名空间的。内置插件统一以omarchy.开头omarchy.clock、omarchy.network、omarchy.notifications等且该命名空间被保留第三方插件永远无法冒用。shell/plugins/README.md 给出了完整的首方插件总表Bar、Image picker、Emojis、Clipboard、Reminders、Omarchy menu、Notifications、Audio、Bluetooth、Clock、Monitor、Network、Power、Tailscale、Agents、Weather、Media、Battery、Idle、Night light、Lock、OSD、Polkit agent并注明首方插件在发现时会被打上__isFirstParty: true标记。查看你手头的插件omarchy plugin list这会打印每一个被发现的插件id、是否启用、属于第一方还是第三方、kinds插件类型以及显示名。需要喂给脚本或其它程序时加--jsonomarchy plugin list --json该命令底层等价于 bin/omarchy-plugin-list 对omarchy-shell shell listPlugins的封装无参时用 jq 把 IPC 返回的 JSON 整理成可读表格--json时直接透传原始 JSON。开启与关闭插件omarchy plugin enable omarchy.tailscale omarchy plugin disable omarchy.weather也可以走图形界面菜单里的Setup Plugins提供 Enable、Disable、Add、Clone、Remove 五个动作每个动作都配一个只展示对该动作有意义插件的选择器。启用状态记录在~/.config/omarchy/shell.json里且两类插件的规则并不对称第三方插件只要其 id 出现在该文件的任何位置顶栏布局条目、plugins[]数组、或作为bar.id即为启用第一方非 bar-widget 插件默认开启只有当它被列进disabledPlugins[]时才被关闭完整的 bar 插件没有关闭状态任何时候有且仅有一个顶栏想换顶栏就去启用另一个被禁用的其实是非当前 bar的插件。关于disabledPlugins[]与 shell 加载细节shell/plugins/README.md 还补充了一条首方的非 bar 插件默认启用除非列在disabledPlugins[]omarchy.bar是默认顶栏只有当选中的插件 manifest 声明了kind: bar时它才让位。bar 内各 widget 的摆放哪个在左、哪个居中、哪个在右属于顶栏布局话题参见 manual/05-the-top-bar.md持久化的实际字段结构见下文shell.json部分。从 git 添加第三方插件第三方插件本质上就是一个根目录带manifest.json的 git 仓库omarchy plugin add https://你的git主机/acme/omarchy-weather.git --enable在执行任何操作前命令会直白地警告你插件将以任意代码、无沙箱的方式运行在你那个长驻 shell 进程内并展示 URL、要求你确认。请认真对待这条警告详见下节安全边界。随后它会把仓库克隆到一个临时暂存目录校验 manifest若已有插件占用了该 id 则拒绝安装移动到~/.config/omarchy/plugins/id/。不加--enable时它会询问你现在是否启用你可以拒绝、先去读一遍代码再决定。安装过程绝不运行插件代码、绝不执行安装钩子、绝不需要 sudo——只是克隆文件、检查 manifest、通过 IPC 翻转一个启用开关。每个omarchy plugin子命令在裸终端中都是交互式的gum 选择器、确认、可审阅的 diff一旦给了参数就完全非交互。加--yes可跳过所有提示这是脚本与 AI Agent 的推荐路径omarchy plugin add https://你的git主机/acme/omarchy-weather.git --enable --yes omarchy plugin update --yes更新与移除更新是对同一份 checkout 做 fast-forward pullomarchy plugin update acme.weather # 更新指定插件 omarchy plugin update # 更新所有 git 托管的插件不带 id 时更新你拥有的全部 git 托管插件。应用前会展示 diff若你有它无法快进的本地改动则拒绝更新若新版本校验失败会自动回滚。omarchy plugin remove acme.weather移除动作会先禁用插件然后若是 git checkout 就删除目录源码仍在上游仓库若是符号链接就解除链接若是一个没有 git 仓库的手工目录则不会直接删掉而是移动到插件目录内的一个时间戳备份里。由于安装好的插件就是一份普通 git checkout任何超出 add/update 的操作如固定某个 ref、切换分支都可以直接在该插件目录里用普通 git 完成。手工安装不经过 gitshell/README.md 记录了绕开 git 的路径把目录放到~/.config/omarchy/plugins/plugin-id/含manifest.json与entryPoints引用的 QML然后omarchy-shell shell rescanPlugins omarchy plugin enable idbar widget 会出现在barWidget.defaultSection缺省则居中可用omarchy bar move移动完整的 bar 插件则会替换当前使用的顶栏。底层 IPC 等价物依然是omarchy-shell shell rescanPlugins、omarchy-shell shell enablePlugin id {}、omarchy-shell shell listPlugins——omarchy plugin系列命令只是这些调用的封装omarchy bar move/omarchy bar set则直接编辑持久化在shell.json里的 widget 布局。想改内置插件克隆它而不是改它如果你希望修改某个内置 widget 的行为不要去编辑$OMARCHY_PATH下的文件——它们属于软件包下次更新就会被覆盖。正确姿势是克隆omarchy plugin clone omarchy.clock该命令会把整个插件复制到~/.config/omarchy/plugins/你的用户名.clock例如dhh.clock用你自己的用户名而非他人重命名为 My Clock启用它并把 shell 从内置版切换到你的副本——同时保留已有 bar widget 的位置与设置。加--edit会用$EDITOR立刻打开新目录菜单里的Setup Plugins Clone Plugin就是替你做了这一步。为什么用用户名做前缀它让你的克隆 id 独一无二分享给别人时不会与任何人的 id 冲突。同时发给原内置 id 的调用会被路由到你的克隆所以一切曾经引用omarchy.clock的快捷键与 IPC 调用都不需要改动。万一改坏了omarchy plugin remove 用户名.clock就会把内置版本装回来。shell/README.md 补充了实现细节克隆会完整复制插件目录包含它声明的所有 kinds 与本地依赖克隆的是插件源码而非源因此从用内置切到用我的副本是安全的 hack 方式。开发体验上最大的亮点是热重载在~/.config/omarchy/plugins/下任何位置保存文件插件代码会自动重新加载。你可以开着编辑器改、立刻在屏幕上看到变化。需要强制重载时仍可手动执行omarchy-shell shell rescanPlugins。编写你自己的插件一个插件 一个目录 一份manifest.json 若干 QML。manifest 声明schemaVersion: 1、id、name、version、一个或多个kinds以及为每种 kind 指向 QML 文件的entryPoints对象。下表给出各 kind 的含义Kind它是什么bar-widget活动顶栏可以放进某个分区的组件panel常驻或被唤起的悬浮窗口overlay全屏浮层menu被唤起的菜单表面service无 UI 的无头单例bar可替换内置顶栏的完整顶栏一个插件可以同时声明多个 kind——媒体插件既是service又是bar-widget。bar widget 还要多一个barWidget块携带显示名、分类、可选的defaultSection以及allowMultiple说明同一时刻放多个是否合理大多数 widget 设falsespacer 与指示器设true。仓库里真实的时钟插件 manifestshell/plugins/panels/clock/manifest.json就是一个标准范例{ schemaVersion: 1, id: omarchy.clock, name: Clock, version: 1.0.0, author: Omarchy, description: Date/time label with a calendar popup, kinds: [bar-widget], entryPoints: { barWidget: BarWidget.qml }, barWidget: { displayName: Clock, description: Date/time label with a calendar popup, category: Time, allowMultiple: false } }shell/plugins/panels/weather/manifest.json 则展示了更丰富的用法除barWidget基本字段外它还声明了settingsForm: weatherSettings让 widget 在顶栏设置里获得专属配置表单。发布前先自检validate与 shell 加载时执行的是同一套检查omarchy plugin validate ./my-plugin它检查schema 版本、必填字段、id 是否被保留命名空间占用、入口点是否为安全的相对路径且真实存在、你声明的每个 kind 是否都有对应入口点、以及文件夹内不允许存在任何符号链接。入口点与宿主注入shell/README.md 的 manifest 章节进一步说明入口点可以声明omarchyPath、shell、manifest、pluginRegistry、barWidgetRegistry等属性用于宿主对象注入。内置插件拿到受信任宿主对象第三方插件拿到能力受限的 facade——普通插件只能查找并控制自己的service 与生命周期内置克隆保留窄的配置/UI 兼容层菜单插件获得应用库 facade插件可读取脱敏的标量 bar 状态完整的 bar 插件额外获得脱敏的 bar 配置与 widget 目录快照、内置 bar widget 所用非认证服务的窄代理以及对已配置的非认证 UI 插件的生命周期控制。完整 schema 与官方索引源码即文档在这里成立manifest 的完整 schema 在 shell/services/PluginRegistry.qml壳的 IPC 契约与shell.json的精确形状在 shell/README.md每个第一方插件的 id、kinds 与入口点清单则在 shell/plugins/README.md含插件到入口点 QML 的完整对照表。shell.json启用状态与布局的唯一真相有一份用户配置文件承载着你的定制与出厂默认的全部差异路径归属用途~/.config/omarchy/shell.jsonshell完整布局 每条目设置 启用的插件列表~/.config/omarchy/plugins/id/用户第三方插件源码文件即插即用仓库中的 config/omarchy/shell.json 描述全新安装状态当用户没有shell.json时 shell 原样使用这份默认配置。一旦用户定制过任何东西shell.json就成为权威文件——系统不会再把默认值深度合并回去。典型结构{ version: 1, idle: { screensaver: 150, lock: 300 }, bar: { id: omarchy.bar, position: top, transparent: false, centerAnchor: omarchy.clock, layout: { left: [{ id: omarchy.menu }, { id: omarchy.workspaces }], center: [{ id: omarchy.clock, format: HH:mm }], right: [{ id: omarchy.audio }] } }, plugins: [] }shell/README.md 归纳了八条存储规则它们是理解启用/禁用语义的关键当前顶栏即bar.id省略或设为omarchy.bar用内置顶栏设为其它声明了kind: bar的 id 即整体替换顶栏。每个插件实例是一条记录bar widget 进bar.layout.section其余panel/overlay/service/menu 等进plugins[]。设置内联在条目上没有config:子对象、没有独立配置文件、没有合并层条目上的字段就是插件看到的取值。内置 widget id 带命名空间用omarchy.clock、omarchy.audio、omarchy.network这类 id迁移逻辑会把Clock、AudioPanel这类旧 id 自动前向改写。第三方启用 ⇔ 存在第三方插件启用当且仅当其 id 出现在 shell.json 某处顶栏即bar.idbar widget 的 enable/disable 就是增删布局条目首方非 bar 插件默认启用除非列在disabledPlugins[]。允许多实例manifest 声明allowMultiple: true时可出现多份独立实例——例如两个时区的时钟就是两条各带timezone: ...的{id:omarchy.clock, ...}。闲置计时在顶层idle.screensaver与idle.lock是从用户开始空闲算起的秒数因此默认配置下即便 150s 的屏保先触发300s 的锁屏依然准时到来。顶层必须带version: 1遇到未知版本 shell 会回退到默认配置而非强行加载。IPC外部世界如何与插件对话shell 暴露一个统一的shellIPC target外加各个插件自行注册的额外 target如 bar 的bartarget、图片选择器的image-selectortarget。核心方法见下表方法返回作用pingok健康检查summon id payloadJsonok/unknown加载并打开 panel/overlay 插件hide id—关闭之前唤起的插件toggle id payloadJson—关闭则唤起打开则隐藏call id method argstring调用已加载插件的某个方法rescanPlugins—重走插件目录并热重载插件代码reloadConfigok重载~/.config/omarchy/shell.jsonsetPluginEnabled id enabledok/unknown翻转持久化启用位见下注listPluginsJSON按名称排序输出全部发现到的插件直接调用底层的方式Hyprland autostart 正是用quickshell -p $OMARCHY_PATH/shell拉起壳的quickshell ipc -p $OMARCHY_PATH/shell call shell ping日常更常用的是便捷封装omarchy-shell它只转发 IPC不会自己启动 shell想重启壳用omarchy-restart-shellomarchy-shell shell ping omarchy-shell shell toggle omarchy.menu {menu:root} omarchy-shell shell listPlugins omarchy-shell shell rescanPlugins关于setPluginEnabled的一个坑enabled参数是字符串只有字面量true会启用插件其它任何值包括True、1、yes、甚至省略都会禁用。这是为了在 QML 的 string-only IPC 参数体系下保持类型稳定——脚本调用时务必传小写true。信任边界为什么插件警告不是走过场再强调一次安全模型因为它被刻意设计成显式且收敛插件以你的用户账户所能触达的一切权限作为无沙箱代码运行在长驻 shell 进程内——第三方插件接口不直接暴露认证服务替换顶栏只拿到已配置的非认证 UI的受限能力视觉类插件仍共享 shell 的 QML 场景、可以遍历普通父级对象所以敏感状态必须留在宿主对象可达图之外认证状态通过把对应服务排除在宿主公共服务表与 QML 对象树之外来单独保护篡改第三方的注册表或配置快照也无法改写宿主状态。因此只添加你愿意运行的仓库启用前先读一遍代码。另一个边界是第三方替换顶栏可以渲染已安装的 widget但依赖服务的第三方 widget功能可能降级——顶栏不允许索取另一个插件的实时服务对象若某个 widget 需要它的配套服务请切回内置omarchy.bar。把你的插件分享出去做好了就放进一个公开 git 仓库——这就是 Omarchy 插件的全部分发机制任何人对着你的 URL 跑一次omarchy plugin add几秒内就能跑起来。为了让别人找得到你也为了你在动手前先查重把插件登记到社区插件目录 omarchyplugins.com——那是 Omarchy shell 插件社区索引也是是否已经有人写过你正要写的 widget的第一站。动手写之前先去翻一翻它。深度阅读指引想进一步吃透实现细节仓库内按此顺序读即可shell/README.md插件 manifest 规范、六种 kind、keepLoaded语义、IPC 契约表、shell.json完整形状与八条存储规则shell/plugins/README.md全部第一方插件的 id / kinds / 入口点总表以及 Bar、Image picker、Lock、Polkit、Menu 等代表性插件的运行细节例如 image-picker 以keepLoaded: true在多次唤起间保活 layer-shell 窗口、lock 屏靠 PAM 服务omarchy-lock-password与指纹服务双重认证shell/services/PluginRegistry.qmlmanifest 完整 schema 与插件注册/校验逻辑config/omarchy/shell.json出厂默认布局与插件配置作为你编辑~/.config/omarchy/shell.json的参照shell/plugins/bar/README.md内置顶栏的 widget 目录与定制 schema。【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
