niri-ipc

核心用法

Niri IPC 技能为 OpenClaw Agent 提供了与 Niri Wayland 合成器交互的完整能力，主要通过三层接口实现：

1. 基础查询层（niri.py）：封装 niri msg --json 命令，支持获取版本、显示器输出、工作区、窗口列表及当前聚焦窗口等状态信息。

2. 智能控制层（niri_ctl.py）：提供基于子串匹配的窗口管理，无需记忆窗口 ID 即可通过应用名称或标题模糊匹配执行聚焦、关闭、移动至工作区等操作。

3. 原始 IPC 层（niri_socket.py）：直接通过 UNIX Socket 与 $NIRI_SOCKET 通信，支持批量请求和事件流订阅，适用于状态栏开发等高级场景。

典型工作流包括：查询窗口状态 → 匹配目标窗口 → 执行聚焦/移动/关闭操作，或订阅事件流实现实时桌面状态同步。

显著优点

• 零外部依赖：仅使用 Python 标准库，无 pip 安装风险，部署极简
• 多层安全封装：从高层抽象到原始 IPC 的分层设计，满足不同复杂度需求
• 原生 JSON 支持：所有查询返回结构化数据，便于 Agent 解析和后续自动化
• 事件驱动能力：支持实时事件流，可构建响应式桌面工具
• 输入安全：全面使用 argparse 进行参数校验，无命令注入风险

潜在缺点与局限性

• 环境强绑定：必须在 Niri 会话内运行，依赖 $NIRI_SOCKET 环境变量，无法跨 compositor 或远程使用
• T3 来源限制：由个人开发者维护，非 Niri 官方项目，长期维护稳定性存疑
• 功能边界明确：仅支持 Niri 特定功能，无法迁移至 Sway、Hyprland 等其他 Wayland 合成器
• 破坏性操作风险：原始 socket 接口可触发退出合成器、关闭显示器等高危操作，需用户自行把控

适合的目标群体

• Niri 用户：已采用 Niri 作为日常 Wayland 合成器的 Linux 桌面用户
• 效率工具开发者：构建 Niri 专属状态栏、工作区指示器、窗口切换器的开发者
• 自动化爱好者：希望通过 Agent 实现智能窗口管理、工作流自动化的技术用户
• r/unixporn 风格用户：追求高度可定制桌面环境的发烧友

使用风险

• 会话依赖风险：若 $NIRI_SOCKET 未设置或 Niri 未运行，所有命令将失败
• 版本兼容风险：Niri 升级后可能出现 niri msg 协议不匹配，需重启合成器
• 误操作风险：窗口关闭、工作区切换等操作无二次确认，自动化脚本可能干扰当前工作
• 权限隐含要求：虽无显式权限申请，但 IPC 操作隐含需要与 Niri 进程同用户权限

核心用法

niri-ipc 是一套用于控制 Niri Wayland 合成器的工具集，提供三层调用方式：

1. 快速查询 (niri.py)：封装 niri msg --json，获取版本、输出、工作区、窗口列表及焦点窗口
2. 高级控制 (niri_ctl.py)：支持按窗口标题/app_id 子串模糊匹配，实现聚焦、关闭、移动窗口到指定工作区
3. 原始 IPC (niri_socket.py)：直接操作 $NIRI_SOCKET，支持批量请求和事件流订阅

关键操作包括：工作区切换 (focus-workspace)、窗口移动 (move-window-to-workspace)、窗口聚焦/关闭 (focus-window/close-window)、配置重载 (load-config-file) 以及命令启动 (spawn/spawn-sh)。

显著优点

• 零依赖设计：仅使用 Python 标准库，彻底规避供应链攻击风险
• 三层抽象：从简单查询到复杂模糊匹配，覆盖不同自动化场景
• 事件流支持：原生支持 Niri 事件流，便于构建状态栏和守护进程
• 本地安全通信：仅通过 Unix Socket 与本地 Niri 进程交互，无网络外发

潜在局限

• 平台限定：仅支持运行 Niri 的 Linux 系统，无跨平台能力
• 环境依赖：必须正确设置 $NIRI_SOCKET，在 SSH 或裸终端中需手动导出
• 版本敏感：niri msg 与合成器版本不匹配时可能解析失败，需重启会话
• 无图形反馈：纯 CLI 工具，错误信息依赖终端输出

适合人群

• 使用 Niri 作为主桌面环境的 Linux 高级用户
• 需要构建自定义工作流、快捷键或自动化脚本的开发者
• 开发 Wayland 状态栏、窗口管理辅助工具的作者

常规风险

• 进程控制风险：可关闭任意窗口、切换工作区，恶意调用可能导致工作中断
• 命令注入边界：spawn-sh 接受 shell 字符串，需确保参数来源可信
• 权限边界：虽无提权能力，但在共享会话中可能干扰其他用户操作

建议仅在单用户桌面会话中使用，避免在系统级服务或共享环境中部署。