ARTICLE · 1256910

给 AI 装上身体:Tiny Engineer 复刻与二开实战

发布时间：2026-10-27 01:20:29 最近访问：2026-10-27 01:20:30

开源硬件 · 实战教程

给 AI 装上身体：Tiny Engineer 复刻与二开实战

AI 编程助手每天都在读文件、思考、改代码，可这些过程只存在于屏幕里。Tiny Engineer 做了一件很有趣的事：把这些事件翻译成一台桌面机器人的动作。它读资料时环顾四周，写代码时敲击键盘，思考时抬头，完成任务时敲一下铃铛。

更重要的是，它不是只能照着清单复刻的成品。仓库同时开放固件、CLI、HTTP 与串口协议、PCB、参数化 CAD 和改装示例。你可以先原样做出来，再把它改成构建监视器、语音搭档、专注计时器，甚至一支多智能体桌面小队。

本文按 2026 年 10 月 27 日的 main@5bf2730 源码与文档整理，属于源码级复刻指南；打印公差、舵机行程和实际供电仍要以你的实物测试为准。

一、先看懂：它把“软件事件”变成了“身体语言”

图：Tiny Engineer 原版桌面机器人，包含 OLED 表情、五舵机身体、迷你电脑和铃铛（图源：Tiny Engineer 官方仓库）

Tiny Engineer 的核心不是某个外壳，而是一条完整链路：

AI IDE 或脚本 → Hook／CLI → HTTP 或 USB 串口 → ESP32-C3 → 舵机、OLED、扬声器。

默认固件已经内置 13 种状态：typing、reading、thinking、talking、ring、welcome、attention、error、abort、dead、wakeup、sleep 和 none。这些不是简单摆动同一组舵机，而是分别编排头、颈、双手、躯干、眼神、灯光和声音。

硬件分工也很清楚：

ESP32-C3-Zero：运行固件、Wi-Fi、HTTP 服务和 USB CDC。

PCA9685：通过 I²C 输出 16 路 PWM，当前使用 0—4 通道驱动五个舵机。

SSD1306 OLED：128×32 像素，负责眼睛和状态显示。

MAX98357A 与 8Ω／1W 扬声器：通过 I²S 播放提示音和 WAV 语音。

WS2812：用白色、红色脉冲等灯效补充当前状态。

这套设计最适合软件工程师入门的理由，是你不必第一天就读懂所有嵌入式代码。先调用 API 就能看到结果，之后再逐层深入固件和机械结构。

二、复刻前准备：先定路线，再买零件

图：模块化接线与集成主控板方案对比，集成板包含 PCA9685、MAX98357A 和 USB-C（图源：Tiny Engineer 官方文档）

官方提供两条电子路线。第一次做，建议选集成主控板；不方便打板时，再选模块化方案。

路线	适合谁	主要差别
集成主控板	希望接线少、结构整洁	用 KiCad 文件打板，可选 PCBA；ESP32、OLED、舵机和扬声器插入对应接口
模块化分线	已有开发板和模块、愿意焊接	用 PCA9685、MAX98357A、USB-C breakout 组合，按模块化装配文档安装

推荐购物清单如下：

Waveshare ESP32-C3-Zero × 1。
Tower Pro SG90 或同级 9g 模拟舵机 × 5。
0.91 英寸 SSD1306 OLED，128×32、I²C、地址 0x3C × 1。
8Ω／1W 小型扬声器 × 1。
主控板 × 1，或模块化方案所需三块 breakout。
M2×4、M2×8、M2×16 塑料自攻螺钉及 M2 螺母；官方数量为 8、27、15 和 6。
5V／不低于 2A 的 USB 电源，以及真正支持数据传输的 USB-C 线。
PLA 或 PETG 打印件；没有打印机可以下单代打印。

舵机要在打印前确定。SG90 是官方推荐给新手的版本，电子仓更宽裕；FS0307 和 ES9051 更紧凑；HD-1370A 主要保留给旧版本。五种舵机必须同型号，并打印对应的 3d_models/parts/{servo_id}/ 文件夹，不能混用。

主控板不是必须购买的成品。仓库提供 KiCad 源文件，可通过 Fabrication Toolkit 导出 Gerber、BOM 和坐标文件。初次打板更适合选单面 PCBA，再自行焊 ESP32 排母；下单前要逐行核对元件库存、封装和贴装方向。

三、动手复刻：正确顺序能避开大半故障

图：Tiny Engineer 的事件、通信和硬件架构，包括 REST API、ESP32-C3、I²C、OLED 与 I²S（图源：Tiny Engineer 官方文档）

官方推荐顺序是：采购 → 打印 → 接线 → 烧录 → 装配 → 配置 → 验证 → 接入 Agent。其中“先烧录、后总装”非常关键，因为舵机居中要在结构件装上之前完成。

1. 先打印两个测试件

