NATS.ioを中心に構築されたGoベースのロボティクスフレームワーク

Gorai

［画像：Goraiのロゴ］

AI時代のロボティクスプラットフォーム。

発音は「ゴライ」（「エイ」のように）

Goraiを選ぶ理由

ロボットは分散システムである。だから、そのように構築しよう。 「単一」のロボットでさえ、MCU、SBC、センサー、そして時にはベースステーションのネットワークです。Goraiはもはやその事実を無視しません。すべてのセンサーとアクチュエーターは、NATSメッシュ上のサービスであり、実行時に名前で発見され、手作業で配線されることはありません。信頼性の高いクラウドシステムを構築した規律――サービスディスカバリ、ロケーション透過性、ヘルスチェック、ファンアウト、リプレイ――は、まさに実際のロボットが必要とするものです。

配線ではなく、ケイパビリティ。 センサーはあなたが読み取るリソースであり、アクチュエーターはあなたが呼び出すツールです。メッシュ上のどのエージェントでも世界を認識し、それを変更できます。AIエージェントに提供されるケイパビリティモデルMCPは、MCPサーバーを介さずにネイティブにNATS上で配信されます。これをNCP（NATS Capability Protocol）と呼びます。

1台のロボットは複数のマシンになり得る。 ケイパビリティは場所ではなく名前でアドレス指定されるため、単一の論理ロボットは、実行時に構成され、プラットフォームが参加・離脱するにつれて優雅に劣化する、ローバー、ドローン、センサーマスト、コンピューティングボックスにまたがることができます。これが複合ロボットであり、それがすべてです。

リプレイなしの自律性は伝説にすぎない。 アクションログ、状態ストリーム、リプレイは、プラットフォームの第一級の関心事であり、アドオンではありません。AI実行は歓迎されますが、決して信頼されるわけではありません。安全性はエージェントではなく、ケイパビリティノードで強制されます。エージェント互換ではあるが、エージェント依存ではない――決定論的な状態機械とルールベースのプランナーが同じケイパビリティを駆動します。

ロボットをソフトウェアのように構築し、システムのように実行する。 主張が強く、実用的で、運用志向です。API、分散システム、デプロイメントで既に考えているなら、数日で生産的になれるでしょう。

北極星を読む：VISION.md。

---

完全なドキュメントはgorai-docsにあります。 戦略、アーキテクチャ、仕様、ハードウェア分析、20章の書籍、実装ガイド――すべて人間とAIエージェントの両方のためにインデックス化されています。AIエージェントをそのリポジトリに向け、CLAUDE.mdとINDEX.mdを通じて100以上のドキュメントを自動的にナビゲートさせます。

---

goraiとは何か（そして何ではないか）

Goraiプロジェクトには2つの異なるバイナリがあり、それらを混同しないことが重要です。

1. あなたのロボットバイナリ――Pi上で実行され、ロボットの仕事をするプログラム。これはあなた自身のGoモジュールです：gorai.Run()を呼び出すコンポーネントをインポートしないインポートするmain.goです。組み込みのNATSサーバー、メッシュ、およびすべてのコンポーネントは、この単一の静的バイナリにコンパイルされます。これは完全に自己完結しており、実行時にgoraiツールから何も必要としません――それをロボットにコピーして実行します。

2. gorai CLI――ワークステーションで実行する開発者およびオペレーターツールです。本番環境のロボットでは決して実行されません。kubectl + ビルドラッパー + パッケージヘルパーが1つのコマンドにまとめられたものと考えてください。

したがって、はい――ロボットプロジェクトをgo build .して結果をPiにscpすることは可能です。gorai CLIは、プレーンなgo buildではできない、そのバイナリの周りのタスクを実行することで、その価値を証明します。

最初の3つはGoツールチェーンに対する便利な機能です。メッシュコマンドは、go buildでは本当に再現できない部分です――それらは実行中のシステムを観測およびデバッグします。これは、ロボット（または複数）がライブになったらすぐに使用するものです。

このREADMEの残りの部分では、CLIのインストール方法、ロボットの定義方法、およびビルド方法を説明します。

