apphane-dev/nehir 来源：https://github.com/apphane-dev/nehir 一个基于 Niri 列布局范式的 macOS 滚动平铺窗口管理器。 > Nehir（土耳其语中的“河流”）——窗口在列中流动，在屏幕上水平滚动。 ## 功能 - Niri 滚动列布局 — 窗口排列在水平滚动的列中，当堆叠的窗口无法在最小高度下容纳时，自动溢出为标签页 - 工作区管理 — 多个工作区，支持热键切换 - 窗口边框 — 可配置颜色的焦点窗口边框 - 工作区栏 — 每显示器状态栏，显示工作区名称和应用图标 - 鼠标跟踪焦点 — 可选的悬停聚焦 - 多显示器支持 — 跨显示器的无缝窗口管理。为了获得最佳 Niri 滚动体验，请使用自动隐藏 Dock，并在 macOS 系统设置中垂直排列显示器，以避免停靠在屏幕外的窗口溢出到相邻显示器上。 - 概览模式 — 所有窗口的鸟瞰视图 - 命令面板 — 命令的模糊搜索 - 应用规则 — 按应用的布局覆盖 - IPC — 用于通过 nehirctl 进行外部控制的 Unix 套接字 - TOML 配置 — ~/.config/nehir/ 下的拆分配置 ## 安装 ### Homebrew 在首个版本发布后，可通过 guria/tap Homebrew tap 分发 Nehir： bash brew tap guria/tap brew install --cask nehir 安装后 Nehir 需要辅助功能权限： text 系统设置 > 隐私与安全性 > 辅助功能 ### 从源码构建 bash # 打包应用 mise run package:release # 用户本地安装（无需 sudo） mkdir -p "$HOME/Applications" "$HOME/.local/bin" rm -rf "$HOME/Applications/Nehir.app" cp -R dist/Nehir.app "$HOME/Applications/Nehir.app" install -m 755 .build/apple/Products/Release/nehirctl "$HOME/.local/bin/nehirctl" 或使用 mise： bash # 用户本地安装 mise run install # 系统级安装 mise run install:system ## 使用 bash # 运行 Nehir # CLI 控制（需要启用 IPC） nehirctl command focus left nehirctl command switch-workspace 2 nehirctl --help ### 崩溃或强制退出后恢复窗口 Nehir 在正常优雅退出时会恢复停靠/屏幕外的窗口。强制退出、崩溃或 kill -9 会绕过关闭清理流程，因此 macOS 可能会将之前停靠的窗口留在屏幕边缘。如果发生这种情况，请使用 macOS 内置的窗口快捷键将选中的 Mission Control 窗口带回屏幕： - 缩放（Fill） — Control + Globe/Fn + F - 居中（Centre/Center） — Control + Globe/Fn + C 你也可以在 macOS 的窗口菜单中找到这些操作。在 Mission Control 中，选中卡住的窗口并应用缩放（Fill）或居中（Centre/Center）通常可以将其恢复到可见桌面。 ## 调试与追踪 追踪捕获和其他调试命令都受开发者模式保护。在设置的诊断标签页中启用它——这会解锁命令面板和热键设置中的 Debug: ... 命令，启用 IPC 调试端点，并显示同一标签页中的调试操作、后台追踪缓冲区和最近追踪面板。 开启开发者模式后，你可以从任何地方开始追踪捕获： - DebugBar — 开发者模式会显示一个轻量级覆盖层，包含录制、recent-clip、重置缓冲区以及保留控制 - 命令面板 — Debug: Toggle Trace Capture（默认热键 Ctrl+Option+Cmd+T） - 自定义快捷键 — 在设置 → 热键下绑定任一调试操作 - CLI / IPC — nehirctl command debug trace toggle；可接受可选的 desiredState 参数（active/inactive），用于幂等脚本，例如 nehirctl command debug trace toggle active；在追踪捕获运行期间，nehirctl command debug capture-recent-trace 会导出一个保留的最近片段 ### 捕获复现 一份干净的追踪只涵盖错误行为本身，并让 Nehir 自有的 UI 不干扰复现： 1. 在设置 → 诊断中启用一次开发者模式。 2. 开始追踪捕获。自定义热键或 DebugBar 是最理想的——它们无需打开设置窗口就能触发。 3. 关闭设置窗口。 Nehir 自有的窗口（设置、命令面板、应用规则）会改变焦点和布局行为，因此在它们关闭时复现，更符合正常使用时问题实际发生的情况。 4. 像往常一样复现问题。 5. 停止追踪捕获。日志包会被写入： text ${XDG_STATE_HOME:-$HOME/.local/state}/nehir/traces/ 并且其路径会复制到你的剪贴板。 6. 分享追踪文件，而不是路径——本地路径只在你自己的机器上有意义。使用最近追踪列表中的复制文件，或将其从追踪文件夹中拖出。 诊断标签页中的最近追踪列表会保留最近十次捕获，并允许你复制路径（方便粘贴到终端）、复制文件或显示文件夹。 提示：触发错误行为之前开始捕获，并立即停止，这样日志就不会被无关活动填充。 同一类别中的其他调试命令： - Debug: Dump Runtime State — 将当前运行时调试转储复制到剪贴板，并写入统一日志 - Debug: Reset Runtime State — 清除运行时调试状态，并从启动式的重新扫描开始重新引导跟踪 - Debug: Restart Clearing Runtime State — 清除运行时调试状态并重新启动应用（确认对话框带有启用追踪复选框，可在引导过程中尽早开始捕获） 有关 IPC/CLI 用法，请参阅 docs/IPC-CLI.md。 ## 配置 Nehir 使用 ~/.config/nehir/ 下的拆分文件配置布局： ~/.config/nehir/ ├── settings.toml # 核心应用行为 ├── hotkeys.toml # 物理按键绑定 ├── workspaces.toml # 工作区定义 ├── apprules.d/ # 每个应用规则一个文件 │ ├── com-google-chrome.toml │ └── pip-floating.toml.sample # 非活动示例 └── monitors.d/ # 每显示器覆盖 └── studio-display.toml 所有文件都会被监视变更——修改会实时生效，无需重启。有关设计原理，请参阅配置原则。 ### 鼠标焦点行为 这里有两个相互作用的设置： - moveMouseToFocusedWindow 会在焦点变化后移动指针，但 Nehir 主要将其视为键盘/命令导航的辅助行为。由指针引发的焦点变化不会移动光标：鼠标悬停/点击、工作区栏点击、标签页覆盖层点击、触控板手势、滚动动画以及浮动窗口点击/拖动都会保持指针位置不变。 - 空工作区命令切换是主要的刻意例外：当没有焦点窗口目标时，Nehir 会跳转到目标显示器中心，使指针落位到你导航到的显示器上。 - focusFollowsMouse 经过防抖处理，并会在滚动/滑动动画完成后以及 Nehir 自有 UI 窗口（设置、应用规则、命令面板）关闭后刷新，因为这些交互可能不会生成新的鼠标移动事件。 - 启用 focusFollowsMouse 后，滑动手势结束时更新视口选择，但不会将焦点提交到吸附的列上；手势/动画结束后，最终焦点会跟随指针。 - 当浮动窗口是 Niri 布局上方的活动表面时，平铺悬停焦点会被禁用，这样向该浮动窗口移动时就不会意外聚焦并提升其背后的平铺列。 - 一个仅可见但位于活动平铺窗口之后的浮动窗口，不会禁用平铺悬停焦点。 - 在可见的非托管 WindowServer 窗口上也阻止悬停聚焦，并且在浮动/非托管指针交互后会短暂抑制，因此点击或拖动这些窗口不会立即激活其背后的平铺列。 ### 默认快捷键模型 Nehir 的默认值以物理按键组合的形式存储和显示。 - Option+Command — 导航、聚焦和打开 UI - Option+Shift+Command — 移动焦点窗口 - Control+Option+Command — 更大范围的导航，如工作区历史记录和列索引 - Hyper — 物理键 Control+Option+Shift+Command，保留用于结构性移动 要更轻量地进入基础层，请参阅 Karabiner 双击 Command 方案。 目标是形成一套小而可预测的修饰键模式： text 不带 Shift = 到那里去 带 Shift = 将当前窗口移动过去 Hyper = 重塑结构或移动结构 ## 开发 bash # 构建（调试） mise run build # 构建并运行 mise run dev # 发布构建 mise run build:release # 运行测试（需要 Xcode） mise run test # 清理 mise run clean 有关搭建细节、变更集、发布流程和 Nehir 的维护原则，请参阅 CONTRIBUTING.md。 ## 系谱 Nehir 是一个有着清晰系谱的想法的 macOS 实现。 ### 范式 — Niri Nehir 的交互模型——窗口位于水平滚动的列中——直接移植自 [Niri] 的设计语言。Niri 是一个可滚动的平铺 Wayland 合成器；Nehir 将这一工作流程带到了 macOS。 ### 代码 — OmniWM Nehir 是 [OmniWM] 的一个有明确取舍的 fork。OmniWM 是 BarutSRB 开发的一个通用 macOS 平铺窗口管理器。我们借用了它的 macOS 窗口管理引擎，并将其收窄为单一的布局引擎，抛弃了向后兼容的包袱，以便做好一件事。对原作者打下这一基础深表感谢——完整致谢请参阅 NOTICE.md。 相对 OmniWM 的显著变化 - 单一布局模型。 Nehir 围绕 Niri 式滚动列重新构建，而不是保留多种布局/控制模型。 - 无传统兼容层。 配置、默认值、热键和行为都可以调整，以适应 Nehir 更专注的工作流程。 - 必需的运动保持启用。 与 OmniWM 中可由用户切换的动画偏好不同，Nehir 将布局运动视为交互模型的一部分：禁用它会使 Niri 式滚动、调整大小和过渡状态难以跟随，因此没有 animationsEnabled 设置。 - 拆分 TOML 配置。 运行时配置组织在 ~/.config/nehir/ 下，分别用单独的配置文件承载设置、热键、工作区、应用规则和显示器覆盖。 - 关闭/折叠时焦点保持本地。 当 macOS 在关闭或折叠当前窗口后报告另一个同应用窗口获得焦点时，Nehir 将其视为原生回退焦点，而非用户导航。对非活动工作区的同应用回退会被忽略；在当前工作区中，非托管的快速终端回退也会被忽略，以免视口滚动到该应用的托管列。显式的 Nehir 焦点命令仍然优先。 - 可配置的手势滚动吸附。 触控板滑动手势可以吸附到列边界，也可以在滚动中途自由停止。由 settings.toml 中的 gestures.scrollSnap 控制（默认 true）。 - 更智能的鼠标焦点和光标跳转。 由指针引发的焦点不再让 moveMouseToFocusedWindow 跳转光标，并且悬停焦点被限制在浮动/非托管窗口周围，以适应 Niri 布局模型。 - 内置运行时调试工具。 Nehir 现在提供命令面板和 IPC/CLI 操作，用于转储运行时状态、重置/重新引导运行时状态、在清除运行时状态时重启，以及在 ${XDG_STATE_HOME:-$HOME/.local/state}/nehir/traces/ 下捕获运行时追踪包。 ### 同类项目 — 其他地方的滚动平铺 Nehir 是探索这一工作流程的多个项目之一： - [PaperWM] — GNOME Shell。 - [Paneru] — macOS（另一个受 Niri 启发的条带管理器）。 - [karousel] — KDE。 - [papersway] — sway/i3。 - [hyprscroller] 和 [hyprslidr] — Hyprland。 - [PaperWM.spoon] — macOS（Hammerspoon）。 [Niri]: https://github.com/niri-wm/niri [OmniWM]: https://github.com/BarutSRB/OmniWM [PaperWM]: https://github.com/paperwm/PaperWM [Paneru]: https://github.com/karinushka/paneru [karousel]: https://github.com/peterfajdiga/karousel [papersway]: https://spwhitton.name/tech/code/papersway/ [hyprscroller]: https://github.com/dawsers/hyprscroller [hyprslidr]: https://gitlab.com/magus/hyprslidr [PaperWM.spoon]: https://github.com/mogenson/PaperWM.spoon ## 许可证 GPL-2.0-only