我把Grok Bot搬上Touch Bar，顺便把SDK开源了

先说清楚它是什么

如果你平时不怎么写代码，可以把 SDK 理解成一套别人做好的标准零件。你不需要从头打磨螺丝，拿来就能拼出自己想要的东西。

Grok Bot 则是账号里带名字和专属头像，也有长期记忆的 AI 助手。每个 Bot 各自负责不同的事情，但同一个账号下的所有 Bot，都共用同一台云电脑。

把这两样东西连在一起，意思就是你可以把账号里的 Bot，放进任何你想放的入口。比如放在笔记本键盘上方的 Touch Bar 里，绑定在全局快捷键上，或者做成一个独立的网页小工具。

grok-bot-sdk 是我依照 Grok Bot 0.70.2 桌面客户端协议做的一套非官方 Node.js SDK。它不是 xAI 官方出品，不是 Cursor 插件，也不是 Grok Bot 官方 SDK。

它的作用很纯粹，就是帮你在自己的 Node.js 环境里，直接跟自己账号下的 Bot 发送消息，并且接收回复。

真实案例：Touch Bar 上的专属助手

做这个 SDK 的缘由，来自我自己的一套桌面交互想法。平时写东西或者看文档，切出客户端去寻找 Bot 对话，总觉得中间多了一道手续。

我想在 MacBook 的 Touch Bar 上放一排自己账号里已有的 Bot。手指滑动就能挑选，点开就能打字或者录音，还能顺手带上 Finder 里选中的文件。

为了配合这个操作，我做了一个轻量的小程序。左边是账号里同步出来的 Bot 列表，右边展示当前选中 Bot 的卡片和开始对话按钮。

在 Touch Bar 上停在某个 Bot 后再点一次，或按快捷键打开小面板。面板能打字、能录音，不打断主屏工作。

打开面板时，Finder 里选中的文件会自动带进来当附件，输入框左下也有现成的回形针与录音按钮。

这样一个交互做下来，桌面操作顺畅了很多。而把这一整套交互连接起来的底层协议通道，正是这个 SDK。

接入原理

为什么现成的方案不够

动手写这套 SDK 之前，我先把已有的几个方案都看了一遍。

官方 Agent SDK 管的是写代码的 Agent，跟账号里的日常助手不是一个维度。

官方 BDK 的 Grok Bot 扩展能够发起对话，但它列出的并不是整个账号的完整名单。而且它按照名字寻找会话，一旦没找到同名会话就会自动新建一个。

社区里的 grokbot-sdk 想要连接的是 Bot 云电脑上面的 gateway，那套服务并不在我这台 Mac 本地。

这三套工具在它们各自的适用范围内都能正常工作，只是跟我想在本地调用的方向不太重合。

登录

第一步是获取账号的登录凭据。SDK 走的是常规的浏览器登录通道。

但在拿回凭据的环节，它完全依靠轮询服务端的结果，不靠浏览器跳回本地应用程序。浏览器没跳回应用也没关系，轮询拿到凭据就算登录成功。

读名单

拿到了凭据之后，就可以从云端读取账号里的 Bot 名单。

读取操作是直接连云端接口拿数据，不用先把云电脑叫醒。云电脑还在休眠，你也能直接拿到名单。

有一点需要留意，如果账号里的 Bot 数量较多，返回的名单数据可能带有 truncated 截断标记。SDK 保持底层的克制，不会自己偷偷翻页，翻页逻辑留给调用方处理。

头像

把名单展示到界面上时，最直观的就是头像。不过接口返回的很多 Bot 数据里，并没有直接给出图形的形状和颜色。

缺了形状或颜色的那一项，客户端按 Bot 的 UUID 派生；SDK 照这个规则离线算回来。SDK 把这套离线计算逻辑完整做了出来，算出来的结果跟客户端里看到的一致。

所以在传入标识时，每个 Bot 的 UUID 必须原样使用，不要做任何额外的加工处理。

发消息

发送消息调用的是 sendMessage 接口。这里的 messageId 需要由调用方固定传入，重复投递时能看到 duplicate。

这里有一个很重要的状态区分，投递请求被服务端接受，只代表消息已经进入系统的投递流程，并不等于 Bot 已经完成了回复。

如果在发送途中网络结果含糊不清，SDK 会直接抛出 SEND_UNCONFIRMED 状态。它不会自动重发，目的就是避免网络抖动时把同一句话发两份。

sendMessage 只接收已经在服务端存在的附件引用。如果你在参数里传一个本机的文件路径，SDK 不会帮你上传，需要先在服务端生成引用。

收回复

服务端给客户端返回数据时，上游走的是 Connect 帧。SDK 在内部把这些帧结构解析转换成了标准的 SSE 事件流。

在调用 botEventsSSE 时，它会直接返回一个标准的 Web Response 对象，方便在现代 JavaScript 环境里消费。

接收到的文本回复是整段更新的方式，并不是大模型常见的那种逐字 token 流。另外，watchBot 在连接断开后不会自动重连，重连控制权交由上层处理。

Touch Bar 这边

回到 Touch Bar 这个项目本身。界面的 Touch Bar 控件和弹出面板是用 Swift 和 AppKit 编写的原生组件。

下层的协议交互则由 Node.js 负责。两层之间用标准输入输出传递 JSON 数据，Node 作为桥梁工作，本机不需要开启任何 HTTP 端口。

开源范围

这次开源的内容，我做了明确的取舍，只开源了底层的协议层。

前面展示的 Touch Bar 界面和语音录音模块，以及附件上传相关的命令行工具，都没有放进这个代码库里。

像令牌刷新、退出登录，以及唤醒云电脑与头像动画这些偏业务层的内容，这次同样没有放进来。

怎么使用

项目采用 MIT 协议开源，运行环境要求 Node.js 版本大于或等于 22.13，内部做到了零外部依赖。

版本号从 0.1.0 起步，目前还没有发布到公共 npm，可以通过 GitHub 仓库直接安装：

npm install github:RongleCat/grok-bot-sdk

命令行工具只保留了两个基础功能，分别是用来登录获取凭据的命令，以及查看当前登录身份的 whoami。

中英文文档站已经准备好，地址是 https://ronglecat.github.io/grok-bot-sdk/ ，中文版请访问 /zh/ 路径。

项目代码仓库在 https://github.com/RongleCat/grok-bot-sdk 。

客户端更新之后，服务端的接口路径和请求头可能会有变动。如果遇到版本不匹配，可以在初始化配置里传入 version 参数。

写在最后

把底层的通信通道理顺之后，剩下就是看你想把自己的 Bot 放在什么地方了。

如果你对这个项目感兴趣，欢迎去仓库点个 star，或者提个 issue，告诉我你想把 Bot 接进哪里。

---

开源 Grok App 作者（GitHub 1400+ Star），正在驻场给企业落地百万级 AI 项目。

持续更新 Grok Bot 实操教程和可复制的提示词，关注 @cgnot996，我踩过的坑你就不用再踩了。