---

1時間以内にロボットを構築できます。JSONを書き、バイナリを取得し、Linuxホスト（Raspberry Pi/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なし。外部サービスなし――Raspberry Pi 5またはOrange Pi 5上の単一バイナリのみです。これはシンプルなケースであり、上限ではありません。複数のバイナリを共有NATSバス（またはリーフノード）に向け、メッシュが複数のプラットフォームを1つの論理ロボットに結び付けます――同じコードで、書き直しなしです。

---

Goraiで動作するハードウェア

Goraiは、海洋、地表、水中、陸上ドメインのプロシューマーがアクセス可能なフィールドロボットを対象としています――自律型潜水艇、自律型水上艇、陸上ロボットなどです。例えば、自律型潜水艇は、圧力ハウジング内のLinuxホスト（Raspberry Pi/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パッケージです。init()関数を持つパッケージを作成し、registry.RegisterComponent()を呼び出します。main.goにインポートしないインポートを追加すると、他のすべてと一緒にバイナリにコンパイルされます。

コンポーネントの共有

コンポーネントを共有するということは、Goモジュールを公開することです。パッケージを独自のレポジトリに抽出し、GitHubにプッシュすれば、誰でもgorai component addで追加できます。レジストリサーバーなし、パッケージ承認プロセスなし――標準的なGoモジュールホスティングです。

なぜこれが重要か

これは、プラットフォーム言語としてGoを選択する際の重要な利点です。単一バイナリの話は、コンポーネントエコシステムにまで及びます。実行時の依存関係解決なし、DLL地獄なし、デプロイ時のバージョン競合なし。すべての依存関係は、Goツールチェーンによってビルド時に解決され、結果としてロボットにコピーする単一の静的バイナリが生成されます。

非Goコンポーネント（Pythonのビジョンパイプライン、C++のSLAM）は、NATS経由で通信する外部サービスとして実行されます。バイナリにはコンパイルされません。これはフェーズ2の複雑さです。

完全な設計については、docs/package-dev-approach.mdを参照してください。

---

Goraiは誰のためか？

Goraiを使用するのは、以下のような場合です。

• 真の自律性（教育用おもちゃやシミュレーションではない）を求めている
• アプローチしやすいソフトウェア（数日で生産的になれる、数ヶ月ではない）を必要としている
• 最新のツール（AI支援コーディング、シンプルなデプロイメント）を重視している
• プロシューマーロボット（海洋モニタリング、陸上車両、研究プラットフォーム）を構築している
• ソフトウェアファーストのチームで、AI/MLに物理的な具現化を追加したり、1台のロボットからフリートにスケールアップしたりしている
• 低レベルのキネマティクスやミドルウェアの内部よりも、動作、協調、運用をより重視している

ROS 2を使用するのは、以下のような場合です。

• エンタープライズ/研究ロボティクス（倉庫自動化、自律走行車）で作業している
• 完全なROSエコシステム（数千のパッケージ、シミュレーション、SLAMライブラリ）を必要としている
• ROS 2が標準である学術界にいる
• 深いハードウェアまたは制御アーキテクチャの実験が必要である（ROS 2が適切なプラットフォームです）

私たちはROS 2を置き換えるのではなく、異なる市場をターゲットにしています。次世代の自律システムのためのAIファースト設計で、「プロシューマー向けのROS 2」と考えてください。

---

将来のロボット市場（そしてGoraiがそれをどう扱うか）

ロボット工学は変化しています。なぜなら、意思決定がスタックの上位に移動しているからです。自律性はもはや手書きのロジックだけではありません。知覚、計画、タスク選択は、ますます学習され、確率的になり、エージェント的になっています。その変化――物理的なAI――は、プラットフォームが提供しなければならないものを変えます。

将来の市場とは：

