configure-macro-keyboard

在 macOS 上配置宏键盘

面向廉价的 3 键 USB-C/Bluetooth 宏键盘的端到端工作流（Jieli、Realtek、CH57x、AliExpress 类）：识别设备，查明每个按钮实际发出的按键，为该设备单独编写 Karabiner 规则，并在一条规则中处理 USB + Bluetooth，即使键盘的蓝牙固件发出的按键码与 USB 端不同也能正常工作。

只想直接照做？ references/09-turnkey-walkthrough.md 是一份可复制粘贴、30 分钟即可完成的操作指南，复现了此插件的演示示例“MacroKeyBot”配置——三个按钮都支持单击/双击：顶部按钮（用于切换 Typeless 的 Fn / Cmd+V 粘贴）、中间按钮（Shift+Return / Return）、底部按钮（up_arrow / down_arrow），并支持 USB + Bluetooth。底部按钮使用两种不同机制（USB：软件区分；蓝牙：通过单独的 equal_sign / Option+Z 按键码由键盘固件区分）——请参阅 03-patterns.md。如果你已知道想要什么，可以从这里开始；需要可复用的工作流或更深入的模式参考时，再回到这里。

自我演进技能：如果某个步骤在新键盘上失效，请立即修复此文件。每个发现的死胡同都应记录在 references/04-anti-patterns.md 中。

何时使用此技能

• 用户在 macOS 上提到“宏键盘”“宏键盘”“3 键键盘”或“Stream Deck 替代品”
• 用户想重新映射从 AliExpress / Amazon 购买的廉价 HID 键盘
• 用户想让按钮发出 Fn、Return、媒体键或自定义快捷键
• 用户在 BetterTouchTool (BTT) 上遇到瓶颈（BTT 无法发出真正的 Fn 键——请参阅相关技能 emit-fn-key-on-macos）
• 用户询问同一键盘的 USB + Bluetooth 双重配置
• 用户提到 Jieli、Free3-P，或产品字符串为“USB Composite Device”的键盘

前置检查

# 1. Karabiner-Elements installed?
test -d /Applications/Karabiner-Elements.app && echo OK || brew install --cask karabiner-elements

# 2. Input Monitoring + Accessibility granted?
#    System Settings → Privacy & Security → Input Monitoring → Karabiner = ON
#    System Settings → Privacy & Security → Accessibility → Karabiner = ON

# 3. On macOS Sequoia+: Login Items toggle for privileged daemon
#    System Settings → General → Login Items → Allow in the Background → Karabiner-Elements Privileged Daemon = ON

如果这三项中任何一项未关闭，重新映射将无法捕获设备，且不会显示错误。

工作流（5 步）

步骤 1 — 识别设备（USB）

# USB product string, VID, PID, serial, interface layout
ioreg -p IOUSB -l -w 0 | grep -B 2 -A 40 "USB Composite Device" | head -80

# Or system_profiler for a human-readable dump
system_profiler SPUSBDataType | grep -A 15 "USB Composite"

记录：idVendor（十六进制）、idProduct（十六进制）、产品字符串、序列号、接口数量。

将 VID/PID 解码为十进制，供 Karabiner 使用（Karabiner 的 JSON 使用十进制）：

python3 -c "print(int('0x4c4a', 16), int('0x4155', 16))"
# → 19530 16725

有关 Jieli 键盘的完整解码，包括 HID 报告描述符以及如何推断芯片系列，请参阅 references/01-hardware-identification.md。

步骤 2 — 识别设备（Bluetooth，如适用）

通过“系统设置” → “Bluetooth” → “连接”进行配对。然后：

# Pad's BT address + VID/PID + firmware
system_profiler SPBluetoothDataType | grep -A 20 "Free3-P\|<pad-name>"

# Confirm Karabiner sees it as a grabbable device
karabiner_cli --list-connected-devices | jq '.[] | select(.product == "<pad-name>")'

预期 VID/PID 与 USB 不同。廉价键盘会借用 Samsung 的 0x04E8 VID，以兼容 macOS HID。你的 Karabiner 规则必须通过一个包含两个标识符的 device_if 同时限定这两个 VID/PID。

有关 Jieli/Free3-P 的实际示例，请参阅 references/08-bluetooth-configuration.md。

步骤 3 — 查明每个按钮实际发出的按键

