Niri IPC

# Niri IPC

通过 `niri msg` CLI（推荐）或向 `$NIRI_SOCKET` 写入 JSON 请求来使用 Niri IPC。

本技能假设： - 您正在运行 Linux 且 Niri 正在运行。 - 已设置 `$NIRI_SOCKET`（在 Niri 会话中通常为真）。

## 快速开始（推荐）

使用内置的辅助脚本（`niri msg --json` 的封装）：

```bash ./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) 高级辅助工具（窗口匹配）

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

```bash # List windows (optionally filtered) ./skills/niri-ipc/scripts/niri_ctl.py list-windows --query firefox

# Focus a window by substring match ./skills/niri-ipc/scripts/niri_ctl.py focus firefox

# Close a matched window (focus then close) ./skills/niri-ipc/scripts/niri_ctl.py close firefox

# Move a matched window to a workspace (by index or by name) ./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox 3 ./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox web

# Focus a workspace by index or name ./skills/niri-ipc/scripts/niri_ctl.py focus-workspace 2 ./skills/niri-ipc/scripts/niri_ctl.py focus-workspace web ```

### 2) 完整 IPC 访问（原始 Socket）

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

```bash # Send a simple request (JSON string) ./skills/niri-ipc/scripts/niri_socket.py raw '"FocusedWindow"'

# Batch requests: one JSON request per line on stdin printf '%s\n' '"FocusedWindow"' '"Workspaces"' | ./skills/niri-ipc/scripts/niri_socket.py stdin

# Event stream (prints JSON events until interrupted) ./skills/niri-ipc/scripts/niri_socket.py event-stream ```

### 动作

透传 Niri 动作：

```bash # Focus workspace by index ./skills/niri-ipc/scripts/niri.py action focus-workspace 2

# Move focused window to workspace ./skills/niri-ipc/scripts/niri.py action move-window-to-workspace 3

# Focus a window by id ./skills/niri-ipc/scripts/niri.py action focus-window 123

# Close focused window ./skills/niri-ipc/scripts/niri.py action close-window

# Reload niri config ./skills/niri-ipc/scripts/niri.py action load-config-file

# Spawn (no shell) ./skills/niri-ipc/scripts/niri.py action spawn -- alacritty

# Spawn through shell ./skills/niri-ipc/scripts/niri.py action spawn-sh -- 'notify-send hello' ```

### 输出配置

通过封装工具使用 `niri msg output ...`：

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

## 直接使用 `niri msg`

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

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

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

## 事件流

针对状态栏/守护进程：Niri 可以流式传输事件。

```bash # Raw JSON event lines (runs until interrupted) ./skills/niri-ipc/scripts/niri.py event-stream

# Just a few lines for a quick test ./skills/niri-ipc/scripts/niri.py event-stream --lines 5 ```

## 故障排除

- 如果命令失败并提示“NIRI_SOCKET is not set”：请在您的 Niri 会话中运行，或导出 socket 路径。 - 如果您需要 socket 协议的详细信息，请阅读：`./skills/niri-ipc/references/ipc.md`。 - 如果您的目标是复杂自动化（按标题/app_id 选择正确的窗口等），请先查询 `windows`，然后按窗口 ID 执行操作。