通过 IPC 接口远程控制 Niri Wayland 合成器，实现窗口/工作区管理、配置重载及事件流监控，专为 Linux 桌面自动化设计。
说明：
## 核心用法
**niri-ipc** 提供三层控制能力，适用于 Niri Wayland 合成器的程序化操控：
| 层级 | 工具 | 典型场景 |
|——|——|———|
| 便捷封装 | `niri.py` | 快速查询状态（outputs/workspaces/windows）、执行标准 action |
| 智能匹配 | `niri_ctl.py` | 按窗口标题/app_id 子串模糊匹配，无需硬编码 ID |
| 原始套接字 | `niri_socket.py` | 直接读写 `$NIRI_SOCKET`，支持批量请求与事件流订阅 |
**关键操作示例**：
– 状态查询：`niri.py outputs|workspaces|windows|focused-window`
– 窗口操控：`niri_ctl.py focus|close|move-to-workspace `
– 事件监控：`niri.py event-stream`（持续输出 JSON 事件，适合状态栏集成）
– 配置热重载：`niri.py action load-config-file`
### 显著优点
1. **零依赖协议**：基于 `$NIRI_SOCKET` 的换行分隔 JSON，任何语言均可实现客户端
2. **模糊匹配层**：`niri_ctl.py` 解决 Wayland 全局唯一 ID 不稳定的痛点，用可读字符串代替数字 ID
3. **事件驱动架构**：原生支持 `event-stream`，无需轮询即可构建实时状态栏
4. **安全隔离**：仅响应本地 Unix 域套接字，无网络暴露风险
### 潜在局限
– **版本耦合**：`niri msg` 与运行中的 compositor 版本必须匹配，升级后需重启会话
– **Linux/Niri 独占**：无法跨平台，依赖特定 Wayland 合成器
– **无内置权限模型**：任何能访问 `$NIRI_SOCKET` 的进程拥有完全控制能力
– **Shell 转义陷阱**：`spawn-sh` 涉及字符串拼接，复杂命令易引发解析错误
### 适合人群
– 使用 Niri 的开发者/高级用户，需构建自定义工作流（如自动窗口布局脚本）
– 状态栏/面板开发者（Waybar、Eww 等），需实时监听工作区切换事件
– 多显示器用户，需程序化控制输出配置与窗口迁移
### 常规风险
| 风险类别 | 说明 | 缓解建议 |
|———|——|———|
| 权限扩散 | `$NIRI_SOCKET` 权限若配置宽松，非预期进程可操控桌面 | 检查套接字文件权限，避免全局可写 |
| 版本不匹配 | 升级后旧客户端调用新协议字段会导致解析失败 | 升级后重启 Niri 会话 |
| 自动化失控 | 脚本高频调用 `action` 可能引发焦点闪烁或窗口状态竞争 | 添加延迟与状态校验逻辑 |
| 命令注入 | `spawn-sh` 的参数通过 shell 解释，特殊字符需转义 | 优先使用 `spawn`（无 shell 模式）|
会员专属
