komorebic start 命令完全指南:后台启动 komorebi 平铺窗口管理器

原创2026-09-21 14:13:032,332 阅读
文章标签:桌面应用CLI

komorebic start 命令完全指南:后台启动 komorebi 平铺窗口管理器

komorebic start 是 komorebi(Windows 平铺窗口管理器)生态中负责拉起整个窗口管理系统的入口命令:它以无窗口后台进程的形式启动 komorebi.exe,并可顺带启动按键守护进程 whkd、状态栏 komorebi-bar 以及用于焦点跟随鼠标的 masir。读完本文,你将掌握该命令的全部参数语义、底层启动机制与初始化流程,并能组合出适合自己工作流的完整启动方案。

start 命令是什么

komorebi 由两个核心二进制组成:komorebi.exe(窗口管理器本体)与 komorebic.exe(向窗口管理器发送命令的控制客户端),详见 安装指南。两者都不负责按键绑定——按键由 whkd 或 AutoHotkey 这类热键守护进程处理。

komorebic start 承担的是“点火”职责:把 komorebi.exe 作为后台进程拉起来,并在可选的参数驱动下,同时启动 whkd、komorebi-bar、masir 等配套进程。命令的官方定义如下:

Start komorebi.exe as a background process

Usage: komorebic.exe start [OPTIONS]

Options:
  -c, --config <CONFIG>
          Path to a static configuration JSON file

  -a, --await-configuration
          Wait for 'komorebic complete-configuration' to be sent before processing events

  -t, --tcp-port <TCP_PORT>
          Start a TCP server on the given port to allow the direct sending of SocketMessages

      --whkd
          Start whkd in a background process

      --bar
          Start komorebi-bar in a background process

      --masir
          Start masir in a background process for focus-follows-mouse

      --clean-state
          Do not attempt to auto-apply a dumped state temp file from a previously running instance of komorebi

  -h, --help
          Print help

参数逐一详解

在 komorebic 源码 中,Start 结构体用 clap 定义了与上述完全对应的字段。下面逐一说明每个参数的语义与适用场景。

-c, --config <CONFIG>

指定静态配置文件(JSON)的路径。komorebi 支持两种配置方式:

  • 静态配置(推荐):通过 -c 传入一份完整 JSON(可由 komorebic generate-static-config 生成),komorebi 启动时直接据此构建窗口管理器;
  • 传统配置:不传 -c 时,komorebi 会依次尝试从主目录读取 komorebi.json、komorebi.ahk、komorebi.ps1 等文件,通过命名管道逐条下发命令完成初始化。

从源码看,-c 路径经过 replace_env_in_path 处理,支持环境变量展开;在 komorebic 的处理逻辑 中,若传入的路径不存在,命令会直接报错 could not find file 并中止,因此在执行前务必确认文件真实存在。

-a, --await-configuration

启用“等待配置完成”模式。加上该参数后,komorebi 启动后不会立刻处理窗口事件,而是等待客户端发送 komorebic complete-configuration(见 complete-configuration 文档)后才开始铺排窗口。

这在传统配置场景下非常关键:因为配置是一系列通过管道逐条下发的命令,如果进程在配置下发完之前就开始响应窗口事件,会出现“窗口管理器已经动了、配置还没加载完”的竞态。与之呼应,komorebi 主程序 中通过全局原子标志 INITIAL_CONFIGURATION_LOADED 实现等待:主线程会以 backoff 自旋,直到 load_configuration 加载完成才继续。若配置是通过 -c 传入的静态文件,则 INITIAL_CONFIGURATION_LOADED 会被立即置位,该参数基本不起作用。

-t, --tcp-port <TCP_PORT>

在指定端口启动一个 TCP 服务器,允许外部程序绕过命名管道、直接发送 SocketMessage。启用后 komorebi 主程序 会调用 listen_for_commands_tcp(wm, port),与默认的命名管道监听(listen_for_commands)并行工作。适合需要从自定义脚本、其他语言程序或远程环境直接驱动 komorebi 的进阶场景。

--whkd

顺带在后台启动 whkd 按键守护进程。实现上(komorebic 源码)先生成一段 PowerShell 脚本:若检测到 whkd 进程尚未运行,则执行 Start-Process whkd -WindowStyle hidden 静默拉起。如果系统 PATH 中找不到 whkd 可执行文件,命令会直接报错提示先安装 whkd(komorebic 源码)。

--bar

顺带启动 komorebi-bar 状态栏。这里有一个值得注意的细节:若 -c 指定的静态配置中存在 bar_configurations 字段,komorebi-bar 会按配置逐条以 --config <路径> 方式启动(对应多显示器、多状态栏实例场景);否则回退为单实例兜底启动(见 komorebic 源码)。bar 的详细配置可参考 bar-configuration 文档。

--masir

顺带启动 masir 进程,为 komorebi 提供焦点跟随鼠标(focus-follows-mouse)能力。若 PATH 中找不到 masir,命令同样会报错中止(komorebic 源码)。注意该参数只是拉起 masir 进程本身,komorebi 侧的 focus-follows-mouse 行为仍由 komorebic toggle-mouse-follows-focus 等命令控制(可参考 mouse-follows-focus 文档)。

--clean-state

komorebi 在退出时会把自己的完整状态(各工作区布局、窗口归属等)以 JSON 形式 dump 到临时目录的 komorebi.state.json 文件中;下次启动时默认会自动尝试恢复该状态。加上 --clean-state 则跳过此恢复流程,从一张“干净的白纸”开始。

