komorebic start 命令完全指南:后台启动 komorebi 平铺窗口管理器
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 的处理逻辑 可以看到一套完整的启动编排:
- 前置校验:若指定了
--whkd/--masir/--ahk,先用which确认对应可执行文件存在于 PATH; - 可执行文件定位:若 komorebi 由 Scoop 安装(PATH 中存在
komorebi.ps1shim),会反推出apps\komorebi\current\komorebi.exe的真实路径,否则默认使用komorebi.exe; - 参数透传:将
--config、--await-configuration、--tcp-port、--clean-state等参数拼接成 PowerShellStart-Process的-ArgumentList,并以-WindowStyle hidden隐藏窗口启动——这就是“后台进程”语义的来源; - 单实例确认与重试:启动后最多重试 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 平铺桌面工作流的第一步。