用途
本技能用于在 macOS 上端到端配置廉价的三键 USB-C/蓝牙宏键盘（macro pad），主要示例为 Jieli、Realtek、CH57x 以及 AliExpress 常见方案。它解决的问题是：这类小键盘出厂键码随意、USB 与蓝牙行为不一致，需要先用诊断方式探明每个按键实际发出的键码，再通过 Karabiner-Elements 编写仅作用于该设备的规则。
主要能力
- 识别设备：通过 ioreg 与 system_profiler 获取 USB 的产品字符串、VID、PID、序列号与接口布局；通过 system_profiler 蓝牙部分获取蓝牙地址、VID/PID 与固件信息；用 karabiner_cli --list-connected-devices 确认 Karabiner 是否识别到设备。
- 探测按键实际输出：使用 ignore: true 的诊断规则（零效果重映射）配合 Karabiner-EventViewer 主标签，逐个按下按键并记录发出的键码，USB 与蓝牙需分别测试。
- 编写 Karabiner 规则：在 ~/.config/karabiner/karabiner.json 的 profile 0 → complex_modifications.rules 中追加规则。单条规则通过 device_if 的 identifiers 数组同时包含 USB 与蓝牙的 VID/PID，使一条规则覆盖两种连接方式。
- 处理特殊键码：例如 simultaneous + detect_key_down_uninterruptedly 用于设备在一个 HID 报告中同时发出修饰键与按键的情况；apple_vendor_top_case_key_code: keyboard_fn 是唯一能发出真实 Fn 的方式。
- 提供目标键码对照：Return、Shift+Return、Fn、Command+Delete、Option+Delete、媒体播放/暂停、音量增减、启动应用（shell_command）、运行脚本等。
- 处理蓝牙多固件模式：例如 Free3-P 有 4 种模式，各模式发出的键码不同；建议选择按键用途最稀少的模式（如 mode 4 的 page_up/page_down/equal_sign），再为这些键码编写直接映射。模式切换组合键常常未文档化，文档给出若干常见尝试方式（长按全部三键、长按顶键、同时按顶键与底键）。
- 提供参考文档：turnkey 走查（约 30 分钟的复制粘贴式流程）、硬件识别、USB 配置、可复用模式、反模式与死路、蓝牙配对路线、蓝牙生态调查、蓝牙工具箱、蓝牙配置实例以及原始转储。
使用方式
前置检查：确认安装 Karabiner-Elements（/Applications/Karabiner-Elements.app），并在系统设置中开启输入监控与辅助功能权限；在 macOS Sequoia 及以上还需在登录项中允许 Karabiner-Elements Privileged Daemon 在后台运行。三项权限任一未开启，重映射都会静默失败。
五步流程：
- 识别 USB 设备并记录 VID/PID、产品字符串、接口数量；Karabiner 的 JSON 使用十进制，需将十六进制 VID/PID 转换为十进制。
- 如使用蓝牙，配对后用 system_profiler 获取蓝牙信息，确认 Karabiner 能抓取该设备；注意蓝牙 VID/PID 通常与 USB 不同，廉价设备可能借用三星 0x04E8 的 VID。
- 用 ignore: true 诊断规则配合 EventViewer 探测每个按键在每种连接方式（及固件模式）下发出的键码。
- 备份 karabiner.json 后编写规则骨架，每个按键在每种传输方式下对应一个 manipulator，并对每个 manipulator 使用 device_if 限定设备，避免影响 MacBook 内置键盘。
- 用 karabiner_cli 检查 is_grabbed 是否为 true，并用 EventViewer 验证按下按键时看到的是目标键码而非原始键码。
按键目标示例（JSON 片段）：Return 用 {"key_code": "return_or_enter"}；Shift+Return 在此基础上加 modifiers ["left_shift"]；Fn 用 {"apple_vendor_top_case_key_code": "keyboard_fn"}；Command+Delete 用 delete_or_backspace 加 left_command；媒体键用 consumer_key_code（如 play_or_pause、volume_increment）。
适用场景
- 用户提到 macOS 上的 macro pad、宏键盘、三键小键盘、Stream Deck 替代品。
- 用户想重映射从 AliExpress 或 Amazon 购买的廉价 HID 小键盘。
- 用户希望按键发出 Fn、Return、媒体键或自定义快捷键。
- 用户在使用 BetterTouchTool 时遇到限制（BTT 无法发出真实 Fn）。
- 用户询问同一小键盘的 USB + 蓝牙双配置。
- 用户提到 Jieli、Free3-P，或产品字符串为 USB Composite Device 的小键盘。
限制
- 文档未提供价格、收费方式、平台支持范围或效果承诺等信息。
- 部分蓝牙固件模式（如 Free3-P 的模式 2、模式 3）在资料中标注为未探索。
- 模式切换组合键常无文档，文档只给出若干常见尝试，未确认哪种一定有效。
- 文档指出使用 to_if_held_down 以 keyboard_fn 为目标会破坏全系统 Fn 发出（已验证失败），需避免。