Shell 插件
本文译自 The Omarchy Manual — Shell Plugins，同步自 basecamp/omarchy@ed7bae4。术语以 TERMS.md 为准。
Omarchy 桌面以一个名为 omarchy-shell 的长驻 Quickshell 进程运行，你在屏幕上看到的几乎一切都是其中的插件。顶栏是插件。从它垂下的面板是插件，emoji 选择器和剪贴板管理器这类全屏 overlay 是插件，Omarchy 菜单本身、锁屏、polkit 对话框，以及盯着电池、晚上把屏幕调暖的无头服务，全是插件。
这不只是实现细节。它意味着你可以关掉桌面的某块零件、把它换掉，或者写一个自己的——一行 Omarchy 源码都不用碰。
第一方插件随 Omarchy 出厂，住在 $OMARCHY_PATH/shell/plugins/。你自己添加的——你的实验品或从 GitHub 找来的——住在 ~/.config/omarchy/plugins/。启动时两者的发现方式完全一样；唯一区别是磁盘上的位置。
看看手里有什么
omarchy plugin list
它会打印每个已发现插件的 id、是否启用、第一方还是第三方、kinds 和显示名。要喂给别的程序就加 --json。
插件 id 带命名空间。内置的全部以 omarchy. 开头——omarchy.clock、omarchy.network、omarchy.notifications——该命名空间是保留的，第三方插件永远不能占用。
开关插件
omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather
也可以用菜单：Setup > Plugins 提供 Enable、Disable、Add、Clone 和 Remove，每项都带选择器，只列出对该操作有意义的插件。
启用状态存于 ~/.config/omarchy/shell.json，两类插件的规则略有不同。第三方插件在其 id 出现在文件中任何位置时即为启用——作为 bar 布局条目、plugins[] 里的条目或 bar.id。非 bar 小部件的第一方插件则相反：默认开启，只有列入 disabledPlugins[] 才关闭。
完整顶栏插件没有「关」这个状态。顶栏永远恰好有一条，所以你只能通过启用另一条来替换。bar 小部件的摆放见顶栏。
从 git 添加插件
第三方插件就是一个根目录带 manifest.json 的 git 仓库。
omarchy plugin add https://github.com/acme/omarchy-weather.git --enable
动手之前，它会直白地告诉你：插件以任意、无沙箱的代码形式运行在你的长驻 shell 进程里，给你看 URL 并要求确认。请认真对待。插件不是配置文件——它是与你的会话同寿的代码，能触达你的用户账号能触达的一切。只添加你愿意运行的仓库，启用之前先读代码。
然后它把仓库克隆到暂存目录、校验 manifest、若 id 已被占用则拒绝安装，最后移入 ~/.config/omarchy/plugins/<id>/。不带 --enable 时会问你要不要现在启用，你可以说不，先去读代码。它从不运行插件里的任何东西、从不执行安装钩子、从不索要 sudo——只是克隆文件、检查 manifest、通过 IPC 翻个开关。
更新就是对同一 checkout 的快进拉取：
omarchy plugin update acme.weather
omarchy plugin update
不给 id 则更新你所有 git 管理的插件。应用前先展示 diff，有无法快进的本地修改时拒绝更新，新版本校验失败则回滚。
omarchy plugin remove acme.weather
移除先禁用插件：git checkout（上游还在）则删除，符号链接则解除链接。没有 git 仓库的手工插件文件夹不会被直接删除，而是移入 plugins 目录里带时间戳的备份。
克隆内置插件来改造
这是我最喜欢的部分。想改变某个内置小部件的行为，别去编辑 $OMARCHY_PATH 下的文件——它们属于软件包，下次更新就会被覆盖。克隆它：
omarchy plugin clone omarchy.clock
它会把整个插件复制到 ~/.config/omarchy/plugins/dhh.clock（你的用户名，不是我的）、改名为 "My Clock"、启用之，并把 shell 从内置版切到你的副本——原有 bar 小部件的位置和设置都保留。加 --edit 可立即在新目录打开 $EDITOR，菜单里的 Setup > Plugins > Clone Plugin 干的就是这事。
用户名前缀保证克隆的 id 属于你，分享出去也不会撞车。对原内置 id 的调用会被路由到你的克隆，引用了 omarchy.clock 的地方什么都不用改。搞砸了的话，omarchy plugin remove dhh.clock 即可还原内置版。
保存 ~/.config/omarchy/plugins/ 下任何位置的文件都会自动重载插件代码，编辑器可以一直开着，看着改动落地。
写你自己的
插件就是一个带 manifest.json 和若干 QML 的目录。manifest 声明 schemaVersion: 1、id、name、version、一个或多个 kinds，以及指向每种 kind 所对应 QML 文件的 entryPoints 对象：
| Kind | 是什么 |
|---|---|
bar-widget |
活动顶栏可放进某个区段的组件 |
panel |
持久或按需召唤的浮动窗口 |
overlay |
全屏覆盖层 |
menu |
召唤式菜单表面 |
service |
无 UI 的无头单例 |
bar |
替换内置版的完整顶栏 |
一个插件可同时声明多种 kind——媒体插件既是 service 又是 bar-widget。bar 小部件另有 barWidget 块：显示名、类别、可选的 defaultSection，以及表示「栏上放多个是否有意义」的 allowMultiple。大多数小部件设为 false；间隔器（spacer）和指示器设为 true。
发布前先检查：
omarchy plugin validate ./my-plugin
它运行与 shell 加载时相同的检查：schema 版本、必填字段、id 未被保留、入口点是安全的相对路径且真实存在、声明的每个 kind 都有入口点、文件夹内没有任何符号链接。
想看全景，源码就是文档：Omarchy 仓库的 shell/README.md 覆盖 manifest schema、shell 的 IPC 契约和 shell.json 的确切结构；shell/plugins/README.md 列出每个第一方插件的 id、kinds 和入口点。
与世界分享你的作品
做出满意的东西后，放进公开 git 仓库。这就是全部的分发机制——任何人对着你的 URL 运行 omarchy plugin add，几秒钟就能跑起来。
为了让人真的找得到它，去 omarchyplugins.com 登记一下。那是 Omarchy shell 插件的社区目录，也是你想知道「我要写的小部件是不是已经有人写了」时的第一站。动手前先逛逛！