基于Neru构建你的桌面工具:Go客户端包、事件流与自定义集成开发实战

原创2026-10-25 10:14:551,361 阅读

基于Neru构建你的桌面工具:Go客户端包、事件流与自定义集成开发实战

Neru 是一个为 macOS、Linux 和 Windows 原生打造的桌面自动化工具,用键盘提示(hints)、网格(grids)和 vim 键位接管整个桌面。除了自己使用,Neru 还内置了完整的 IPC 协议、Go 客户端包和实时事件流,让你可以低门槛地构建状态栏、启动器、语音控制等自定义集成。这篇文章带你从零上手 Neru 集成开发。

Neru 桌面自动化工具的 hints 模式演示截图

为什么 Neru 适合做集成底座

Neru 的核心设计是「一切热键步骤都是命令」:你的每一个快捷键绑定,背后都是一条 neru 命令,同时也是一个 IPC 请求。这意味着:

  • 读状态:neru status --json、neru query 等命令随时输出结构化 JSON
  • 发指令:任何模式(hints、grid、scroll……)都能通过命令行或 IPC 触发
  • 听事件:neru watch 提供实时事件流,监听模式切换、应用焦点、配置重载等变化
  • 接配置:[hooks] 配置项让 Neru 在事件发生时自动执行你的脚本

官方把集成选型整理成了一张速查表,见 docs/guide/integrations.md:

你想做什么 用什么
响应配置文件里定义的事件 [hooks]
从脚本运行命令 neru CLI
以 JSON 读取状态 status、query、doctor 加 --json
实时跟随状态 neru watch(可用 --event 过滤)
查找元素及 hint 标签 neru query hints
从 Go 程序驱动 Neru client 包
校验配置或 IPC 数据 schemas/ipc.schema.json

完整协议细节在 docs/reference/ipc.md,命令行参考在 docs/reference/cli.md。

第一步:安装并启动 Neru

集成开发的前提是本机跑着一个 Neru daemon。推荐用官方安装脚本(安装脚本见 docs/guide/installation.md),安装后即可用登录服务在开机时自动启动。

快速检查 daemon 是否就绪:

neru status --json

能输出 JSON 就说明 IPC 端点可用。不同平台的端点位置略有差异(Unix socket 或 Windows 命名管道),这些细节在 docs/reference/ipc.md 的 Endpoint 一节有完整说明——好消息是,你几乎不需要关心它们,因为客户端会自动找到端点。

第二步:用 Go 客户端包驱动 Neru

如果你写 Go 程序,直接导入官方的 client 包即可,无需手写任何协议逻辑:

go get github.com/y3owk1n/neru/client

这个包做了三件麻烦事(实现见 client/client.go):

  1. 自动定位端点——和 neru CLI 用同样的方式查找,daemon 晚启动也没关系
  2. 携带协议号——当前是 protocol 1,daemon 收到更高版本会拒绝请求,避免静默不兼容
  3. 返回类型化回复——Status、Displays、Cursor、Window、App、Hints 都有专门方法和结构体(见 client/status.go 与 client/query.go),其余命令走通用的 Send

最小示例:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

neru := client.New()

status, err := neru.Status(ctx)
if errors.Is(err, client.ErrNoDaemon) {
    log.Fatal("neru is not running, start it first")
}

两点值得注意:

  • ErrNoDaemon 表示端点上没有任何监听——先确认 Neru 已启动
  • *client.Error 表示 daemon 主动拒绝了请求,其 Code 字段是 docs/reference/ipc.md 中列出的响应码(如 ERR_MODE_DISABLED、ERR_NOT_RUNNING)。分支判断时认准 Code,不要解析人类可读的 message

想触发一个没有专用方法的命令,直接走 Send:

_, err = neru.Send(ctx, "hints", "--action", "left_click")

参数就是你在命令行 neru hints 后面敲的那些词。完整可运行的示例见 docs/guide/integrations.md。

第三步:事件流 Watch,实时感知桌面变化

静态查询只能回答「现在怎样」,Watch 事件流回答「接下来发生了什么」。它保持连接打开,daemon 每发生一件事就推一行 JSON:

