基于Neru构建你的桌面工具:Go客户端包、事件流与自定义集成开发实战
基于Neru构建你的桌面工具:Go客户端包、事件流与自定义集成开发实战
Neru 是一个为 macOS、Linux 和 Windows 原生打造的桌面自动化工具,用键盘提示(hints)、网格(grids)和 vim 键位接管整个桌面。除了自己使用,Neru 还内置了完整的 IPC 协议、Go 客户端包和实时事件流,让你可以低门槛地构建状态栏、启动器、语音控制等自定义集成。这篇文章带你从零上手 Neru 集成开发。
为什么 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):
- 自动定位端点——和
neruCLI 用同样的方式查找,daemon 晚启动也没关系 - 携带协议号——当前是 protocol 1,daemon 收到更高版本会拒绝请求,避免静默不兼容
- 返回类型化回复——
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 打磨你的工具。
延伸阅读
- 协议与响应码:docs/reference/ipc.md
- CLI 完整参考:docs/reference/cli.md
- Go 客户端实现:client/client.go
- IPC 服务端实现:internal/adapter/ipc/
- 脚本化指南:docs/guide/scripting.md
- 集成开发指南:docs/guide/integrations.md
