HachimoDock（哈基米机）

哈基米机 HachimoDock：让你的宠物 / 朋友 / 你推变成 AI Agent，和你一起工作

把 ChatGPT（Codex）、Claude 等 Agent 的实时工作状态变成桌上宠物的表情、动作、Session 气泡和提醒。

硬件方案 · 硬件端资料 · 图集 · 软件架构 · 复刻与部署 · 快速开始 · 常见问题

HachimoDock（哈基米机）是一套桌面端管理器、ESP32-P4 小屏固件和开源硬件方案。它把电脑里正在运行的 Agent Session 实时同步到桌面小屏，让 AI 的思考、执行、完成和报错状态变成看得见的宠物动画与气泡；实体按键、四向摇杆和麦克风又能把操作与语音送回 Agent。

你可以在这里下载 Windows/macOS 客户端和 ESP32-P4 完整烧录包，也可以获取源码自行构建。硬件资料与装配教程见 OSHWHub。

桌面小屏实拍：把 Agent 状态放到工位视野里。

新版三按键与四向摇杆机身，屏幕显示内置西高地形象。

家居控制能力由Xiaomi MiLoCo 提供，相关 MiLoCo 授权作品的版权归小米所有，适用 Xiaomi Miloco License，版权标识、免责声明及许可证随相关实现一并保留。非商业使用仍须符合该许可证的用途范围；本项目不向第三方授予额外的商业使用、再许可或商标权限。完整说明见 第三方声明。

• 可见内置工具依次为自选股行情、敲木鱼、近期待办、电脑状态，之后为其他组件。
• 配套 v1/v3 固件 0.7.72-p4；保留实时对话和按键语音、实时组件及全局按键设置。
• 对外安装包不内置 API Key、企业 CA 证书或固定代理。第三方组件及服务仍适用各自许可证和使用条件。

• 对话大模型支持编辑模型名，并按服务商分别保存 Key；默认豆包，MiMo 默认 mimo-v2.6-flash。
• 实时对话支持按需联网与行情查询，由宠物口语总结结果，不新增 PC 搜索结果面板。公开包需填写自己的服务 Key，调用能力取决于账号权限。
• 西高地出厂默认音色调整为「佩奇猪 2.0」，保留已有个人音色设置。
• 配套 v1/v3 固件 0.7.64-p4 去掉实时对话状态文案中的省略号，避免显示为问号；普通字幕保留标点。
• 回复阶段增加 ASR 二次确认后打断，支持单字“停”。间歇性误打断仍在排查，尤其音箱播放、环境声和 Windows 使用场景；本版不承诺已消除。

公开安装包不含内置 Key、企业 CA 或固定代理；保留 Xiaomi MiLoCo 和 ESP-SR 许可证。安装客户端后需在「固件升级」中手动更新设备，普通 OTA 保留用户数据。

• 实时对话：配置语音服务与对话大模型后，在宠物界面长按 SW2 开始聊天，再次长按结束。支持人设、TTS 2.0 音色、蓝色字幕气泡；配套固件支持边听边说与打断，效果受麦克风、扬声器安装位置和环境影响。
• 智能家居：在「智能家居」授权米家账号后，可在实时对话中用自然语言控制账号授权的设备，例如“让音箱放一首爵士乐”。能力取决于设备及账号权限；较长编排通过语音确认，不要求回到 PC 点击。
• 自选股行情：组件列表第一项内置行情组件，默认小米与阿里。在组件详情页按名称或代码搜索、管理自选股；PC 每 2 秒更新并通过 USB 下发，需保持客户端运行。涨价和涨幅红色、下跌绿色，行情可能有延迟，不提供交易功能。
• Windows 音频与形象管理：改善实时对话句内断音、内置形象切换和跨形象提示音；Agent 语音输入可多次追加。
• 生成失败提示：区分生图与图生视频审核；明确人像限制，并提供自行生成 MP4 后上传的入口说明，不承诺绕过平台审核。

公开包不内置 API Key、企业 CA 或固定代理地址。首次使用请在「API 配置」中填写自己的服务凭据。详见 实时对话、智能家居、实时数据组件。

桌面端不是一个简单的串口烧录工具，而是 HachimoDock 的管理与 Agent 路由中心。当前版本支持 Windows 与 Apple silicon macOS，预编译安装包可从 GitHub Releases 下载。

