# Embit 技术文档

## 1. 概述

Embit（桂枢）是基于 MoonBit 的通用具身智能机器人全栈开发框架，打通「动力学仿真—多模态感知—VLA推理—运动控制—真机部署」完整技术链路。

本技术文档面向开发者与维护者，详细说明 Embit 的技术架构、模块设计、接口规范与部署方式。Embit 采用分层解耦设计，底层支撑为 MoonBit Native 运行时，上层依次覆盖通信层、推理层、控制层与应用层，确保各模块可独立开发、测试与替换。

## 2. 技术栈

| 技术 | 版本要求 | 用途 |
|------|----------|------|
| MoonBit 工具链 | >= 0.1.20260807 | 主开发语言，提供静态编译、内存安全、结构化并发 |
| Ignition Gazebo Fortress / Harmonic | 最新稳定版 | 动力学仿真引擎，提供物理仿真与传感器模拟 |
| Ignition Transport | 最新稳定版 | 机器人中间件通信协议（话题发布/订阅、服务调用） |
| ggml / vla.cpp | 最新稳定版 | VLA 多模态推理后端，支持 INT4~FP16 量化 |
| CUDA 兼容 GPU | （可选） | 大模型推理 GPU 加速 |
| Selene | 最新稳定版 | 可视化监控引擎，支持实时状态观测与数据回放 |
| Git / GitHub | — | 版本控制与开源协作 |

**选型理由**：

- **MoonBit**：国产新一代系统编程语言，具备静态编译、内存安全、结构化并发等特性，天然适合机器人高实时控制场景，填补 Python 在实时性上的不足。
- **Ignition Gazebo**：开源机器人仿真引擎，支持多物理引擎后端，与 ROS 2/ROS 1 生态兼容，是行业主流仿真方案。
- **ggml/vla.cpp**：轻量级推理引擎，支持多种 LLM/VLA 模型格式，CPU/GPU 跨平台调度能力成熟。
- **Selene**：MoonBit 生态可视化监控工具，与 MoonBit 原生类型系统良好集成。

## 3. 系统架构

```
┌──────────────────────────────────────────────────────┐
│  应用层  embit-examples                              │
│  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐ │
│  │ 人形行走Demo │ │ 四足避障Demo │ │ 机械臂抓取Demo │ │
│  └─────────────┘ └─────────────┘ └───────────────┘ │
├──────────────────────────────────────────────────────┤
│  控制层  embit-control                               │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────┐  │
│  │ 传感器抽象层  │ │ 运动学解算层  │ │ 安全联锁层  │  │
│  └──────────────┘ └──────────────┘ └─────────────┘  │
├──────────────────────────────────────────────────────┤
│  推理层  embit-ggml                                  │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────┐  │
│  │  模型管理     │ │  张量处理     │ │ 多硬件调度   │  │
│  └──────────────┘ └──────────────┘ └─────────────┘  │
├──────────────────────────────────────────────────────┤
│  通信层  embit-gazebo                                │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────┐  │
│  │ 话题发布订阅  │ │  仿真控制     │ │ 数据传输    │  │
│  └──────────────┘ └──────────────┘ └─────────────┘  │
├──────────────────────────────────────────────────────┤
│  底座层                                              │
│  ┌──────────────────┐  ┌─────────────────────────┐  │
│  │  Ignition Gazebo │  │  ARM / RISC-V 真机硬件   │  │
│  │     仿真引擎      │  │                           │  │
│  └──────────────────┘  └─────────────────────────┘  │
└──────────────────────────────────────────────────────┘
              底层支撑：MoonBit Native 运行时
```

**模块职责说明**：

| 层级 | 模块 | 职责 |
|------|------|------|
| 应用层 | embit-examples | 提供典型任务 Demo，演示框架端到端使用流程 |
| 控制层 | embit-control | 实现传感器数据抽象、运动学正向/逆解算、安全联锁保护 |
| 推理层 | embit-ggml | 加载 VLA 模型、执行多模态推理、管理张量生命周期、调度 CPU/GPU 算力 |
| 通信层 | embit-gazebo | 封装 Ignition Transport，实现仿真环境内话题通信与命令下发 |
| 底座层 | （外部依赖） | Ignition Gazebo 提供仿真物理引擎；真机硬件提供执行器与传感器输入 |

