emergingrobotics/gorai

来源: https://github.com/emergingrobotics/gorai

Gorai

面向 AI 时代的机器人平台。
发音为 “go-ray”（类似 “sting-ray”）

为什么选择 Gorai？

机器人是一个分布式系统——请以构建分布式系统的方式来构建它。
即使是“单一”机器人，也已经是由微控制器、单板计算机、传感器以及有时一个基站组成的网络。Gorai 不再假装不是这样：每个传感器和执行器都是一个运行在 NATS 网格上的服务——在运行时发现，按名称寻址，永不手动接线。
构建可靠云系统的规范——服务发现、位置透明性、健康检查、扇出、重放——恰恰是真正机器人所需的。

能力，而非接线。
传感器是你可以读取的 资源；执行器是你调用的 工具。网格上的任何智能体都可以感知世界并改变它——MCP 赋予 AI 智能体的能力模型，现在通过 NATS 原生传递，路径中无需 MCP 服务器。我们称之为 NCP，即 NATS 能力协议。

一个机器人可以由多台机器组成。
因为能力是按名称寻址而非位置寻址，一个逻辑机器人可以跨越一辆漫游车、一架无人机、一个传感器桅杆和一个计算盒——在运行时组合，随着平台的加入和离开优雅地降级。这就是组合机器人，也是它的全部意义所在。

没有重放的自主性只是民间传说。
动作日志、状态流和重放是一等公民的平台特性——而非附加组件。AI 执行是受欢迎的，但绝不被信任：安全性在能力节点而非智能体上强制执行。兼容智能体，而非依赖智能体——确定性状态机和基于规则的规划器驱动着相同的能力。

像构建软件一样构建机器人。像运行系统一样运行它们。
固执己见，务实，可运维。如果你已经习惯于 API、分布式系统和部署，你将在几天内而非几个月内高效工作。
请阅读北极星文档：VISION.md。

