Buddy logo Buddy
EN

Menu

Buddy navigation

EN
文档

Buddy 文档

Buddy 的公开文档分两条线：一条给想把 Buddy 跑起来的用户，一条给希望基于公开协议做兼容设备、但不能依赖服务端或 CLI 源码的硬件开发者。

总览

用户文档

如果你只想安装公共 CLI、把 Buddy 接到 Codex / Claude / Enter、绑定一个设备并确认状态推送已经送达，请看这条线。

设备开发者文档

如果你正在为兼容设备做固件或客户端，需要依赖公开的 bootstrap、MQTT、快照协议，请看这条线。

Buddy 对外是一个黑盒产品。第三方开发者应当依赖公开命令、bootstrap 响应和快照 payload，而不是 Buddy 内部实现细节。
用户文档

快速上手

适合一个账号、一个绑定设备的最简跑通路径。

  • 登录 Buddy 网页端。
  • 生成一个 CLI key。
  • 用同一个账号绑定一个设备。
  • 执行 buddy init --key buddy_xxx。
  • Codex 用 buddy codex 启动；Claude / Enter 先执行 buddy install-claude-hooks，再启动新会话。
  • 用 buddy status 确认快照已经更新。
npm install -g hibuddy
buddy init --key buddy_xxx
buddy whoami
buddy install-claude-hooks
buddy codex
buddy status

安装与初始化

用户只需要公共 CLI 包和一个有效的 CLI key。

  • 运行环境：Node.js 20+。
  • 安装：npm install -g hibuddy。
  • 初始化：buddy init --key <cli-key>。
  • 确认本地配置：buddy whoami。
buddy init --key buddy_xxx
buddy whoami
buddy status --json
Buddy 有两种输出模式：mqtt 是默认值，会把快照推到绑定设备的 topic；local 只把同样的快照写到本地，不发 MQTT。

接入 Codex / Claude / Enter

Buddy 在旁观察你的 AI 会话，持续生成一份给设备用的精简快照。按你实际用的 agent 选一个接入方式即可。

Codex

希望 Codex 的活动直接更新设备时，把 Buddy 当成 wrapper 启动。

buddy codex
buddy codex exec -- "Summarize this repository"

Claude / Enter

Claude 和 Enter 共用 ~/.claude/settings.json 这一份 hook 配置。先安装一次 Buddy hook，再启动新会话。需要 Buddy 帮你启动 Claude 时用 buddy claude；Enter 仍然按你平时的方式启动。

buddy install-claude-hooks
buddy claude    # 或者按你平时的方式启动 Enter
想完全卸载，运行 buddy remove-claude-hooks。它只会从 ~/.claude/settings.json 里清掉 Buddy 那部分条目，不会动文件里其他内容。

设备配置

Buddy V1 当前默认一个账号绑定一个设备。

  • 先在网页端绑定设备。
  • 用同一个账号生成 CLI key。
  • 确认设备已绑定后再执行 buddy init --key ...。
  • 用 buddy status 或 buddy status --json 确认快照在更新。
如果 buddy status --json 本地能更新但硬件没反应，问题通常出在设备端或 MQTT 链路，而不是 Codex / Claude / Enter 接入。

下载与刷写固件

宠物形象和渲染都在固件里，不在云端。要让 Buddy 设备跑起来，需要从 GitHub 下载最新固件，再刷到 M5StickS3 上。

  • 打开固件仓库：github.com/guolin/HiBuddy。
  • 下载最新的 firmware release，或者直接从源码构建。
  • 按仓库 README 里的刷机说明操作——里面写了工具链、数据线和串口的具体步骤。
刷完上电，再到网页端配对即可。宠物形象是固化在固件里的，换宠物等于换一份固件。

故障排查

buddy init 失败

确认 CLI key 有效、账号下确实绑定了设备、控制面板可访问。

设备没有更新

看一下 buddy whoami，确认设备和账号匹配，并且没在 local 模式。

hook 没生效

重新跑 buddy install-claude-hooks，然后重启 Claude 或 Enter 会话——hook 只在新会话开始时才挂上。

清空本地状态

运行 buddy reset 清掉本地运行状态和设备日志。