{"seq":0,"event":"snapshot","status":{"enabled":true,"mode":"idle"}}
{"seq":1,"event":"mode_enter","mode":"hints"}
{"seq":2,"event":"mode_exit","mode":"hints","reason":"completed"}

事件流的设计规则(详见 docs/reference/cli.md 的 neru watch 一节):

  • 首行一定是 snapshot,携带完整状态快照;后续每行是一个增量事件
  • 事件名与 [hooks] 配置一一对应(去掉 on_ 前缀):mode_enter、mode_exit、select、app_focus、config_reload、on_ready 等
  • 用 --event mode_enter,mode_exit 只接收指定事件,快照始终会发
  • 如果读取端跟不上,错过的事件会被一条带 dropped 计数的新 snapshot 替代——所以每次收到 snapshot 都当作完整状态重建,把事件当作对它的修改,这是最稳的消费方式

在 Go 客户端里,Watch 把每一行解码成 client/status.go 中的 WatchLine 结构体,回调逐行投递:

err := client.New().Watch(ctx, func(line client.WatchLine) error {
    if line.Event == "mode_enter" {
        fmt.Println("entered", line.Mode)
    }
    return nil
}, "mode_enter", "mode_exit")

取消 context 即关闭连接、结束监听。官方给出的一个经典用例是「状态栏跟随 Neru 模式」:先打印快照里的当前模式,之后每次 mode_enter 打印新模式,mode_exit(reason 非 switched 时)打印 idle。完整代码见 docs/guide/integrations.md,shell 版写法在 docs/guide/scripting.md。

四个开箱即用的集成场景 🛠️

结合 Go 客户端和事件流,下面几个场景都能快速落地:

1. 状态栏实时显示 Neru 模式

长驻进程消费 Watch 事件流即可,避免每个事件都 fork 一个进程。Eww、Waybar、sketchybar 都适用。

2. 启动器里展示 Neru 状态

启动器插件调用 Status(),把「当前模式 + 运行/暂停」显示在结果项上;没有 daemon 时优雅降级。

3. 语音控制 / 辅助 UI

neru query hints --json 会列出 hints 模式将要标注的每个元素及其标签。语音工具可以朗读标题,用户说「点 Save」后:用相同 flags 打开 hints 模式,再用 neru action feed --mode 把标签按键喂进去。注意标签只在屏幕不变的前提下有效,查询与触发要带上同一组 flags。

4. 把你的元素坐标喂给 hints 模式

当某个应用对所有识别策略都「隐身」时,你可以自己知道控件在哪:--targets - 从 stdin 读取与 neru query hints --json 同形状的 JSON,每个目标给出 x、y、width、height 即可被点击。这是自定义集成里最有威力的一条通道。

更多脚本化技巧(健康检查、--on-exit 传递坐标、与别的快捷键守护共存)见 docs/guide/scripting.md。

兼容性规则:让集成代码长命 📌

Neru 的协议只有一个版本号:protocol 1。规则很简单(docs/reference/ipc.md):

  • 同一 protocol 内,已文档化的字段、响应码、命令名、data 键保持名字、类型、含义不变
  • 协议可以新增命令、flags、键和事件——所以客户端应当忽略不认识的字段
  • 只有会破坏现有客户端的变更才会升号,且只在 Neru 主版本发布时发生(Neru 2 = protocol 2)

因此你的集成代码只需遵循一条:认 code 不认 message,忽略未知的键和事件。client 包本身就按这条规则演进,只在主版本才破坏兼容。另外,所有回复形状都发布为 JSON Schema(schemas/ipc.schema.json),需要严格校验时可以直接 $ref 使用。

小结

Neru 的集成面可以归纳为三层:

层 工具 适合
配置层 [hooks]、--on-exit 事件驱动、不想写代码
命令层 neru CLI + --json 脚本、快捷指令
程序层 IPC socket / Go client 包 长驻程序、Go 工具

从 Status() 的一行调用到 Watch 的实时事件流,Neru 为桌面集成提供了完整且稳定的通路。建议从 docs/guide/integrations.md 的官方场景示例起步,再对照 docs/reference/ipc.md 打磨你的工具。

延伸阅读

登录后查看全文
neru