三条官方路径,先选对
机器人本体不挑工具:它只收一个动画名。官方接入文档给出三条路径,按手头的工具和场景选:
| 路径 | 适合 | 入口 |
|---|---|---|
tiny-engineer CLI(默认) |
Cursor / Claude Code / Antigravity 的 hooks | npx -y tiny-engineer setup |
| REST API(进阶) | 自定义 agent、其他 IDE、CI、任意脚本 | POST /anim?name=… |
| USB 串口 | 无 Wi-Fi 或 USB-only 场景 | --transport serial |
前置条件:固件已刷好、已连 2.4 GHz Wi-Fi、http://tiny-engineer.local/health(或 OLED 上显示的 IP)有响应。
三家 IDE 的一键 setup
CLI 统一包名 tiny-engineer,发布在 npm 上,无需 clone 仓库。官方支持一键 setup 的 IDE 只有三家:Cursor、Claude Code、Antigravity;旧的分体包(tiny-engineer-cursor / tiny-engineer-antigravity / tiny-engineer-claude-code)已废弃,新装一律用统一 CLI。
npx -y tiny-engineer setup npx -y tiny-engineer setup cursor --yes npx -y tiny-engineer setup --all --yes --url http://192.168.1.10 npx -y tiny-engineer doctor
setup 把 hook 命令合并写入对应 IDE 的项目配置(Cursor 的 .cursor/hooks.json、Claude Code 的 .claude/settings.json、Antigravity 的 .agents/hooks.json),命令统一是 npx -y tiny-engineer hook <ide>;只合并条目,不删除别人家的 hook。装完用官方冒烟测试验证:
echo '{"hook_event_name":"stop"}' | npx -y tiny-engineer hook cursor
官方另有共享 skill tiny-engineer-play(用 curl 走 POST /play),同一个 skill 在三家 IDE 里都能装。
其他工具全部走 REST:机器人只认 name
官方 README 写明接入范围:Works with Claude Code · Cursor · Antigravity — via npx -y tiny-engineer setup — or Codex, Windsurf, and any script that can POST。也就是一键 setup 只覆盖上面三家;Codex、Windsurf、Trae、通义灵码、CodeBuddy、其他国产编程助手、任意脚本和 CI 走同一条路:自己写映射,直接 POST /anim。集成文档的原话是 Mapping is yours; the robot only cares about name——映射由你定,机器人只认 name 参数,不认具体工具。
最小接入模板(遵守官方的短超时+忽略网络错误建议):
curl -4 -sS -m 2 -X POST "http://tiny-engineer.local/anim?name=reading" >/dev/null || true
await fetch("http://tiny-engineer.local/anim?name=thinking", {
method: "POST",
signal: AbortSignal.timeout(2000),
}).catch(() => {});
接入点建议:提交 prompt 时发 reading,工具调用/写码时发 typing,回合结束发 ring,需要用户确认发 attention。这套映射对任何能发 HTTP POST 的工具一视同仁,无论 IDE 是哪家的。
配置落点:用户级目录,而非项目 .env
这是中文资料里写错最多的一个点。连接偏好(transport、URL、端口、token)写在用户级 user config:
- macOS / Linux:
~/.config/tiny-engineer/env - Windows:
%APPDATA%\tiny-engineer\env - 可用环境变量
TINY_ENGINEER_CONFIG_DIR覆盖目录
setup 从不编辑项目根目录的 .env,向导里会把全局与项目级标注清楚。完整加载顺序是:命令行 flag → 进程环境变量 → 项目 .env(可覆盖用户配置,setup 和 doctor 会在这种覆盖发生时警告)→ user env → 默认值。另有一条安全细节:当 URL 只来自项目 .env 时,用户级或进程级的 TINY_ENGINEER_TOKEN 不会被发送(请求继续但不带 Bearer,stderr 警告),防止把个人 token 发给项目文件里指定的地址;串口路径则完全跳过 Bearer。
冷启动与 Node 版本的三个坑
-
npx冷启动可能很慢,setup写入 hook 时把timeout设为 ≥ 30 秒,别手动调小。 - CLI 要求 Node 18 及以上(
engines.node >= 18)。这与固件仓库 PlatformIO 构建要求的 Node 20.19+/22.12+ 是两个不同场景的口径,别互相套用。 - 优先用 registry 的
npx -y tiny-engineer,别用npx github:…——SSH 拉取在 IDE hooks 环境里经常失败。
常用命令速查
| 命令 | 作用 |
|---|---|
setup |
交互式选 IDE 写入 hooks;setup cursor --yes 跳过确认;setup cursor --yes --transport serial 走串口;setup --all --yes --url … 一次装三家并指定地址 |
doctor |
体检:连接、配置、hook 状态逐项检查 |
hook <ide> |
IDE hook 实际调用的入口,把 hook 事件映射成动画请求 |
anim ring |
命令行直接发动画,不用自己写 HTTP 客户端 |
play / park / health / reset
|
播 WAV、舵机归中、查健康、恢复出厂 |
daemon status |
查看串口守护进程状态(是否已 install、端口占用、通道来源) |
rules list |
查看「机器人事件→宿主程序」规则表(add/remove 配套) |
uninstall cursor --yes |
只移除 Tiny Engineer 写入的 hook 条目,不动其他配置,没有 --purge-env |
串口模式与 daemon
串口类命令(anim、play、watch、monitor、settings、doctor、hooks 等)会自动拉起 tiny-engineer daemon 并通过本地 socket 与之通信;HTTP 命令不启动 daemon。关掉终端不会停掉它,但要保证常驻,需要执行 daemon install(注册的是每用户登录包装,进程崩溃后自动重启,并非系统级开机服务)。HTTP 路径的 anim 和 hooks 不经过 daemon。
国内玩家怎么选
结论:不必纠结 IDE,用什么都能接。Cursor、Claude Code、Antigravity 三家走一行 npx -y tiny-engineer setup;其中 Claude Code 在国内默认需要境外网络与外币支付,用不上它完全不影响接入。Trae、通义灵码、CodeBuddy、Codex、Windsurf、其他国产编程助手、任意脚本和 CI,只要能在事件发生时发一个 POST /anim?name=…,就与官方三家用到同一套固件能力——映射自己定,机器人只认 name。没有 Wi-Fi 的环境(比如公司网络不让设备入网)加 --transport serial 走 USB 串口协议即可。