## 4. 核心模块设计

### 4.1 embit-core（核心基础库）

**职责**：定义所有上层模块共同依赖的基础类型、抽象接口与工具函数。

**关键接口设计（伪代码）**：

```moonbit
// 机器人关节状态
struct JointState {
  name: String
  position: f64
  velocity: f64
  effort: f64
}

// 传感器观测
enum SensorType { Camera, Lidar, Imu, JointState }
struct SensorReading {
  kind: SensorType
  timestamp: f64
  data: Vec<u8>
}

// 动作指令
struct ActionCommand {
  joint_commands: List<(String, f64)>
  timestamp: f64
}

// 机器人抽象接口（所有机型需实现）
trait Robot {
  fn get_sensor_readings() -> List<SensorReading>
  fn execute_actions(commands: List<ActionCommand>) -> Result<(), RobotError>
  fn get_model_info() -> RobotModelInfo
}
```

**依赖**：无外部依赖，仅依赖 MoonBit 标准库。

### 4.2 embit-gazebo（仿真通信SDK）

**职责**：封装 Ignition Transport C API，提供 MoonBit 原生话题发布/订阅、服务调用接口。

**关键接口设计（伪代码）**：

```moonbit
// 连接仿真环境
struct GazeboClient {
  conn: IgnitionTransportHandle
}

impl GazeboClient {
  fn connect(address: String) -> Result<GazeboClient, ConnectError>
  fn subscribe[T](topic: String, handler: Fn(T) -> ()) -> Result<Subscription, SubscribeError>
  fn publish[T](topic: String, msg: T) -> Result<(), PublishError>
  fn call_service[T, U](service: String, req: T) -> Result<U, ServiceError>
}
```

**依赖**：embit-core、Ignition Transport C 库（通过 FFI 调用）。

### 4.3 embit-ggml（全尺度VLA推理SDK）

**职责**：封装 ggml/vla.cpp，提供统一的多模态推理接口，支持从端侧 1B 模型到工作站 70B+ 模型的调度。

**关键接口设计（伪代码）**：

```moonbit
// VLA 模型加载与推理
struct VlaModel {
  ctx: GgmlContext
  model_path: String
}

impl VlaModel {
  fn load(path: String) -> Result<VlaModel, LoadError>
  // 多模态推理：图像 + 语言指令 → 动作序列
  fn infer(image: ImageData, instruction: String) -> Result<List<ActionCommand>, InferError>
  fn supported_backends() -> List<Backend>  // CPU / CUDA / Metal
  fn set_backend(backend: Backend) -> Result<(), BackendError>
}

enum Backend { Cpu, Cuda, Metal }
```

**依赖**：embit-core、ggml/vla.cpp C 库（通过 FFI 调用）。

### 4.4 embit-control（运动控制框架）

**职责**：实现通用机器人抽象层、运动学解算、传感器融合与安全防护。

**关键接口设计（伪代码）**：

```moonbit
// 机器人模型描述
struct RobotModel {
  urdf_path: String
  joints: List<JointSpec>
  sensors: List<SensorSpec>
  limits: SafetyLimits
}

struct SafetyLimits {
  max_joint_velocity: f64
  max_joint_effort: f64
  collision_check_distance: f64
}

// 运动控制器
struct MotionController {
  model: RobotModel
  state_estimator: StateEstimator
}

impl MotionController {
  fn new(model: RobotModel) -> MotionController
  fn compute_trajectory(
    start: List<(String, f64)>,
    goal: List<(String, f64)>,
    constraints: TrajectoryConstraints
  ) -> Result<Trajectory, PlanError>
  fn execute_trajectory(
    traj: Trajectory,
    robot: &dyn Robot
  ) -> Result<(), ControlError>
}
```

**依赖**：embit-core、embit-gazebo（仿真模式）。

