i3 与 Emacs 的 XCB 级集成：通过 passthrough 机制实现零延迟键盘事件转发

对于同时依赖 i3 窗口管理器与 Emacs 的重度用户而言，如何在两者之间实现一致的键盘导航体验是一个长期存在的工程难题。传统的代理脚本方案虽然可行，但难以消除延迟；而 EXWM 虽然提供了原生集成，却在处理 Steam 等图形程序时表现不佳。本文将深入解析一种通过修改 i3 源码实现的底层集成方案，该方案利用 XCB 事件转发机制，让 i3 在保持对全局按键的独占捕获的同时，能够将特定按键事件直接传递给 Emacs 处理。

问题背景：从 EXWM 到代理脚本的局限

EXWM（Emacs X Window Manager）曾被视为 Emacs 用户理想的窗口管理解决方案，它将 X 窗口作为 Emacs buffer 管理，理论上实现了统一的键盘操作体验。然而实际使用中，EXWM 对某些图形程序（如 KiCad、Steam）的输入处理存在兼容性问题，且整体响应速度难以满足对延迟敏感的用户需求。

另一种常见方案是使用外部脚本代理按键命令。该方案通过 xdotool 检测当前焦点窗口，若为 Emacs 则通过 emacsclient 转发命令，否则调用 i3-msg 执行 i3 命令。这种方案虽然避免了 EXWM 的稳定性问题，但实测延迟达到 30-100 毫秒，对于高频使用的窗口导航快捷键而言，这种延迟足以破坏操作的流畅感。

XCB 事件抓取机制与转发原理

i3 的按键捕获基于 XCB（X C Binding）实现。在 src/bindings.c 中，i3 通过 xcb_grab_key() 在根窗口（root window）上注册全局按键监听，关键参数 owner_events = 0 意味着 X 服务器将所有匹配事件直接路由到 i3，而非事件产生的目标窗口。这种设计确保了窗口管理器对系统快捷键的绝对控制，但也造成了与 Emacs 等应用程序的按键冲突。

核心问题在于：当 i3 捕获到按键事件后，如果判断当前焦点窗口是 Emacs，能否将事件重新注入到 Emacs 的事件队列？答案是肯定的。通过 xcb_send_event() 函数，可以将原始的 xcb_key_press_event_t 结构体重新发送到指定的目标窗口。这一机制构成了 passthrough 方案的技术基础。

实现细节：扩展 Binding 结构体与解析器

nausicaä 的 patch 方案在 i3 的 Binding 结构体中新增了一个 passthrough 字段，用于存储允许直接透传按键事件的窗口类名：

struct Binding {
    struct {
        char *class;
    } passthrough;
};

在配置解析层面，patch 扩展了 i3 的配置 DSL，新增 --passthrough 选项。用户在 i3 配置文件中可以这样声明：

bindsym --passthrough $mod+h focus left
bindsym --passthrough $mod+j focus down

当解析器遇到 --passthrough 标志时，会将对应的窗口类名（默认为 "Emacs"）存储到 Binding 结构体的 passthrough.class 字段中。

事件处理的核心逻辑位于 handle_key_press() 函数。当按键事件触发时，系统首先检查当前 binding 是否配置了 passthrough。若已配置，则通过 xcb_get_input_focus() 获取当前焦点窗口，并比对窗口的 class_class 属性。如果匹配成功，patch 将修改原始事件结构体的 event 字段为目标窗口 ID，然后调用 xcb_send_event() 重新发送事件，并立即返回，跳过 i3 的默认命令执行流程。

需要注意的是，由于 i3 在捕获事件时已经导致 Emacs 窗口失去焦点，patch 目前尚未完全解决焦点恢复问题。这是一个已知的限制，需要进一步研究 XCB 的焦点管理 API。

Emacs 端的双向导航实现

在 Emacs 端，需要实现与 i3 的双向通信机制。当 Emacs 接收到透传的导航命令时，首先尝试在 Emacs 内部进行窗口切换；若当前方向已无 Emacs 窗口可切换，则通过 i3-msg 将命令回传给 i3，实现跨应用程序的窗口导航。

窗口移动的核心函数利用 Emacs 内置的 windmove 库：

(defun nausicaa/emacs-i3-windmove (dir)
  "Select window in DIR, if it exists; if not, i3-select it."
  (let ((other-window (nausicaa/find-other-window dir)))
    (if (or (null other-window) (window-minibuffer-p other-window))
        (nausicaa/i3-msg "focus" (symbol-name dir))
      (nausicaa/do-window-select dir))))

其中 nausicaa/i3-msg 是一个宏，用于异步调用 i3-msg 命令：

(defmacro nausicaa/i3-msg (&rest args)
  `(start-process "emacs-to-i3" nil "i3-msg" ,@args))

这种设计确保了导航操作的单向延迟最小化。当在 Emacs 内部移动窗口时，使用 window-swap-states 实现窗口状态交换；当需要跨越 Emacs 边界时，则委托 i3 处理容器级别的窗口移动。

可落地的配置参数与实施步骤

对于希望采用此方案的用户，以下是具体的实施步骤：

1. 获取并应用 patch

patch 文件可从 khz.ac 获取。应用 patch 前确保 i3 源码版本为 4.25.1 或兼容版本：

cd i3-source
git apply i3-passthrough.patch

2. 编译与安装

使用 meson 构建系统重新编译 i3。对于 Nix 用户，可参考以下 shell.nix 配置开发环境：

pkgs.mkShell {
  nativeBuildInputs = with pkgs; [
    pkg-config meson ninja libxcb libxcb-util libxcb-wm
    libxcb-keysyms libxkbcommon xcbutilxrm
  ];
}

3. i3 配置语法

在 i3 配置文件中，为需要透传给 Emacs 的按键绑定添加 --passthrough 标志：

bindsym --passthrough $super+Return exec mistty-create
bindsym --passthrough $super+Control+Return exec alacritty-create

4. Emacs 端配置

确保 Emacs 以 server 模式运行，以便外部脚本通过 emacsclient 调用：

(add-hook 'after-init-hook #'server-start)

绑定 passthrough 按键到 Emacs 函数：

(map!
 "s-<return>" #'mistty-create
 "C-s-<return>" #'nausicaa/launch-alacritty)

权衡与替代方案

此方案的主要优势在于消除了代理脚本的进程创建开销，实现了接近原生的响应速度。然而，它也存在明显的权衡：需要维护一个 fork 或 patch 版本的 i3，增加了系统更新的复杂性；且由于 i3 维护者认为此功能超出项目范围，patch 不会进入上游。

对于不愿意维护自定义 i3 构建的用户，经典的 xdotool + emacsclient 代理方案仍是可行的替代选择。虽然存在可感知的延迟，但对于非高频操作而言，这种延迟在可接受范围内。另一种选择是探索 Wayland 生态下的类似解决方案，如 Sway 与 Emacs 的集成，尽管这需要重新评估技术实现路径。

无论采用何种方案，核心设计原则是一致的：在窗口管理器与编辑器之间建立双向的、上下文感知的命令路由机制，让用户能够在不感知边界的情况下，在 Emacs 窗口与系统窗口之间无缝导航。

资料来源

• nausicaä, "my i3-emacs integration", khz.ac, 2025
• SqrtMinusOne, "Getting a consistent set of keybindings between i3 and Emacs", sqrtminusone.xyz, 2021
• i3wm, "IPC interface (interprocess communication)", i3wm.org/docs/ipc.html

systems