设备开发者文档

集成边界

第三方硬件开发者应把 Buddy 当成一个黑盒来对接：设备只消费一份精简的公开快照，不应当依赖 Buddy 服务端源码、CLI 源码或上游 AI 事件格式。

设备应当做

  • 未配对时获取或刷新配对码。
  • 拉取 bootstrap 状态。
  • 连接到指定 MQTT broker 和 topic。
  • 解析最近一条 retained 快照。
  • 渲染对应的 UI / 动画状态。

设备不应当做

  • 解析 Codex 原始 payload。
  • 解析 Claude 或 Enter 的 hook payload。
  • 自己从原始事件还原会话优先级。
  • 依赖 Buddy 内部运行时文件。

Bootstrap

设备运行时应当以最近一次 bootstrap 响应作为 MQTT 连接的真实数据源。

POST /functions/v1/device-bootstrap

请求体：

{
  "device_id": "demo-device-001",
  "device_token": "dev_xxx"
}

对于已配对设备，关键的公开字段：

  • paired
  • mqtt.mqttBrokerUrl
  • mqtt.mqttUsername
  • mqtt.mqttToken
  • mqtt.mqttClientId
  • mqtt.mqttTopic
  • config
  • activePet
如果 paired 是 false，设备应继续走配对或 bootstrap 轮询流程，先不要连 MQTT。

配对 API

Buddy 配对有三组对外 API：设备申请配对码、用户账号绑定设备、任意一端解绑。

申请配对码

未配对时调 POST /functions/v1/device-pair-code。响应包含 deviceId、deviceToken、pairCode、pairUrl、expiresAt。

{
  "device_id": "demo-device-001",
  "device_token": "dev_xxx"
}

绑定与解绑

POST /functions/v1/bind-device 需要登录态。

  • {"device_id":"123456"} 用 6 位配对码绑定。
  • {"device_id":"demo-device-001","device_key":"optional-device-key"} 用明确的 device id 绑定。
  • POST /functions/v1/unbind-device 由用户端解绑。
  • POST /functions/v1/device-unbind 由设备端解绑，带 device_id 和 device_token。

快照协议

Buddy 设备只消费一份 retained 的精简 JSON 快照。

{
  "version": 1,
  "updated_at": 1776520000,
  "pet_state": 3,
  "session_states": [2, 0],
  "requires_user": true,
  "total_tokens": 120000,
  "today_tokens": 34000
}

字段含义：

  • version：当前协议版本，目前是 1。
  • updated_at：秒级 Unix 时间戳。
  • pet_state：设备顶层状态。
  • session_states：按优先级排序的活跃会话状态，最高优先级在前。
  • requires_user：最高优先级的活跃会话是否需要用户介入。
  • total_tokens：累计 token 数。
  • today_tokens：今天的 token 数。

pet_state

  • 0 idle
  • 1 thinking
  • 2 busy
  • 3 waiting
  • 4 error
  • 5 done
  • 6 sleep

session_states

  • 0 thinking
  • 2 waiting
  • 3 error

MQTT 契约

Buddy 把快照发布到 bootstrap 返回的设备专属 topic。

  • Payload：一份 JSON snapshot。
  • QoS：1。
  • Retain：true。
  • Topic：用 bootstrap 返回的 topic。
设备应只订阅自己的 topic；新快照到达时替换当前渲染状态；重连后依赖 retained 消息恢复。

最小设备行为

  • 未绑定时刷新配对码或继续轮询 bootstrap。
  • 用最新的 bootstrap 凭据连 MQTT。
  • 解析并校验快照 payload。
  • 把 pet_state 和 requires_user 映射到 UI / 动画状态。
  • MQTT 断开时重连。
推荐回退策略：bootstrap 失败稍后重试；MQTT 断了重连；遇到坏 payload 保留上一份合法快照；遇到未知字段忽略它，不要让整份 payload 失败。

兼容性

Buddy 设备对依赖应当保守，对接收的数据应当宽松。

  • 不要假定 session_states 有固定最大长度。
  • 忽略未知的新字段。
  • 在做协议相关行为前先看 version。
  • 渲染细节由设备自己决定，但不要重新解释公开字段的语义。