• 物理的なAI――動作、自律性、協調がモーター制御やキネマティクスよりも複雑なシステム
• ソフトウェアファーストのチーム――ロボット工学インフラストラクチャの専門家になることなく、ロボットやフリートを出荷する必要があるエンジニアやAI/ML実践者
• スペクトラムとしての自律性――スクリプト化された動作や状態機械から、学習された知覚やエージェント的プランナーまで、すべてが同じ運用サーフェスを必要とします

Goraiがそれを実現するために構築されている理由：

• 設計によるAIファースト――AI駆動の実行を第一級の前提として扱います。ツールのためのケイパビリティサーフェス、実行時のガバナンスと安全性、監査可能性/リプレイをベースラインとして、アドオンとしてではなく。
• シンプルに開始し、書き直しなしでスケールアップ――今日は単一バイナリ。MLサービス、マルチロボット協調、またはフリート運用を追加しても、同じ契約とRDLを使用します。
• 最大の柔軟性よりも明確さ――自律性、オーケストレーション、デプロイメント、安全性が最も難しい問題であるチームのために最適化します――低レベルのロボット工学研究ではありません。

私たちはすべてのロボットを対象としているわけではありません。私たちは、「ロボットが次に何をすべきかを安全に決定する方法――そしてそれをシステム全体にスケールさせる方法」と問うチームのためのデフォルトプラットフォームを構築しています。

完全な戦略的コンテキストについては、gorai-docsリポジトリのGorai Overarching Strategyを参照してください。

---

前提条件

GoraiをビルドするにはGo 1.25+が必要です。それだけです。

macOS:

brew install go

Ubuntu/Debian:

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

または、最新バージョンをhttps://go.dev/dl/からダウンロードします。

NATSはgoraiバイナリに組み込まれています――インストールする外部メッセージブローカーはありません。

NATS CLI（オプション、デバッグ用）

NATS CLIを使用すると、メッセージを購読したり、ロボットをデバッグしたりできます。

macOS:

brew install nats-io/nats-tools/nats

Linux:

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

---

クイックスタート

1. Gorai CLIのインストール

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

2. テンプレートからロボットプロジェクトを作成する

# テンプレートをクローンする（またはGitHubで「Use this template」をクリック）
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. ビルドしてデプロイする

# Raspberry Pi用にビルド
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リポジトリのハードウェア要件を参照してください。

ハードウェアアクセスパターン

Goraiは、ハードウェアにアクセスするための2つのパターンをサポートしています。どちらも同じインターフェースを持つコンポーネントを生成します――アプリケーションコードはどちらが使用されているかを知ることも気にかけることもありません。

コプロセッサ（GSP/2経由のRP2040）： RP2040マイクロコントローラーがリアルタイムハードウェアI/O（PWM、モーター制御、エンコーダー）を処理します。RPiはGoraiシリアルプロトコルv2を使用してUSBシリアル経由で通信します。タイミングクリティカルな制御、ハードウェアをLinuxスケジューラージッターから分離すること、および信頼性クリティカルなアプリケーション（例：自律型潜水艇――水中でのモーター制御のグリッチは許されない）に最適です。

ネイティブRPiハードウェア（GPIO/I2C/SPI）： GoコードからRaspberry PiのGPIOピン、I2Cバス、SPIバスに直接アクセスします。シンプルなセンサー、I2Cデバイス、プロトタイピング、RP2040が不要なコスト重視のビルドに最適です。

両方のパターンを同時に使用できます――例えば、RP2040がモーターを処理し、PiがI2Cセンサーに直接読み取るなどです。

---

CLIコマンド

コアコマンド

コンポーネント管理

メッシュコマンド（サービスディスカバリ）

---

コアコンポーネント

コアリポジトリは、コンポーネントインターフェース、リモートプロキシ（マルチロボットメッシュアクセス用）、およびフェイク（テスト用）を提供します。ハードウェア固有の実装は、外部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/encoder/remote

フェイク（コア内、テスト用）

camera/fake、motor/fake、pwm/fake、servo/fake

外部コンポーネント（別Goモジュール）

ハードウェア固有の実装は、gorai component addでインストールされます。

• gorai-picarx -- SunFounder PiCar-Xロボットキット
• gorai-driver-hcsr04 -- HC-SR04超音波距離センサー
• コンポーネントレジストリにもっとあります