不要一上来打印整套外壳。先打印 ServoSizingTester.3mf 和 ScrewSizingTest.3mf：前者验证舵机仓，后者从约 2.00—2.40mm 的孔径中选出适合你打印机的 M2 底孔。

官方导出默认值是 2.1mm，但你的打印机、材料和切片参数才有一票否决权。如果结果不同，在 Fusion 中修改 screw_thread_diameter，重新导出结构件。灯罩 LampDiffuser 是刻意的薄壁件，切片时需要 Arachne 墙生成器或“打印薄壁”选项，不要直接缩放。

2. 在桌面完成接线和烧录

把 ESP32 按 PCB 的 USB 标记方向插好，再接 OLED、舵机和扬声器。扬声器只能在连接器与焊盘中二选一，而且 SPK− 不是地线。整机只用主控板的 USB-C 供电和烧录，装配后不要再同时连接 ESP32 自带的 USB-C。

用 Chrome 或 Edge 打开官方 Web Flash，选择最新 Release 并安装。网页固件包含 LittleFS 音频，不需要先装 PlatformIO。烧录后应出现 TinyEngineer-XXXX 热点；如果红灯单闪后停顿，通常是 I²C 地址 0x40 的 PCA9685 没被找到，而不是烧录失败。

3. 90° 居中后再装结构

手机或电脑连接配置热点，打开 http://192.168.4.1/config，在 Assembly support 中执行 Move all to 90°。每装完一个关节就拔掉对应舵机线，最后再按通道接回：

通道 0：头部俯仰。

通道 1：颈部左右转动。

通道 2：左手。

通道 3：右手。

通道 4：躯干。

官方装配文档把头颈、胸腔、座椅、桌面、电子仓、手臂和灯具拆成 20 个步骤。照图施工时，比拧螺丝更重要的是理线：线不能进入螺钉路径，也不能被底盖夹住。

4. 校准、联网、验收

总装后重新进入配置向导，依次完成舵机范围、OLED 方向、RGB 顺序、扬声器与 2.4GHz Wi-Fi。断电重启后执行：

curl http://tiny-engineer.local/health curl -X POST "http://tiny-engineer.local/anim?name=ring" curl -X POST http://tiny-engineer.local/test/movement

.local 解析慢或失败时，直接使用 OLED 显示的 IP，或给 curl 加 -4。如果多个舵机同时动作就重启、抖动或 OLED 闪烁，先查 5V 供电和共地，不要急着改代码。舵机绝不能从 ESP32 的 3.3V 稳压器取电。

接入 Cursor、Claude Code 或 Antigravity 只需：

npx -y tiny-engineer setup npx -y tiny-engineer doctor

企业网络不方便联网时，可以在设备端选择 USB-only，并在 CLI 端使用 --transport serial。这两条设置一个在机器人上，一个在电脑上，不要混为一谈。

四、零改固件二开：先做构建监视器和语音搭档

项目最友好的二开入口是 REST API。任何能发 HTTP POST 的语言都能控制它，不必等待官方支持某个 IDE。

例如，新增一个“专注”场景可以直接复用现有状态：

# 开始专注：进入思考姿态 curl -X POST "http://tiny-engineer.local/anim?name=thinking" # 25 分钟后：敲铃提醒 curl -X POST "http://tiny-engineer.local/anim?name=ring" # 暂时离开：休眠 curl -X POST "http://tiny-engineer.local/anim?name=sleep"

更有用的是把本地构建命令包一层：开始时 thinking，成功时 ring，失败时 error。下面这个 Python 脚本只用标准库；机器人离线时最多等待 2 秒，不会卡住构建。

import os, subprocess, sys, urllib.parse, urllib.request  base = os.environ.get("TINY_ENGINEER_URL", "http://tiny-engineer.local").rstrip("/") token = os.environ.get("TINY_ENGINEER_TOKEN", "")  def anim(name):     url = f"{base}/anim?{urllib.parse.urlencode({'name': name})}"     headers = {"Authorization": f"Bearer {token}"} if token else {}     req = urllib.request.Request(url, headers=headers, method="POST")     try:         with urllib.request.urlopen(req, timeout=2):             pass     except OSError:         pass  anim("thinking") try:     result = subprocess.run(sys.argv[1:], check=False) except KeyboardInterrupt:     anim("abort")     raise SystemExit(130) anim("ring" if result.returncode == 0 else "error") raise SystemExit(result.returncode)

保存为 build_with_robot.py，这样运行：

python build_with_robot.py npm test python build_with_robot.py python -m pytest

云端 GitHub Actions 通常访问不到你家局域网里的机器人。想接入 CI，优先在能访问机器人的本机或自托管 runner 上执行；不要把控制端口直接暴露到公网。正式使用还应通过 POST /settings 设置 access_token，客户端再发送 Bearer Token。

第二个低门槛改造是“会说话”。/play 可以流式播放 WAV，并同步驱动 talking 表情和动作。先转换音频：

