Mujoco_WASM/web_platform/ARCHITECTURE.md

前端架构

src/ 采用“应用壳 + 业务域 + 共享基础设施”的组织方式。

目录职责

src/
├── app/            应用入口、跨域编排、工作区壳和全局反馈
├── components/ui/  无业务依赖的共享 UI 基础组件
├── controller/     Python 控制器运行时、类型和面板
├── map/            地图加载、生成、编辑和面板
├── mobile/         移动操作 RL 底层；agent/ 为独立语义契约、物理技能与任务 UI
├── 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。

主要运行链路

项目文件 → 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。

Website 产品边界

vite --mode website 使用 app/websiteConfig.ts 关闭云端首版的训练/调参/外控入口，构建到 website-dist/，不包含 tuning.html；默认 local 构建和底层算法保留。WebsiteModelSettings 仅在展开设置后建立同源匿名会话，DecisionClient.website() 自动携带 Cookie/CSRF/配置版本，配置与模型请求仍遵守旧的任务失效机制。API_KEY 与设备码不写浏览器持久化。

后端 web_server/web_sessions/web_config/model_catalog 分离公网边界、逐用户内存状态、固定上游配置及模型目录，复用原 Service 的有界请求、契约和物理控制解耦。订阅由逐会话 CodexAccount 提供官方设备码登录，不共用进程级账号、不放开任意 CLI 执行。部署与验证见 docs/website-deployment.md。

LeKiwi 智能任务

主工作台控制台同时承载 RL 与 mobile/agent/AgentTaskPanel；独立 mobile.html 构建入口已移除，tuning.html 和物理夹具保留。App.loadEntry() 仍负责同一适配器/查看器的事务与回滚；智能任务只添加场景配置，不另建 RobotManager。任务场景不应用/清空地图草稿，RL 切回时重新编译 RL 场景。

AgentTaskController → gated 本地技能 → 同一个 SimulationSession.advance()；模型 Promise 只写邮箱，票据限定同步物理窗口。任务级暂停可继续，全局暂停/外力拖动/地图编辑/模型重载撤销旧请求。完整 CAD 软件渲染时 agent 仅降低绘制频率，空闲帧仍调用同一个 advance，不新建时钟、不减面。

DecisionClient 仅访问本机 decision_server；模型 key 只在服务内存，页面临时输入保存后清空，令牌不进入持久存储/任务证据。模型连接、官方 Codex 登录均无隐式付费来源回退。算法、网络和认证 UI 位于各自业务模块，不嵌入 App 的加载算法。验收边界见 智能抓放。

机器人接口边界

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 层详见 机器人接口。

测试文件使用 *.test.ts(x) 与被测模块共置；端到端测试统一保存在 e2e/。physics/runner.html 是仅开发服务器提供的真实 WASM 夹具，不进入生产构建；普通桥接使用小型通用模型，完整 LeKiwi / LeRobot / 60 秒 UI 回归通过独立配置和 CPU 环境运行。