chenlin
3ad29356c9
集成通用机器人数值接口、本机控制桥、LeRobot 插件和统一键盘遥操作。采用离线 CoACD 全臂碰撞配方 revision 4、局部装配区切分与结构自接触，限制直接关节位姿写入并保留安全看门狗。同步版本号、变更记录、来源许可证和兼容性验证。
54 lines
3.6 KiB
Markdown
54 lines
3.6 KiB
Markdown
# 前端架构
|
|
|
|
`src/` 采用“应用壳 + 业务域 + 共享基础设施”的组织方式。
|
|
|
|
## 目录职责
|
|
|
|
```text
|
|
src/
|
|
├── app/ 应用入口、跨域编排、工作区壳和全局反馈
|
|
├── components/ui/ 无业务依赖的共享 UI 基础组件
|
|
├── controller/ Python 控制器运行时、类型和面板
|
|
├── map/ 地图加载、生成、编辑和面板
|
|
├── project/ 工程导入、转换、文件树和工作区
|
|
├── rl/ ONNX 策略运行时、任务绑定、类型和面板
|
|
├── robot/ 通用机器人契约、profile、实时协议与外部控制面板
|
|
├── simulation/ MuJoCo 会话、物理适配器和仿真控制组件
|
|
├── telemetry/ 数据源抽象、记录器、导出和数据面板
|
|
├── training/ 本地训练/调参客户端、类型、共享连接和面板
|
|
├── tuning/ 独立 tuning.html 的 Agent dashboard 与 scalar 图表
|
|
├── viewer/ Three.js 场景、渲染和交互
|
|
├── stores/ 跨域应用状态
|
|
└── test/ 全局测试初始化
|
|
```
|
|
|
|
## 依赖规则
|
|
|
|
1. `components/ui` 不依赖任何业务域。
|
|
2. 业务组件、类型和测试与所属业务域共置。
|
|
3. `app` 负责组合业务域，不承载可复用的业务算法或运行时。
|
|
4. `simulation` 不依赖 React 应用状态；遥测通过 `TelemetrySource` 接口读取仿真数据。
|
|
5. 业务域之间通过显式类型和门面交互，避免从其他域读取内部状态。
|
|
6. 新文件优先放入已有业务域；只有跨域复用且不含业务语义的组件才进入 `components/ui`。
|
|
|
|
## 主要运行链路
|
|
|
|
```text
|
|
项目文件 → project → PhysicsAdapter → SimulationSession → MuJoCo WASM
|
|
├→ controller / rl
|
|
└→ telemetry
|
|
SimulationSession snapshot → app → viewer / 各业务面板
|
|
```
|
|
|
|
主工作台由 `index.html → src/main.tsx` 启动；自调参工作台由 Vite MPA 入口 `tuning.html → src/tuning/main.tsx` 启动，避免把 MuJoCo/Three.js 主应用依赖打入监控页面。两页仅通过训练 HTTP API和严格同源的短消息交接训练服务凭据/策略导入请求，不在 URL 中传 token。
|
|
|
|
## 机器人接口边界
|
|
|
|
`robot/types + validation` 定义跨语言契约，`robot_profiles/` 是唯一参数源；可信 `RobotAdapter` 封装物理模型，`ModelBindings` 为机器人/Python/Go2 共用索引。`ControlArbiter` 在 Session 边界授予身份票据，所有写入都经过所有者检查，不依赖 UI 灰化。
|
|
|
|
外部 Python SDK → 独立 `control_bridge` → `ExternalControlClient` → `RobotRuntime` 最新目标邮箱。网络事件不直接改 qpos/qvel；物理步前施加目标、步后确认，观测是实测状态。外控的有界固定-dt 调度器独立于 renderer，React 快照不是传输时钟。暂停时由轻量生命周期轮询补一次状态快照，避免 UI 停留在旧授权状态。
|
|
|
|
`app/hooks/useExternalControl` 只负责连接、内存凭据、显式授权及隐藏/卸载清理。profile 变更走既有候选编译事务；回滚不恢复 lease。协议、指纹、单位、软件渲染预算和后续独立 task/RL 层详见 [机器人接口](../docs/robot-interface.md)。
|
|
|
|
测试文件使用 `*.test.ts(x)` 与被测模块共置；端到端测试统一保存在 `e2e/`。`physics/runner.html` 是仅开发服务器提供的真实 WASM 夹具，不进入生产构建；普通桥接使用小型通用模型，完整 LeKiwi / LeRobot / 60 秒 UI 回归通过独立配置和 CPU 环境运行。
|