ffmpeg -i voice.mp3 -ac 1 -ar 22050 -c:a pcm_s16le voice.wav curl -X POST http://tiny-engineer.local/play \   -H "Content-Type: audio/wav" --data-binary @voice.wav

格式必须是 22050Hz、单声道、16-bit PCM。请求会播完才返回，而且设备 HTTP 服务一次处理一个请求；把它当提示音通道，不要同时发多段音频抢资源。

五、进阶改造：人格、传感器和多机器人小队

方案 A：不改动作代码，先换一套人格

固件已经提供 classic、kaomoji、cover、dots 四种眼睛风格，可以直接切换：

curl -X POST http://tiny-engineer.local/settings \   -H "Content-Type: application/json" \   -d '{"eyes_style":"kaomoji","volume":40}'

想换声音，在 mods/<名字>/assets/ 放同名 WAV，并在 platformio.ini 设置 custom_audio_mod = <名字>，再执行 pio run -t upload。构建系统先复制原版音频，再用 Mod 文件覆盖；缺哪个文件就保留哪个原版。welcome、attention、error、abort、dead 还需要同名 .cue 标记语句时间，动作才能对上语气。

仓库里的 Halloween Mod 是现成范本：南瓜头、灯具、杯子和替换语音可以独立组合。照这个结构做春节、赛博朋克或自己 IP 的主题包，比直接改原版目录更容易维护。

方案 B：加距离传感器，做离座休眠与回座唤醒

主控板 J3 是共享 I²C 扩展口，J4 还引出了 GPIO6、7、8 等资源。可以优先选择 3.3V 兼容、地址不与 0x40、0x3C 冲突的 I²C 距离传感器：

1.在 mods/presence/3d_models/ 设计支架，避开舵机运动区和 ESP32 天线。

2.在固件中加入传感器初始化与非阻塞采样，不要在主循环里长时间 delay。

3.连续多次确认“离座”后触发 sleep，确认“回座”后触发 wakeup。

4.加超时和手动覆盖，避免传感器抖动让机器人反复睡醒。

5.同步更新 include/pins.h、引脚文档和接线图。

GPIO 都是 3.3V 域，GPIO8、9 有启动约束，GPIO18、19 已用于原生 USB，不能随手占用。新增功耗也要单独核算，传感器不能成为舵机掉电重启的新原因。

方案 C：新增动作，而不是硬写舵机角度

如果“成功敲铃”不足以表达你的项目，可以新增 celebrate：双臂举起、点头、眼睛惊喜，再回到 none。

固件的动作入口在 src/animation.h、src/animation/ 和 src/animation/registry.cpp。新增动作需要定义 AnimationId，实现 start／update，并在注册表绑定名称与已有 EyeMode。动作目标使用 −1 到 1 的归一化姿态，由每台的校准范围映射成角度，不要把 0—180° 硬编码进动画。完成后至少运行 pio run、pio test -e native，并同步 API 与 Web UI 文档。

想做“一人一个 Agent”的桌面小队，也不必改通信协议：给每台机器人设置不同 hostname，电脑端按不同 URL 分发事件。一个 Agent 写代码，另一个跑测试，第三个只在失败时提醒，分工就有了身体语言。

六、发布改造前，还要守住三条边界

第一是安全。原厂默认每个关节只在 80°—100° 的保守范围内工作，校准后才扩展到适合本机的区间。不要用 /setup/servo 的全行程能力去驱动已经装好的机构；刷写前可先调用 /servos/park，让关节平滑回到中位。
第二是维护性。只写脚本，尽量不改固件；只换外观和音频，放进 mods/；改结构，以 .f3d 为源文件并重新导出，不要手改 STL 当主版本。新增机械件要在所有舵机预设下重建验证，新 API 则要同步文档和界面。
第三是许可证。软件、脚本和文档采用 MIT；CAD、打印件和 PCB 采用 CERN-OHL-S-2.0，修改并分发基于这些设计的产品时，需要按强互惠条款提供对应的完整源码。Tiny Engineer 名称、Logo 和 AI 徽标不随代码授权，可以如实写“基于 Tiny Engineer 开源设计”，但不要把自己的改造包装成官方产品。

Tiny Engineer 真正值得借鉴的，不只是“AI + 舵机”的创意，而是它把复刻和二开拆成了几个清晰层级：API 给应用开发者，动作注册表给固件开发者，参数化 CAD 给结构开发者，扩展口给硬件开发者。

你可以从今晚的一行 POST /anim?name=ring 开始，也可以做一台只属于自己的桌面同事。你最想让它学会哪一种新动作？留言区聊聊；如果这篇教程有用，也可以转给正在做 AI 硬件的朋友。

参考来源

Tiny Engineer 官方仓库

Getting started：完整复刻流程

Shopping list：物料与舵机选择

Mechanical assembly：20 步机械装配

HTTP API：动作、设置与语音接口

Parametric design：参数化 CAD 与新增舵机

Mods：外观和音频改装规范

Licensing：软硬件许可证边界