### 4.5 embit-view（可视化调试面板）

**职责**：基于 Selene 引擎提供实时监控面板，支持机器人状态可视化、数据回放与参数在线调优。

**关键接口设计（伪代码）**：

```moonbit
// 监控面板
struct ViewPanel {
  selene_ctx: SeleneContext
  widgets: List<Widget>
}

impl ViewPanel {
  fn new() -> ViewPanel
  fn add_widget(&mut self, widget: Widget)
  fn render(robot_state: RobotState) -> Result<(), RenderError>
  fn record(session_id: String) -> RecordingHandle
  fn playback(handle: RecordingHandle) -> Result<PlaybackStream, PlaybackError>
}
```

**依赖**：embit-core、Selene 可视化引擎。

### 4.6 embit-examples（示例工程集）

**职责**：提供三类典型具身任务 Demo，展示框架端到端使用方式。

**示例清单**：

| 示例名 | 描述 | 涉及模块 |
|--------|------|----------|
| humanoid_walk | 人形机器人行走任务 Demo | embit-gazebo + embit-control + embit-ggml |
| quadruped_avoid | 四足机器人避障任务 Demo | embit-gazebo + embit-control + embit-ggml |
| arm_grasp | 机械臂抓取任务 Demo | embit-gazebo + embit-control + embit-ggml |

## 5. 数据模型

### 5.1 核心实体表

| 实体名 | 字段 | 类型 | 说明 |
|--------|------|------|------|
| JointState | name | String | 关节名称 |
| | position | f64 | 关节角度（rad） |
| | velocity | f64 | 关节角速度（rad/s） |
| | effort | f64 | 关节力矩（Nm） |
| SensorReading | kind | SensorType | 传感器类型枚举 |
| | timestamp | f64 | 采集时间戳（秒） |
| | data | Vec<u8> | 原始数据字节流 |
| ActionCommand | joint_commands | List<(String, f64)> | 目标关节位置映射 |
| | timestamp | f64 | 指令时间戳 |
| RobotModel | urdf_path | String | URDF 模型文件路径 |
| | joints | List<JointSpec> | 关节规格列表 |
| | sensors | List<SensorSpec> | 传感器规格列表 |
| | limits | SafetyLimits | 安全约束参数 |
| VlaModel | model_path | String | 模型文件路径（.gguf） |
| | backend | Backend | 当前推理后端 |
| | context_size | usize | 上下文窗口大小 |

## 6. 接口设计

### 6.1 对外 API 列表

Embit 目前为研发框架，尚未发布对外 REST/gRPC API。所有接口通过 MoonBit 包导入方式调用，详见各模块设计（第 4 节）。

| 模块 | 主要导出接口 | 说明 |
|------|------------|------|
| embit-core | `Robot` trait、`JointState`、`SensorReading`、`ActionCommand` | 基础类型与抽象接口 |
| embit-gazebo | `GazeboClient::connect`、`subscribe`、`publish`、`call_service` | 仿真通信接口 |
| embit-ggml | `VlaModel::load`、`infer`、`set_backend` | VLA 推理接口 |
| embit-control | `MotionController::new`、`compute_trajectory`、`execute_trajectory` | 运动控制接口 |
| embit-view | `ViewPanel::new`、`add_widget`、`render`、`record`、`playback` | 可视化接口 |
| embit-examples | 各 Demo `main()` 函数 | 示例入口 |

### 6.2 FFI 接口契约

所有 C/C++ FFI 绑定遵循以下契约：

- 错误通过 `Result<T, Error>` 返回，不在 FFI 层抛异常
- 资源句柄（如 `IgnitionTransportHandle`）通过 `new`/`drop` 成对管理
- 字符串采用 `&[u8]` 零拷贝传递，避免重复分配

## 7. 部署与运行

### 7.1 环境要求

