项目>Reachy Mini>开发自己的 App:脚手架、契约与发布

开发自己的 App:脚手架、契约与发布

摘要:用官方命令行工具生成应用骨架、实现运行契约、本地验证到通过 daemon 启停和开机自启,并知道哪些中文教程里的接口根本不存在。

只用官方脚手架起骨架

写自己的应用,第一步是用命令行工具生成骨架:reachy-mini-app-assistant create。官方在应用文档里特意加了一句 Never create app folders manually,意思是别自己新建目录拼文件,脚手架会按要求把目录结构、配置和入口一次生成好。执行后会提示选模板,Default 是空骨架、Conversation 带对话相关的起步代码,选完得到一个可直接改的应用目录。卡住时先看是不是手动建了同名目录,清理掉重跑 create 比手工补文件省事;生成后目录里应当已经有入口模块和配置文件,缺哪一样都先重生成一次。

实现 ReachyMiniApp 契约

生成的骨架围绕 ReachyMiniApp 契约组织,几个方法各有明确分工,照着填逻辑就行:

成员 职责
run(reachy_mini, stop_event) 应用主体,拿到已连接的机器人实例和停止事件,在里面写动作与交互循环
wrapped_run() 负责建立连接、启动服务,把 run 包起来
stop() 由 daemon 经 SIGINT 触发,收尾退出

还要在 pyproject.toml 里把应用登记到 entry-point 组 reachy_mini_apps,daemon 才能发现并拉起它。漏了这一步最常见的结果是在应用列表里根本看不到自己的应用,先回配置文件核对,别急着怀疑代码逻辑。

写 run 时有个和 daemon 配合的细节:循环里要定期看一眼 stop_event,被置位就收尾退出,这样 Stop 发来的 SIGINT 才能走优雅退出、机器人也才能回到默认姿态。循环里若一直阻塞、从不检查这个事件,停应用时容易卡住不退出,得靠强制杀进程收场。把动作和交互都放进这个循环;wrapped_run() 负责连接和起服务,stop() 负责收尾,这两块脚手架已生成好,通常不用改动。

一次启动背后发生的事

点 Start 之后,daemon 起一个 Python 子进程 python -u -m your_app.main,把已经连好的 ReachyMini 实例和 stop_event 传进应用,应用因此不用自己管理硬件连接;停止时 daemon 向子进程发 SIGINT 让它优雅退出,退出后机器人回到默认姿态。理解这条链,就能看懂为什么应用里不该出现自己连硬件的代码。在 Reachy Mini Wireless 上应用跑在共享虚拟环境 /venvs/apps_venv/ 里,依赖由所有应用共用,装依赖时留意版本冲突。

从检查到开机自启的验证链

骨架填完,按官方顺序逐步验证,每一步都有明确预期:

  1. reachy-mini-app-assistant check:静态检查结构和契约,会看到检查项逐条通过或报出具体不合格项;报错就按提示补齐再重跑,别带着未通过项往下走。
  2. python -m my_app.main:脱离 daemon 直接本地跑主模块,确认应用逻辑本身没问题,会看到应用自己的输出。这一步没有注入连接,连不上机器人属正常,别当成脚本坏了。
  3. 经 daemon 起停:用 curl /api/apps/start-app/... 让 daemon 按真实生命周期启动,再用对应停止接口停掉,会看到机器人按应用逻辑动作、Stop 后回默认姿态。
  4. --startup-app:把应用设为开机(Reachy Mini Wireless 上也能摸天线触发)自启,重启一次验证开机即自动进入应用,不用再手动点 Start。

这几步是层层收窄范围的:check 没过是结构或契约问题,本地跑不起来是应用逻辑问题,到 daemon 起停才出问题多半是 entry-point 没登记或连接没注入,设了自启却没生效就核对启动参数。哪一步的预期结果没出现,就停在那一步改,别跳过前面的检查直接怀疑机器人硬件。

可选的网页界面

应用要带网页界面,就在里面设 custom_app_url,daemon 会自动起一个 FastAPI 服务托管 static/ 目录,端口是 8042:Reachy Mini Lite 上访问 localhost:8042,Reachy Mini Wireless 上访问 reachy-mini.local:8042。刚 Start 就刷页面常常 404 或连不上,因为路由是在应用的 run() 启动之后才注册进服务,页面要重试几次才出现,别当成服务没起来去反复重装;若重试多次仍打不开,先确认应用确实在跑,再查 8042 有没有被别的进程占着。

两种形态与给编码代理的材料

应用默认形态是 JS,也就是 Live、Web 这一类跑在浏览器里的;Python 应用留给重计算、离线 LAN、常驻无人值守这类确实需要本地进程的场景。选形态时按实际用途定,不必两种都写一遍。仓库根目录有 AGENTS.md 给 AI 编码代理看,另有 skills/ 六份技能文档,把这些交给代理能少走弯路:

  • create-app
  • ai-integration
  • control-loops
  • motion-philosophy
  • interaction-patterns
  • symbolic-motion

中文教程里流传的一些应用开发命令和方法,在官方仓库里并不存在,遇到时以这一页写的官方契约为准。把生成骨架、实现契约、本地验证、经 daemon 启停、设开机自启这条链走通,一个能从零跑起来的应用就齐了;卡在哪一步,就回到那一步的预期结果去对照。

资料来源

  • 应用构建官方页
  • AI 代理开发指南
  • 官方 README
  • 双平台使用官方页

相关内容

Reachy Mini 深拆:399 美元的开源桌面机器人实践