omarchy-plugin

Omarchy 插件

介绍如何将一个栏部件的想法从零打造成达到市场品质的插件， 避免花上一整天制作一个最终不会显示的栏部件。流程就是产品本身：先用 HTML 做原型， 确认每种状态都获认可，再开始构建。

阶段 1：调研（Agent 并行只读）

1. 扫描市场。 https://plugins.omarchy.org/catalog.json 是完整的 目录（网站上的 registry.json 返回 404；GitHub 上的 registry.json 只包含仓库 URL）。搜索 id、名称和描述。确认这个想法尚未出现在目录中，并且你想要的 id 尚未被占用。浅克隆最接近的 3 到 5 个插件，并记下每个插件在栏中显示什么、面板中展示什么、如何轮询，以及有哪些值得借鉴之处。
2. 参考实现。 阅读 references/quattro-facts.md，然后查看 /usr/share/omarchy/shell/plugins/panels/ 中随附的面板（power、 network、bluetooth、audio），以及 plugins/dev-gallery/GalleryPanel.qml——所有共享组件的实时目录。
3. 数据验证。 运行实际 CLI（支持的地方使用 --json），并粘贴栏部件可以展示的字段。只根据现有数据进行设计。

阶段 2：先用 HTML 做原型，再编写任何 QML

用户看重视觉效果。关于面板的文字描述毫无意义；渲染出来的面板才最重要。一次完成，全程保持统一风格，不要分派多个 Agent 并行处理。

