chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: release v1.0.1 CADWorld 网站与 LeKiwi 智能抓放
web-platform-ci / Standalone decision service (no cloud credentials) (push) Has been cancelled
Details
web-platform-ci / TypeScript, lint, unit, build (push) Has been cancelled
Details
web-platform-ci / Playwright E2E (push) Has been cancelled
Details
lekiwi-compatibility / cpu-compatibility (push) Has been cancelled
Details
web-platform-ci / Standalone decision service (no cloud credentials) (pull_request) Has been cancelled
Details
web-platform-ci / TypeScript, lint, unit, build (pull_request) Has been cancelled
Details
web-platform-ci / Playwright E2E (pull_request) Has been cancelled
Details
lekiwi-compatibility / cpu-compatibility (pull_request) Has been cancelled
Details

Browse Source 
集成同源 BYOK 会话隔离、精简模型设置、官方订阅入口和 HTTPS 发布运维；保留本地训练/调参与控制能力。同步 npm 版本及 CHANGELOG，记录公网真实 API 验收仍待用户凭据。
This commit is contained in:
cen617-code
2026-09-24 09:57:41 +08:00
parent 3ad29356c9
commit f3a8a38acd
194 changed files with 32918 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/lekiwi-agent.md
+148
View File
@@ -0,0 +1,148 @@
# LeKiwi 智能抓放：实施进度与物理基线
当前计划 **10/10 已完成**。自动回归、物理故障与真实双 API 回合已通过；用户明确确认以 **DeepSeek `deepseek-flash` + OpenRouter `typesafe/jev-1.13` 的主工作台真实抓放**作为最终验收，不再要求本次订阅推理回合。仅仿真，不控制实机。
ChatGPT 隔离官方登录已确认成功，未发现隔离 HOME 中的 `auth.json`，没有读取全局登录。订阅浏览器用例在模型请求前因选择器未匹配而中止（已为协议/型号下拉框补充显式可访问名称）；用户随后要求结束验收，因此**未运行订阅推理**，不能宣称订阅抓放成功。该临时会话已关闭，LLM/Jev 请求均为 0。记录：`build/lekiwi-agent/subscription-login-only.json`；失败用例保留于 `build/e2e/lekiwi-agent-subscription-first/`。
## 网站模式补充
网站版不再填写本机地址或服务令牌。在“模型设置”中填写自己的 DeepSeek/OpenRouter LLM API_KEY/型号与独立 Jev OpenRouter API_KEY；也可选 ChatGPT 订阅，走官方设备码登录。订阅网络/账号不可用时明确提示，不自动转付费 API。网站暂不开放 RL 训练和调参，本地模式继续保留。
网站生产构建已通过真实同源后端/假 HTTP 上游与双浏览器隔离测试，并完成一次显式 mock 的真实 WASM 抓放与证据导出；这不是此次云端真实 API/订阅推理验收。后续真实验收需用户提供测试凭据/完成官方登录。见 [网站部署](website-deployment.md)。
## 主工作台使用
1. 导入 A ZIP，在 URDF 对话框选择 `lekiwi-v1`，然后打开「控制台 → LeKiwi 智能抓放」。缺资产会报错，不下载/替换机器人。
2. 点击「加载 A 任务场景」，初始为显式 mock（不调用 API）。开始、任务级暂停/继续、单技能步进、停止、重置和证据导出都在同一主视口。全局暂停/隐藏/拖动会取消任务，不等同于可继续的任务级暂停。
3. 目标可在暂停后用米制 X/Y 编辑；首版范围 X `[0.237,0.277]`、Y `[0.565,0.665]`，Z 固定 `0.128`。修改后开始会重新载入方块/支撑台并启动新回合，不复用旧计划。范围编辑仍属受限实验，不等于已验证任意位置。
4. 真实模式先启动本机服务，再展开「模型连接与官方订阅登录」，输入服务终端显示的临时令牌。仅连接/读取配置不推理；测试连接和开始真实任务可能计费。选 API 或官方 Codex 均需显式保存型号/协议，不自动换模型。修改草稿后禁止继续使用旧付费连接运行/测试，保存后才重新启用；保存会刷新两角色的服务配置。
```bash
source .venv/bin/activate
npm run decision-server -- --openrouter-env .env --deepseek-env .env
# 另一个终端：npm run dev
```
这两个可选参数只按授权读取根 `.env` 的 OpenRouter Jev 与 DeepSeek key，固定 `typesafe/jev-1.13` / `deepseek-flash`；不是订阅登录失败后的自动回退。也可不传参数，在界面临时输入自己的 API 配置；换 URL 必须重新输入密钥。Codex 需固定 0.147.0，可在界面发起官方登录、取消、退出、刷新账号/可见型号/官方配额；CLI/门禁/账号任一步不可用都明确报错。
界面展示计划、当前技能、Jev 判断、双指力/支撑/搬运历史、调用数、墙钟/仿真时间、服务报告 token/部分费用。证据导出不包含密钥、服务令牌或认证地址；重置前请先导出当前回合。地图草稿与后台训练作业保留，进入 RL 则重新载入 RL 场景。
首个主工作台 mock 端到端测试通过：真实文件导入 → 单技能暂停 → 继续 → 独立物理成功 → JSON 导出 → 场景重置。证据：`build/e2e/lekiwi-agent-workbench-first/`；初版截图发现支撑台因默认碰撞组被隐藏，已显式放入可见组，碰撞仍保留；修复后主视口同一完整回合复测通过，截图与证据保存在 `build/e2e/lekiwi-agent-workbench-step9/`。生产构建已核对不含 `mobile.html`，保留 `tuning.html`；`/physics/mobile.html`、两变体 RL/ONNX 底层不删除。
## 第 10 步：真实回合、故障与回归
### 真实双 API（不是 mock 或订阅）
主视口已完成两次真实 API 回合，均为 **1 次规划 + 11 次 Jev 判断**，无回退、无网络自动重试。最新证据位于 `build/e2e/lekiwi-agent-final-gates/` 下的 `live-physical-evidence.json` 与 `live-workbench.png`：
- 仿真 **47.220 s**；任务墙钟 **73.271 s**，等待模型不推进仿真。
- 有效持物底盘平移 **0.593727 m**；目标误差 **0.007689 m**。
- 最终两指力均为 0，目标台支撑成立，末端撤离 **0.093133 m**。
- DeepSeek 最新报告 input/output **916/1101 tokens**，未报告费用，**不能记为 0**。
- Jev 11 次累计 input/output **15351/2194 tokens**，报告费用 **$0.000644742**；这不是包含 DeepSeek 的完整账单。
首次浏览器连接尝试在发起推理前失败：原生 `fetch` 被作为类成员调用触发 `Illegal invocation`。已改为使用全局 receiver，并增加单元回归。失败保留于 `build/e2e/lekiwi-agent-live-first/`，修复后首轮保留于 `build/e2e/lekiwi-agent-live-second/`，未用最后一次成功覆盖失败。
真实用例必须显式 opt-in；普通 CI 不读取 `.env` 或调用模型。测试服务在生产预算之外进一步限制为 **总计 1 次 LLM / 12 次 Jev**，临时服务令牌不写证据，关闭后销毁临时状态目录：
```bash
LEKIWI_LIVE_API=1 PLAYWRIGHT_HTML_OPEN=never npx playwright test \
-c web_platform/playwright.agent.config.ts lekiwi.agent.live.spec.ts \
--output build/e2e/lekiwi-agent-live-new
```
### 真实 WASM 故障（模型选择为显式 mock）
`build/e2e/lekiwi-agent-faults-final/` **10/10** 通过：
| 注入 | 实际结果 |
| ------------------------------ | ------------------------------------------------------------------------ |
| 夹爪持续锁开 | 3 次 `empty_grasp`，最多恢复 2 次，42.007 s 停止 |
| 一次空抓后移除故障 | 恢复 1 次，61.219 s 完成真实抓放 |
| 实际 IK 目标偏移 20 mm | 3 次 `alignment_timeout`，最多恢复 2 次 |
| 已搬运 12 cm 后渐进开爪 | `lost_grasp`，无重试，清除有效搬运历史 |
| 肩关节驱动锁定 | `joint_stall`，3.291 s 停止，无重试 |
| 驱动器目标突跳（模拟超速故障） | 首个 1 ms 子步检测 `joint_velocity` 后停止 |
| 轮驱动锁定 | `navigation_timeout`，40.004 s 停止，无重试 |
| 真实 scratch IK 求解不可达目标 | `unreachable`，未发出对应运动目标 |
| 两个受限目标角点 | `[.237,.565,.128]` / `[.277,.665,.128]` 均真实成功；非区域内全部位姿保证 |
注入只在非生产物理夹具中修改执行器输出或 IK 输入；不通过写物体 qpos、焊接或假反馈实现结果。恢复时从实测臂/夹爪位置重新初始化目标，避免故障解除后旧内部目标造成跳变。臂卡住保护采用版本化阈值：跟踪误差 ≥0.14 rad、实测速度 <0.02 rad/s 持续 0.75 s；不把正常夹爪接触阻挡当作臂卡住。
### 生命周期、资源与保留功能
- 最终 agent 门禁 **18/18**：原规则 5 种子、mock 5 种子、同一时钟基线、5 个迟到响应场景、8 次资源循环及上述真实 API。故意忽略 abort 的 mock 规划在任务暂停/全局暂停/停止/外力交互/模型重载后交付，真实 WASM 控制、qpos、时间均未变化，Jev 调用为 0。
- 8 次 A 全模型与 IK 加载释放：逐一核验 model、live data、scratch data、两 Jacobian buffer、接触 force buffer 共 48 个原生句柄均已删除。heap 容量为 **1143.19 → 1367.56 → 1567.75 MiB**，后 6 次保持稳定；不是保证 heap 缩小或无限次无泄漏。
- 主视口 mock、单技能、继续、成功、导出、重置、编辑目标后新 run、新源方块与旧计划失效通过：`build/e2e/lekiwi-agent-workbench-final/`。
- 从暂停中的 agent 场景切入真实 RL 训练、上传快照、导入 ONNX、继续训练通过；服务器的 `*.training.xml` 明确不含 `__agent_`：`build/e2e/lekiwi-agent-to-rl/`。短训练不是抓放收敛证明。
- 原主工作台/地图/调参/通用外控 **92 通过、6 个既有可选用例跳过**；完整 LeKiwi 原套件 **20/20**；两模型物理/ORT **2/2**。目录分别为 `lekiwi-agent-existing-workbench`、`lekiwi-agent-regression`、`lekiwi-agent-mobile-regression`。
- 最新 LeRobot 60 s / 30 Hz：1800 动作、57.596 s 仿真、RTT P95 27.593 ms、max 312.842 ms，超时/丢请求为 0；未放宽 500 ms 门槛。
- Vitest **129 文件 / 608 测试**、typecheck、TS/Python lint、生产 build 通过。决策服务 **28 项**（25 常规 + 3 单独启用的真实 CLI 离线门禁）；训练服务 126 项中 102 通过/24 可选跳过；控制桥 16/16；隔离 MuJoCo 3.11 移动操作 Python 7/7。
最终汇总与 43 个关键源码文件的 SHA-256 位于 `build/lekiwi-agent/final-verification.json`。源码/证据扫描未匹配到根 `.env` 两个已授权角色的真实 API key（不打印密钥值或其指纹）。最新两机器人训练快照还通过原生 MuJoCo 3.11 的 12 步对照：A 的 qpos 最大误差约 `5.67e-9`，bundle 约 `3.09e-6`，不声称长轨迹逐位相同。
全仓格式检查仍仅被四个原有文件阻塞：两份 `.pytest_cache/README.md` 与 `contracts/fixtures/{mobile-golden,mobile-motion-v2-golden}.json`，未擅自改写。真实账号配额不足/型号推理资格与订阅回合仍未验证；本次用户已接受该边界，不阻塞已完成的 API 验收。将来验证订阅需重新建立隔离会话，不使用现有全局 Codex 登录代替，也不回退到 API 付费。
## 已验证的 A 基线
资产固定为 `build/lekiwi/lekiwi-v1.zip` / `lekiwi-v1`，不是 Link1–Link4 bundle。完整轮网格与性能边界见 [网格说明](lekiwi-mesh-compatibility.md)。
`contracts/lekiwi-pick-place-v1.json` 冻结了当前空旷平地任务：36 mm 方块、110 mm 支撑面、两个支撑台沿 Y 相隔 600 mm、5 个 ±2 mm 的小扰动种子。不是任意桌面高度、任意物体位姿、障碍导航或广泛随机化的成功率。
- `PickPlaceScene.ts` 在任务专属场景中组合物体/目标/支撑台，保留旧 RL 契约及其 EEF site；新增 `__agent_tcp` 是经 CAD 指端位置标定的抓取点。
- `LeKiwiIK.ts` 用独立 scratch `MjData`、`mj_jacSite`、阻尼最小二乘求解五臂轴的位置和竖直接近方向，不假设能满足任意六维姿态。明确释放 scratch 和 Jacobian buffers。
- `DeterministicBaseline.ts` 只发限位、限速/限加速度的执行器目标；不自行建物理循环、不调用模型、不使用 RL 的 `manual=true/hasLifted` 绕过训练门控、不修改物体 qpos、无焊接/吸附。
- `PhysicalEvidence.ts` 每物理步汇总两侧分别与物体的接触法向力、支撑、速度和位姿；同一侧多个凸包不能冒充两侧。结合试抬和相对稳定验证抓持，只累计抓持有效期间的底盘平移。放置同时要求历史搬运、目标误差、释放、撤离和持续支撑；重复/冻结观测不能累加稳定时间。
真实 WASM 5/5 结果：每回合约 47.24 秒仿真时间、持物平移 0.5938 m、最大臂/夹爪关节速度约 0.5801 rad/s；最终误差约 8 mm、无指面接触、支撑成立、末端撤离超过 9 cm。原生 MuJoCo 曾先行完成一次标定探索，不把该探索替代浏览器验收。
```bash
npx playwright test -c web_platform/playwright.agent.config.ts --output build/e2e/lekiwi-agent-baseline
```
证据在各用例的 `physical-evidence.json` / `governed-baseline.json`。它们包含 50 Hz 控制级轨迹；评估器和速度保护在 1 ms 物理子步运行。没有 RL 训练收敛或真实模型调用的声明。
## 契约与控制边界
- `contracts/lekiwi-agent-v1.schema.json`：有界具名 SI 观测、计划、Jev 选择/分类/诊断、技能结果；观测明确标注 `mujoco-ground-truth`，非视觉识别。
- `protocol.ts` 使用本版本 schema 的有限子集校验器，拒绝未知字段/对象/技能、非有限数字、越界坐标、跳过物理前置阶段与循环计划。模型文本不变成代码或文件路径。
- `RequestGate.ts` 对 run/scene/sequence/plan/request 标识逐项校验，取消、替换和超时立即拒绝；提供者忽略 AbortSignal 也不能把迟到结果重新交付。
- `SimulationSession` 新增 `agent` 所有者。写入能力只在当前票据对应的同步物理回调或安全保持中有效；网络回调直接写入会被拒绝。等待期间冻结并丢弃墙钟积压，暂停/reset/控制切换/重载使旧能力失效。
- 带动态方块的场景不能冒充“唯一浮动根”的 LeRobot 外控模型；agent 使用现有移动操作环境进行绑定/安全保持，并独占原 `SimulationSession` 物理时钟，不启动第二个 `RobotManager`。真实 agent 所有者路径已经完成一轮同一基线。
步骤 8 的单元门禁已在第 10 步复跑；最新数量、真实回合、物理故障及残余边界见上文，不把 mock、真实 API 和订阅证据混用。
## 第 8 步：有界异步闭环
`AgentTaskController` 编排 LLM → Jev → 已验证的本地技能 → 物理观测。Promise 只能填充邮箱，在下一次 `SimulationSession` 同步写入窗口应用；等待时冻结物理，旧响应、暂停/取消、重载后不可继续执行。支持任务级暂停/继续/单技能步进，区别于全局暂停取消任务。
- ungated `DeterministicBaseline` 保留冻结基线；gated 模式逐技能等待授权，重新检查停车、TCP/物体对齐、双指力、试抬、运输历史、支撑和释放。
- 每技能最多 2 次恢复、每回合 2 次重规划/3 次 LLM/60 次 Jev，20 分钟墙钟及原 70 秒仿真期限；取消请求也计入前端次数，服务端另有并发/小时限额。重规划不能重置恢复计数或搬运历史。
- 只允许源位置附近、仍被支撑且静止的空抓/对齐失败重新开爪、对齐和抓取。滑落、关节超速、不可达、底盘异常等硬失败立即保持/停止，不询问模型放行。LLM 要求重规划时，Jev 的重试建议只能升级为重规划，不能直接重试。
- `DecisionClient` 仅访问本机网关；取消同时 abort HTTP 和指定服务端请求，取消先于 POST 到达也留下有界拒绝记录。凭据不写浏览器存储，无真实 API → mock 降级。`MockDecisionProvider` 只供显式测试模式。
- Jev 的 `secure` 与本地证据矛盾即拒绝；搬运要求双方一致。最终成功仍由 `PickPlaceEvaluator` 决定，不采信模型或技能的自报结果。
`build/e2e/lekiwi-agent-step8/`：11/11 真实 WASM 用例通过（5 个原始基线、5 个 mock 决策闭环、1 个 agent 所有权基线）。mock 闭环每回合 1 次规划、11 次判定，47.217–47.221 秒仿真、持物平移 0.59371–0.59375 m，释放/支撑/撤离均通过。此批**未调用真实模型**。单元测试覆盖有限恢复/重规划、预算、硬停、非法选择、401/超时、过期响应和物理成功否决；后续真实物理故障结果见第 10 步。
## 第 7 步：模型服务与单请求验证
新增 `decision_server/`，配置、接口、安全限制、费用及真实单请求证据见 [服务说明](../decision_server/README.md)。OpenRouter Jev 和经用户确认的 DeepSeek `deepseek-flash` 早期均用合成契约输入完成真实单请求；这些早期探针本身不是完整回合，后续真实主视口回合见第 10 步。
Codex 已实现官方 stdio 的登录/取消/退出、账号/模型/额度、结构化规划与中断；固定 0.147.0，独立临时 HOME、仅会话 OAuth。当前 5 个可见模型在匹配目录的受限配置下，均通过空工具表与 4 类强行工具调用拒绝测试；真实 stdio 假推理也验证了最终结构化计划和线程释放。真实 ChatGPT 隔离登录后来已确认成功；订阅推理未运行，未冒充通过。
### 早期探测记录（保留失败与改进过程）
本机为 `codex-cli 0.147.0`。使用独立临时 `HOME/CODEX_HOME/cwd`、清理后的进程环境和回环假 Responses 服务，未读用户已有登录、未登录、未调用真实模型或消耗 API 额度：
1. 单独关闭 shell、unified exec、多 agent、插件，并设 read-only/never approval，仍会暴露 `update_plan`、`request_user_input`、`apply_patch`、`view_image`。**不能以 read-only 声称禁工具。**
2. 再关闭 `tools.update_plan.enabled`、`tools.experimental_request_user_input.enabled`、`features.view_image`，并使用与 0.147.0 匹配的模型目录将 `apply_patch_tool_type` 设为 null，离线请求的 `tools` 为空。
3. 假服务强行注入 `apply_patch` 调用，CLI 返回 `unsupported custom tool call: apply_patch`，未生成探针文件。
这段早期实验本身不是订阅登录或真实可用模型证明。探针使用的 `gpt-5.4` 在该目录标为隐藏/退役，**不可把它作为默认可用订阅模型**。后续实现已结合官方 `account/read` / `model/list`、匹配版本目录与逐模型门禁，保持现有登录隔离；失败时明确不可用且不得转收费 API。当前默认/API 提供者是用户显式授权的选择，不是 Codex 静默回退。
离线原始证据及探针副本位于 `build/lekiwi-agent/codex-capability/`；临时源码路径只是实验用途，不能作为生产服务启动入口。
Sources:
- [Codex 0.147.0 配置 schema](https://raw.githubusercontent.com/openai/codex/rust-v0.147.0/codex-rs/core/config.schema.json)
- [版本匹配的模型目录](https://github.com/openai/codex/blob/rust-v0.147.0/codex-rs/models-manager/models.json)
docs/lekiwi-mesh-compatibility.md
+56
View File
@@ -0,0 +1,56 @@
# LeKiwi A：完整网格导入与当前边界
适用资产：`build/lekiwi/lekiwi-v1.zip`，profile `lekiwi-v1`。
ZIP SHA-256：`a10ac577ea49cdf87f324f3f6e9a7a887a1e3c0254ae638059711fef9e385b04`。
不替换为 Link1–Link4 bundle，也不将其 SO-ARM100 命名的 CAD 宣称为已验证 SO101。
## 几何与导出
- 官方 MuJoCo/WASM 3.11.0 的二进制 STL 解码器拒绝超过 200,000 面的文件。现在针对选定 URDF/MJCF/include 图中的超限 STL 自动生成 OBJ：保留每个三角形、绕序及 float32 坐标，仅精确去重相同顶点，不减面。
- 三个轮分别保留 **314,244 面、157,080 顶点**。原始三个文件内容相同，共享一个内容寻址 OBJ（15,735,476 字节），但仍是三个独立的随轴视觉实例。
- 保留原始文件和来源哈希；派生文件名含转换器版本与 SHA-256。源内容变化使缓存失效，不覆盖用户同名文件。转换分批让出主线程，可取消；取消/失败不会替换活动场景。
- 支持工程内 `meshdir`、`assetdir`、`content_type`、`strippath` 与嵌套 include；不通过同名猜测、网络下载补齐资源。非法长度、坐标、路径、循环 include 和超预算输入明确报错。ASCII STL、厂商私有 STL 颜色、无限大小网格不在保证范围内。
- 沿用单文件 128 MiB、工程 512 MiB 的限额，另有限制转换工作内存的保守估算；这不是浏览器实际峰值内存承诺。
- 主工作台命令面板提供 **“导出完整仿真工程 ZIP”**，包含原始资源、派生网格及原目录内的 `compiled-scene.xml`（有重名则递增编号）。导入 ZIP 后选择该编译入口可直接加载。原来的“导出 MJCF 文件”仍只下载 XML，不是自包含包。
- 主控制台训练快照与移动操作训练 ZIP 同样携带派生 OBJ；不会修改已有训练作业/策略指纹。
## 视觉不等于碰撞
完整轮 CAD 对齐到既有理想轮轴，零附加质量、无接触；简化轮毂/滚子只作为碰撞诊断几何。保留原有轮惯性、被动滚子、整臂凸分解、自碰撞和夹爪接触配方（collision revision 4）。新增独立 visual revision 1；旧缺轮 cooked MJCF 需从原始 URDF 重新转换。
本改动没有实现或证明真实抓取—搬运—放置，更没有连接 LLM/Jev。该任务仍需通过批准计划中的后续独立验收。
## 已运行的检查
- 边界 200,000/200,001 面、坏头/长度/NaN、路径/include、重复引用、内容缓存、取消及导出单测。
- 真实 WASM 三轮面数、毫米缩放、轴心一致性、随轴旋转、零碰撞/质量；完整 ZIP 重导及同包 8 次加载释放。
- 底盘全向运动/站稳/障碍、夹爪两侧接触和阻挡、整臂碰撞/关节扫掠、108 个外部接触探测及 XML 重载。
- 两机器人 12 次交替切换、失效候选回滚、VFS/model/data 释放、拖动、训练包导出；主工作台两机器人真实训练与策略导入通过。**这些不是训练收敛证据。**
- A 的新训练快照在原生 MuJoCo 3.11.0 重放 12 步，WASM/Python 最大误差：qpos `5.68e-9`、观测 `4.66e-10`、控制 `5.10e-9`、奖励 `2.31e-11`。
复现命令（大资产需本地存在）：
```bash
npm run typecheck
npm run lint
npm test
npx playwright test -c web_platform/playwright.lekiwi.config.ts lekiwi.meshes.spec.ts lekiwi.meshPerformance.spec.ts lekiwi.physics.spec.ts lekiwi.gripper.spec.ts lekiwi.armCollision.spec.ts lekiwi.fullCollision.spec.ts --output build/e2e/lekiwi-step4-meshes
npx playwright test -c web_platform/playwright.lekiwi.config.ts lekiwi.workspace.spec.ts lekiwi.training.spec.ts --output build/e2e/lekiwi-step4-workbench
npx playwright test -c web_platform/playwright.mobile.config.ts -g '两种机器人'
python3 -m zipfile -e build/mobile-validation/lekiwi-training.zip build/mobile-validation/lekiwi-complete-package
build/venvs/mobile/bin/python -m training_server.mobile_manipulator.validate_rollout --package build/mobile-validation/lekiwi-complete-package --rollout build/mobile-validation/lekiwi-rollout.json
```
## 性能、失败记录与未验证项
本机 Chromium headless 使用 **SwiftShader 软件 WebGL**，不能把其结果当成硬件 GPU 性能。一次 992×676 主视口、60 秒完整 CAD 测量：加载约 8.95 秒、平均 3.82 FPS、帧间隔 P95 333 ms、物理批次 P95 8.3 ms，60 秒墙钟只推进约 5.36 秒普通播放仿真。没有重新测量旧简化轮基准，不报告性能改善倍率。
完整 CAD 初次实测触发了外控 500 ms 看门狗。修复不减面、不放宽看门狗、不增加物理追赶：批量复制 WASM mesh 数组，避免逐元素创建 embind 视图；外控激活且软件绘制超过 500,000 三角形时，完整视口刷新最多约 **0.25 FPS**，优先为原有实时物理/消息时钟留出空闲。小型软件场景仍最多 5 FPS，硬件外控仍最多 30 FPS。完整网格始终保留；软件模式的低刷新率是明确限制。
修复后真实 LeRobot 60 秒测试：1,800 次动作、仿真推进约 57.73 秒、RTT P95 30.14 ms / 最大 282.76 ms、0 超时/丢请求，原安全门槛未放宽。外控 reset/崩溃/隐藏/冻结恢复测试通过。
首次跨模型第 8 次加载发生 WASM heap 扩容，原“第 8 次必须等于第 6 次”断言失败；扩展为 12 次，保持原 1,600 MiB 上限和末轮稳定断言，观测到约 1,272.2 MiB 高水位稳定。独立完整 ZIP 的 8 次重载高水位可接近 1.8 GiB；WASM heap 不会随模型释放缩小，不能把容量直接称为活跃内存或泄漏。大模型仍可能受浏览器/硬件内存限制，未承诺无限重复/任意穿透姿态。
单元测试最初有大数组深比较超时；改为字节比较。初版导出夹具缺少派生 OBJ 导致重导失败，现已走完整缓存/ZIP 资源路径。重导测试曾每轮追加一份 XML 快照，混淆工程增长与内存泄漏；现固定同一个导出包重载，另用单测验证快照不覆盖用户文件。
硬件 GPU FPS、更多浏览器、长期压力运行及完整抓放任务尚待后续验收。测试产物位于上述 `build/e2e/`、`build/mobile-validation/` 目录；它们是本机证据，不提交大型资产。
docs/mobile-manipulator.md
+154
View File
@@ -0,0 +1,154 @@
# 可拔插移动操作环境（mobile-manipulator-v2）
统一训练入口：主工作台「控制台 → 强化学习任务」。独立 `/mobile.html` 产品页已移除；主工作台另有「LeKiwi 智能抓放」，见 [智能任务](lekiwi-agent.md)。物理/ONNX/训练底层与 `/physics/mobile.html` 夹具保留。服务配置及完整点击流程见 [训练服务](../training_server/README.md) 和 [统一训练面板](../web_platform/TRAINING.md)。
任务**复用现有加载器、MuJoCo WASM 与 Three.js 查看器**，不替换 Go2 任务、不授予外部控制桥训练 RPC。v2 控制、分阶段训练与评估说明见 [训练课程](mobile-training-curriculum.md)；旧 v1 策略不能继续使用。
## 1. 分层与文件规划
| 层 | 文件 | 职责 |
| ------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| A：描述与加载 | `contracts/mobile-robots-v1.json`、`web_platform/src/mobile/RobotDescriptor.ts` | 强类型 `RobotConfig`；名称绑定、限位、默认姿态、底座混合矩阵、夹爪与末端配置 |
| A：场景 | `web_platform/src/mobile/SceneComposer.ts` | URDF bundle 独立适配；已展开 MJCF 中加入物体、目标、地面和 EEF site |
| A：生命周期 | `web_platform/src/mobile/RobotManager.ts` | ZIP 导入、双槽 VFS、候选验证、查看器提交、失败回滚、策略失效及资源释放 |
| B：任务契约 | `contracts/mobile-manipulator-v2.json`、`web_platform/src/mobile/TaskKernel.ts` | 归一化、动作映射、阶段奖励、成功/超时；不依赖渲染和 ONNX |
| B：WASM 环境 | `web_platform/src/mobile/MobileManipulatorWasmEnv.ts` | `reset/observe/step`、编译后地址缓存、物理积分与交互状态重置；另导出别名 `InteractiveManipulatorEnv` |
| C：推理 | `web_platform/src/mobile/ONNXPolicyRunner.ts` | 单飞 ONNX、元数据和 SHA-256 校验、过期结果隔离、延迟指标 |
| C：交互 | `app/components/WorkspaceToolsPanel.tsx`、`mobile/agent/`、`TaskDragController.ts` | 主工作台 RL / 智能任务；拖动模块供保留的物理夹具使用 |
| Python | `training_server/mobile_manipulator/{kernel,env}.py` | 同公式的 Gymnasium 环境，加载浏览器导出的同一份 MJCF |
| Python | `training_server/mobile_manipulator/{train,export_onnx,validate_rollout}.py` | 可选 SB3 PPO 入口、PyTorch 导出及 ORT 校验、跨引擎短轨迹校验 |
现有组件仅增加小型接入点：
- `PhysicsAdapter.load()` 的 `sceneComposer` 在 URDF 转换/地图组合后展开 include，再组合任务场景；`configureRobotRuntime: false` 允许使用模型配方而不安装旧外控运行时。任务增加了第二个 freejoint，不能调用要求“唯一自由基座”的旧 LeKiwi 外控绑定。
- ZIP **继续复用现有 `fflate`**（功能等价于此处使用 JSZip），保留路径穿越/文件数/解压大小检查；`MemfsWorkspace` 负责 `FS.mkdirTree/writeFile/unlink/rmdir`。不增加第二套 VFS 或依赖。
- `MuJoCoViewer` 的可选 `advance(now)` 回调提供唯一物理时钟。设置它之后查看器**不再调用** `SimulationSession.advance()`，避免双重步进。
## 2. 机器人与适配边界
| 描述符 | 本次实际验证的 ZIP | 机械臂 |
| --------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `lekiwi-v1` | `build/lekiwi/lekiwi-v1.zip` | 原始五臂轴 + `arm_gripper`；复用已有来源校验、全臂凸包和被动滚子配方 |
| `lekiwi-bundle` | `../Reference_Projects/LeKiwi/New_urdf/robot_urdf_bundle (1).zip` | `Link1…Link4` + `arm_wrist_roll` + `arm_gripper`；独立配方，不冒充旧外控 profile |
验证资产 SHA-256：
- 原始 ZIP：`a10ac577ea49cdf87f324f3f6e9a7a887a1e3c0254ae638059711fef9e385b04`
- bundle ZIP：`f35734d3b4e3d6ef8399491987f50974476bfdd9d6c18506b915bcb9497f5752`
文件名不能证明机械结构相同；历史上同目录其他 ZIP/同名导出可能有不同活动轴。本次支持以上具体结构，**不自动把未知活动轴按顺序重命名**。
新 bundle 配方保留新臂的关节框架、惯性及四个有界关节的限位，给连续腕轴/夹爪补充仿真限位和伺服；替换超过 MuJoCo 面数上限的轮视觉，并构建理想化三全向轮/被动滚子。重复碰撞仅在同网格、同局部变换时去重。新臂接触使用 MuJoCo 原生凸包近似，**没有套用原臂的离线凸分解数据**。底盘质量、驱动增益、夹爪行程和 EEF 偏移是仿真估计，未实机标定。
扩展其他机器人：提供预先带执行器的 MJCF ZIP 和 `recipe: "mjcf"` 的 `RobotConfig`，通过 `RobotManager.loadZip()` 开发接口载入；独立页的自定义 JSON 上传控件不再提供。底层支持：
- 任意数量轮子，`baseMix[nwheel][3]` 定义车体坐标 `vx, vy, wz → wheel rad/s`；差速轮可令第二列为零。
- 1–8 个标量机械臂关节；每个 `mode` 可为 `position` 或 `velocity`。目前要求移动根为 freejoint，不支持固定底座或任意浮动关节参数化的自动推断。
- 多个夹爪执行器可指定各自 `joint` 和 `closed/open`；观测使用 `gripperJoint` 的行程比，主关节必须由匹配行程的执行器控制。
- 指定 `eefSiteName` 时，组合器在 `eefBodyName` 上按 `eefOffset` 加 site；未指定时直接使用 body 原点/姿态。
- 编译后校验关节类型/限位、执行器 transmission、gear、控制类型和 ctrlrange；不兼容则回滚。
固定接口只保证任务/UI 不随 DOF 改写，**不保证同一策略能跨机器人泛化**。8 轴以外或需力矩动作时应创建新版本契约，不能静默截断。
## 3. 数学契约
世界坐标为右手 Z-up；米、秒、弧度；四元数一律 **wxyz**。姿态四元数归一化并采用 `w >= 0` 的符号。所有观测限制在 `[-1,1]`。区间均为左闭右开。
### Observation：`Float32Array(92)` / ONNX `[1,92]`
| 区间 | 内容 |
| --------- | ------------------------------------------------------------ |
| `[0,3)` | 底座世界位置 / 2 m |
| `[3,7)` | 底座四元数 |
| `[7,10)` | 底座世界线速度 / 2 m/s |
| `[10,13)` | 底座世界角速度 / 4 rad/s（freejoint 局部角速度先转世界坐标） |
| `[13,21)` | 8 个臂角槽：`2*(q-min)/(max-min)-1`；无效槽为 0 |
| `[21,29)` | 臂关节速度 / 4 rad/s；无效槽为 0 |
| `[29,37)` | 臂槽 mask（有效为 1） |
| `37` | 夹爪行程比 `g` 映射为 `2*g-1` |
| `[38,45)` | EEF 世界位置 / 2 m + 四元数 |
| `[45,52)` | 物体相对 EEF 的位置 / 2 m + 四元数 |
| `[52,59)` | 物体相对目标的位姿（目标坐标系） |
| `[59,66)` | 目标世界位置 / 2 m + 四元数 |
| `66,67` | 已抓取抬升标记、当前阶段稳定计数 / 10 |
| `[68,80)` | 上次实际施加的归一化动作 |
| `[80,92)` | 积分控制目标状态：臂位置与夹爪开度归一化，其余槽为 0 |
相对位姿严格使用 `p_rel = R_parent^T*(p_object-p_parent)`、`q_rel = inverse(q_parent)*q_object`，不是仅减世界 XYZ。
### Action：`Float32Array(12)` / ONNX `[1,12]`
- `[0,3)`：归一化车体 `vx,vy,wz`，先经过共享契约速度/加速度限制再经 `baseMix` 转轮速；超过 `wheelLimit` 时**同比缩放所有轮速**。
- `[3,11)`：8 个臂槽。位置模式是积分目标的归一化增量速度，目标每步最多移动 `min(velocityLimit,0.5)*dt`，并限制跟踪误差；速度模式同样限幅。不存在的槽忽略。零动作保持目标，不再映射到全行程中点。
- `11`：归一化开合速度，+1 张开、-1 闭合、0 保持；开度每秒最多变化 0.5。
- 输入完整校验有限值后才写 ctrl；越界有限数裁剪；NaN/Infinity/尺寸错误拒绝，不部分写入。
控制步长 `0.02 s`（50 Hz）；复用源模型物理 timestep（旧全凸包配方 1 ms，新 bundle 2 ms），必须整除控制步长。每个 step 在积分后调用 `mj_forward`，使观测不是上一个积分边界的派生位置。
### 奖励、终止
- `reach = dt * 0.1 * exp(-8 * distance(eef, object))`
- `lift = dt * 0.3 * clip((object.z - 0.019) / 0.08, 0, 1)`
- 当抬升达到 8 cm、末端距物体小于 9 cm、夹爪开度小于 0.4 时锁存 `hasLifted`。
- `transport = hasLifted ? dt * 0.5 * exp(-4 * distance(object, goal)) : 0`
- 以上抓放密集项按仿真时间积分（`dt=0.02`），上界为 18。v2 另有导航进展/距离/朝向项、动作变化率惩罚及关节速度惩罚，见共享契约与训练课程。
- 已抬升后，物体距目标小于 4 cm、线速度小于 0.05 m/s、夹爪开度大于 0.65、EEF 已撤离 9 cm，连续稳定 10 步才成功：一次性 `success=20`，`terminated=true`。
- 1000 步未成功则 `truncated=true`；结束后必须 reset。不存在自动焊接/吸附物体，搬运依赖实际物理接触。奖励中的抓取是近距/开度/抬升启发式，不是双指接触传感器的证明。
- 导航/末端接近阶段分别使用接近位驻留、末端驻留成功条件，不以抓放成功判断导航。任务训练顺序为 `navigate → reach → pick-place`。
- `info` 包含 `reward_components,is_success,stage,safety_stop,navigation_distance,max_joint_velocity`。物理子步实测关节超速、底盘倾倒/越界均失败终止。
TS `step()` 返回借用的同一对象，obs、raw-state、ctrl、action 缓冲全部复用；需要历史时由调用者复制。Python 返回独立 obs/info，避免 replay buffer 存到后续被覆盖的引用。两端奖励/观测/动作数学相同；引擎浮点求解不承诺长时间逐位一致。
## 4. 浏览器操作与集成
主工作台训练使用 `SimulationSession` + `MobilePolicyController`，在同一视口中组合任务场景并加载策略，不创建第二个物理步进所有者。
1. 在主工作台导入对应 ZIP，进入「控制台 → 强化学习任务」选择已注册变体，按训练服务流程同步场景、训练并导入 ONNX。
2. 「LeKiwi 智能抓放」仅支持固定 A，使用另一套具名 SI 契约和独立接触评估，不改 RL 92/12 契约。进入 RL 时会重新载入 RL 场景，不能把智能任务双支撑台直接冒充训练快照。
3. 地图草稿保留；智能任务只使用隔离的空旷平地预设，编辑地图使旧模型请求失效。任意机器人/训练后台作业不会因切换智能任务而被远程取消。
4. `RobotManager.loadZip(file, config, entryPath)`、`TaskDragController` 与 `moveTaskEntity()` 仍供开发/物理夹具使用，包括 Shift 拖动、状态重置和两变体资源回归；不再维护第二个产品网页。
`ONNXPolicyRunner` 要求固定 float32 `observation:[1,92] → action:[1,12]`、匹配 v2 task/robot/controlDt/动作语义/训练阶段，以及模型与 RobotConfig SHA-256。**不要格式化训练包里的 `robot.json`**，它的原始字节是导出指纹来源。它校验配置而不是所有网格字节；更改几何/动力学后必须从新场景重新训练和导出，不能只改标签绕过。
推理是单飞异步、固定仿真步长锁步：等待 ORT 时继续渲染，但不积分物理；下一次 rAF 消费动作后才生成下一观测。这避免“持续施加上次动作”造成训练端没有的动作延迟；代价是慢策略导致仿真时钟落后墙钟。计时累计有界，不在恢复后狂追补步。reset、拖动、模式切换、重载和 dispose 都使迟到推理结果失效；ORT 等待在途 run 结束后才 release。
## 5. 后台训练与自动导出
用户只需在统一面板点击开始训练。浏览器内部上传完整资产、组合后的 `*.training.xml`、`robot.json`、`task.json`、`environment.json`；服务器验证并保存快照，作业仅引用服务器 ID。Python **不再次转换 URDF**。内部 ZIP 只是传输格式，不要求用户下载、解压或运行 Python。
使用独立 MuJoCo 3.11.0 + SB3 解释器，通过训练服务 `--mobile-python` 配置；不要升级已有 Go2/LeRobot 环境。`allow_version_mismatch=True` 仅供底层诊断，服务训练不会启用此绕过。
任务设置包括阶段、接续作业、示教步数、随机化、独立评估回合，以及采样步数、迭代数、环境数、设备和种子。训练按种子扰动物体/目标 XY，部署保留名义初态；评估用不同种子。日志输出共用迭代/损失/平均奖励协议，取消覆盖训练、评估与导出整个进程组。自动导出固定 float32 `[1,92] → [1,12]` 并用原生 ORT 对5组输入比对 PyTorch；元数据包含控制语义、阶段、实际评估、权重/RobotConfig/场景 SHA-256。
阶段门槛和实测导航结果见 [训练课程](mobile-training-curriculum.md)。短程冒烟不是已收敛的抓取策略；尚未验证抓放收敛或跨机器人泛化。底层 `export_policy()`、`--smoke` 及 `RobotManager.exportTrainingBundle()` 仅保留给开发测试，不是用户训练流程。
## 6. 验证与性能边界
```bash
npm run typecheck
npm run lint
npm test -- web_platform/src/mobile
build/venvs/mobile/bin/python -m unittest training_server.tests.test_mobile_manipulator -v
npm run test:e2e:mobile
```
浏览器测试需要两个上述 ZIP；也可用 `MOBILE_BUNDLE_ZIP=/path/to/file.zip` 指定新包。缺少本地资产会明确 skip。测试包括真实模型动作、8 次交替切换、模型/data `isDeleted()`、VFS 数量、候选绑定失败回滚、真正的鼠标拖动；主工作台 UI 另由 `test:e2e:agent` 验收。产物在 `build/mobile-validation/`；测试用 `/physics/mobile.html` 不进入生产构建。
跨引擎回归与真实 ONNX 测试：
```bash
# 先运行浏览器测试产生 bundle-training.zip 和 rollout.json
python -m zipfile -e build/mobile-validation/bundle-training.zip build/mobile-validation/package
build/venvs/mobile/bin/python -m training_server.mobile_manipulator.validate_rollout \
--package build/mobile-validation/package --rollout build/mobile-validation/rollout.json
build/venvs/mobile/bin/python -m training_server.mobile_manipulator.export_onnx \
--package build/mobile-validation/package --smoke --output build/mobile-validation/smoke.onnx
npm run test:e2e:mobile
```
单元对齐另有 Python 生成的 40 组随机/旋转/饱和动作 golden，覆盖两个机器人；成功、重置、超时、速度模式、NaN 原子拒绝、生命周期和过期 ONNX 结果分别测试。重新生成：`python -m training_server.tests.generate_mobile_golden`，之后 Prettier 格式化 fixture。
内存注意：官方 JS 绑定通过 `MjData.delete()`、`MjModel.delete()` 执行原生析构；查看器的 mjvScene/GPU 资源必须先 detach，VFS 随后清理。共享 WASM 线性内存不会缩小，**不能用 heap 不下降判定泄漏**。仅释放 model/data 还不够：新路径会扩大原生资产缓存。管理器串行化加载，并交替复用两个独占 VFS 根目录；编译使共享 heap 增长后，旧环境在回滚/恢复屏障刷新 typed-array views。
以下为 v1 的历史性能基线，不作为 v2 策略验收结果：本机无头 Chromium 短测，8 次交替切换后 heap 在约 862 MiB 稳定（完整 CAD 配方开销很高），VFS 仅保留活动槽，旧 model/data 已删除。记录的是短期稳态检查，不是无限次泄漏证明。原生/WASM 3.11.0 的 12 步对照：原 LeKiwi 最大 qpos 误差约 `1.3e-15`、obs 无差异；新 bundle 最大 qpos 误差约 `6.1e-6`、obs `1.2e-6`；smoke ORT 最近推理约 `0.1 ms`、冷启动约 `4.5 ms`，不代表真实大策略延迟。精确本次数据以 `traces.json`、`onnx-metrics.json` 为准。
60 FPS 是渲染目标而非保证：策略推理、旧臂上千凸包接触、软件 WebGL、加载峰值都会影响墙钟速度。请在目标 GPU 上录制至少 60 秒 FPS/物理耗时/推理 P95/P99 与长时堆曲线；若需硬实时或低内存部署，应先降面/优化碰撞和将推理放 Worker，而不是跳过物理子步或放宽对齐公式。
docs/mobile-training-curriculum.md
+54
View File
@@ -0,0 +1,54 @@
# 移动操作 v2：先接近，再抓放
## 为什么不直接继续原来的策略
- v1 把动作映射到关节全行程的绝对位置；50 Hz 下可产生数弧度的位置目标跳变。v2 使用带速度/加速度约束的积分位置目标。
- Bundle 转换后关节层遗留的 `actuatorfrcrange="-1 1"` 覆盖了配方中舵机的 ±8 N·m 限力，导致保持姿态也会下垂、碰撞。现在关节和执行器限力一致。**这是仿真配方修正，不是实机扭矩标定，也不修改源 URDF。**
- 单纯跑通 PPO→ONNX 不等于任务学会。现在独立评估成功率、关节速度峰值、安全终止次数都写入 `deployment.json`，完整逐回合结果保存为 `evaluation.json`。
设计参考本机 IsaacLab 的 `source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/reach/`：
- `config/franka/joint_pos_env_cfg.py`：缩放的位置动作，而非全关节行程跳变。
- `reach_env_cfg.py`：分开的动作/观测/奖励/终止定义，动作变化率、关节速度惩罚和课程设计。
- `config/franka/agents/rsl_rl_ppo_cfg.py`：有界 PPO 更新与 MLP 策略。
这里借鉴结构和训练原则，没有复制 Franka 的关节范围、质量、奖励尺度，也**没有新建或启动 IsaacLab/Isaac Sim 环境**。继续使用同一份 MuJoCo 3.11 场景，是为了保持现有浏览器推断、API 与 Go2 训练链路不变。
## 控制与版本
唯一当前契约：`contracts/mobile-manipulator-v2.json`，固定 `float32 [1,92] → [1,12]`，50 Hz。
- 前 68 维保留原任务状态；68–79 为上次实际施加的归一化动作；80–91 为控制目标状态（底盘/未用槽为 0，臂位置目标及夹爪开度归一化）。积分器和滤波状态不是隐藏变量。
- 底盘三个分量目标上限：0.12 m/s、0.12 m/s、0.5 rad/s；加速度上限：0.3、0.3、0.8（对应 SI 单位）。轮速仍受描述符限制。
- 臂位置目标速率不超过 `min(velocityLimit, 0.5 rad/s)`；增量命令经过 1.5 rad/s² 加速度限制和 0.2 rad 跟踪误差防积分饱和。零动作保持既有目标，不追随重力下垂位置；暂停/撤销策略也保留安全位置目标，不清零位置舵机，不在每次暂停后继续向下垂姿态累积漂移。
- 夹爪动作变为开合速度：+1 张开、-1 闭合、0 保持；开度每秒最多变化 0.5。
- 目标限速不是物理速度的硬上界。每个物理子步检查实际臂/夹爪速度，超过 2 rad/s 即结束回合；底盘倾倒/越界也失败。**不通过裁剪 qvel 或跳过碰撞伪造安全。** 浏览器安全终止后暂停并显示原因。
- 部署校验任务版本、动作语义 `rate-limited-position-target-v1`、阶段、张量以及权重/机器人/场景指纹。旧 68 维全行程位置策略明确拒绝，必须重新训练；Go2 契约不变。
## 主控制台操作
1. 导入相应机器人，在「控制台 → 强化学习任务」连接本地训练服务。
2. 默认阶段 **1 · 底盘接近**：机械臂/夹爪保持；学习到物体前方世界坐标偏移 `(0.3, 0)` 的接近位，并朝向 +X。不是驶向放置目标，不是通用避障导航。
3. 默认可先做 4096 步导航示教初始化（闭环底盘控制器采样、监督训练 MLP），再用 PPO 微调。初始化还采样 ±0.6 rad 的初始朝向；设为 0 可做纯 PPO 对照。**部署只导出神经网络，不附带示教控制器。** 使用低初始探索噪声、较小学习率和 KL 约束，避免马上破坏接近行为。
4. 成功条件：接近位误差 <6 cm、偏航误差 <0.2 rad、线速度 <0.035 m/s、角速度 <0.1 rad/s，连续稳定 10 个控制步。1000 步超时。
5. 完成后查看评估，不只看 loss。点击「接续此作业（保留权重）」可同阶段续训；只接受服务拥有的 checkpoint，不接受浏览器提供 Python/PPO 文件路径。接续绑定完整资产快照；升级阶段还须保留已评估的坐标/随机范围，改变分布应先同阶段续训。
6. 上一阶段至少 **10 回合、成功率 ≥80%、无安全终止**，才允许切到 **2 · 末端接近**。先导航，接近位附近停止底盘并启用臂控制；末端 <9 cm 且臂速低、稳定驻留才成功。
7. 同样达标后才允许 **3 · 抓取放置**。保持接近门控，抬升后允许搬运；沿用真实接触、抬升、释放和稳定放置判据，不焊接/吸附物体。升级阶段时放开新启用机械臂的探索噪声。不能跨过未通过的阶段。
未达标作业仍可导出和导入，便于可视化调试，但界面明确警告，且不能用于跳级。服务重启会丢失当前内存作业索引；目前接续入口依赖同一服务会话，磁盘 checkpoint/评估文件不会因此删除。
## 随机化、奖励与评估边界
训练默认在名义物体/目标 XY 周围 ±0.1 m 采样；可设置 0–0.3 m。训练、示教、评估使用不同种子序列。浏览器复现部署中的名义初态，不复现隐藏随机数状态。
导航有距离进展和位置/朝向误差奖励。各阶段加入 `-0.005 * ||a_t-a_(t-1)||²` 和 `-dt * 0.01 * ||qdot_arm||²`；成功奖励 20，安全失败惩罚 -5。阶段 1 不包含抓取奖励，阶段 2 不包含抬升/搬运奖励。具体常量在共享 JSON，两端同公式并做多步 golden 对照。
本次实际实验（CPU、4 环境、128 rollout、位置扰动 0.1 m、示教 4096 步）：
- Bundle：PPO 30 次更新 / 15360 步，10 回合评估 10/10，关节峰值约 1.084 rad/s，无安全终止。
- LeKiwi v1：同样初训后 6/10；继续 30 次更新后 7/10，峰值约 0.299 rad/s，无安全终止。**尚未达到升级门槛，未继续训练抓放。**
- 原 Bundle 全行程控制环境即使保持零位，短测臂速峰值约 5.52 rad/s；修正限力后同样保持姿态约 1.09 rad/s。这是仿真模型上的对照，不是硬件限速证明。
额外用导出的 ONNX（不是 PyTorch actor）在另一组从未用于上述 rollout/初始化的种子 `300000…300019` 上复测：Bundle 20/20，LeKiwi v1 17/20；两者安全终止均为0，峰值分别约1.085和0.299 rad/s，结果保存于各产物目录 `evaluation-independent-20.json`。v1 的服务部署元数据仍保留原 7/10 评估，没有用较好的一组结果覆盖门槛。Bundle 另做了 checkpoint→末端接近的两次更新连通性检查，0/2成功，尚不能升级为抓取放置。
这些是小样本、有限训练种子、有限初态分布结果，不代表大范围导航、任意朝向、未知资产、抓取成功或实机安全。后续需要更多独立种子和长回合评估；不得把成功导出 ONNX 写成“已经学会抓放”。实验产物在 `build/mobile-curriculum/`，服务作业成果仍按原路径位于 `logs/rsl_rl/web_jobs/{id}/`。
docs/robot-interface.md
+5 -3
View File
@@ -9,7 +9,9 @@
| `lerobot_robot_mujoco` | 实际 LeRobot 0.6.1 的 Robot/Config、发现、工厂、九维控制循环 | 冒充硬件 ZMQ 服务、官方所有 CLI 原样运行 |
| 仿真 | 官方浏览器 MuJoCo WASM 3.11.0 | 用原生 MuJoCo 测试代替浏览器物理验收 |
| 环境 | Ubuntu 24.04 x86_64、Python 3.12、CPU torch 2.11.0+cpu / torchvision 0.26.0+cpu | 修改既有训练 `.venv` 或加载物理机器人 |
| V1 能力标志 | `lockstep=false`、`cameras=false`、`training=false` | 相机、LeRobot 数据采集、Gym/RL 训练 |
| V1 能力标志 | `lockstep=false`、`cameras=false`；LeKiwi 声明 `training=true` | 相机、LeRobot 数据采集、外控桥训练 RPC |
`training` 是平台控制台训练能力，不是外控桥训练 RPC；TS/Python/JSON Schema 接受布尔值。移动操作训练由本地 training_server 执行，主会话使用单飞锁步推断，不改变外控协议的 `lockstep=false`。
普通 MJCF/URDF、Pyodide 控制器和 Go2 ONNX/训练链保持独立。未知模型不会因关节数相似自动套用 LeKiwi。平台自己的有界遥测 CSV/JSON 仍可使用，但不是 LeRobot dataset。
@@ -72,11 +74,11 @@ WS `/ws/control/v1`：先发送 `{type:"auth",token:…}`；注册 descriptor/
- LeRobot 九维反馈使用实测轮速里程计以兼容上游；通用 observation 另有真实机身位姿/速度，因此碰撞/打滑时两者可能不同。
- LeRobot 部分动作仅保持最后 **确认** 的臂/夹爪目标，省略底盘速度为零。连接初始保持值来自实测观测。拒绝 `use_degrees=False`、相机配置、物理校准目录以及非法 scalar。
URDF 和整臂 18 个视觉 STL 必须匹配固定来源 SHA-256；导出 MJCF 必须含受支持的 profile、version、source SHA、`platform_lekiwi_collision_revision=4` 和当前 `platform_lekiwi_collision_recipe_sha256`（旧配方，包括 revision 3，必须从原始 URDF 重新转换）。再校验编译后的浮动根、关节/执行器、传动、轴向、限位、增益和力限等。缓存编辑继承当前显式 profile，校验失败保留旧场景但不恢复外部授权。
URDF 必须匹配固定来源 SHA-256，或通过机械语义等价校验（显示名、换色、XML 重排、等价数值/RPY）；URDF 导入还校验全部 45 个原始 STL 哈希，机械结构/物理参数变化拒绝套用。导出 MJCF 必须含受支持的 profile、version、基准 source SHA、`platform_lekiwi_collision_revision=4` 和当前 `platform_lekiwi_collision_recipe_sha256`，重载仍校验整臂 18 个碰撞源 STL（旧配方，包括 revision 3，必须从原始 URDF 重新转换）。再校验编译后的浮动根、关节/执行器、传动、轴向、限位、增益和力限等。缓存编辑继承当前显式 profile，校验失败保留旧场景但不恢复外部授权。七关节新臂不兼容旧接口，详见 [URDF 变体支持与控制边界](lekiwi-urdf-compatibility.md)。
启用机器人 profile 后，关节角仅作实测显示：禁止 `setJointPosition()` 或 `resetJoints()` 直接写 qpos，禁用关节拖动/单独重置关节，也禁止忽略关节限位；完整仿真 reset 的撤权/epoch 行为不变。旧滑条是暂停时的姿态编辑而非物理运动，任何碰撞体都不能防止这种直接插入。需要运动时播放仿真，通过执行器目标或外控驱动；普通非 profile 模型的姿态编辑不变，外控仍排斥手动执行器写入。
`modelFingerprint` 是最终输入 XML 字节的 SHA-256，不是语义哈希或所有 mesh 的合并内容哈希；资源另有 `source-manifest.json`。导出保留 `platform_robot_profile`、`platform_robot_profile_version`、`platform_robot_source_sha256`，并添加 `platform_robot_source_fingerprint` 追溯已加载源。重新序列化/导入会重新计算指纹；标记不是签名，也不能代替运行时校验。需要限定精确模型时设置插件的 `expected_model_fingerprint`。
`modelFingerprint` 是最终输入 XML 字节的 SHA-256，不是语义哈希或所有 mesh 的合并内容哈希；资源另有 `source-manifest.json`。导出保留 `platform_robot_profile`、`platform_robot_profile_version`、`platform_robot_source_sha256`（配方基准）和新转换模型的 `platform_robot_input_sha256`（实际 URDF 字节），并添加 `platform_robot_source_fingerprint` 追溯已加载源。重新序列化/导入会重新计算指纹；标记不是签名，也不能代替运行时校验。需要限定精确模型时设置插件的 `expected_model_fingerprint`。
## 停止、冻结与回滚
docs/website-api.md
+20
View File
@@ -0,0 +1,20 @@
# Website API 契约
网站模式与原本机 Bearer 模式分别启动，不自动降级。前缀 `/api/decision/v1`。
| 路径 | 方法 | 语义 |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------- |
| `/session` | POST | 同源 JSON 空对象建立/恢复会话，返回 CSRF、版本、设置状态；不调用模型 |
| `/session` | DELETE | CSRF 保护，取消任务、销毁凭据和订阅进程 |
| `/status` | GET | 当前会话状态、配置版本，不延长空闲寿命 |
| `/models` | GET | DeepSeek 固定型号及服务端缓存的 OpenRouter 结构化模型目录 |
| `/configuration` | PUT | 原子更新 `{llm:{provider,model,apiKey?},jev:{apiKey?}}`，拒绝其他字段 |
| `/plan`,`/decide`,`/test`,`/cancel` | POST | 沿用既有契约，作用域仅当前会话 |
| `/codex/status`,`/codex/models`,`/codex/limits` | GET | 会话独立订阅状态，无账号时不启动 CLI |
| `/codex/login`,`/codex/cancel`,`/codex/logout` | POST | 官方设备码登录、取消、退出；拒绝任意 RPC |
生产 Cookie 为 `__Host-cadworld-session; Secure; HttpOnly; SameSite=Strict; Path=/`，无 Domain。修改/推理携带 `X-CSRF-Token` 和 `X-Config-Version`，精确 Origin/Host 校验。开发 HTTP 只接受显式 `--website-dev` 与回环来源，用不同 Cookie 名，不改变生产要求。代理只信任配置的来源 IP，覆盖外来转发头。
省略 apiKey 表示同提供方保留内存密钥，换提供方必须重填；清除通过销毁整个会话完成。配置草稿不改变后台，保存不推理。并发标签页以配置版本拒绝旧配置。错误只返回稳定错误码，不回显上游文本。
会话空闲 30 分钟、最长 8 小时，状态轮询不续期。最多 128 会话，单会话 1 推理、全局 8 推理、2 Codex 账号；会话/IP/全局限流分别生效。浏览器模型 ZIP 不上传。真实 API/订阅验收必须由用户显式授权，不加载仓库 `.env`。
docs/website-deployment.md
+58
View File
@@ -0,0 +1,58 @@
# CADWorld Sim 网站部署与运维
目标：`https://cadworld-sim.robotquan.com`，主机 `root@47.93.31.109`。复用 1Panel 的 OpenResty，独立容器仅发布 `127.0.0.1:8768`。不安装训练/GPU 服务，不改系统 Python，不需要访问者开启终端。
## 产品边界
- 网站公开、无需注册。LLM 选择 DeepSeek/OpenRouter 并填写自己的 API_KEY；Jev 单独填写 OpenRouter API_KEY，型号固定 `typesafe/jev-1.13`。
- 保留 ChatGPT 官方设备码登录。当前主机对官方订阅端点的连通性不稳定，入口会诚实显示失败；订阅资格、额度和真实推理需要用户验证，不自动转收费 API。
- 密钥经 HTTPS 到后端，只在会话内存；浏览器输入保存后清空，不进入 URL/存储/日志。空闲 30 分钟或最长 8 小时销毁。关页不保证立即销毁，可点击“清除本次凭据”。同浏览器标签页共享会话，配置版本隔离旧任务；其他浏览器独立。
- ZIP/URDF/地图/物理仿真仍在浏览器。网站隐藏训练、调参和外控，浏览器 Python/ONNX 保留；本地 `npm run dev` 的旧功能不变。
- 容量：128 会话、每会话 1 推理/120 次每小时、全站 8 推理和 2 个订阅账号；按 IP 另有限额。匿名限制不是无限防滥用承诺，需持续观察负载。
- 备案已由站长确认；正式备案/公安备案展示号码由站长提供，不能编造。TLS 证书首次无邮箱注册，自动续期由 systemd timer 负责，建议管理员另行设置证书到期监控。
## 本地开发与测试
```bash
source .venv/bin/activate
python -m decision_server --website-origin http://127.0.0.1:5173 --website-dev
# 开发者另一个终端（仅开发时）：
npm run dev:website -- --host 127.0.0.1
npm run build:website # 输出 website-dist/，不含 tuning.html
npm run test:e2e:website # 真实后端 + 假 HTTP 上游，无 API 额度消耗
```
生产必须 HTTPS，不能携带 `--website-dev`。前后端 Origin 要一致；本机 Bearer 模式仍使用 `npm run decision-server`，两种模式不自动回退。契约见 [website-api.md](website-api.md)。
## 构建、传输与首次发布
1. 保留工作树变更基线，运行 TS/Vitest/Python/Playwright 门禁。`build/website-deployment/baseline/` 保存部署前工作树摘要，不包含 `.env`。
2. 使用 [官方 crane v0.20.6](https://github.com/google/go-containerregistry/releases/tag/v0.20.6)，校验 release checksums。将 `deploy/cadworld/images.lock.json` 中的 linux/amd64 digest 拉为 docker archive（`crane pull --platform linux/amd64 REF FILE`）；不需要本机 Docker daemon，也不让服务器访问不明镜像源。
3. 为 Python 3.12 下载 `requirements.lock.txt` 指定 wheels，验证 hash；从官方 npm `@openai/codex@0.147.0-linux-x64` 包验证 registry 的 integrity 后提取二进制。文件放在 `build/website-deployment/vendor/{wheels/,codex,codex-origin.json}`。不复制任何用户的 Codex HOME/auth.json。
4. `npm run build:website` 后运行 `python3 deploy/cadworld/prepare_bundle.py RELEASE`。脚本只打包显式白名单、生成每文件 SHA-256，并输出归档 SHA-256；不打包 `.env/.git/.venv/build/`、测试代码或个人模型。
5. SSH 传送归档、两份镜像 tar 和 SHA-256 到 `/opt/cadworld-sim/uploads/`。核验 SHA-256 后解压到 `/opt/cadworld-sim/releases/RELEASE/`，运行该版本的 `deploy/import-images.sh IMAGE_DIRECTORY`。先确认 `172.30.88.0/24` 不与现有 Docker 网络冲突。
6. 首次运行 `bash /opt/cadworld-sim/releases/RELEASE/deploy/bootstrap-tls.sh`：备份原 OpenResty conf，创建独立 HTTP challenge vhost，签发域名证书，安装 HTTPS vhost 与续期 timer。不修改默认站点/1Panel账号；已存在同域名配置则拒绝覆盖。
7. `bash /opt/cadworld-sim/releases/RELEASE/deploy/publish.sh RELEASE`：逐文件验 hash、离线构建、启动最小权限容器、健康检查、原子切换静态目录、`nginx -t`、reload。失败恢复上一版本，首次失败撤下新 vhost 恢复默认站点。成功生成 `current.txt/previous.txt/image-id.txt`。
只有 80/443 提供网站流量；8768 绑定回环。不挂载 Docker socket、SSH key、宿主 HOME；应用非 root、只读根、tmpfs、2 GiB/2 CPU/128 PID 限制。证书在已有 OpenResty www 挂载下独立 `ssl/`，不在站点 document root 内。
## 日常操作（目标主机）
```bash
cd /opt/cadworld-sim
docker compose --env-file release.env -f compose.yaml ps
docker compose --env-file release.env -f compose.yaml logs --tail 100 decision
curl -H 'Host: cadworld-sim.robotquan.com' http://127.0.0.1:8768/healthz
systemctl status cadworld-certificate.timer
bash /opt/cadworld-sim/renew-certificate.sh --dry-run
# 后台更新/重启会销毁所有临时凭据，用户需要重新输入/登录：
docker compose --env-file release.env -f compose.yaml restart decision
# 回滚：取 previous.txt 中的具体版本，调用那个版本的发布脚本，前后端一起恢复。
bash /opt/cadworld-sim/releases/PREVIOUS/deploy/publish.sh PREVIOUS
```
不要在 1Panel 重复创建同域名覆盖手工 vhost，不要将开发服务器或后台端口直接暴露公网。不要打印完整 Cookie、请求体、API_KEY、设备码或 OAuth 链接来排障。应用和 API 访问日志不记录请求正文；会话异常仅返回稳定错误码。
## 验证边界
普通测试使用假上游，不证明云端模型可用；mock 抓放使用真实 WASM 物理，不证明真实 LLM/Jev 被调用。真实 API 测试必须由用户明确提供密钥并触发，订阅登录须在官方页面交互。`HEAD` 的 200/401/403/404 只作为连通性证据，不是 POST 推理成功。生产证书、重启/回滚及浏览器验证结果另见实际发布记录。
docs/website-release-2026-09-23.md
+53
View File
@@ -0,0 +1,53 @@
# CADWorld Sim 发布记录 · 2026-09-23
**网站已上线：<https://cadworld-sim.robotquan.com>。代码/部署及公网非付费验收已完成；真实 API 验收等待用户自带测试密钥。**
## 当前版本
- 当前发布：`20260923T130923Z-web`
- 可回滚发布：`20260923T125007Z-web`
- 应用镜像：`sha256:f3375d42b54f6bbdb65d31ba275d6fd6c415917b71a2f01f4cdb6893d9f1678c`
- 主机：`47.93.31.109`，复用现有 1Panel/OpenResty；应用仅绑定 `127.0.0.1:8768`。
- Let's Encrypt 域名证书有效至 **2026-12-22**，完整验证链通过；续期 timer active，ACME dry-run 成功。
- `cadworld-sim-decision-1` healthy；异常退出自动重启已实测，重启后旧会话返回 401。检查时容器约 30 MiB/2 GiB（非并发峰值基准）。
- 已完成“当前→上一版→当前”的前后端成对回滚演练；1Panel、Docker、证书 timer 保持正常。
## 已验收
| 项目 | 实际结果 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| TypeScript / ESLint / Python Ruff / diff whitespace | 通过 |
| Vitest | 130 文件、611 项通过 |
| 决策服务 | 39 项通过，含固定版本原生 Codex 离线门禁 |
| 训练服务（保留的本地功能） | 126 项：102 通过、24 可选跳过 |
| 控制桥（保留的本地功能） | 16/16 通过 |
| 原工作台/地图浏览器回归 | 92 通过、6 既有可选跳过 |
| 原本地 LeKiwi 工作台 | 导入、单技能暂停/继续、物理成功、导出/重置与目标编辑回归通过 |
| website 生产构建＋真实网关/假 HTTP 上游 | 2/2：设置、CSRF/Cookie、双浏览器隔离及真实 WASM mock 抓放 |
| 公网 HTTPS 浏览器 | 3/3：模型导入、Python/Pyodide 控制、精简设置、订阅边界探测、真实 WASM mock 抓放 |
| 公网暴露边界 | `.env`、`tuning.html`、物理夹具、训练 API 均 404；未建会话的模型状态 401；8768 外部直连失败 |
| HTTPS 静态策略 | HTML no-cache、hash 资源缓存、WASM MIME、安全头与无 mixed-content/跨站模型请求通过 |
最终公网抓放结果：明确为 **mock 决策＋真实 MuJoCo 物理**，仿真 `47.220 s`，有效持物搬运 `0.5937274 m`，目标支撑成立、最终两指力均为 0；模型推理请求数 **0**。不能把它称为真实 LLM/Jev 成功。
订阅官方入口实际返回 **502 / `codex_rpc_failed`**，未提供设备码、未登录账号、未调用推理。测试结束销毁会话返回 200。入口保留并明确报错，不自动切付费 API；按用户接受的边界不阻塞网站上线。
## 尚未验收与限制
1. 本次没有读取既有 `.env`、没有借用任何管理员 API_KEY 或全局 Codex 登录。DeepSeek/OpenRouter 的真实规划与 Jev 完整回合需用户在网站填写自己的测试密钥后显式触发；计划第 9 步因此仍有待完成部分。
2. 订阅真实登录和推理未通过，当前只验证明确不可用及清理逻辑；不承诺这台大陆主机对官方订阅网络/账号资格的支持。
3. 网站不含 RL 训练、奖励调参、外控服务；原本地代码保留。LeKiwi 个人 ZIP 未发布到服务器，用户仍需自行导入。
4. 站长已确认备案，具体备案/公安备案公示号码尚未提供，页面不能编造，需后续补充。
5. 全仓格式检查仍仅报告四个既有文件：两份 `.pytest_cache/README.md` 与 `contracts/fixtures/{mobile-golden,mobile-motion-v2-golden}.json`；未覆盖原有工作。
6. 2026-09-23 上线时未提交或推送 Git；2026-09-24 按用户要求将当前源码归档为 `v1.0.1` 本地提交/标签，未推送远端。原有工作一并保留，基线清单中没有文件被删除；此次 Git 归档不重新部署服务器，也不改变待完成的真实 API 验收。
## 证据与运维
- 工作树和服务器基线：`build/website-deployment/baseline/`
- 发布白名单和逐文件哈希：`build/website-deployment/bundles/20260923T130923Z-web/manifest.json`
- 最终测试及 screenshots：`build/website-deployment/{e2e-final,production-final,local-agent-regression}/`
- 续期：`build/website-deployment/certificate-dry-run-second.txt`
- 回滚/恢复：`build/website-deployment/{rollback-roundtrip,recovery-second}.txt`
- 操作手册：[website-deployment.md](website-deployment.md)；API 契约：[website-api.md](website-api.md)。
保留了早期失败证据：首次续期探针因 Certbot 自带随机延迟超出检查窗口，已改为 timer 自行抖动、客户端关闭随机睡眠后复测成功；首次崩溃探针将 Tini 连带终止 exec 的 137 误判为失败，修改探针判断后证明真实自动重启与会话销毁。没有把失败日志用后续成功覆盖。