不要假设出厂映射。廉价键盘的按键码可能随意分配（Jieli/Free3-P 出厂设置为 Ctrl+C/Ctrl+V/Ctrl+X——_并非_按剪切/复制/粘贴的惯例排列——按钮顺序由硬件随机决定）。

使用 ignore: true 诊断规则（不产生效果的重新映射，用于记录原始事件）。完整工作流请参阅相关技能 diagnose-hid-keycodes。简要步骤：

1. 添加一条禁用规则，其中包含 "conditions": [{"type": "device_if", "identifiers": [{...}]}]，并在设备上设置 "ignore": true
2. 打开 Karabiner-EventViewer → “Main”标签页
3. 按下每个按钮，并截取发出的按键码
4. 对蓝牙重复此操作（如果键盘有多种固件模式，则在每种模式下分别操作）

第 4 步 — 编写 Karabiner 规则

位置：~/.config/karabiner/karabiner.json → 配置文件 0 → complex_modifications.rules → 追加一条新规则。

先备份：

cp ~/.config/karabiner/karabiner.json ~/.config/karabiner/karabiner.json.bak.$(date +%Y%m%d-%H%M%S)

规则骨架（一条规则，N 个 manipulators = 按键数 × 传输方式数）：

{
  "description": "<pad-name>: Top → Fn, Middle → Return, Bottom → Command+Delete",
  "manipulators": [
    {
      "type": "basic",
      "from": {
        "simultaneous": [{ "key_code": "left_control" }, { "key_code": "c" }],
        "simultaneous_options": {
          "detect_key_down_uninterruptedly": true,
          "key_down_order": "strict_inverse",
          "key_up_order": "strict_inverse",
          "to_after_key_up": []
        },
        "modifiers": { "optional": ["any"] }
      },
      "to": [{ "apple_vendor_top_case_key_code": "keyboard_fn" }],
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            { "vendor_id": 19530, "product_id": 16725 },
            { "vendor_id": 1256, "product_id": 28705 }
          ]
        }
      ]
    }
  ]
}

（为中间键、底部键和蓝牙模式变体重复 manipulator 代码块——纯 3 键键盘 × 2 种传输方式需要 6 个 manipulators；对于每个使用 Karabiner 端轻击与双击区分的按键，每种传输方式需 额外增加 2 个 manipulators（参见 references/03-patterns.md）。Jieli/Free3-P 的完整示例在全部三个按键上都使用了轻击与双击区分 → 总计 12 个 manipulators。注意：底部键仅在 USB 下使用 Karabiner 端区分（两次按下均为 Ctrl+X）；在蓝牙模式下，键盘固件会发送两个不同的键码（单击为 equal_sign，双击为 Option+Z），因此其 2 个蓝牙 manipulators 是简单的即时转换，而不是检测器/处理器组合。无论哪种方式，总数都为 12：8 个（顶部键 + 中间键，两种传输方式，软件区分）+ 2 个（底部键 USB，软件区分）+ 2 个（底部键蓝牙，固件决定键码的转换）。JSON 不支持 // 注释，因此不要将注释行粘贴到配置中。）

要记住的五条规则：

1. simultaneous 搭配 detect_key_down_uninterruptedly: true——当键盘在同一份 HID 报告中发送修饰键 + 按键时需要此设置。默认的 mandatory 匹配器无法匹配这些情况。
2. apple_vendor_top_case_key_code: keyboard_fn 是发送真正 Fn 键的唯一方式。key_code: fn 无效；modifiers: ["fn"] 也无效。
3. device_if 使用多个标识符——将 USB VID/PID 和蓝牙 VID/PID 都放在同一个 identifiers 数组中。一条规则即可处理两种传输方式。
4. 将每个 manipulator 限定到设备。如果没有 device_if，你会重新映射 MacBook 内置键盘，并破坏 Apple 的原生按键。
5. modifiers: {"optional": ["any"]}——允许固件发送的修饰键报告通过，而不会阻止规则生效。

完整示例（Jieli + Free3-P，全部三个按键均支持轻击/双击，共 12 个 manipulators；底部键采用非对称机制——USB 下由软件区分，蓝牙下由固件决定键码并进行转换）：references/raw/karabiner-rule.json。

第 5 步 — 验证拦截状态并测试

# Karabiner sees and grabs the device
karabiner_cli --list-connected-devices | jq '.[] | select(.product == "<pad-name>") | {product, is_grabbed}'

# Should return {"product": "...", "is_grabbed": true}