完整文档位于 gorai-docs (https://github.com/emergingrobotics/gorai-docs)。
战略、架构、规范、硬件分析、一本 20 章的书以及实施指南——全部为人类和 AI 智能体建立了索引。将你的 AI 智能体指向该仓库，它将通过 CLAUDE.md 和 INDEX.md 自动导航 100 多份文档。

gorai 是什么（以及不是什么）

在一个 Gorai 项目中有两个不同的二进制文件，切勿混淆：

1. 你的机器人二进制文件 ——在树莓派上运行并 执行机器人功能 的程序。这是你自己的 Go 模块：一个 main.go，它导入（blank-import）你想要的组件并调用 gorai.Run()。其内置的 NATS 服务器、网格和每个组件都编译进这一个静态二进制文件。它完全自包含，在运行时不需要 gorai 工具提供任何东西——你只需将其复制到机器人上并运行它。

2. gorai 命令行工具 ——一个你在工作站运行的开发者和运维工具。在生产环境中从不在机器人上运行。可以将其视为 kubectl + 构建包装器 + 包助手的结合体，集成在一个命令中。

是的——你可以只对你的机器人项目执行 go build . 然后用 scp 将结果传输到树莓派。gorai 命令行工具的价值在于完成了那个二进制文件之外的事情，而普通的 go build 无法做到：

前三个是对 Go 工具链的便利性增强。网格命令是你真正无法用 go build 复制的部分——它们观察和调试正在运行的系统，这正是当一台（或多台）机器人上线时你需要用到的功能。

本 README 的其余部分涵盖如何安装命令行工具、定义机器人以及构建它。

在一小时内构建一个机器人。编写 JSON，获得一个二进制文件，部署到 Linux 主机（树莓派/Orange Pi 等）。

# 1. 安装 CLI（一个开发者/运维工具——不是机器人本身）  
go install github.com/emergingrobotics/gorai/cmd/gorai@latest  

# 2. 从模板创建一个机器人项目  
git clone https://github.com/emergingrobotics/gorai-robot-template.git my-robot  
cd my-robot  

# 3. 编辑 robot.json，然后验证并运行  
gorai validate robot.json  
gorai run robot.json  

# 4. 构建用于部署的二进制文件  
gorai build robot.json -o robot --target linux/arm64  
scp robot pi@raspberrypi:~ && ssh pi@raspberrypi ./robot  

没有容器。没有 K8s。没有外部服务——只有树莓派 5 或 Orange Pi 5 上的一个二进制文件。这是简单情况，而非上限：将多个二进制文件指向一个共享的 NATS 总线（或一个叶子节点），网格就会将多个平台连接成一个逻辑机器人——相同的代码，无需重写。

Gorai 驱动的硬件

Gorai 面向跨越海洋、水面、水下和陆地领域的专业消费者可访问的现场机器人——自主潜水器、自主水面船舶和陆地机器人。例如，一个自主潜水器在压力壳内的 Linux 主机（树莓派/Orange Pi 等）上运行 gorai run。

组件生态系统

Gorai 采用 Caddy 模型 进行组件打包：你的机器人项目是一个标准的 Go 模块，main.go 中的导入列表就是组件清单。每个组件通过调用 registry.RegisterComponent() 的 init() 函数进行自注册。没有自定义包管理器——Go 模块处理一切。

工作原理

机器人的 main.go 通过空导入声明要包含哪些组件：

package main  

import (  
    gorai "github.com/emergingrobotics/gorai/pkg/gorai"  

    // 来自 GoRAI 核心的远程代理组件  
    _ "github.com/emergingrobotics/gorai/components/motor/remote"  
    _ "github.com/emergingrobotics/gorai/components/camera/remote"  

    // 生态系统中的第三方组件  
    _ "github.com/someone/gorai-component-lidar/rplidar"  

    // 本仓库中的自定义组件  
    _ "my-robot/components/ballast"  
)  

func main() {  
    gorai.Run()  
}  

Go 的导入列表取代了 package.json、requirements.txt 或任何自定义清单。你导入的内容就是被编译到二进制文件中的内容。

工作流程

gorai component search lidar     # 在生态系统中查找组件  
gorai component add sensor/rplidar # go get + 在 main.go 中添加空导入  
gorai build robot.json           # 包含所有内容的单个二进制文件  

自定义组件

自定义组件是你项目仓库中的普通 Go 包。编写一个带有调用 registry.RegisterComponent() 的 init() 函数的包，在 main.go 中添加一个空导入，它就会与其他所有内容一起编译到二进制文件中。

共享组件

共享组件意味着发布一个 Go 模块。将该包提取到其自己的仓库中，推送到 GitHub，然后任何人都可以 gorai component add 它。没有注册表服务器，没有包审批流程——标准的 Go 模块托管。

为什么这很重要

这是选择 Go 作为平台语言的关键优势。单二进制文件的故事一直延伸到组件生态系统：没有运行时依赖解析，没有 DLL 地狱，没有部署时的版本冲突。每个依赖都在构建时由 Go 工具链解析，结果是一个静态二进制文件，你只需将其复制到机器人上。

非 Go 组件（Python 视觉管道、C++ SLAM）作为外部服务运行，通过 NATS 通信。它们不会编译到二进制文件中。这是第二阶段的复杂性。完整设计请参见 docs/package-dev-approach.md。

Gorai 的目标用户是谁？

如果你符合以下情况，请使用 Gorai：

• 想要 真正的自主性（非教育玩具，非模拟）
• 需要 易于上手的软件（几天内高效工作，而非几个月）
• 重视 现代工具链（AI 辅助编码，简单部署）
• 正在构建 专业消费级机器人（海洋监测、陆地车辆、研究平台）
• 是一个 软件优先的团队，为 AI/ML 增加物理实体，或从一台机器人扩展到车队
• 更关心 行为、协调和运维，而非底层运动学或中间件内部原理

如果你符合以下情况，请使用 ROS 2：

• 从事 企业/研究 级机器人（仓库自动化、自动驾驶车辆）
• 需要 完整的 ROS 生态系统（数千个包、仿真、SLAM 库）
• 在 学术界，ROS 2 是标准
• 需要 深入的硬件或控制架构实验（ROS 2 是正确的平台）

我们不是在取代 ROS 2——我们针对的是不同的市场。可以理解为 “面向专业消费级市场的 ROS 2”，采用 AI 优先 的设计，面向下一波自主系统。

未来的机器人市场（以及 Gorai 如何应对）

机器人技术正在转变，因为决策能力正在向堆栈上移：自主性不再仅仅是手工编写的逻辑。感知、规划和任务选择越来越多地通过学习、概率或智能体方式实现。这种转变——物理 AI——改变了平台必须提供的内容。

未来市场的特点：

• 物理 AI —— 行为、自主性和协调性比电机控制或运动学更复杂的系统
• 软件优先的团队 —— 需要交付机器人和车队，而无需成为机器人基础设施专家的工程师和 AI/ML 从业者
• 自主性是一个频谱 —— 从脚本行为和状态机到学习型感知和智能体规划器，都需要相同的操作界面

Gorai 为何为此而构建：

• AI 优先的设计 —— 我们将 AI 驱动的执行视为一等假设：为工具提供能力接口、运行时治理和安全，以及将可审计性/重放作为基线而非附加功能
• 从简单开始，无需重写即可扩展 —— 今天一个二进制文件；当你添加 ML 服务、多机器人协调或车队运营时，使用相同的契约和 RDL
• 清晰性优先于最大灵活性 —— 我们为那些最困难的问题是自主性、编排、部署和安全的团队进行优化——而非底层机器人研究

我们不试图服务每一个机器人。我们为那些提出以下问题的团队构建默认平台：“我们如何安全地决定机器人接下来应该做什么——并将其扩展到多个系统？”

完整的战略背景请参见 gorai-docs 仓库中的 Gorai 总体战略 (https://github.com/emergingrobotics/gorai-docs/tree/main/docs/overview/)。

先决条件

你需要 Go 1.25+ 来构建 gorai。仅此而已。

macOS:

brew install go  

Ubuntu/Debian:

sudo apt update && sudo apt install -y golang-go  

或从 https://go.dev/dl/ 下载最新版本。

NATS 内嵌在 gorai 二进制文件中——无需安装外部消息代理。

NATS 命令行工具（可选，用于调试）

NATS CLI 允许你订阅消息并调试你的机器人：

macOS:

brew install nats-io/nats-tools/nats  

Linux:

go install github.com/nats-io/natscli/nats@latest  

快速入门

1. 安装 Gorai 命令行工具

go install github.com/emergingrobotics/gorai/cmd/gorai@latest  

2. 从模板创建一个机器人项目

# 克隆模板（或在 GitHub 上点击“使用此模板”）  
git clone https://github.com/emergingrobotics/gorai-robot-template.git my-robot  
cd my-robot  

# 更新模块路径为你自己的  
go mod edit -module github.com/yourorg/my-robot  

3. 编辑 robot.json

模板包含一个 robot.json 骨架。根据需要添加组件：

{  
  "version": "2",  
  "robot": { "name": "my-robot", "description": "My first robot!" },  
  "nats": { "embedded": true, "url": "nats://localhost:4222" },  
  "dashboard": { "enabled": true, "listen": ":10101" },  
  "components": []  
}  

4. 验证并运行

make validate   # 检查配置  
make run        # 在开发模式下运行  

内置的 NATS 服务器会自动启动——无需单独的进程。

5. 构建并部署

# 为树莓派构建  
make build TARGET=linux/arm64  

# 部署  
make deploy DEPLOY_HOST=pi@raspberrypi  

使用外部 NATS 服务器

对于多机器人部署或共享代理，指向外部 NATS 服务器：

{  
  "nats": {  
    "url": "nats://nats-server.local:4222",  
    "external": true  
  }  
}  

当 external 为 true 或 URL 指向非本地地址时，gorai 会连接到外部服务器而不是启动自己的服务器。

硬件平台

不支持： Pi 3, Pi Zero

详细信息请参见 gorai-docs (https://github.com/emergingrobotics/gorai-docs/tree/main/docs/specifications/) 仓库中的硬件要求。

硬件访问模式

Gorai 支持两种访问硬件的模式。两者产生具有相同接口的组件——应用程序代码不知道也不关心使用了哪种模式。

协处理器（通过 GSP/2 的 RP2040）： 一个 RP2040 微控制器处理实时硬件 I/O（PWM、电机控制、编码器）。RPi 使用 Gorai 串行协议 v2 通过 USB 串行与其通信。最适合对时序要求严格的控制，将硬件与 Linux 调度器抖动隔离，以及对可靠性要求严格的应用（例如，自主潜水器——水下电机控制不能出错）。

原生 RPi 硬件（GPIO/I2C/SPI）： 从 Go 代码直接访问树莓派 GPIO 引脚、I2C 总线和 SPI 总线。最适合简单传感器、I2C 设备、原型制作以及不需要 RP2040 的成本敏感型构建。

两种模式可以同时使用——例如，RP2040 处理电机，而 Pi 直接读取 I2C 传感器。

命令行工具命令

核心命令

组件管理

网格命令（服务发现）

核心组件

核心仓库提供组件接口、远程代理（用于多机器人网格访问）和模拟对象（用于测试）。特定于硬件的实现位于外部 Go 模块中。

接口（在核心中）

arm, base, camera, gripper, input, link, motor, power, pwm, sensor, servo, space, stepper, thruster, valve

远程代理（在核心中）

camera/remote, gpio/remote, input/remote, motor/remote, pwm/remote, sensor/remote, servo/remote, space/remote, stepper/remote, thruster/remote

模拟对象（用于测试）

motor/fake, camera/fake, gpio/fake, input/fake, pwm/fake, sensor/fake, servo/fake, stepper/fake, thruster/fake