MINILA-R keyd 键位配置与扩展指南

MINILA-R keyd 键位配置与扩展指南

MINILA-R Convertible 的系统级键位映射由 modules/keyd.nix 声明。所有主机复用同一份配置。NixOS 负责安装 keyd、生成配置、启用服务以及在配置变化后重启服务。

设备 ID 是 0c45:22b8。配置只匹配这个设备，不影响其他键盘。

配置边界：改哪里

这套快捷键分成两层，必须按职责修改：

keyd 不应该直接执行截图、启动程序或修改桌面状态。它只负责键盘输入转换；需要执行命令时，在 chezmoi 的 Hyprland 绑定中完成。

当前完整映射

可复用的语音 Ctrl 映射

语音输入的键盘侧逻辑集中在 modules/keyd-voice.nix，F24 桌面绑定在 Labwc rc.xml / keybinds/*.xml 和 Hyprland bindings.lua。按住说话由 用户服务 voxtype-ptt 监听 keyd 虚拟键盘上的 F24。因此新增键盘时， 只需在该键盘自己的 settings.main 中组合需要的映射。

例如，在 ~/nixos-config/modules/keyd.nix 或其他 NixOS keyd 模块中：

let
  voice = import ./keyd-voice.nix;
in
{
  services.keyd.keyboards.some-keyboard.settings.main = {
    # 该键盘自己的映射...
  } // voice.leftControl;
}

可用片段：

• voice.leftControl：单独按住左 Ctrl 超过 300ms 开始语音，松开转写；Ctrl 组合键在超时前后都保持为 Control（慢按 Ctrl+A 仍是全选）；若超时后已经开始录音又按下其他键，则取消录音并发送组合键；
• voice.rightControl：同样应用到右 Ctrl；
• voice.capsLock：同样应用到 CapsLock（MINILA-R 上 CapsLock 也是语音键）。

这些片段只负责在确认是单独长按后输出按住的 F24，不直接执行命令。 Labwc 用 F24 松开绑定 voxtype record stop 并吞掉 F24，避免漏进终端； 真正的按下开始 / 松开结束由 voxtype-ptt 完成。Hyprland 则直接绑定 F24 按下 start、松开 stop：

hl.bind("F24", hl.dsp.exec_cmd("voxtype record start"), {
  description = "MINILA-R Ctrl dictation start"
})
hl.bind("F24", hl.dsp.exec_cmd("voxtype record stop"), {
  release = true,
  description = "MINILA-R Ctrl dictation stop"
})

只有配置了相应 keyd 映射的键盘会产生 F24；其他键盘不会受到这个桌面绑定影响。 F9 和 Alt+A 仍是开关式 voxtype record toggle。

Muhenkan 独立层

modules/keyd.nix 中的核心结构如下：

[main]
muhenkan = layer(muhenkan)

[muhenkan]
v = C-M-v
l = C-M-l
3 = C-S-f3
s = print

[muhenkan+shift]
s = C-S-print

按住 Muhenkan 时，keyd 在 muhenkan 层查找按键；如果同时按住 Shift，则优先使用 muhenkan+shift 层。左 Ctrl、右 Ctrl、Alt 和 Super 不会被混入这个独立层。

为什么截图使用 Print 和组合键

Muhenkan + S 直接输出真实的 Print，因此可以复用 Omarchy 原生的智能截图流程，不需要 F13/F14 中转。

Shift + Muhenkan + S 输出 Ctrl + Shift + Print，这是一个不会覆盖普通 Shift + Print 的专用组合键。它在 chezmoi 中绑定为：

o.bind(
  "CTRL + SHIFT + PRINT",
  "MINILA-R active monitor screenshot",
  "nixarchy-screenshot-active-monitor"
)

Fn + Shift + S 在 Labwc 下优先截取当前窗口所在的显示器；显示桌面、没有窗口焦点时则按鼠标所在显示器截图。截图会保存到图片目录、复制到剪贴板并发送通知。普通 Shift + Print 仍保留原来的延迟截图功能。

Muhenkan + 3 输出 Ctrl + Shift + F3，在 chezmoi 中调用 omarchy-delayed-screenshot 3 fullscreen。脚本等待 3 秒后再调用 omarchy-capture-screenshot fullscreen slurp，因此仍使用 Omarchy 原生的截图保存、剪贴板、缩略图通知和编辑入口。 脚本使用运行时锁，同一时间只保留一个待执行的延迟截图；重复按键会提示已有截图正在等待，避免 Omarchy 截图辅助程序互相取消。

以后如何增加快捷键

方案一：复用已有桌面快捷键

如果目标功能已经有系统快捷键，优先让 keyd 输出真实按键。例如新增 Muhenkan + T，让它执行已有的 Super + T：

settings.muhenkan = {
  v = "C-M-v";
  s = "print";
  t = "M-t";
};

这里的 M 是 Meta/Super，C 是 Control，S 是 Shift，G 是 AltGr。keyd 的组合键写法使用连字符，例如 C-M-v、C-S-print。

方案二：绑定一个新的桌面命令

如果目标是启动程序、截图、录音或调用 Omarchy 命令，则分两步：

1. 在 modules/keyd.nix 中选择一个不会冲突的真实按键或组合键作为输出。
2. 在 ~/chezmoi/dot_config/hypr/bindings.lua 中绑定这个输出并执行命令。

例如：

# ~/nixos-config/modules/keyd.nix
settings.muhenkan = {
  t = "C-S-t";
};

-- ~/chezmoi/dot_config/hypr/bindings.lua
hl.unbind("CTRL + SHIFT + T")
o.bind("CTRL + SHIFT + T", "MINILA-R terminal action", "your-command")

不要把 shell 命令写进 keyd 的 settings。keyd 的职责是发出按键，Hyprland 才是执行桌面命令的位置。

选择输出键时的规则

• 优先使用目标功能已有的真实快捷键。
• 没有现成快捷键时，使用不冲突的组合键，例如 C-S-<key>。
• 先检查 omarchy menu keybindings --print 和 hyprctl binds -j。
• 不要随意使用 F13/F14；它们曾经是旧方案的中转键，当前截图配置不再使用。
• 不要覆盖普通 Print、Shift + Print、Super + Print 等 Omarchy 原生功能，除非确实要改变它们的全局行为。
• 不要直接修改 /etc/keyd/minila-r.conf 或 ~/.config/hypr/bindings.lua。

修改、应用和验证

修改 keyd 层

cd ~/nixos-config
nix flake check --no-build
sudo nixos-rebuild switch --flake .#hx90

NixOS 会生成 /etc/keyd/minila-r.conf 并重启 keyd。配置修改在重建前不会可靠地进入系统；不要只修改生成文件。

修改 Hyprland 动作

cd ~/chezmoi
chezmoi apply
hyprctl reload

如果只修改了 Hyprland 源文件，也可以使用 chezmoi apply ~/.config/hypr/bindings.lua。

检查顺序

systemctl status keyd
sudo keyd check /etc/keyd/minila-r.conf
sed -n '1,160p' /etc/keyd/minila-r.conf
omarchy menu keybindings --print
hyprctl binds -j

要观察实际输出事件：

sudo keyd monitor

本配置应看到：

• Muhenkan + S：print down / print up；
• Muhenkan + 3：leftcontrol、leftshift、f3 组合事件；
• Shift + Muhenkan + S：leftshift、leftcontrol、print 依次按下并释放；
• Muhenkan + V：leftcontrol、leftmeta、v 组合事件。

keyd monitor 会同时显示原始键盘和 keyd virtual keyboard。判断最终效果时关注虚拟键盘输出；判断物理按键名称时关注 MINILA-R Convertible 设备。

截图验证

find ~/图片 -maxdepth 1 -name 'screenshot-*.png' -printf '%TY-%Tm-%Td %TH:%TM:%TS %p\n' | sort | tail

Shift + Muhenkan + S 成功后应生成全屏 PNG，并弹出 Omarchy 的 “Screenshot saved to clipboard and file” 通知。

常见问题