Holocube 表情系统

将 GeekMagic Holocube 设备变为你的 AI 的“面部”。生成全息风格的角色表情精灵图（sprite），上传至设备后，即可根据智能体（agent）/会话（session）状态实时切换表情。

首次设置

0. 查找设备

自动发现局域网内的 Holocube 设备：

python3 scripts/holocube.py --discover

输出示例：FOUND: 192.168.0.245 — HelloCubic-Lite V7.0.22

若自动发现失败，请在设备屏幕或路由器的客户端列表中查找其 IP 地址。

1. 生成精灵图

生成完整表情套件（需启用 nano-banana-pro 技能，并配置 GEMINI_API_KEY）：

python3 scripts/generate_sprites.py --output-dir ./sprites

自定义角色（示例）：

python3 scripts/generate_sprites.py --output-dir ./sprites 
  --character "一只悬浮于纯黑虚空中的发光全息猫。霓虹紫色线框风格。"

该命令将生成 7 种表情（neutral、happy、thinking、surprised、concerned、laughing、sleeping），每种均包含静态 JPG 与动态 GIF 格式，适配设备 240×240 像素显示屏。

2. 上传至设备

python3 scripts/setup_device.py --sprites-dir ./sprites --clear --backup-dir ./backup

常用参数说明：

• --clear：清空设备上已有图片（推荐使用 — 设备总存储约 3MB）
• --backup-dir：清除前将现有文件备份至指定目录
• --ip：若未提供，则自动发现；也可手动指定 IP

3. 配置 TOOLS.md

将 Holocube 的 IP 地址及表情映射关系添加至工作区的 TOOLS.md 文件中，便于后续参考。详见 references/tools-example.md。

日常使用

直接设置表情

python3 scripts/holocube.py happy
python3 scripts/holocube.py thinking --static   # 使用 JPG 而非 GIF

按智能体状态设置表情

python3 scripts/holocube.py working    # → thinking
python3 scripts/holocube.py complete   # → happy
python3 scripts/holocube.py error      # → concerned
python3 scripts/holocube.py opus       # → thinking（调用重型模型时）
python3 scripts/holocube.py haiku      # → neutral（调用轻量级模型时）

按一天中的时段自动选择表情

python3 scripts/holocube.py --auto

• 23:00–07:00 → sleeping
• 07:00–09:00 → happy
• 其余时段 → neutral

检查设备状态

python3 scripts/holocube.py --status
python3 scripts/holocube.py --list

心跳集成（Heartbeat Integration）

在 HEARTBEAT.md 中添加以下条目，实现表情的自动管理：

## Holocube Emote Check
- Run `python3 scripts/holocube.py --auto` to set time-appropriate emote

何时设置表情

以下为智能体常规运行过程中推荐的表情使用场景：

自定义插槽（Custom Slot）

设备上预设了一个保留文件 adam-custom.gif，可随时覆盖以实现按需或一次性动画播放。请先生成 GIF 动画，将其上传为 adam-custom.gif，再执行 python3 scripts/holocube.py custom 播放；完成后可随时切回标准表情。

设备注意事项

• 型号：GeekMagic HelloCubic-Lite（240×240 像素玻璃显示屏）
• 格式要求：仅支持 GIF（动态）或 JFIF JPEG（静态）。建议使用 Pillow 生成 JPEG（ffmpeg 缺少 JFIF 头信息）。
• 存储容量：总容量约 3MB。6 个动态 GIF 占用约 1.5MB，剩余约 500KB 可用于 custom 插槽。
• 美术风格：深色/纯黑背景可使玻璃屏“隐形”，推荐使用发光、全息、霓虹等视觉元素。
• ⚠️ 切勿发送 /set?reset=1 —— 此为出厂重置指令，将清除 Wi-Fi 配置。

依赖要求

• 本地网络中已接入 GeekMagic HelloCubic-Lite（或兼容设备）
• Python 3 及 Pillow 库（pip install Pillow）
• nano-banana-pro 技能并配置 GEMINI_API_KEY（仅用于生成精灵图）
• uv 工具（brew install uv）（仅用于生成精灵图）