项目>Tiny Engineer>接入 AI 编程助手:npx setup 只管三家 IDE,配置落在用户目录

接入 AI 编程助手:npx setup 只管三家 IDE,配置落在用户目录

摘要:用一行 npx 命令给 Cursor、Claude Code 或 Antigravity 装好 hook,知道配置写在用户级目录而非项目文件、冷启动要给足超时,以及 Codex、Windsurf 和任意脚本该走 REST 而非 setup。

三条官方路径,先选对

机器人本体不挑工具:它只收一个动画名。官方接入文档给出三条路径,按手头的工具和场景选:

路径 适合 入口
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 串口协议即可。

资料来源

  • 集成指南官方页
  • 命令行工具说明
  • 配置说明官方页
  • 接口文档官方页
  • 官方 README