对应实现见 komorebi 主程序:启动时若临时目录存在 komorebi.state.json 且 --clean-state 未指定,则反序列化后调用 apply_state 应用;若文件损坏或结构过期,会打印 warning 并跳过,不会导致启动失败。这保证了“非正常退出 → 重启”的会话连续性。

-h, --help

打印命令帮助信息。

后台启动机制:start 的底层实现

komorebic start 并不仅仅往系统里“扔”一个进程。从 komorebic 的处理逻辑 可以看到一套完整的启动编排:

  1. 前置校验:若指定了 --whkd / --masir / --ahk,先用 which 确认对应可执行文件存在于 PATH;
  2. 可执行文件定位:若 komorebi 由 Scoop 安装(PATH 中存在 komorebi.ps1 shim),会反推出 apps\komorebi\current\komorebi.exe 的真实路径,否则默认使用 komorebi.exe;
  3. 参数透传:将 --config、--await-configuration、--tcp-port、--clean-state 等参数拼接成 PowerShell Start-Process 的 -ArgumentList,并以 -WindowStyle hidden 隐藏窗口启动——这就是“后台进程”语义的来源;
  4. 单实例确认与重试:启动后最多重试 3 次、每次等待 3 秒,轮询系统中是否出现 komorebi.exe 进程;若始终未出现,会改为前台直接运行 komorebi.exe 并打印 stderr,方便用户看到详细的报错输出。

作为呼应,komorebi 主程序 自身也做了单实例保护:启动时枚举系统进程,若发现已存在非 shim 的 komorebi.exe 实例,会记录错误并以退出码 1 终止,提示“请先退出已有进程”。

komorebi.exe 启动后的初始化流程

komorebic start 只是触发点,真正的初始化发生在 komorebi/src/main.rs 的 main 函数中,大致分为几个阶段:

  • 环境准备:调用 Windows API 允许设置前台窗口、设置进程 DPI 感知上下文,并获取当前会话 ID;
  • 日志初始化:按 --log-level(默认 Info)在临时目录创建每日滚动的 komorebi.log 与 komorebi_plaintext.log;
  • 窗口事件监听:启动 winevent_listener,作为后续窗口事件的输入源;
  • 窗口管理器构建:若传了 -c 静态配置,走 StaticConfig::preload 直接构建;否则构建 WindowManager 后异步 load_configuration 从配置文件逐条加载(这里与 --await-configuration 联动);
  • 状态恢复:如上一节所述,尝试应用 komorebi.state.json;
  • 服务模块就绪:依次启动 border_manager、stackbar_manager、transparency_manager、monitor_reconciliator、reaper(进程回收)、focus_manager、theme_manager 等通知监听线程,随后进入命令监听与事件处理主循环;
  • 优雅退出:收到 Ctrl-C 后,恢复所有隐藏窗口、等待动画完成、关闭订阅 Socket、dump 状态到临时文件并以退出码 130 结束。

整个生命周期中,各管理器(边框、堆叠栏、透明度、主题、焦点)均通过通知通道与窗口管理器解耦协作,这也解释了为什么 start 之后还需要 komorebic 系列命令持续驱动——启动只负责“把机器转起来”。

与其他命令的配合使用

start 不是孤立命令,它与以下命令形成了完整的启动-配置-停止闭环:

  • complete-configuration:与 --await-configuration 配对,传统配置模式下下发完最后一条配置后发出信号;
  • stop:对称地停止 komorebi 进程并恢复所有隐藏窗口,同样支持 --whkd、--bar、--masir 反向关闭配套进程(见 stop 文档);
  • quickstart:新用户可先运行 komorebic quickstart 拉取示例配置到主目录,再配合 start --whkd --bar 一键体验(见 quickstart 文档);
  • configuration:显示 komorebi.json 的路径,方便核对 -c 指向的默认文件。

实战启动示例

场景一:全新用户,一条命令拉起完整桌面环境

komorebic quickstart
komorebic start --whkd --bar

先由 quickstart 生成示例配置,再启动窗口管理器、热键守护进程与状态栏。

场景二:使用静态配置,显式指定文件

komorebic start --config "$HOME\komorebi.json" --whkd --bar

适合已经通过 komorebic generate-static-config 生成了完整静态配置、希望配置可版本化管理的用户。示例配置结构可参考仓库中的 komorebi.example.json。

场景三:传统配置,等待配置下发完成

komorebic start --await-configuration --whkd
# ... 在 komorebi.ahk / komorebi.ps1 中逐条下发配置 ...
komorebic complete-configuration

场景四:启用焦点跟随鼠标

komorebic start --masir
komorebic toggle-mouse-follows-focus

场景五:希望开机自启

无需手动写启动脚本,直接使用 enable-autostart 命令(在 shell:startup 创建快捷方式),并可通过 disable-autostart 命令 移除。

场景六:排查启动失败

如果 start 重试后仍提示进程未启动,命令会自动以前台方式运行 komorebi.exe 并输出错误信息。也可手动前台运行 komorebi.exe --log-level trace 查看详细日志,日志文件位于 Windows 临时目录(%TEMP%\komorebi.log)。

小结

komorebic start 是 komorebi 生态的“总开关”:它通过 PowerShell Start-Process -WindowStyle hidden 将窗口管理器本体与 whkd、komorebi-bar、masir 等配套进程编排为后台服务,配合 --config 的静态配置与 --clean-state 的状态控制,构成了可脚本化、可复现的桌面环境启动方案。理解其参数与底层初始化流程,是正确搭建 Windows 平铺桌面工作流的第一步。

登录后查看全文
komorebi