• 扫描时处于 working/thinking/tool-running 等活跃状态的 Session 才会新增到设备。
• 已经显示在设备上的活跃 Session 会持续接收后续状态变化，不会因一次扫描遗漏而立即消失。
• Session 进入 done 或 error 后保留 60 秒；idle、历史完成任务和 Agent 内部会话不会作为新气泡下发。
• 气泡数量由 Agent 当前活跃 Session 自动决定，不需要用户手动配置。

气泡自动对应当前正在工作的 Agent Session。	长按按键录音，把 ASR 文字送入目标 Session。

1. 在 ChatGPT（Codex）或 Claude 中调用 petui Skill，并描述希望生成的小游戏或工具。
2. Skill 按 480×640 屏幕、三个按键和四向中按摇杆的设备能力生成组件，不套用固定游戏外壳。
3. 校验脚本检查 manifest、状态机、按钮映射、资源路径和设备字节限制，再原子发布到统一组件库。
4. 桌面端自动读取组件库，用户在组件卡片上直接同步到设备或从 PC/设备双端删除。

_{Agent 状态变化时，宠物动画随之变化。}

上传本地视频、导入社区形象，或使用 AI 生成自己的宠物动作；通过 petui Skill 还可以创建番茄钟、喝水提醒、Token 仪表盘和小游戏。新机型对应的形象管理与组件中心截图将在完整代码同步后补充。

本仓库给出软件和固件配套；PCB、BOM、硬件装配和复刻资料请看： OSHWHub 硬件端页面。

硬件端不只是一张接线图，包含从主控、屏幕、PCB、外壳到装配的复刻路径：

flowchart LR
  agent["Agent<br/>ChatGPT（Codex）/ Claude"]
  desktop["HachimoDock（哈基米机）桌面端<br/>Tauri + React"]
  bridge["Bridge sidecar<br/>Session / ASR / USB"]
  board["ESP32-P4 firmware<br/>renderer / input / PetUI runtime"]
  screen["480×640 MIPI 小屏<br/>宠物动画 / 气泡 / PetUI 组件"]

  agent --> desktop
  desktop --> bridge
  bridge -->|"USB serial"| board
  board --> screen

桌面端读取并归一化 Agent Session，将正在设备上显示的活跃任务及其状态变化通过 USB 下发。ESP32-P4 固件负责动画和气泡生命周期、输入事件、资源双槽以及 PetUI 组件运行；设备输入则由桌面端路由回对应 Agent。

硬件复刻请从 OSHWHub 硬件端页面 开始，页面提供 PCB、BOM、结构与装配资料。设备端采用完整 ESP32-P4 镜像，镜像同时包含应用固件、分区表、内置西高地形象和默认 PetUI 组件，避免首次安装后缺少资源。

首次烧录请使用与芯片版本对应的完整烧录包，工具核对芯片后再擦除并从地址 0x0 写入；日常升级请使用 Pet Manager 的固件升级功能。完整镜像会覆盖设备设置、形象和组件，仅应在新设备或明确恢复出厂时使用。

前往 最新 Release：

• Apple silicon Mac 下载 HachimoDock-Pet-Manager_0.1.101_macOS-arm64.dmg；
• Windows x64 下载 HachimoDock-Pet-Manager_0.1.101_Windows-x64-setup.exe；
• 安装后连接设备，Pet Manager 会自动识别 ESP32-P4，并提供固件升级、形象和组件同步入口。

公开安装包不内置 ASR 或内容生成 API Key；需要相关能力时请在 Pet Manager 的“API 配置”中填写自己的服务凭据。

Release 提供 v1、v3 两种完整烧录包，均包含 Bootloader、应用固件、形象、组件及双平台烧录工具。请按实际芯片修订版选择，不能互刷；微雪 ESP32-P4-WIFI6-M 的 M 不代表芯片版本。同一芯片的固件由 Windows/macOS 共用。完整镜像会覆盖设备现有数据。

v1 与 v3 烧录包不可互刷，具体版本可以咨询客服进行确认。 包内脚本需要 Python 3.10+，自动安装 esptool 5.4.0。屏幕连接 DSI，不是 CSI；请断电后插拔排线。详细版本和步骤见 固件构建与烧录指南。

v3 的 24 MHz 显示修复已在实机确认恢复宠物动画；本版本按键、麦克风、完整形象与固件传输等仍需实机验收，请先在测试设备上验证。

提供软件端和固件端的正式二进制文件：

• 软件端：Windows x64 与 Apple silicon macOS 安装包。
• 固件端 / 设备运行时：可烧录到 ESP32-P4 的完整出厂镜像与清单。
• 硬件端：PCB、BOM、装配和复刻资料在 OSHWHub 硬件端页面。

