Niri IPC

核心用法

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 <pattern>
• 事件监控：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 模式）|

核心用法

niri-ipc 是一套面向 Niri Wayland 合成器的本地 IPC 控制工具集，提供三层调用接口：顶层 niri.py 封装常用查询与动作命令；中层 niri_ctl.py 支持按窗口标题或应用 ID 模糊匹配进行智能操控；底层 niri_socket.py 可直接读写 $NIRI_SOCKET 实现原始 JSON 通信与事件流监听。用户可查询显示器、工作区、窗口状态，执行聚焦、移动、关闭窗口，切换工作区，派生命令，重载配置等操作，亦可订阅实时事件流用于状态栏或守护进程开发。

显著优点

该技能架构精简，仅依赖 Python 标准库，零第三方包，极大降低供应链攻击面。三层 API 设计兼顾快速上手与深度定制：新手用 niri.py 一行命令即可操控；进阶用户以子字符串匹配窗口，免记繁琐 ID；高阶开发者直接操作 socket 实现批量请求与事件驱动编程。全程本地 Unix Socket 通信，无网络外连，隐私数据零出境。代码结构清晰，静态与动态分析均获高分，功能行为与声明高度一致。

潜在缺点与局限性

使用场景高度受限：必须运行于已启动 Niri 的 Linux 会话内，且依赖 $NIRI_SOCKET 环境变量正确设置。对非 Niri 用户（如 sway、Hyprland、i3 等其它窗口管理器用户）完全无价值。子进程调用本地 niri 命令需确保二进制来源可信，若系统包管理器版本与 skill 预期不一致可能出现解析错误。此外，T3 来源级别意味着缺乏成熟开源社区的长期维护背书，后续更新与漏洞响应依赖个人开发者。

适合的目标群体

主要面向三类用户：其一，Niri 重度用户与平铺式窗口管理爱好者，追求键盘驱动的高效工作流；其二，Linux 桌面极客与开发者，需自动化窗口布局、工作区切换或构建自定义状态栏；其三，开源贡献者与技术审阅者，关注 Wayland 生态工具链实现细节。不推荐普通 Linux 桌面用户或非技术背景人员使用，亦不适合无 Niri 环境的开发者。

常规使用风险

性能方面，频繁的 socket 通信与 JSON 序列化在极端高频场景下可能引入微秒级延迟，但常规使用无感知。依赖项单一但刚性：必须预装 Niri compositor，且版本匹配至关重要，升级后未及时重启合成器易导致命令解析失败。权限层面，需具备与 Niri socket 通信的用户权限，多用户系统需注意 socket 文件权限配置。来源可信度 T3 提示用户应自行审阅代码，关注平台更新与用户反馈，避免在未审计情况下用于敏感生产环境。