Hermes ESP32-S3 桌面终端

Hermes ESP32-S3 桌面终端是一台面向个人 AI Agent 的常驻桌面设备。它不是另一个缩小版聊天网页，而是把 Agent 最需要被看见、被回应和被确认的几个环节放进一块 320×240 的触控屏：状态、消息、语音、拍照、澄清问题与执行审批。

这个项目有什么用

当 Hermes Agent 在服务器上持续运行时，用户不应该为了查看一条提醒、确认一次工具调用或补充一个选项，反复切回电脑浏览器。这个终端让 Agent 在桌面上拥有一个独立、低打扰的入口：空闲时由“小七”展示当前状态；有新消息时亮屏并播放提示音；需要输入时直接在触屏上处理；需要更丰富的上下文时，可以说话或拍照发送给 Agent。

它适合放在书桌、工作台或家庭公共区域，作为个人 Agent 的状态灯、消息终端和可信交互面板。

它解决了哪些问题

1. Agent 状态通常藏在电脑窗口里

传统聊天界面只有在用户主动打开时才存在。终端用 idle、review、run、waiting、wave、failed 等状态驱动小七动画，把“准备就绪、思考中、执行中、等待输入、完成、失败”变成一眼可见的桌面反馈。

2. 高风险操作缺少独立、可信的确认入口

Hermes 发起工具调用时，设备可以展示命令与说明，并提供 once、session、always、deny 四种审批选择。设备与服务端同时校验 approval ID、会话和过期时间，避免旧审批、跨会话回复或伪造设备身份被误接受。

3. 纯文本不足以覆盖真实环境

点击小七即可开始或结束录音，语音被分片上传到 Hermes 并转写为对话输入；“更多”菜单中的拍照入口会启动 GC0308 实时预览，按下快门后在设备端压缩 JPEG，再作为图片消息交给 Agent。这样可以直接询问桌面上的物品、硬件接线或现场情况。

4. ESP32 的内存与网络条件不适合直接照搬 Web 上传方式

语音与图片都通过现有 MQTT/TLS 连接上传。固件使用 PSRAM 承载媒体队列，限制并校验分片，上传期间临时关闭 Wi‑Fi 省电，并等待 MQTT outbox 真正清空与服务端回执后才向 UI 报告完成。摄像头仅在拍照页面初始化，退出后立即反初始化，避免长期占用 DMA 内存影响原有录音任务。

5. 断网或重启后仍需要保留基本可用性

网络未配置时 UI 仍可离线启动。消息使用 NVS 环形缓存保存，并带有去重记录；屏幕支持自动休眠和物理按键唤醒，通知音也可以单独静音。

系统结构

Hermes Agent Gateway
        │
        │  MQTT v1 / TLS / QoS 1
        ▼
Mosquitto :8883
        ▲
        │  每台设备独立账户与 ACL
        │
ESP32-S3 桌面终端
  ├─ ST7789 320×240 显示屏
  ├─ FT6336 触控
  ├─ ES7210 麦克风采集
  ├─ ES8311 提示音播放
  ├─ GC0308 摄像头
  └─ NVS 本地消息与设置

服务端的 hermes-esp32 插件把设备注册为 Hermes messaging platform，负责 MQTT 上下行、语音与图片重组、身份映射、状态同步以及审批和澄清回复。固件负责交互、媒体采集、本地缓存和网络状态管理。

设备上可以做什么

• 首页查看小七动画、Agent 状态、时间与联网状态。
• 点击小七开始或停止语音输入，并查看实时音量波形和发送状态。
• 在消息页查看普通消息、提醒、工具进度和主动聊天记录。
• 在审批卡片上选择单次允许、会话允许、始终允许或拒绝。
• 在澄清卡片上直接选择 Hermes 提供的候选答案。
• 从快捷菜单发起 /new、/stop、/status。
• 打开相机实时预览，拍照后把图片发送给 Agent。
• 在设置页扫描或切换 Wi‑Fi、调节亮度、静音通知。

如何部署

部署分为服务端、MQTT Broker、Hermes 插件和设备固件四部分。

