EmbodiedJev

# 🤖 EmbodiedJev · 行知

### 把具身 AI 实验，搬到你的浏览器里。

**📦 开箱体验三大仿真任务 · 🧠 本地小模型 / 云端 API · 🎮 看得见的每一步决策**

无需机械臂，无需先训练模型。跟着步骤启动，在自己的电脑上体验「观察 → 决策 → 执行 → 反馈」。

[](https://github.com/FBddcz/embodied-jev/actions)
[](https://github.com/FBddcz/embodied-jev/stargazers)
[](LICENSE)
[](https://www.python.org/)
[](https://mujoco.org/)

[🚀 快速上手](#-零机器人基础快速上手) · [🧠 接入模型](#-给机械臂接上模型) · [📊 实测结果](#-有结果也有边界) · [🤝 一起维护](#-一起把行知做得更好)



**行而有据，知而能行。**

如果这个项目帮你迈出了具身 AI 的第一步，欢迎点一颗 **⭐ Star**，让更多人一起玩、一起改！

</div>

## ✨ 打开行知，你能做什么？

- 📦 **先玩起来，再接模型**：内置规则基线，无需 API Key、GPU 或模型权重，即可运行三个任务。首次安装依赖需要联网。
- 🦾 **真实物理交互**：MuJoCo + Franka Panda，夹爪接触、抓取、搬运和放置都有物理反馈。
- 🧠 **模型入口放在界面里**：可接 TypeSafe Jev、Claude 原生 API、OpenAI 兼容 API，以及本地 MiniCPM5-2B。
- 👀 **决策过程看得见**：查看阶段或短步选择、公开的动作说明、调用次数与延迟；有原生候选概率的接口还会显示概率。
- 🧭 **逐步规划也能试**：模型逐轮选择 XYZ 方向、步长和夹爪动作，执行后重新观测；可用原始图像输入并加入中途扰动。
- 📷 **相机自由组合**：仅外部、仅腕部、双相机或无相机；启用的视角按动作边界更新，腕部相机随手移动。
- 🆚 **同一任务，不同模型**：可选 2–3 路独立实验，统一任务和种子，真实运行后按仿真时间对齐回放。
- 🧩 **按自己的想法扩展**：多套具名模型接口、任务/场景预设、JSON 导入导出与独立输入测试，方便二次开发。
- 🧪 **执行前先预演**：在仿真副本里检查候选动作，拦截已配置的碰撞和抓取丢失情况。
- ⏯️ **实验随手控制**：运行、暂停、单步、停止、重置、轨迹回放、JSON 导出，一站完成。
- 💻 **本地工作台**：浏览器交互，桌面与手机尺寸均有适配；数据由本机服务处理，调用云端模型时发送任务状态，直接图像模式还发送已启用相机的 RGB。

## 🎯 三个任务，感受完整闭环

| 任务 | 你会看到什么 |
| --- | --- |
| 📥 搬运入盘 | 抓住红色方块，搬到蓝色托盘，松爪并撤离 |
| 🧱 方块堆叠 | 将红色方块放在固定蓝色方块上，检查支撑与稳定状态 |
| 🚧 越障搬运 | 抬高物体、越过障碍，再放到目标位置 |

抓取依靠双侧夹爪接触，成功由物理状态判定。页面中的“验证通过”对应实际仿真检查。

## 🧭 方法论：模型做选择，物理验证结果

每次动作之后重新观察，再决定下一步。模型负责当前选择；控制器负责动作转换与执行，成功由独立的物理条件判定。

```mermaid
flowchart LR
    A[任务与当前观测] --> B[模型决策]
    B --> C[动作转换与安全检查]
    C --> D[MuJoCo 执行]
    D --> A
    D --> E[独立评估与轨迹记录]
```

| 控制模式 | 模型输入 | 模型输出 |
| --- | --- | --- |
| 预设技能 | 结构化状态或 RGB-D 检测坐标、可用技能 | 阶段与技能选择 |
| 逐步 XYZ | 状态、RGB-D 检测坐标，或已启用相机的 RGB | 一个 XYZ／夹爪短步候选 |
| 分层 XYZ | 状态或 RGB-D 检测坐标、接触事实、近期动作 | 子目标，再分别选择