适用环境：Omarchy 4.x + Hyprland 0.55+（Lua 配置模式，configProvider: lua）+ hyprpm 0.56。 本机验证版本：omarchy 4.0.4-1 / hyprland 0.56.2-2 / hymission 0.8.0。

1. 用 hyprpm 安装插件

hyprpm update
hyprpm add https://github.com/gfhdhytghd/hymission
hyprpm enable hymission

hyprpm 0.56 把构建产物放在 /var/cache/hyprpm/<用户名>/<仓库>/（本机为 /var/cache/hyprpm/czyt/hymission/hymission.so），启用状态记在 /var/cache/hyprpm/<用户名>/<仓库>/state.toml。 不要把 .so 手动拷到 ~/.local/lib/，也不要 hyprctl plugin load 它—— 插件归 hyprpm 管，路径和重建都由 hyprpm 负责。

2. 让插件随 Hyprland 启动自动加载

Hyprland 不会自动加载 hyprpm 的插件（官方 wiki 要求在 autostart 里跑 hyprpm reload）。在 ~/.config/hypr/autostart.lua 里写：

-- Extra autostart processes.
-- o.launch_on_start("my-service")
hl.on("hyprland.start", function()
  hl.exec_cmd("hyprpm reload && hyprctl reload")
end)

两条命令各有用处：

  • hyprpm reload：按 hyprpm 的 state 加载所有 enabled 插件（无需 sudo）。
  • hyprctl reload：插件加载完成后再解析一遍配置。hymission.lua 里 的 hl.config / hl.bind 都带守卫，第一次解析（插件还没加载）会跳过， 必须靠这次重解析才能真正生效，否则按键不会注册。

3. 配置与绑定（~/.config/hypr/hymission.lua）

~/.config/hypr/hyprland.lua 里确保有：

require("hypr.hymission")

~/.config/hypr/hymission.lua 的内容：

-- 插件由 autostart.lua 里的 `hyprpm reload` 负责加载，这里不要写
-- hyprctl plugin load（配置解析阶段 IPC socket 还没就绪，必然失败）。

if hl.plugin and hl.plugin.hymission then
  -- 接管 Omarchy 默认的切工作区快捷键，让它们打开 Mission Control。
  -- 放在守卫内：插件不可用时 Omarchy 默认绑定会自动保留。
  hl.unbind("SUPER + TAB")
  hl.unbind("SUPER + SHIFT + TAB")
  hl.unbind("SUPER + CTRL + TAB")

  -- macOS 风格配置
  hl.config({
    plugin = {
      hymission = {
        toggle_switch_mode = 1,
        switch_toggle_auto_next = 1,
        switch_release_key = "Super_L",
        gesture_invert_vertical = 1,
      },
    },
  })

  hl.bind("SUPER + TAB", hl.plugin.hymission.toggle, { description = "Mission Control" })
  hl.bind("SUPER + SHIFT + TAB", function()
    hl.plugin.hymission.toggle("reverse")
  end, { description = "Mission Control (reverse)" })
  hl.bind("SUPER + CTRL + TAB", hl.plugin.hymission.close, { description = "Close Mission Control" })
  hl.bind("SUPER + A", function()
    hl.plugin.hymission.toggle("forceall")
  end, { description = "Mission Control (all)" })
end

-- 三指上滑打开总览
hl.gesture({
  fingers = 3,
  direction = "up",
  action = function()
    if hl.plugin and hl.plugin.hymission then
      hl.plugin.hymission.toggle("forceall")
    end
  end,
})

4. README 里容易踩的三个坑

  1. 路径不对：README 的 Omarchy 4 示例写的是 hyprctl plugin load ~/.local/lib/hymission.so——那是"手动构建并自行拷贝 .so"场景的路径。用 hyprpm 安装时该文件根本不存在，每次开机都会报错。
  2. 加载时机不对：hymission.lua 在 Hyprland 的 IPC socket 就绪之前 执行，所以任何写在配置里的 hyprctl plugin load 都会失败。加载只能放在 hl.on("hyprland.start", ...) 里。
  3. 配置键未注册：插件没加载时，hl.config({plugin={hymission={...}}}) 会抛 unknown config key 'plugin.hymission.xxx'——这就是"每次开机报错" 的直接来源。所有 hl.config / hl.bind 都必须加 if hl.plugin and hl.plugin.hymission 守卫。

5. Omarchy 默认键位冲突

Omarchy 4 的 tiling.lua 默认把 SUPER+TAB / SUPER+SHIFT+TAB / SUPER+CTRL+TAB 绑到工作区切换；而 Hyprland 对同键位的多个绑定是 全部执行（源码 handleKeybinds：先收集所有命中再依次执行）， 不会自动覆盖。所以需要 hl.unbind(...) 先移除默认绑定，再注册 hymission 的绑定（见第 3 节）。

注意：README 推荐的 “post-update hook + sed 注释 tiling.lua” 方案在 Omarchy 4 上无效——~/.local/share/omarchy 是 /usr/share/omarchy （root 所有）的符号链接，hook 以普通用户运行，sed -i 静默失败。 hl.unbind 是用户级方案，omarchy update 后依然有效，无需 sudo、无需 hook。

6. 验证清单

hyprctl plugin list                                     # 应列出 hymission
hyprctl configerrors                                    # 应为空
hyprctl getoption plugin:hymission:toggle_switch_mode   # 应为 int: 1
hyprctl binds | grep -c 'Mission Control'               # 应为 4
hyprctl binds | grep -c 'Next workspace'                # 应为 0

7. 更新与维护

hyprpm update     # Hyprland 升级（ABI 变化）后重建插件
hyprpm reload     # 重新加载已启用插件

hyprpm update 后若 Hyprland 版本也变了，按提示重启 Hyprland。