name: niri-ipc
description: 通过 Niri Wayland 合成器的 IPC 接口（niri msg --json / $NIRI_SOCKET）在 Linux 上控制 Niri。当您需要在 Niri 会话中运行的 OpenClaw 代理查询 Niri 状态（输出/工作区/窗口/焦点窗口）或执行操作（聚焦/移动/关闭窗口、切换工作区、启动命令、重载配置）时使用。

Niri IPC

通过 niri msg 命令行工具（推荐）或向 $NIRI_SOCKET 写入 JSON 请求来使用 Niri IPC。

本技能假设：
- 您在运行 Niri 的 Linux 系统上。
- $NIRI_SOCKET 环境变量已设置（通常在 Niri 会话内自动设置）。

快速开始（推荐）

使用附带的辅助脚本（基于 niri msg --json 的封装）：

./skills/niri-ipc/scripts/niri.py version
./skills/niri-ipc/scripts/niri.py outputs
./skills/niri-ipc/scripts/niri.py workspaces
./skills/niri-ipc/scripts/niri.py windows
./skills/niri-ipc/scripts/niri.py focused-window

深入控制

1) 高级助手（窗口匹配）

当您希望通过标题或应用 ID 子字符串来引用窗口，而非直接使用 ID 时，请使用 scripts/niri_ctl.py：

# 列出窗口（可选过滤）
./skills/niri-ipc/scripts/niri_ctl.py list-windows --query firefox

# 通过子字符串匹配聚焦窗口
./skills/niri-ipc/scripts/niri_ctl.py focus firefox

# 关闭匹配的窗口（先聚焦再关闭）
./skills/niri-ipc/scripts/niri_ctl.py close firefox

# 将匹配的窗口移动到指定工作区（通过索引或名称）
./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox 3
./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox web

# 通过索引或名称聚焦工作区
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace 2
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace web

2) 完整 IPC 访问（原始套接字）

使用 scripts/niri_socket.py 直接与 $NIRI_SOCKET 通信（换行分隔的 JSON）：

# 发送简单请求（JSON 字符串）
./skills/niri-ipc/scripts/niri_socket.py raw '"FocusedWindow"'

# 批量请求：标准输入每行一个 JSON 请求
printf '%s\n' '"FocusedWindow"' '"Workspaces"' | ./skills/niri-ipc/scripts/niri_socket.py stdin

# 事件流（持续打印 JSON 事件，直到被中断）
./skills/niri-ipc/scripts/niri_socket.py event-stream

操作

传递 Niri 操作命令：

# 通过索引聚焦工作区
./skills/niri-ipc/scripts/niri.py action focus-workspace 2

# 将焦点窗口移动到工作区
./skills/niri-ipc/scripts/niri.py action move-window-to-workspace 3

# 通过 ID 聚焦窗口
./skills/niri-ipc/scripts/niri.py action focus-window 123

# 关闭焦点窗口
./skills/niri-ipc/scripts/niri.py action close-window

# 重载 Niri 配置
./skills/niri-ipc/scripts/niri.py action load-config-file

# 启动程序（不通过 shell）
./skills/niri-ipc/scripts/niri.py action spawn -- alacritty

# 通过 shell 启动程序
./skills/niri-ipc/scripts/niri.py action spawn-sh -- 'notify-send hello'

输出配置

通过封装脚本使用 niri msg output ...：

./skills/niri-ipc/scripts/niri.py output --help

直接使用 niri msg

如果不希望使用辅助脚本，可以直接调用 Niri：

niri msg --json windows
niri msg --json action focus-workspace 2

提示：如果升级后 niri msg 出现解析错误，请重启合成器（新版本的 niri msg 与旧版本合成器不匹配是常见问题）。

事件流

适用于状态栏/守护进程：Niri 可以流式传输事件。

# 原始 JSON 事件行（持续运行直到被中断）
./skills/niri-ipc/scripts/niri.py event-stream

# 仅输出几行用于快速测试
./skills/niri-ipc/scripts/niri.py event-stream --lines 5

故障排除

• 如果命令失败并提示“NIRI_SOCKET is not set”：请在 Niri 会话内运行命令，或手动导出套接字路径。
• 如果需要了解套接字协议详情，请阅读：./skills/niri-ipc/references/ipc.md。
• 如果您的目标是复杂自动化（例如通过标题或应用 ID 选择正确的窗口等），请先查询 windows，然后根据窗口 ID 执行操作。