1. 将三个方向分别制作成 option-a/b/c.html，另建一个 index.html，将它们并排放入 iframe。三者使用相同的数据。每个页面都包含：展示栏部件所有状态的模拟栏条、面板，以及浅色／深色切换。读取用户在 ~/.config/omarchy/themes/*/colors.toml 中的主题，并以该主题为默认值。使用等宽字体栈（"JetBrainsMono Nerd Font", ui-monospace），面板尺寸参照 references/design-language.md。
2. 使用无头 Chromium 分别截图，并在展示任何内容之前亲自查看 PNG。
3. 使用固定端口启动服务（轻量级 Python HTTP server，配合 webbrowser.open），然后为用户打开浏览器。简要说明你的首选方案及理由。
4. 选定方向后，制作 design-<x>-full.html，其中包含所有状态 （正常、运行中、失败、过期／警告、尚未设置、设置），每种状态单独放在一个卡片中，并在下方附上一段解释原因的文字，同时在页面内模拟通知。每条文案都要是带有下一步操作建议的完整句子。请在此页面上获得用户认可。
5. 只有这时才编写规格说明。

阶段 3：创建仓库

创建模板有两种方式。如果你之前构建过自己的插件，就使用第二种方式；它已经包含服务／栏部件拆分、测试和 CI。

1. 以随附插件为模板。 omarchy plugin clone omarchy.clock --edit 会将随附插件复制到 ~/.config/omarchy/plugins/omarchy.clock-copy/ （omarchy plugin list --json 会显示各 id；omarchy.clock 是最精简的栏部件加面板插件，omarchy.power 则是不错的状态面板）。将该文件夹移至 ~/src/<repo>，在 manifest.json 中重命名 id，运行 git init，然后用实际方式安装它（见下文）。在你运行 omarchy plugin remove 移除它之前，该克隆会一直保留在配置文件夹中。
2. 以自己的插件为模板。 复制上一个构建的插件骨架 （例如 github.com/steveclarke/omarchy-headroom）：manifest.json、 BarWidget.qml、Service.qml、CollectorProcess.qml、TintedIcon.qml、 Model.js、tests/、tools/、CI 工作流和 LICENSE。删除领域逻辑，保留基础设施。不要复制 Agent 指令文件（参见“用实际方式安装”）。

无论采用哪种方式：运行 gh repo create <user>/<repo> --public --source=. --push，然后运行 omarchy plugin add https://github.com/<user>/<repo> --enable 和 omarchy-restart-shell。此后，在 ~/src 中编辑，提交并推送， 再运行 omarchy plugin update。

第 4 阶段：构建

顺序很重要。每一步结束时，都要有一张用户可见的截图。

1. 清单 + BarWidget.qml，让图标显示在栏中。第一小时内完成。 根节点或插槽上的 implicitWidth/implicitHeight 为 0x0。
2. Model.js 纯函数及 Node 测试：解析、状态机、相对时间、错误类别映射。选择 references/testing.md 中的测试用例。
3. Service.qml 单例，带看门狗的 Process 封装（复制 Headroom 的 CollectorProcess.qml），在 test/stub/ 下放置桩二进制文件，确保测试不会触及真实硬件或真实代码仓库。
4. 仅使用第一方组件实现 Panel.qml 的正常状态（PanelHero、 PanelSectionHeader、PanelSeparator、CursorSurface、PanelActionButton）。 将 grim 截图与原型并排比较。
5. 通过调试 IPC（omarchy-shell <id> debugState failed）强制进入其他所有状态，截图并进行比较。
6. 通过清单的 barWidget.schema 实现 SettingsView.qml，使用 shell.updateEntryInline 保存。
7. 通知：每个事件调用一次 notify-send -u critical -A key=Label， 按事件时间戳去重。
8. 设计审查：安排三到四个只读 Agent，每个负责一个视角（第一方组件对比、冷读并制作对照表、流程与健壮性）。一次性应用修改，重新截取每个状态，再次征询意见。何时完成由用户决定。 预览：精确裁剪到面板边框（用 magick ... -format "%[pixel:p{x,y}]" 采样边缘像素），用中性色填充，并放大查看四个角。
9. 提交前进行安全审查：运行 omarchy-plugin-security 技能（先用 grep 审计，再在本地对已推送的提交运行市场扫描器），修复所有命中项。每轮审查都要花一天，且每次推送后审查人员都会重新阅读整个代码树。
10. preview.png（放大检查四条边，只使用虚构名称），然后按照 references/release.md 中的发布流程操作（版本、CI 通过、附注标签、GitHub 发布），最后根据 references/marketplace.md 提交市场问题。

无需触碰用户鼠标即可验证

运行 omarchy-shell <id> open、omarchy-shell shell toggle <id>，然后根据 omarchy-shell shell debugBarGeometry 提供的面板几何信息运行 grim -g。 保存 hyprctl -j cursorpos 的结果后，通过 hyprctl eval 'hl.dispatch(hl.dsp.cursor.move({x=..,y=..}))' 模拟悬停，并在 finally 中恢复光标位置。绝不要让用户点击某个东西来告诉你发生了什么。

小组件未加载时

从上到下检查 references/debugging.md（文件、schema、发现、启用、加载、生命周期、IPC、进程、交互），在第一个失败的环节停止。清单仍无效时，不要猜测 QML 的问题。

按正确方式安装

源代码位于 ~/src/<repo>。omarchy plugin add <git url> --enable 会将代码克隆到 ~/.config/omarchy/plugins/<id>/；绝不要在该目录中编辑。提交、推送后，运行 omarchy plugin update；任何清单、图标或 IPC 变更后，都要运行 omarchy-restart-shell。插件目录中不得有符号链接。代码仓库、测试夹具、截图或历史记录中不得包含任何个人信息。

插件代码仓库中不得包含 Agent 指令文件。 整个目录树中不得有 AGENTS.md、CLAUDE.md、GEMINI.md、.claude/、.cursor/、 SKILL.md 或类似文件：omarchy plugin add 会将代码仓库复制到编码 Agent 会自动发现的路径中，市场审查也会因此阻止发布。贡献者指南应放在 docs/CONTRIBUTING.md 中。从第一次提交开始，就要将 github.com/steveclarke/omarchy-headroom 中的 tools/check-agent-files 复制到 bin/check，并加入 CI。

截图必须裁剪到面板边框，绝不能截取整个屏幕。 面板区域的截图也会捕捉到后方窗口（曾有一次，终端记录因此进入了公开代码仓库的历史记录）。

参考资料

• references/quattro-facts.md：Quickshell / Quattro 中那些不起眼却会耗费数小时的事实。
• references/design-language.md：几何布局、设计令牌、组件术语、状态颜色规则、文案规则。
• references/testing.md：状态用例、实时生命周期检查、证据记录。
• references/debugging.md：故障排查流程和只读命令。
• references/release.md：版本、CI、附注标签、兼容性声明。
• references/marketplace.md：提交正文、验证器特性、审核轮次。