# Live event test
open -a "Karabiner-EventViewer"
# Press buttons → should see your TARGET keycode, not the SOURCE

如果 is_grabbed: false，请重新检查“输入监控”+“辅助功能”+“登录项”（前置条件检查步骤）。

如果已拦截，但按键仍原样透传：你的 simultaneous 匹配器可能有误——键盘在同一份报告中发送了组合键，但你写的是 mandatory。请重新检查第 3 步。

如果加载规则后，系统范围内的真实 Fn 键停止工作：立即还原。不要将 keyboard_fn 设为 to_if_held_down 的目标——这会导致整个系统无法发送 Fn 键（已验证的问题）。参见 references/04-anti-patterns.md →“Fn 键轻击与长按发送”。

决策树：选择哪个目标键码？

你希望按钮触发……	目标 JSON
Return / Enter	{"key_code": "return_or_enter"}
Shift+Return（换行但不提交）	{"key_code": "return_or_enter", "modifiers": ["left_shift"]}
Fn（用于 Typeless、听写）	{"apple_vendor_top_case_key_code": "keyboard_fn"}
Command+Delete（删除至行首）	{"key_code": "delete_or_backspace", "modifiers": ["left_command"]}
Option+Delete（删除单词）	{"key_code": "delete_or_backspace", "modifiers": ["left_option"]}
媒体播放/暂停	{"consumer_key_code": "play_or_pause"}
音量增大/减小	{"consumer_key_code": "volume_increment"} / volume_decrement
启动应用	{"shell_command": "open -a 'App Name'"}
运行 shell 命令	{"shell_command": "/path/to/script.sh"}
单击 = A，双击 = B（单个按钮）	查看 references/03-patterns.md 中的模式 → “单击与双击的区分”（set_variable + to_delayed_action）

处理多种蓝牙固件模式

许多廉价按键板有 2-4 种固件模式，每种模式下会发出不同的键码。Jieli/Free3-P 有 4 种模式：

模式	顶部	中间	底部
1	volume_increment	volume_decrement	spacebar（播放/暂停）
2	（尚未探索）	—	—
3	（尚未探索）	—	—
4	page_up	page_down	equal_sign

选择使用频率最低的键的模式（Free3-P 选择模式 4——笔记本电脑上很少使用 page_up/page_down）。然后添加直接匹配这些键码的操纵器（单键固件模式无需使用 simultaneous）。

模式切换组合键通常没有文档说明。常见尝试包括：同时按住全部 3 个键 ≥ 5s、只按住顶部按键 ≥ 5s、同时按下顶部和底部按键。找到有效方法后，请记录下来。

完整的模式 4 设置请参见 references/08-bluetooth-configuration.md。

深入参考（按需加载）

主题	文件
开箱即用指南（从这里开始）	references/09-turnkey-walkthrough.md
设备概览（TL;DR 表格）	references/overview.md
硬件识别	references/01-hardware-identification.md
实时 USB 配置（Jieli）	references/02-usb-wired-configuration.md
可复用模式	references/03-patterns.md
反模式 / 死胡同	references/04-anti-patterns.md
BT 配对路线图（历史记录）	references/05-bluetooth-roadmap.md
BT 生态调研	references/06-bluetooth-landscape-survey.md
BT 工具箱（已评估的工具）	references/07-bluetooth-toolbox.md
实时 BT 配置（Jieli 模式 4）	references/08-bluetooth-configuration.md
原始转储	references/raw/

相关技能

• emit-fn-key-on-macos — 重点说明为什么只有 Karabiner 能发出真正的 Fn 键（BTT / hidutil / 锁定固件上的 QMK 都会失败）
• diagnose-hid-keycodes — 用于查明未知按钮会发出什么按键的 ignore: true + EventViewer + Quartz 无焦点截屏工作流

执行后复盘

此技能完成后，在结束任务前进行复盘：

0. 确认当前位置。 — 在进行任何编辑前，确认此 SKILL.md 是规范文件。
1. 哪些地方失败了？ — 修复导致失败的指令。
2. 哪些做得比预期更好？ — 将其提升为推荐实践。
3. 哪些内容过时了？ — 如果实际情况与文档不符，更新供应商 ID、键码或 FOSS 工具版本。
4. 记录下来。 — 添加演进日志条目（或在 04-anti-patterns.md 中添加一行），记录触发条件、修复方法和证据。

不要推迟。下一次调用会继承你留下的内容。