- **操作系统**：Linux（Ubuntu 22.04+ 推荐）、macOS（Apple Silicon 支持 Metal）
- **MoonBit 工具链**：>= 0.1.20260807（安装详见 https://www.moonbitlang.com/）
- **Ignition Gazebo**：Fortress 或 Harmonic 版本
- **CMake**：>= 3.20（用于编译 FFI 绑定）
- **（可选）CUDA**：>= 11.8，用于 GPU 推理加速
- **（可选）Git LFS**：用于下载 VLA 模型文件

### 7.2 安装步骤

```bash
# 1. 克隆仓库
git clone https://github.com/toadium/embit.git
cd embit

# 2. 添加核心依赖到你的 MoonBit 项目
moon add walkzzz/embit/embit-core
moon add walkzzz/embit/embit-gazebo
moon add walkzzz/embit/embit-ggml
moon add walkzzz/embit/embit-control
moon add walkzzz/embit/embit-view

# 3. 编译（Native 目标）
moon build --target native
```

### 7.3 配置说明

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| Gazebo 地址 | `EMBIT_GAZEBO_ADDR` | `localhost:9000` | Ignition Transport 连接地址 |
| VLA 后端 | `EMBIT_VLA_BACKEND` | `cpu` | 推理后端：`cpu` / `cuda` / `metal` |
| 模型路径 | `EMBIT_MODEL_PATH` | — | VLA 模型文件路径（.gguf） |
| 日志级别 | `EMBIT_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |

### 7.4 最小运行示例

```moonbit
fn main() {
  // 1. 连接仿真环境
  let robot = GazeboRobot::connect("t800")?
  // 2. 加载VLA行动模型
  let model = VlaModel::load("models/smolvla-7b-q4.gguf")?
  // 3. 获取视觉观测 + 语言指令
  let image = robot.get_camera_image()
  let command = "走到桌子旁边拿起水杯"
  // 4. 推理生成动作序列并执行
  let actions = model.infer(image, command)
  robot.execute_actions(actions)
}
```

## 8. 安全与性能

### 8.1 安全措施

- **内存安全**：MoonBit 编译期内存安全保证，杜绝空指针、数据竞争、缓冲区溢出等常见漏洞
- **FFI 安全层**：所有 C API 调用封装在类型安全的 MoonBit 接口内，拒绝裸指针暴露
- **安全联锁**：embit-control 内置关节速度/力矩上限检查，超出阈值立即中止执行
- **启动安全检查**：框架启动时校验 URDF 模型完整性与参数合理性

### 8.2 性能目标

| 指标 | 目标值 | 测量条件 |
|------|--------|----------|
| 控制环路延迟 | < 1ms（CPU） | 双足机器人，6 DoF 关节控制 |
| VLA 推理延迟 | < 200ms（7B 模型，CPU） | smolvla-7b-q4，1080p 输入 |
| VLA 推理延迟 | < 50ms（7B 模型，GPU） | smolvla-7b-q4，CUDA 加速 |
| Sim2Real 切换时间 | < 5min | 同一 URDF 模型，仿真→真机 |
| 内存占用（推理） | < 4GB（7B INT4） | 7B 模型 INT4 量化，CPU |

## 9. 开发计划

与项目申报书实施计划保持一致（共 6 个月）：

| 阶段 | 时间 | 技术任务 | 交付物 |
|------|------|----------|--------|
| Phase 1：核心能力验证 | 第1个月 | Ignition Transport FFI 绑定；ggml 推理 FFI 绑定；最简控制 Demo | 核心 FFI 绑定原型、控制 Demo |
| Phase 2：SDK与框架开发 | 第2-3个月 | embit-gazebo v1.0；embit-ggml v1.0；embit-control v1.0；embit-view 内测版 | 四个 SDK 稳定版本 |
| Phase 3：系统整合与多机型适配 | 第4个月 | 框架联调；人形/四足/机械臂 URDF 适配；文档初稿 | 整合版框架、三类机型 Demo |
| Phase 4：场景Demo与性能优化 | 第5个月 | 三类任务完整 Demo；性能调优；基准测试 | 性能基准报告、完整 Demo 集 |
| Phase 5：开源发布与生态建设 | 第6个月 | v1.0 正式版；文档完善；社区搭建 | embit v1.0 正式版 |