---

アーキテクチャ

Goraiは、すべてのコンポーネントが組み込みNATSサーバーを介して通信するメッセージベースのアーキテクチャを使用します。

┌──────────────────────────────────────────────────────┐
│                  あなたのロボットバイナリ                    │
│                                                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐                │
│  │  GPS    │ │ Motor   │ │ Sensor  │    ...          │
│  │コンポーネント│ │コンポーネント│ │コンポーネント│                 │
│  └────┬────┘ └────┬────┘ └────┬────┘                 │
│       │           │           │                      │
│       └───────────┴─────┬─────┘                      │
│                         │                            │
│                   ┌─────▼─────┐                      │
│                   │  メッセージ  │                      │
│                   │   ルーター  │                      │
│                   └─────┬─────┘                      │
│                         │ NATSプロトコル              │
│                   ┌─────▼─────┐                      │
│                   │ 組み込み  │                      │
│                   │   NATS    │  （JetStream有効） │
│                   └───────────┘                      │
└──────────────────────────────────────────────────────┘

主要原則：

• 組み込みNATSを持つ単一バイナリ――外部サービスは不要
• 各コンポーネントは独自のゴルーチンで実行される
• 内部制御はGoチャネルを使用
• コンポーネント間の通信はNATSのみを使用
• コンポーネント間に共有メモリはない
• メッセージベースのアーキテクチャによりリモートデバッグが可能
• 外部NATSはマルチロボットまたは共有ブローカーデプロイメントでサポートされる

---

例

---

サービスディスカバリ（メッシュ）

Goraiには、独立したプロセス間での実行時ディスカバリのための組み込みサービスメッシュが含まれています。これにより、以下が可能になります。

• クロスバイナリディスカバリ――一緒にコンパイルされていないモジュールでも互いを見つけることができます
• チャネルレジストリ――利用可能なNATSサブジェクトとそのスキーマを発見する
• ヘルスモニタリング――古いサービスのための自動TTLベースの有効期限切れ
• スキーマドキュメント――メッセージタイプのJSONスキーマ定義

アーキテクチャ

┌─────────────────────────────────────────────────────────────────────────┐
│                         NATS JetStream KV                                │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │  gorai-services (TTL: 30s)     → アクティブなサービス登録   │    │
│  │  gorai-channels (永続的)      → チャネル/サブジェクト記述子    │    │
│  │  gorai-schemas  (永続的)      → メッセージスキーマ（JSONスキーマ） │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

クイック例

// サービスを登録する
client, _ := mesh.NewClient(natsConn)
reg, _ := client.Register(ctx, mesh.ServiceDescriptor{
    Name:    "motor-controller",
    Type:    mesh.TypeComponent,
    Subtype: "motor",
    RobotID: "robot-alpha",
})
defer reg.Deregister()

// 他のサービスを発見する
motors, _ := client.FindServices(ctx, mesh.Query{Subtype: "motor"})

CLIディスカバリ

# 実行中のすべてのサービスを一覧表示する
gorai mesh services

# リアルタイムでの変更を監視する
gorai mesh watch

# 利用可能なチャネルを一覧表示する
gorai mesh channels robot-alpha

完全なドキュメントについては、gorai-docsリポジトリのメッシュサービスディスカバリ仕様を参照してください。

---

動的ディスカバリ

Goraiはハイブリッド静的/動的設定をサポートします。RDLで構造を定義し、実行時にハードウェアを発見します。

問題

従来の方式では、すべてのデバイスを設定に宣言する必要があります。

{
  "components": [
    {"name": "motor1", "type": "motor/pwm", "config": {"pin": 18}},
    {"name": "motor2", "type": "motor/pwm", "config": {"pin": 19}}
  ]
}

接続されるデバイスがわからない場合はどうなりますか？ デバイスがホットプラグされた場合はどうなりますか？

解決策

個々のデバイスではなく、ディスカウルールを定義します。