1. 准备服务端

在 Ubuntu/Debian 服务器上安装 Hermes Agent，完成模型提供商与 API Key 配置。建议用 systemd 运行唯一一个 Hermes Gateway，避免多个实例重复消费消息。

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source /root/.bashrc
hermes setup

2. 部署 MQTT TLS Broker

仓库的 deploy/mqtt 目录提供 Mosquitto Compose、ACL 和证书续期脚本。生产环境只开放 8883 TLS 端口，并为 Gateway 与每台设备创建不同账号。

cd /opt/hermes-mqtt
docker compose up -d
docker compose ps

设备账号只允许订阅自己的 down topic，并发布自己的 up/status；Gateway 账号使用相反方向的最小权限。域名证书可以用 Certbot 签发，并通过 deploy hook 在续期后更新 Broker。

3. 安装 Hermes ESP32 插件

将仓库中的 hermes-esp32 目录复制到 Hermes 插件目录，安装依赖并显式启用。

install -d /root/.hermes/plugins/hermes-esp32
cp -a hermes-esp32/. /root/.hermes/plugins/hermes-esp32/
/usr/local/lib/hermes-agent/venv/bin/python -m pip install \
  -r /root/.hermes/plugins/hermes-esp32/requirements.txt
hermes plugins enable hermes-esp32

在 Hermes .env 中配置 MQTT TLS 地址、Gateway 凭据、设备 ID、默认频道与可信 owner。ESP32_HOME_CHANNEL、ESP32_DEVICE_IDS、固件 Device ID、设备 MQTT 用户名和 ACL 中的设备 ID 必须保持一致。

ESP32_MQTT_URL=mqtts://mqtt.example.com:8883
ESP32_MQTT_USERNAME=hermes-gateway
ESP32_MQTT_PASSWORD=<gateway-password>
ESP32_HOME_CHANNEL=desk-01
ESP32_DEVICE_IDS=desk-01
ESP32_ALLOWED_USERS=owner

然后安装并启动系统服务：

hermes gateway install --system
hermes gateway start --system
hermes gateway status --system

4. 编译并刷写固件

固件需要 ESP-IDF 5.1–5.5。首次构建会通过 ESP Component Manager 获取 LVGL、触控、音频和摄像头依赖。

. "$IDF_PATH/export.sh"
idf.py menuconfig
idf.py build
idf.py -p /dev/cu.usbmodemXX flash monitor

在 Hermes ESP32 Terminal 菜单中配置：

• Device ID，例如 desk-01。
• Wi‑Fi SSID 与密码。
• MQTT TLS URI，例如 mqtts://mqtt.example.com:8883。
• 该设备独立的 MQTT 用户名与密码。

凭据写入本地 sdkconfig，该文件不应提交到 Git。未配置网络时，固件仍会启动 UI，之后也可以在设备设置页扫描和连接 Wi‑Fi。

如何使用

设备启动后会自动连接保存的 Wi‑Fi 和 MQTT Broker。首页右上角显示连接状态；小七下方展示 Hermes 当前状态。

• 要说话：点击小七开始录音，再次点击结束并发送。
• 要拍照：打开左下角“更多”，选择“拍照”，在预览页按快门。
• 要查看历史：点击右下角消息入口。
• 要控制任务：在“更多”中选择新对话、停止或状态。
• 要处理请求：审批或澄清卡片出现后直接在触屏上选择。

新消息和最终回复会触发提示音与亮屏；如果不希望有声音，可以在设置中静音通知，麦克风能力不受影响。

已验证的结果

项目已完成固件构建、Python 协议测试与实机媒体链路验证。长语音可以在不丢分片、不触发 MQTT keepalive 断线的情况下完成上传；两次实拍拍照均被压缩到 8 KB 以内并收到 Hermes 最终回复。摄像头帧缓冲位于 PSRAM，退出拍照页后仍能正常创建原有录音任务。

当前固件预留双 OTA 应用分区，但签名 OTA 更新流程仍是后续工作。生产部署还应继续坚持每台设备独立凭据、最小 ACL、TLS 校验和服务端可信 owner 映射。