当前固件、完整镜像、MIPI 显示、资源分区和 USB 协议均针对 ESP32-P4 实现。更换主控需要重新适配显示、输入、存储布局和桌面端通信协议。

可以，但必须确认接口、电压、排线定义和初始化序列。当前固件按 2.8 英寸 480×640 MIPI-DSI 屏、三个按键、GPIO20/GPIO21 双轴与 GPIO4 中键摇杆和配套音频电路适配；GPIO2/GPIO3 的旧旋钮输入仍保留兼容。仅仅驱动 IC 相同不代表屏幕或输入器件可以直接互换。

不需要。当前产品交互以三个实体按键、四向摇杆和语音为主，固件不依赖触摸屏。

不是必须。定制 PCB 主要是为了减少杜邦线、让结构更整洁。调试阶段可以先用杜邦线直连；想做成完整产品形态时再按 OSHWHub 的硬件资料打样。

成本取决于 ESP32-P4 主板、MIPI 屏、PCB、音频器件、摇杆按键、外壳和打样数量，请以硬件复刻页面的最新 BOM 为准。

当前重点适配 ChatGPT（Codex）和 Claude 桌面 Agent，并通过本地 bridge 读取 Session、切换会话和路由语音输入。状态协议保持可扩展，后续可以接入更多 Agent。

设备状态、形象和组件同步走 USB，不要求 ESP32-P4 加入局域网。语音识别、Agent 本身以及 AI 形象或组件生成仍可能需要电脑联网。

按住绑定的语音输入键开始录音，松开后由桌面端完成 ASR，并把文字注入当前气泡对应的 Agent Session。设备没有气泡时，桌面端会拉起当前跟随的 Agent，再定位其输入框。语音识别需要已配置且可用的 ASR 服务。

可以。项目提供 petui Skill，用户可以在 Agent 中用自然语言生成小组件或小游戏，校验并发布到统一组件库，再由桌面端通过 USB 同步到设备。

当前源码采用 HachimoDock 项目许可证，仅限许可范围内的非商业用途。商业使用、商业集成或独立产品开发须另行取得权利人书面授权。允许个人非商业复刻、项目内修改，以及组件的生成、调试和分享。第三方材料继续遵循 THIRD_PARTY_NOTICES.md 中各自的许可证；历史安装包遵循其随包许可证。

可以在 GitHub 提 Issue 或 Discussion。硬件复刻相关问题建议同时参考 OSHWHub 硬件端页面。

每个 Release 都提供 SHA256SUMS 和 release-manifest.json。下载后请先核对 SHA-256，再安装客户端或烧录固件；不要混用不同 Release 的出厂镜像和 JSON 清单。

HachimoDock 的实现参考、借鉴并集成了以下开源项目，特此致谢：

• Clawd on Desk — 开源项目致谢；第三方版权与许可证见 THIRD_PARTY_NOTICES.md。
• OpenClaw（MIT）— CLI Agent 运行时与插件 SDK。
• Claude Code — 主力 coding agent 与 hook 状态协议。
• Codex — 被适配的 CLI Agent 之一；同时支持 Cursor、Gemini CLI、GitHub Copilot CLI 等。

贡献者 / Contributors：Wanzheng Liu、Zinuo Tian。

• 📧 邮箱：avalon.ty@gmail.com
• 💬 微信交流群：扫描下方二维码加入

如果 HachimoDock 对你有帮助，欢迎给仓库点一个 ⭐ Star、点击 Follow 关注后续更新，也欢迎通过 Issue 提交可复现的问题与建议。

Copyright (C) 2026 Yizheng Wang.

项目采用 HachimoDock 项目许可证。允许许可范围内的个人非商业使用、修改和组件创作；商业用途须另行取得书面授权。项目名称、标识及素材的相关权利仍由各权利人保留。

重要声明：本项目仅限许可范围内的非商业用途。未经权利人书面授权，不得用于商业产品、收费服务或独立于本项目的 APP、Web 服务及其他软件、硬件产品。 项目内非商业组件开发按许可证明确允许。

Current sources are provided under the HachimoDock Project License for permitted non-commercial purposes only. Commercial use and independent product development require prior written permission. Third-party licenses and licenses accompanying earlier releases remain applicable. See the English overview.

想自行编译或修改功能？请从下方目录开始。直接使用请前往 下载页面，选择适合电脑系统的客户端和设备烧录包。

克隆源码后，请安装 Git LFS 并运行 git lfs pull 获取配套素材。使用语音识别或形象生成时，在客户端的“API 配置”中填写自己的服务 Key。