{
  "gateways": [
    {
      "name": "usb-gateway",
      "type": "gateway/gsp",
      "config": {
        "discovery": {"enabled": true, "patterns": ["/dev/ttyACM*"]}
      }
    }
  ],

  "discovery": {
    "enabled": true,
    "auto_adopt": true,
    "rules": [
      {"match": {"capability": "PWM"}, "adopt_as": {"type": "motor"}},
      {"match": {"capability": "IMU"}, "adopt_as": {"type": "sensor", "subtype": "imu"}}
    ]
  },

  "services": [
    {
      "name": "patrol",
      "type": "behavior/patrol",
      "depends_on": ["@discovered:motor/*", "@discovered:sensor/imu/*"]
    }
  ]
}

何が起こるか：

1. ゲートウェイがUSB経由でPicoをPWM+IMUケイパビリティとともに発見します。
2. （ルールを通じて）モーターとIMUセンサーとして自動的に採用されます。
3. パトロールサービスの@discovered:依存関係が解決されます。
4. ロボットは発見されたハードウェアでパトロールを開始します。

完全なドキュメントについては、gorai-docsリポジトリの動的ディスカバリ仕様を参照してください。

---

なぜGoraiか？

クラウドネイティブパターン

言語戦略

• Goコア――NATSオーケストレーション、設定、Webダッシュボード
• Pythonサービス――ビジョン（OpenCV）、ML推論（PyTorch）――将来
• C++サービス――SLAM（Cartographer）、点群処理――将来

NATSは40以上の言語でクライアントを提供しています。各ジョブに最適なツールを使用してください。

---

プロジェクトステータス

バージョン： 0.1.0（初期開発）

現在のフェーズ：単一バイナリデプロイメント

現在の焦点は、ゼロ依存関係の単一バイナリデプロイメントモデルです。

• 組み込みNATSサーバーを持つ単一のGoバイナリ
• 外部サービスは不要――すべてが1つのプロセスに収まる
• コンテナなし、K8sなし
• systemdを使用してRaspberry Pi上で直接実行
• イベントソーシングとメッシュディスカバリのためにデフォルトでJetStreamが有効

コンポーネントエコシステム（Caddyモデル）

GoRAIは、コンポーネント配布にCaddyモデルを使用します。各ハードウェアドライバーはスタンドアロンのGoモジュールです。ユーザーのロボットプロジェクトには、GoRAIコアと必要な各コンポーネントのインポートしないインポートをインポートするmain.goがあります。go buildは、それらのコンポーネントのみがコンパイルされた単一バイナリを生成します。詳細についてはREQUIREMENTS.mdを参照してください。

将来のロードマップ

• 非Goサービス――Python/C++サービス（ビジョン、SLAM）は、コンパイル済みコンポーネントではなく、外部プロセスとしてNATS経由で通信します。
• フリート管理――マルチロボット協調（将来のフェーズ）
• ROS 2ブリッジ――ROS 2エコシステムとの相互運用（将来のフェーズ）

---

ドキュメント

すべてのドキュメントはgorai-docsリポジトリに移動しました。これには以下が含まれます。

• はじめに――ハードウェア要件、ロボット定義言語（RDL）設定
• アーキテクチャと設計――戦略、ビジョン分析、設計比較、メッシュサービスディスカバリ、動的ディスカバリ
• AIアシスタント/LLM向け――CLAUDE.md（このリポジトリ内）、gorai-docs INDEX.md
• 将来の状態――ロードマップ、コンポーネントエコシステム計画

---

貢献

GoraiはClaude Codeで構築されています。私たちはAI支援開発が未来であると信じています――プロジェクトは人間とAIの両方が効果的に推論できるように整理されています。

人間向け

• 貢献者ガイドラインについてはCLAUDE.mdを参照してください。
• コード構成とパッケージの場所については、gorai-docsリポジトリを参照してください。

AIアシスタント向け

• gorai-docsリポジトリのLLM設計ガイドを参照してください――コードベース全体を読まずに新しいコンポーネントやサービスを設計するために必要なすべてです。

---

ライセンス

Apache 2.0