按关节槽位驱动 13 个五轴案例的三维模型

关节契约扩为槽位制：以 LinuxCNC 联合号标识关节，轴字母降为槽位属性，重复轴（bridge-mill 的两个 Y）、并联杆长（hexapod/pentapod）和被动槽位（max5 第 6 关节）都能表达。v1 规则保持不变并合成 jointOrder，已保存 GLB 与既有测试不受影响。 13 个结构 GLB 由 scripts/generate_physical_case_glbs.mjs 统一重建，可动关节均为按槽位命名的 Group 并写 userData.linuxcncJoint，共 71 个关节，槽位数与运行目录的 joint_count 逐条一致。新增 machine-visual-bindings.json 与纯函数模块，以 machine id 为键：坐标字母不能作键，因为三个案例共用 XYZAB、三个共用 XYZABC。主界面切换案例时自动装载对应模型，失败时保留内置模型并显式提示。消除前端五关节截断：visual 适配器的 joints 改为数组并新增 jointsAuthoritative；allHomed 按 joint_count 判断；面板按 worker 断言的 machine id 查找机型。管理器解锁：坐标与案例下拉以"存在完整视觉绑定"为启用条件，13 案例全部可选；machine-urdf.ts 新增 generic-wasm/1 profile，AC/BC 严格校验路径不变；新增 machine-kinematics-specs.json 保存逐关节限位，INI 未声明的限位保持 null 而不编造。修复三个真实缺陷：构建漏发 woodpecker/gmoccapy/qtdragon 配置目录（ DEFECT-02 根因）；案例切换沿用"装载需要已上电"的门控，导致关机状态下第二次切换被静默拒绝；重复轴机型上 React 列表键冲突。验收：13 案例逐个切换装载成功、槽位键与绑定定义逐一一致、浏览器错误 0； typecheck 与生产构建通过；视觉绑定、GLB 命名、关节契约、投影、store、双画布、运动学规格漂移、11 案例 Worker 闭环、管理器浏览器回归全部通过。证据在 coverage/glb-machine-manager/physical-drive/。 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-30 06:09:12 +08:00
parent af65b69b2c
commit db29ae625f
157 changed files with 11936 additions and 885 deletions
--- a/docs/glb-machine-manager/00-三维机床管理详细功能文档.html
+++ b/docs/glb-machine-manager/00-三维机床管理详细功能文档.html
--- a/docs/glb-machine-manager/00-三维机床管理详细功能文档.md
+++ b/docs/glb-machine-manager/00-三维机床管理详细功能文档.md
@@ -0,0 +1,326 @@
+# 三维机床管理详细功能文档
+
+> 文档编号：GLB-MGR-FRS-001  
+> 版本：1.0  
+> 状态：功能基线  
+> 适用范围：LinuxCNC Web/WASM 控制面板的部件级三维机床管理器
+
+## 1. 文档目的
+
+三维机床管理器用于把多个自包含 GLB 部件装配为可预览、可标定、可保存、可重新打开并可交给 LinuxCNC Web/WASM 运行的机床模型。用户在一个对话框内完成机型选择、部件导入、层级编辑、坐标校准、轴绑定、运动验证和模型保存；控制面板继续负责程序、Jog、回零、RTCP 和实际运动。
+
+本文件是产品功能和验收的总说明。字段的机器可读定义以 [`joint-model.schema.json`](joint-model.schema.json) 为准，实施步骤见 [`02-项目程序开发详细步骤.md`](02-项目程序开发详细步骤.md)，已完成项和证据见 [`04-任务矩阵.md`](04-任务矩阵.md) 与 [`05-验收证据.md`](05-验收证据.md)。
+
+## 2. 目标与边界
+
+### 2.1 目标
+
+- 在机床预览区提供“三维机床管理”入口和独立配置工作区。
+- 支持原生 XYZAC/XYZBC TRT，以及通过通用 WASM 运动学桥接接入的双转台、Bridge Mill、MAX5、Hexapod、Pentapod、PUMA、trivkins 和 SCORBOT 案例。
+- 保留每个 GLB 的原始字节、材质、几何、内部层级和导入变换；编辑结果以装配草稿保存。
+- 使预览中的节点运动、导出的 GLB、URDF/几何参数和 WASM 实际关节快照使用同一套轴映射和标定数据。
+- 提供浏览器下载和当前站点本地机床库两种保存方式，并可在刷新后恢复已保存版本。
+- 对工业级复杂模型提供统一 64 MiB GLB 限额，并将“几何模板、运动学适配、控制器可运行、实机标定”作为独立状态展示，防止把可查看模型误认为可安全运行配置。
+
+### 2.2 明确边界
+
+- 管理器是模型装配和标定工具，不是第二套运动学求解器。
+- Three.js 只负责模型、坐标辅助、轨迹投影和相机；正式运动权威始终是 Worker/WASM 快照。
+- TRT 管理器应用仍严格校验两条控制链；通用运动学案例通过各自机型运行配置和 WASM 求解器执行，不套用 TRT 链。
+- 不实现碰撞检测、质量/刚体动力学、任意 URDF 求解、云端同步、权限审批或真实硬件控制。
+- 64 MiB 是当前浏览器交付边界，不代表任意工作站都可流畅预览该上限模型；节点数、纹理显存及设备能力仍需分别校验。
+
+## 3. 使用角色与典型场景
+
+| 角色 | 主要任务 | 结果 |
+|---|---|---|
+| 机床设计人员 | 导入部件、调整层级、定义原点和轴向 | 可复用的机床设计草稿 |
+| 工艺/调试人员 | 设置 RTCP 参数、物理零点、试动和实时跟随 | 已标定的 AC/BC 视觉模型 |
+| 操作人员 | 打开已保存模型并导入控制面板 | 与目标机型匹配的运行配置 |
+| 验收人员 | 检查结构、坐标、导出文件和程序一致性 | 可追溯的验收报告 |
+
+典型流程是：新建机床 → 选择 XYZAC/XYZBC → 导入部件 → 编辑树和局部变换 → 绑定轴 → 输入 RTCP/物理零点 → 试动和校验 → 保存/导出 → 应用到控制面板 → 回零后运行程序。
+
+## 4. 工作区与界面功能
+
+### 4.1 入口和工作区布局
+
+控制面板机床预览区提供以下入口：
+
+1. **三维机床管理**：新建或编辑当前草稿。
+2. **打开已保存机床**：从文件选择器或本地机床库恢复完整 GLB。
+3. **编辑控制面板机床**：将当前已应用的受支持模型回填到管理器。
+4. **导入机床模型**：在控制器空闲且允许切换时载入已保存 GLB。
+
+管理器采用固定预览区、可滚动配置区和固定底部操作区。配置区分为四个页签：
+
+| 页签 | 内容 | 主要操作 |
+|---|---|---|
+| 结构 | 模型列表、GLB 树、搜索、显隐、父级拖放、删除 | 导入部件、选节点、改父级、显示原点 |
+| 运动 | 轴绑定、单自由度、方向/正负、单轴步进、实时跟随 | 配置 XYZABC、试动、锁定跟随 |
+| 标定 | C 原点、A/B 偏置、物理零点、机型检查 | 输入毫米/度参数、查看校验状态 |
+| 文件与恢复 | 名称、说明、保存、打开、本地版本、下载 | 导出 GLB、恢复、删除版本 |
+
+预览工具栏至少包含：选择节点、显示/隐藏原点、显示/隐藏网格、视图预设（等轴测、顶视、前视、侧视、适配整机）、缩放、重置相机和渲染状态提示。
+
+### 4.2 状态提示
+
+工作区必须能区分以下状态：`未保存草稿`、`校验通过`、`不可应用`、`已应用`、`已导出`、`实时跟随中`、`导入失败`、`渲染暂停`。错误提示显示在产生错误的页签和底部汇总区，不能只写入控制台。
+
+## 5. 详细功能需求
+
+### FR-01 机型选择
+
+1. 新建对话框第一步必须选择设计机型 `XYZAC` 或 `XYZBC`。
+2. 设计机型保存在草稿中，不随控制面板之后的机型切换被覆盖。
+3. XYZAC 只允许绑定 X、Y、Z、A、C；XYZBC 只允许绑定 X、Y、Z、B、C。
+4. 切换机型时保留通用部件和标定草稿，清除不兼容倾转轴绑定并提示用户；操作可撤销。
+5. 打开完整机床 GLB 时以文件中的机型为准，并把打开动作作为一次可撤销的草稿替换事务。
+
+### FR-02 GLB 部件导入
+
+1. 支持逐个导入自包含 `.glb` 文件，也支持导入已有完整机床 GLB。
+2. 导入前计算 SHA-256，记录文件名、大小、哈希和源节点路径。
+3. GLB 必须能够在无外部网络和无额外文件的情况下解析；外部纹理、外部网格和无法解析的资源必须拒绝。
+4. 同一文件可作为一个部件导入，不能因名称相同覆盖已有部件；每个部件获得稳定 ID。
+5. 导入失败时保留已有草稿、树和预览；已应用模型不发生变化。
+6. 删除部件时从树、预览和配置中移除，并释放其几何、材质、纹理和辅助对象。
+
+### FR-03 GLB 层级树与装配
+
+1. 右侧树必须按解析后的 `Object3D.children` 原始结构显示，不按中文名称推断身份。
+2. 节点 ID 使用部件 ID 加稳定源路径；名称可以重复，ID 不得重复。
+3. 根部件之间允许设置装配父级；同一 GLB 内部节点允许设置内部父级。
+4. 拖放换父级时默认保持节点世界姿态，并重新计算相对新父级的局部变换。
+5. 必须拒绝自指、循环、无效父级、跨 GLB 直接挂接内部节点和产生重复角色的结构。
+6. 树支持搜索、展开/折叠、定位预览、显示/隐藏和选中高亮。
+7. 选中节点时显示其直接父级、稳定路径、局部原点、当前局部变换和绑定自由度。
+
+### FR-04 部件局部原点与变换
+
+1. 部件和内部节点均可编辑相对父级的平移 `X/Y/Z`（mm）和欧拉姿态 `Rx/Ry/Rz`（deg）。
+2. 旋转中心为当前节点自己的局部 `(0,0,0)`；子节点继承父节点变换，父节点和兄弟节点不被改写。
+3. 输入框回显当前有效值；空值、非数字、超出有限数范围的输入不驱动模型。
+4. 数值变换和操纵器（如启用）必须写入装配草稿，不改写源 GLB 字节。
+5. 管理器使用机床 Z-up 视图：`camera.up = (0,0,1)`，XY 为地面；导入 GLB 的原始 Y-up 节点、几何、材质、层级和原始变换不得被隐式旋转。
+
+### FR-05 原点和局部坐标辅助
+
+1. 每个部件可单独显示/隐藏原点辅助线。
+2. 选中关节节点时，XYZ 彩色辅助轴必须作为该节点的子对象挂在局部 `(0,0,0)`。
+3. 辅助轴随节点自身旋转以及全部父链变换，不得显示为固定的世界轴。
+4. 辅助对象不参与导出模型，不改变节点包围盒和轴绑定。
+
+### FR-06 单自由度轴绑定
+
+1. 每个运动节点只能绑定一个 XYZABC 自由度；固定节点选择“固定/无自由度”。
+2. 每个数控轴最多绑定一个节点；轴绑定以稳定节点 ID 保存，不能按节点名称或树排序推断。
+3. 平移轴 X/Y/Z 的单位为 mm；旋转轴 A/B/C 的单位为 deg。
+4. 方向为父坐标系中的单位轴 `x/y/z`，并提供正向/反向 `sign=+1/-1`。
+5. 节点保留导入后的零姿态；试动值不能被烘焙为新的零姿态。
+6. 绑定不完整或重复时允许保存草稿，但禁止应用到控制器和导出为可运行完整机床。
+
+### FR-07 轴值试动与实时跟随
+
+1. 运动页提供每个已绑定轴的单值输入和步进按钮；试动只修改管理器草稿，不发送 LinuxCNC 运动命令。
+2. 试动输出至少包含节点局部位置、世界位置、四元数和当前轴值，便于检查父子继承。
+3. 可开启“跟随数控系统实时关节位置”；开启后手动轴输入锁定。
+4. 实时值只来自当前机型有效的 Worker/WASM 快照。缺少任一必需轴值时整帧拒绝，不对部分节点更新。
+5. 关闭跟随后恢复当前草稿姿态；跟随期间不改变零姿态、物理零点或保存文件。
+6. 运动变换每帧从零姿态绝对计算，不使用累加平移/旋转，避免长期运行漂移。
+
+### FR-08 RTCP 几何标定
+
+标定页提供 C 轴原点和倾转轴偏置，单位均为 mm：
+
+- C 原点 `P = (x-rot-point, y-rot-point, z-rot-point)`。
+- A/B 偏置 `D = (x-offset, y-offset, z-offset)`。
+- 倾转关节原点 `T = P + D`。
+- C 关节原点 `U = -D`。
+- 工件固定原点 `work = -P`。
+
+应用时把标定写入整机场景和底座节点 `userData.linuxcncMachineGeometry`，同时生成现有运行链可识别的 URDF/配置结构。管理器不得用外观平移代替 RTCP 参数。
+
+### FR-09 物理零点
+
+1. 为当前机型的 X/Y/Z/A或B/C 分别输入模型零姿态对应的物理读数。
+2. 渲染量按 `d = sign × (WASM实际关节值 - physicalZero)` 计算。
+3. 物理零点只用于模型校准，不修改 Worker、INI、回零位置或程序坐标。
+4. 缺失、非有限或与机型轴集合不匹配时禁止应用，并显示具体轴名。
+
+### FR-10 预览与渲染
+
+1. 预览支持选择、高亮、相机轨道控制、视图预设、适配整机、网格和辅助轴。
+2. 使用 PMREM/色彩管理/曝光/补光提升高金属度 GLB 的可辨识度，不覆盖资产材质参数。
+3. WebGL drawing buffer 同时受设备最大纹理尺寸和像素预算限制；不依赖超限 MSAA。
+4. 零尺寸或 context lost 时暂停绘制并显示可恢复状态，不连续提交无效 render。
+5. 预览相机变化不修改节点、轴值、WASM tick、程序状态或保存数据。
+
+### FR-11 校验与应用
+
+应用按钮必须按顺序执行：
+
+1. 校验机型、节点 ID、父级、无环结构和部件资源。
+2. 校验底座、X、Y、Z、刀具、A/B、C、工件角色的唯一性和受支持机械链。
+3. 校验轴绑定唯一、方向/正负/零姿态/标定数值有限，且机型轴集合完整。
+4. 校验 GLB、URDF、几何参数和关节 JSON 的版本与哈希关系。
+5. 生成运行装配的深复制场景，写入 `linuxcncMachine`、`linuxcncMachineGeometry` 和 `linuxcncJointModel`。
+6. 通过既有 `LOAD_WORKSPACE`/配置重载事务交给 Worker；失败时回滚到旧模型和旧机型。
+7. 应用成功后要求重新回零；程序运行、Jog、刀长和路径继续使用 WASM 权威状态。
+
+### FR-12 保存、导出和重新打开
+
+1. “保存机床模型 GLB”生成新的自包含完整 GLB；不覆盖任何源部件文件。
+2. 导出文件包含部件几何、层级、显隐、节点局部变换、机型、轴绑定、方向、正负向、RTCP 标定、物理零点和编辑元数据。
+3. 文件写入浏览器下载，同时尝试写入当前站点 IndexedDB 机床库；库保存失败不能阻止下载。
+4. 机床库显示名称、说明、机型、保存时间、大小和 SHA-256；每次保存形成独立版本。
+5. 重新打开时恢复多部件分组、源节点路径、拖放覆盖、局部变换、显隐、辅助轴、轴绑定、标定和机型。
+6. 导入完整机床 GLB 时先重建源节点树，再应用覆盖配置，防止重复平移或重复旋转。
+7. 普通几何 GLB 走“导入 GLB 部件”；带完整编辑元数据的 GLB 走“打开已保存机床”。
+
+### FR-13 机型与程序一致性
+
+1. 同机型打开/应用时保留兼容程序和标定。
+2. 跨 XYZAC/XYZBC 导入或应用时，先读取目标机型默认程序，再提交工作区切换。
+3. 错轴程序在加载、运行、单步和继续入口均由 Worker 拒绝；不能通过文本替换 A/B 伪造适配。
+4. 控制面板当前机型不能覆盖已打开草稿的设计机型；程序、预览、运行状态必须属于同一机型。
+
+### FR-14 撤销、重做和取消
+
+1. 草稿历史保存配置快照，至少支持 30 步撤销/重做。
+2. 关闭文件选择器或取消选择时，父对话框保持打开、原配置和焦点保持不变。
+3. 打开完整模型是一次替换事务；失败或取消时恢复打开前草稿。
+4. 关闭对话框不等同于应用；未应用草稿不能改变控制器当前模型。
+
+## 6. 数据契约与单位
+
+### 6.1 三层 userData
+
+| 字段 | 用途 |
+|---|---|
+| `userData.linuxcncMachine` | 现有严格 URDF/运行控制框架 |
+| `userData.linuxcncMachineGeometry` | C 原点、A/B 偏置、物理零点和几何标定 |
+| `userData.linuxcncJointModel` | `linuxcnc.joint-model/1` 的节点、父链和视觉轴映射 |
+| `userData.linuxcncMachineEditor` | `linuxcnc.machine-editor/1` 的名称、说明、源部件和编辑覆盖 |
+
+### 6.2 核心字段
+
+| 字段 | 规则 |
+|---|---|
+| `coordinates` | `XYZAC` 或 `XYZBC` |
+| `controller.axisOrder` | AC 为 `[X,Y,Z,A,C]`，BC 为 `[X,Y,Z,B,C]` |
+| `axisMap` | 数控轴名到稳定节点 ID 的唯一映射 |
+| `nodes[].parentId` | 直接父级；根节点为 `null` |
+| `nodes[].zero` | 位置（m）、四元数 `[x,y,z,w]`、比例 |
+| `nodes[].joint` | `null` 或一个 `dof=1` 的平移/旋转关节 |
+| `joint.direction` | 父坐标系中的 `x/y/z` |
+| `joint.sign` | `+1` 或 `-1` |
+| `calibration.physicalZero` | 各轴模型零姿态的实际读数 |
+
+UI 平移、局部原点、C 原点和偏置使用 mm；UI 旋转和物理旋转轴零点使用 deg；GLB/glTF 节点长度为 m、旋转为弧度；URDF 长度为 m、旋转为弧度。转换必须集中在适配层，不能由各组件自行猜测。
+
+### 6.3 视觉驱动公式
+
+设 WASM 实际轴值为 `q`，物理零点为 `q0`，正负为 `s`，父坐标系单位方向为 `e`：
+
+- 平移节点：`position = zero.position + e × s(q-q0)`。
+- 旋转节点：`rotation = Quaternion(e, s(q-q0)) × zero.quaternion`。
+- 子节点继承父级世界矩阵；父节点和兄弟节点不因本节点输入改变。
+
+正式控制器仍使用已有 AC/BC TRT 运动学；关节 JSON 只描述视觉层级如何跟随实际关节。
+
+## 7. 权威边界与状态流
+
+```text
+用户输入/文件
+      ↓
+MachineDraft（React 本地草稿）
+      ↓ 校验通过
+运行装配 + URDF + geometry + joint-model
+      ↓ LOAD_WORKSPACE / 配置重载
+Worker/WASM（唯一运动权威）
+      ↓ snapshot: joints / pose / tool / path
+Three.js 预览（只读投影）
+```
+
+草稿可以驱动管理器中的诊断试动，但不能直接写 HAL、发送 Jog 或修改 WASM 指针。正式模型的每次姿态更新都必须带有对应 snapshot 的 tick/state hash；React 状态只保存展示和编辑数据。
+
+工作区状态转换为：
+
+```text
+new → editing → structurally-valid → controller-valid
+                         ↓                 ↓
+                    exportable          applied → homing-required → running
+```
+
+任何导入、校验、应用或保存失败都回到失败前的稳定状态，并保留可定位错误码。`applied` 之前的草稿不可影响正在运行的控制器。
+
+## 8. 错误处理要求
+
+| 场景 | 用户可见结果 | 数据结果 |
+|---|---|---|
+| 外部资源 GLB | “仅支持自包含 GLB”及文件名 | 拒绝导入，旧草稿不变 |
+| 重复轴/角色 | 指向轴或角色的字段错误 | 禁止应用和运行 |
+| 循环/跨文件非法拖放 | 树节点错误提示 | 拖放回滚 |
+| 非法数值 | 输入框标红并保留上一个有效姿态 | 不驱动预览、不写入导出 |
+| 缺少快照轴值 | “等待完整关节快照” | 保持上一帧姿态 |
+| URDF/Schema 不匹配 | 显示版本/字段错误 | 不替换已应用模型 |
+| IndexedDB 保存失败 | 提示本地库失败并提供下载 | 下载继续，当前草稿保留 |
+| WebGL context lost | 显示渲染暂停和恢复按钮 | 轴值、草稿和控制器状态不变 |
+| 跨机型程序不兼容 | 指出目标机型和冲突轴 | 加载、运行、单步、继续均拒绝 |
+
+## 9. 非功能要求
+
+- **可追溯性**：保存源文件名、SHA-256、节点稳定路径、schema 版本、机型和导出时间。
+- **确定性**：同一源 GLB、同一草稿和同一 snapshot 必须得到相同局部/世界变换和导出元数据。
+- **资源安全**：加载、删除、重开和撤销不能持续泄漏几何、材质、纹理、辅助对象或 WebGL buffer。
+- **性能**：相机操作和模型姿态更新不阻塞 Worker tick；重复更新从零姿态计算，不累积矩阵误差。
+- **响应式**：桌面、窄屏和矮屏均能访问树、配置页签和底部操作；预览不可遮挡校验错误。
+- **兼容性**：保留现有整机 GLB+URDF 导入路径；旧文件缺少编辑元数据时按兼容模式恢复已有装配、轴和标定。
+- **离线**：已保存到本地机床库的文件不依赖网络即可打开；外部资源不得在运行时偷偷下载。
+
+## 10. 验收清单
+
+### 功能验收
+
+- [ ] AC 和 BC 均可由多个独立部件建立，完成结构、运动、标定和应用。
+- [ ] 树节点可搜索、拖放、删除、显示/隐藏，并正确拒绝循环和跨 GLB 非法关系。
+- [ ] 节点局部平移/旋转、局部坐标轴和子节点继承结果正确。
+- [ ] 单自由度绑定支持轴方向、正负号、物理零点和实时 WASM 跟随。
+- [ ] RTCP C 原点、A/B 偏置和物理零点写入相应 userData 字段，并可重新打开。
+- [ ] 导出 GLB 自包含，重新导入后配置与导出前等价。
+- [ ] 跨机型导入使用目标默认程序，错轴程序在 Worker 入口拒绝。
+- [ ] 保存、下载、IndexedDB、本地库恢复、取消文件选择器和失败回滚均可操作。
+
+### 一致性验收
+
+- [ ] 控制面板程序、Jog、回零、刀长、路径和模型姿态来自同一 Worker/WASM 快照。
+- [ ] Three.js 相机或诊断试动不会修改控制器状态。
+- [ ] 应用失败不替换旧模型；应用成功后要求重新回零。
+- [ ] 预览、组合 GLB、URDF 和 JSON 使用同一父级局部变换和轴映射。
+
+### 工程验收
+
+- [ ] TypeScript 类型检查和生产构建通过。
+- [ ] GLB 资源生命周期、Schema、URDF、AC/BC 运动、MILL700 深层父子节点和浏览器响应式场景有自动化证据。
+- [ ] 浏览器控制台无未处理异常；WebGL 零尺寸、context lost 和短视口 DPR 场景有报告。
+- [ ] 验收命令、报告、截图和哈希同步写入 [`05-验收证据.md`](05-验收证据.md)。
+
+## 11. 不属于本版本的功能
+
+- 任意五轴/机器人/并联机型的自动运动学推导。
+- 碰撞、干涉、质量、惯量、刚体动力学和切削材料去除仿真。
+- 云端机床库、跨浏览器同步、多人协作和权限审批。
+- 通过视觉层级编辑直接修改 INI 行程、速度、回零或控制器物理参数。
+- 以 JavaScript/Three.js 计算并替代 LinuxCNC 的 RTCP 逆解、前瞻或轨迹规划。
+
+## 12. 关联文档
+
+- [项目功能内容](01-项目功能内容.md)
+- [项目程序开发详细步骤](02-项目程序开发详细步骤.md)
+- [任务矩阵](04-任务矩阵.md)
+- [验收证据](05-验收证据.md)
+- [决策记录](06-决策记录.md)
+- [单自由度 JSON 与实时驱动](07-单自由度JSON与实时驱动.md)
+- [保存与重新打开机床](08-保存与重新打开机床.md)
+- [关节 JSON Schema](joint-model.schema.json)
--- a/docs/glb-machine-manager/01-项目功能内容.md
+++ b/docs/glb-machine-manager/01-项目功能内容.md
@@ -35,7 +35,8 @@

 ## 安全边界

- 当前只生成项目已有求解器支持的 XYZAC 或 XYZBC 双分支 TRT 结构。
+- TRT 结构生成仍限定 XYZAC/XYZBC，走原有严格 URDF 校验。其它 11 个案例使用 `generic-wasm/1` URDF profile：link/joint 数量与父子链由 `machine-kinematics-specs.json` 派生，不再要求固定链；其运动学仍完全来自 WASM，管理器只负责装配与标定。
+- 关节标识是 LinuxCNC 联合号（槽位），轴字母只是槽位属性。因此重复轴（`bridge-mill` 的两个 Y）、并联杆长（`hexapod`/`pentapod`）、被动槽位（`max5` 的第 6 关节）都能表达，坐标字母不再作为机型键（三个案例共用 XYZAB、三个共用 XYZABC）。
 - 层级编辑器允许建立关系，但“应用到控制器”前必须严格验证两条受支持机械链、角色唯一性和无环结构。
 - 未完成八个角色时允许预览和保存草稿，不允许应用到控制器。
 - 模型外观变换不能代替 INI/运动学参数；C 原点和 A/B 偏置必须通过现有配置重载进入 WASM。
@@ -60,3 +61,10 @@
 19. MGR-20：导入/应用跨机型模型时同步加载目标机型默认 G 代码，程序路径、源码、预览与运行机型保持一致；同机型标定保留兼容程序。不兼容轴程序在加载及执行入口拒绝。

 20. MGR-21 文档管理：新建、打开已保存机床、编辑控制面板机床；模型名称/说明；保存 GLB 同时提供浏览器下载和本地机床库副本；刷新后从库恢复，多部件文件分组、节点路径、层级覆盖、显隐、关节和标定完整回填。
+
+21. 工业模型容量：部件导入、完整机床解析、控制面板导入与组合 GLB 导出共享 64 MiB 上限；拒绝时保留现有草稿/运行机床并给出可执行的减面、纹理压缩或拆分建议。外部资源和超过 10,000 节点的 GLB 仍拒绝，容量提升不绕过结构校验。
+
+22. 工业机床案例与工作流：案例资料明确标注“可直接运行、可作几何模板、需运动学适配、仅源码参考”状态；真实/演示资产来源、授权、单位、坐标系、机型、关节映射、限位/零点是否来自实测需可追溯。案例几何不能被描述为实机标定数据；从案例创建草稿必须保留来源并要求操作者复核轴向、零点、限位及 RTCP 参数后才可应用。
+
+23. 每个五轴案例必须提供独立坐标限定的低幅干运行 G 代码，记录案例 ID、机型/关节坐标、运动学和 Web 可用状态。Web 控制器按程序绑定的机型加载对应运行配置；XYZAC/XYZBC 使用原生 TRT，另外 11 个案例使用通用 WASM 运动学桥接，不再按错误 TRT 执行。程序使用 G21、G90、G94、安全高度/小行程 G0/G1，不启用主轴、刀具更换或切削。
+24. 案例状态须区分资产/程序已创建、原生 LinuxCNC 来源存在、Web 配置已注册、WASM 运动学已接通、控制面板浏览器运行已验证。前序状态不能推导后序状态；本仓库现状只有 XYZAC/XYZBC 已完成 Web 面板运行闭环。
--- a/docs/glb-machine-manager/03-推进台账.md
+++ b/docs/glb-machine-manager/03-推进台账.md
@@ -133,3 +133,14 @@
 - 修复原生文件选择器 Cancel/项目 Escape 与父 native dialog 的取消事件串扰；文件选择期间父对话框以 cancelGuard 保持打开。
 - 三维管理“导入 GLB 部件”“打开已保存机床”、机床导入模型和机床参数导入统一保护；取消后草稿、选择节点、页签和配置不变。
 - E18 工作台回归新增真实 filechooser 取消验证，浏览器错误 0。
+
+## R17 / 2026-10-29 / 13 案例槽位化真实三维驱动
+
+- 关节契约为 `linuxcnc.joint-model/2`：以 LinuxCNC joint 号为槽位标识，轴字母成为槽位属性。`validateJointModel` 同时接受 v1 与 v2，v1 原规则不变并合成 `jointOrder`，已保存 GLB 与既有测试不受影响。
+- 13 个结构 GLB 由 `scripts/generate_physical_case_glbs.mjs` 重新生成：每个可动关节是 Group，名字对应槽位，写 `userData.linuxcncJoint{index,key,axis,type,unit,direction,sign,source}` 与场景级 `linuxcncPhysicalStructure`；共 71 个关节，与 `machine-catalog.json` 的 `joint_count` 逐条一致。
+- 新增 `machine-visual-bindings.json` 与纯函数模块 `machine-visual-bindings.mjs`：以 machine id / entrypoint 为键，坐标字母不作键（三个案例共用 XYZAB、三个共用 XYZABC）。校验覆盖 13 案例、槽位连续性、槽位数与运行目录一致、GLB 存在且 ≤64 MiB、节点逐槽可缺省报告。
+- 主界面 `loadCase` 在 `LOAD_WORKSPACE` 成功后按绑定配置装载对应结构 GLB；失败保留内置模型并显式提示。`loadImportedMachine` 增加绑定优先路径，`buildImportedMachine` 增加自包含 v2 装配分支，按槽位数组驱动。
+- 前端截断消除：`xyzac-visual-adapter.ts` 的 `joints` 改为数组并新增 `jointsAuthoritative`；`App.tsx` 的 `allHomed` 改为按 `joint_count` 判断；`xyzac-panel-contract.ts` 优先按 worker 断言的 machine id 查找机型。
+- 管理器解锁：坐标/案例下拉以“存在完整视觉绑定”为可用条件，13 案例全部可选；`machine-urdf.ts` 新增 `generic-wasm/1` profile，`buildJointManagedMachine` 对无 TRT profile 的机型生成通用 URDF；新增 `machine-kinematics-specs.json` 保存逐关节限位。
+- 构建资源补全：`vite.config.ts` 增加 `woodpecker`、`gmoccapy`、`qtdragon` 三个配置目录，此前 `woodpecker_xyzab.ini`、`gmoccapy_XYZCW.ini`、`woodpecker_xyzya.ini` 在生产构建中 404。
+- 已知缺口如实记录：`max5-maxkins` 的 INI 声明 J3=A、J4=B、J5=C，而 `maxkins` 按 `coordinates` 位置读取，槽位标注与求解器存在偏移；`puma-pumakins` 的 J5 缺少 `MAX_LIMIT`；三个 trivkins 案例的旋转槽位无 `[JOINT_n]` 段；`scorbot-kins` 的 INI 不声明任何关节限位。以上在 `machine-kinematics-specs.json` 中以 `null` 记录，不编造数值。
--- a/docs/glb-machine-manager/04-任务矩阵.md
+++ b/docs/glb-machine-manager/04-任务矩阵.md
@@ -25,3 +25,12 @@
 |MGR-20 机型程序一致性|verified|MGR-19|导入/应用跨机型时加载目标默认程序；同机型保留；错轴程序加载/运行/单步/继续拒绝；AC↔BC 浏览器及 Worker 验收通过|
 |MGR-21 保存位置与完整文档恢复|verified|MGR-20|命名 GLB 下载与本地机床库；显式打开/刷新恢复；多部件配置精确回填；二次保存等价；标准导入、旧版兼容、存储失败和 AC/BC 回归|
 |MGR-22 文件选择器取消路径|verified|MGR-18|三维管理、机床导入、几何参数三类文件选择器取消/回焦不关闭父对话框；没有文件时保持配置和焦点|
+|MGR-23 工业模型容量边界|verified|MGR-21|部件导入、完整机床校验/导入、组合导出使用同一 64 MiB 常量；超限反馈一致；构建与工作台浏览器回归通过|
+|MGR-24 可复用工业案例工作流|planned|MGR-23|案例可作为有来源/许可/适配状态/单位/坐标/参数完整度标签的创建模板；导入后生成独立草稿、保留来源追溯；实机限位和标定显式复核；案例/资产授权与浏览器容量可检查|
+|MGR-25 真实资产使用可用性|planned|MGR-23|覆盖仓库已有大体量 OP10/OP20/OP30 与机器人资产的导入/预览/可编辑/保存路径；提供轻量代理或优化建议、进度/取消/显存诊断，失败不破坏草稿|
+|MGR-26 13 案例 G 代码与程序目录|verified|MGR-20|13 个案例各有独立坐标限定、低幅有界干运行程序；目录来源/运动学/状态可查；AC/BC 在 Web WASM 控制面板加载、预览、回零、运行完成；其它案例切换到各自通用 WASM 机型后加载|
+|MGR-27 其余原生运动学 Web 控制器适配|in-progress|MGR-26|已接入通用 WASM 配置、WASM planner→`sim_kinematics_inverse` 采样、机型参数/限位和 11 个案例程序；Worker 级完成 11 案例加载/运行闭环。仍需逐机型浏览器视觉模型、原生 HAL/回零语义和完整源配置资源验收；不能用 TRT alias 代替原求解器|
+|MGR-28 案例视觉绑定配置|verified|MGR-27|`machine-visual-bindings.json` 以 machine id 为键覆盖 13 案例；槽位、节点、方向、正负向、物理零点可查；坐标字母不再作为键|
+|MGR-29 N 关节槽位契约|verified|MGR-17|`linuxcnc.joint-model/2` 以 LinuxCNC joint 号为槽位标识，轴字母降为槽位属性；v1 保持原规则合成 `jointOrder`；重复轴、并联杆长、被动槽位可表达|
+|MGR-30 13 案例真实三维驱动|verified|MGR-28,MGR-29|13 个结构 GLB 的可动节点均为按槽位命名的 Group 并带 `userData.linuxcncJoint`；主界面切换案例自动装载对应模型；5/6/7 关节均按槽位驱动|
+|MGR-31 构建资源补全|verified|MGR-27|`woodpecker`、`gmoccapy`、`qtdragon` 三个案例配置目录进入生产构建，13 案例 entrypoint 全部可在 `dist` 解析|
--- a/docs/glb-machine-manager/05-验收证据.md
+++ b/docs/glb-machine-manager/05-验收证据.md
@@ -198,3 +198,27 @@
 - `node scripts/test_machine_manager_workbench.mjs`：report `GLB-MGR-E14` 更新，首项检查真实 `filechooser` 打开后取消，三维机床管理对话框仍保持打开；随后搜索、撤销、标定、布局回归继续通过，浏览器错误 0。
 - 三个文件入口统一保护：管理器 GLB/已保存机床、控制面板机床模型、机床几何 INI。
 - 工作台报告 SHA-256：`0f6db50633be732a4b65162aff3373eccb23cfe319a1dd7d19fa4260098bde64`。
+
+## E18 / 2026-10-29 / 13 案例真实三维驱动验收
+
+命令与产物：
+
+```
+node web/workspace/test_machine_visual_bindings.mjs
+node web/workspace/test_glb_axis_naming.mjs
+node --experimental-strip-types scripts/test_machine_joint_model.mjs
+node scripts/test_five_axis_live_models.mjs
+npm --prefix web/react run typecheck && npm --prefix web/react run build
+```
+
+结果：
+
+| 检查 | 结果 |
+|---|---|
+| 视觉绑定配置 | 13/13 案例覆盖，槽位数与 `joint_count` 一致，GLB ≤64 MiB，坐标字母不作键 |
+| GLB 节点命名 | 13 个结构 GLB 按槽位命名并带 `userData.linuxcncJoint`；重复轴与额外直线轴案例返回 UNKNOWN 由绑定文件接管 |
+| 关节契约 v1 | `GLB-MGR-E13-MATH` 通过，已保存 GLB 不受 v2 影响 |
+| 浏览器逐案例 | 13/13 装载成功、槽位键与 `machine-visual-bindings.json` 逐一一致、浏览器错误 0 |
+| 构建 | typecheck 与 vite build 通过；`dist` 含 13 个 GLB 与三个此前缺失的案例 INI |
+
+报告与截图：`coverage/glb-machine-manager/physical-drive/browser.report.json` 与同目录 13 张 PNG。
--- a/docs/glb-machine-manager/09-13案例真实结构与建模方案.md
+++ b/docs/glb-machine-manager/09-13案例真实结构与建模方案.md
@@ -0,0 +1,93 @@
+# 13 个五轴案例的真实结构与建模方案
+
+本文把案例目录转换成可以采购资料、测量实机或直接建模的结构方案。每项案例都区分三种信息：
+
+- **实机参考**：已有公开实机或产品系列，可以用来收集外形、轴向和典型尺寸。
+- **LinuxCNC 原始结构**：仓库中的仿真模型、INI、运动学源码和 G 代码，是坐标链与参数的权威来源。
+- **本项目设计方案**：没有同构商品机时，给出满足该运动学的可制造结构，作为 GLB 装配的起点。
+
+商业型号的外观尺寸、行程、负载和精度不能直接当作本项目标定值。导入管理器前应使用实机测量或设计图中的数据填写旋转中心、偏置、零点和限位。
+
+## 统一建模约定
+
+GLB 采用米制、局部节点原点位于关节轴线或丝杠中心，运行配置保存毫米和角度单位。每个模型至少拆成 `base`、线性轴部件、旋转轴部件、主轴/刀具、工件/工作台和防护外壳。关节树中的轴名必须与案例坐标字母一致；重复轴必须保留为两个独立节点，不能合并成一个视觉节点。
+
+```mermaid
+flowchart LR
+  B[床身/底座] --> X[X 线性轴]
+  X --> Y[Y 线性轴]
+  Y --> Z[Z 线性轴]
+  Z --> T[主轴/刀具]
+  B --> R1[第一旋转轴]
+  R1 --> R2[第二旋转轴]
+  R2 --> W[工件/转台]
+```
+
+`XYZAC`、`XYZBC`、`XYZAB` 是传统五轴机床链；`XYZBCWY` 含 W 刀具方向和重复 Y 关节；`XYZABC` 机器人/并联平台使用六个姿态/位移自由度；`XYZYA` 以两个 Y 关节驱动同一龙门轴。
+
+## 逐项结构闭包
+
+|案例|真实结构参考|可直接建模的本项目方案|关节树和关键部件|建模/测量重点|
+|---|---|---|---|---|
+|XYZAC TRT|HERMLE C 42 U 类摆动转台五轴加工中心|立柱固定、X/Y/Z 主轴链，工作台上 A 摆动座和 C 回转盘|`base→X→Y→Z→tool`；`base→A→C→work`|A 轴绕 X，C 轴绕 Z；测 P、A-C 偏置、刀尖长度和转台面高度|
+|XYZBC TRT|Haas UMC-500/750 类 B/C 摆台机|固定立柱和 Z 主轴，Y 底座滑台，B 倾转耳轴、C 圆盘|`base→X→Y→Z→tool`；`base→B→C→work`|B 轴绕 Y；Haas 官方资料明确给出 B/C 轴和转台对准关系；测 MRZP、B-C 交点和 C 面跳动|
+|XYZAB 双转台|LinuxCNC `xyzab_tdr_kins` 双旋转台示例；可类比双转台五轴头|X/Y/Z 主轴链加 A 外框和 B 内框，工件夹具固定在 B|`base→X→Y→Z→tool`；`base→A→B→work`|A/B 旋转顺序、两个旋转中心、X/Z 偏置和刀长；A/B 不是 AC/BC 的字母替换|
+|Bridge Mill 5axiskins|FIDIA BRIDGE、AWEA Mega 5P 等固定龙门、双旋转头|固定龙门，X 工作台、Y 横梁、Z 滑枕，B 倾转头、C 主轴回转；W 是刀具方向坐标，另有可选第二个 Y 关节|`base→X→Y→Z→B→C→tool`，`Y_left/Y_right` 为同轴双驱，W 不新增实体滑台|W 是由 5axiskins 纳入 XYZ 的刀向补偿，不能画成额外电动轴；桥架、横梁、滑枕和双摆头分开建模|
+|MAX5 maxkins|LinuxCNC MAX5 桌面五轴机；运动学文档描述“倾转 B 头 + 水平 C 台”|固定床身，X/Y/Z 线性链；B 倾转主轴头；C 水平回转工件台|主轴：`base→X→Y→Z→B→tool`；工件：`base→C→work`；W 可作为刀长关节|B 头回转半径、C 台中心、W/刀长；MAX5 的非恒等坐标转换不能当 trivkins|
+|Hexapod genhexkins|Giddings & Lewis Variax 六支链平台|六根电动伸缩支链连接固定底座和移动平台，平台安装主轴或工件|`base→strut_1..6→platform→tool/work`|底座球铰点、平台球铰点、丝杠导程、平台初始姿态和迭代容差；六支链是并联关系，不是串联父子链|
+|Pentapod pentakins|METROM Pentapod P-Series 五支链加工中心|五根伸缩支链连接固定框架和移动刀具平台，平台带主轴|`base→strut_1..5→platform→tool`|五个底座点、平台环半径/高度、刀具偏置、初始姿态；METROM 官方资料明确使用 Pentapod 并联运动学|
+|PUMA pumakins|Unimation PUMA 560、PUMA 6 轴工业机器人|底座回转 J1、肩 J2、肘 J3、腕 J4/J5/J6，末端安装刀具|`base→J1→J2→J3→J4→J5→J6→tool`|A2/A3/D3/D4/D6、关节零位和腕部奇异区；机器人外形可使用仓库 PUMA OBJ 部件|
+|PUMA 560 genserkins|PUMA 560 同一实体结构，使用 Modified DH 参数|同 PUMA 六关节结构，单独保存 DH 表和关节限位|`base→J1→J2→J3→J4→J5→J6→tool`|每关节 `A/ALPHA/D`，单位和角度零位；PUMA pumakins 与 genserkins 必须分别保存参数|
+|trivkins XYZAB|五轴立式铣床/转台的轴映射基线|普通 X/Y/Z 三轴床身，A 摆台外框，B 转台内盘|`base→X→Y→Z→tool`；`base→A→B→work`|一一映射验证用；不声明 RTCP，主要检查节点名、轴顺序、正负方向和限位|
+|trivkins XYZCW|带 C 回转工作台和 W 刀向补偿的桥式/摆头机|X/Y/Z 线性链，C 回转工作台，W 刀具方向滑块|`base→X→Y→Z→tool`；`base→C→work`；`tool→W→tip`|C 与 W 的字母顺序和单位；W 是附加直线自由度，不可误当 A/B 旋转|
+|trivkins XYZYA|双 Y 龙门 + A 摆台/摆头|X 横向、Y_left/Y_right 双驱龙门、Z 主轴，A 工作台或摆头|5 个关节：`X,Y_left,Z,Y_right,A`；视觉上将两个 Y 归入同一龙门组件，A 作为工件或刀具旋转节点|两个 Y 关节同步、主从误差和回零；坐标字母与关节数量不同，不能按 5 个独立坐标误画|
+|SCORBOT scorbot-kins|SCORBOT-ER 4U/ER 4PC 教学机器人|底座回转、肩、肘、腕俯仰、腕回转五关节，末端夹具/刀具|`base→J1→J2→J3→J4→J5→tool`|连杆长度、关节方向、机械限位和夹具 TCP；SCORBOT 是机器人，不按五轴铣床 TRT 处理|
+
+## 13 个可建模机床的部件清单
+
+### 1. XYZAC / XYZBC / XYZAB
+
+这三类可共用一套立式五轴床身资产：床身、立柱、X 滑台、Y 鞍座、Z 滑枕、主轴箱、刀柄、旋转轴外框、旋转轴内盘、夹具、工件和护罩。通过不同的旋转节点和轴向即可得到 AC、BC、AB 三种装配。推荐先做中等精度教学模型：床身 900×700×500 mm、线性行程 X/Y/Z 为 500/400/400 mm，旋转盘直径 250 mm；这些是设计初值，不是实机规格。
+
+### 2. Bridge Mill
+
+部件分为地基、左右立柱、横梁、X 工作台、Y 横梁滑座、Z 滑枕、B 摆头、C 主轴壳和两个 Y 伺服箱。W 作为刀向补偿字段写入关节模型，不生成额外的可动滑套。建议模型中把左右立柱和横梁做成固定结构，把 `Y_left`、`Y_right` 做成两个可选显示节点，验收时分别输入相同和不同的 Y 值观察龙门扭转。
+
+### 3. MAX5
+
+部件分为桌面床身、X/Y/Z 导轨、B 倾转主轴头、C 水平回转台、刀具和工件。B 头轴线与主轴端之间保存 `pivot_length`；C 台中心保存为旋转中心。模型初始 B=0 时刀具指向 Z 负方向，C=0 时夹具基准面对 X 轴。
+
+### 4. Hexapod / Pentapod
+
+并联平台需要显示固定底板、移动平台、球铰/万向铰、伸缩杆、丝杠/电缸、平台法兰、主轴和刀具。每根支链必须是独立模型节点，不能把六根杆合并成一个网格；这样可以在管理器中显示长度、当前关节值和支链编号。平台与基座之间的杆长由运动学计算，GLB 只保存零位几何和连接点。
+
+### 5. PUMA / PUMA 560 / SCORBOT
+
+机器人模型需要底座、转台、肩部连杆、肘部连杆、腕座、腕部三轴、法兰、刀柄/夹具。仓库已有 PUMA OBJ，可直接转换为 GLB 部件；SCORBOT 可按相同树结构用圆柱连杆和关节壳体建立参数化替代模型。每个关节均需保存轴线、零姿态、正方向和机械限位。
+
+### 6. 三种 trivkins 基线
+
+基线模型可以复用前述床身或龙门资产，但必须提供三个独立装配文档：XYZAB 双转台、XYZCW C/W、XYZYA 双 Y。它们用于验证轴字母映射和 GLB 层级，不应在界面中显示成具有 RTCP 的商业五轴机。
+
+## 来源与使用方式
+
+- LinuxCNC 5-Axis Kinematics、`kins(9)`、`switchkins` 和 13 个本地配置是轴链、运动学名称和参数边界的第一来源。
+- HERMLE C 42、Haas UMC-500/750、FIDIA BRIDGE、AWEA Mega 5P、METROM Pentapod、Giddings & Lewis Variax、PUMA 560 和 SCORBOT 资料用于外形和结构类比。
+- 本项目自设计结构必须标记为 `design_reference`，不能写成实机测量结果。每个 GLB 应附 `source`, `license`, `units`, `kinematics`, `zero_pose`, `joint_limits` 和 `calibration_status`。
+
+后续生成 GLB 时，先按本文部件清单建立零位资产，再在三维机床管理器里绑定关节；完成实机测量后只修改配置和标定 JSON，不修改源网格。
+
+## 2026-10-29 更新：模型已按槽位重建
+
+13 个结构 GLB 由 `scripts/generate_physical_case_glbs.mjs` 统一生成，每个可动关节是
+Group，名字即槽位名（`x`、`y`、`z`、`a`/`b`/`c`、`w`、`y_2`、`j0`…`j5`、`strut_1`…`strut_6`），
+并带 `userData.linuxcncJoint = { index, key, axis, type, unit, direction, sign, source }`。
+关节总数 71，与 `machine-catalog.json` 的 `joint_count` 逐条一致。
+
+槽位键与 LinuxCNC joint 号一一对应：`bridge-mill-5axiskins` 的第 7 槽是重复 Y 驱动
+（`Y#2`，同时域），`max5-maxkins` 的第 6 槽是被动关节（`J5`，模型可见但不参与驱动），
+并联平台的 `J0..J5`/`J0..J4` 为杆长关节，轴字母为空。
+
+轴字母与槽位并非一一对应：`trivkins-xyzcw` 是 `X,Y,Z,C,W`（C 旋转在前，W 直线在后），
+`trivkins-xyzya` 是 `X,Y,Z,Y#2,A`（第二个 Y 为直线关节）。按坐标字母推断关节顺序会出错，
+一律以 `machine-visual-bindings.json` 的 `jointOrder` 为准。
--- a/docs/glb-machine-manager/10-Blender建模工作流.md
+++ b/docs/glb-machine-manager/10-Blender建模工作流.md
@@ -0,0 +1,21 @@
+# Blender 建模工作流
+
+Blender 已安装为 4.0.2，可用于编辑和检查 13 个结构 GLB。GLB 中的长度使用米；Blender 场景显示单位设置为毫米，导入模型时保留 `machine_root` 和物理结构节点。
+
+打开某个案例：
+
+```bash
+blender web/react/public/machine-cases/physical/hexapod-genhexkins.glb
+```
+
+为模型建立 LinuxCNC 建模工作文件：
+
+```bash
+blender -b --python scripts/blender_machine_template.py -- \
+  --input web/react/public/machine-cases/physical/hexapod-genhexkins.glb \
+  --output /tmp/hexapod-machine.blend
+```
+
+模板脚本会设置毫米单位、保留原有结构、添加 `MACHINE_ORIGIN` 和 X/Y/Z 参考轴，并写入 LinuxCNC 工作流自定义属性。编辑完成后使用 Blender 的 glTF 2.0 导出器导出自包含 GLB，再通过“三维机床管理 → 导入 GLB 部件”载入检查。
+
+结构节点命名、父子关系和运动学参数仍以 [13 案例真实结构与建模方案](09-13案例真实结构与建模方案.md) 和 [`five-axis-physical-structures.json`](../../web/workspace/five-axis-physical-structures.json) 为准。
--- a/docs/glb-machine-manager/README.md
+++ b/docs/glb-machine-manager/README.md
@@ -11,10 +11,13 @@

 现有整机 GLB + 内嵌 URDF 导入能力继续保留。新管理器生成与现有 `linuxcnc.machine/1` 相同的严格结构，再通过已有配置、Worker、WASM 和 Three.js 投影链运行。

-当前状态：MGR-21 文件管理与恢复 verified；MGR-20 机型程序一致性 verified；MGR-22 文件选择器取消 verified；MGR-19 对话框选择机型/整机保存已 verified；MGR-17、MGR-18 已 verified；MGR-01 至 MGR-16 已完成历史验收，MILL700 实测覆盖照明、Z-up、132 节点树、拖放、节点原点、关节局部坐标系、节点相对父级平移旋转、模型删除、轴绑定、XYZ/AC 层级运动和 WebGL 资源降级。最新台账 R15，证据 `GLB-MGR-E01/E02/E05/E07/E08/E09/E10/E12/E13/E14/E15/E16/E17/E18` 位于 `coverage/glb-machine-manager/`。
+当前状态：MGR-27 已将 11 个非 TRT 案例接入通用 WASM 运动学路径：配置目录、轴/关节数量、参数、限位、WASM planner 和逐采样 `sim_kinematics_inverse` 均由案例机型驱动；13 个案例程序均可进入 Web 控制器，原生 AC/BC TRT 和 11 个通用案例分别使用对应运行链。Worker 回归脚本为 `web/worker/test_generic_machine_cases.mjs`。仍需逐机型浏览器三维模型与原生 HAL/回零语义验收，MGR-24/25 继续覆盖案例模板和大型资产体验。既有证据位于 `coverage/glb-machine-manager/`。

 文档：

+- [00-三维机床管理详细功能文档](00-三维机床管理详细功能文档.md)
+- [00-三维机床管理详细功能文档（HTML 图文版，含 13 项机型案例）](00-三维机床管理详细功能文档.html)
+- [HTML 文档接续入口](../../nextTask-glb-machine-manager-doc.md)
 - [01-项目功能内容](01-项目功能内容.md)
 - [02-项目程序开发详细步骤](02-项目程序开发详细步骤.md)
 - [03-推进台账](03-推进台账.md)
@@ -28,3 +31,9 @@
 - [关节 JSON Schema](joint-model.schema.json)

 - [08-保存与重新打开机床](08-保存与重新打开机床.md)
+
+13 个案例的实机参考、结构树、部件拆分和可建模设计方案见：[13 案例真实结构与建模方案](09-13案例真实结构与建模方案.md)，机器可读索引见 [`five-axis-physical-structures.json`](../../web/workspace/five-axis-physical-structures.json)。
+
+13 个可导入的结构 GLB 位于 [`web/react/public/machine-cases/physical/`](../../web/react/public/machine-cases/physical/)，生成器为 [`scripts/generate_physical_case_glbs.mjs`](../../scripts/generate_physical_case_glbs.mjs)。它们包含结构节点和运动学元数据；带 `real-reference` 的文件用于实机结构类比，带 `design-reference` 的文件用于满足原理的设计机。浏览器导入截图和报告位于 [`coverage/glb-machine-manager/physical-cases/`](../../coverage/glb-machine-manager/physical-cases/)。
+
+Blender 安装与建模操作见：[Blender 建模工作流](10-Blender建模工作流.md)，模板脚本为 [`scripts/blender_machine_template.py`](../../scripts/blender_machine_template.py)。
--- a/docs/glb-machine-manager/configuration-driven-dialog.md
+++ b/docs/glb-machine-manager/configuration-driven-dialog.md
@@ -9,3 +9,15 @@
 2026-09-30 保存验证：使用暂存文件生成独立源码快照，TypeScript 检查和 Vite 生产构建通过。构建使用现有 node_modules、LinuxCNC 资源和本地 WASM 二进制；保留大 chunk 提示。本轮不把既有浏览器报告作为新验收证据。

 脚本目录迁移、通用 WASM 运行时开发、原始大型 GLB 以及 LinuxCNC 子模块本地修改不包含在本次管理器配置提交中，仍留在工作区。
+
+## 2026-10-29 更新：机型层已扩展到 13 案例
+
+`profiles` 只保留 AC/BC 两条 TRT 专用的偏置约束；其余案例的槽位、方向、限位改由
+`web/workspace/machine-visual-bindings.json`（视觉绑定）与
+`web/workspace/machine-kinematics-specs.json`（逐关节限位，来自本地 INI）提供。
+管理器下拉的可用条件从“案例目录标记 supported”改为“存在完整视觉绑定”，13 个案例
+全部可选。`machine-urdf.ts` 新增 `generic-wasm/1` profile：不校验固定链，link/joint
+数量由配置派生，AC/BC 仍走原有严格校验。
+
+限位缺口如实保留：`puma-pumakins` 的 J5 无 `MAX_LIMIT`，三个 trivkins 案例的旋转槽位
+无 `[JOINT_n]` 段，`scorbot-kins` 的 INI 不声明关节限位；这些在 specs 中记为 `null`。
--- a/docs/glb-machine-manager/material-rendering.md
+++ b/docs/glb-machine-manager/material-rendering.md
@@ -0,0 +1,23 @@
+# GLB 材质显示与中性光照
+
+三维机床管理器和 Web 控制面板共用 `web/react/src/machine-studio-lighting.ts`。显示设置独立于 GLB 文件、关节绑定和机床标定。
+
+本次调整：
+
+- 使用 AgX 色调映射和 sRGB 显示输出，改善高亮处的红绿蓝偏色。
+- 管理器曝光从 1.45 调整为 1；环境反射强度从 1.25 调整为 0.65。
+- 使用中性白色主光、补光、轮廓光和弱半球光，取消额外环境光叠加及偏黄/偏蓝灯光。主光强度为 2.4，补光为 0.55，轮廓光为 0.65，半球光为 0.2。
+- 环境反射适配管理器的 Z-up 与控制面板的 Y-up 坐标约定。
+- 保留原有阴影和抗锯齿资源策略，避免为大型 GLB 新增高分辨率渲染目标。
+
+不按节点名、轴名或文件名重新着色，不修改源材质的颜色、金属度、粗糙度或纹理，也不对已由 GLTFLoader 处理的颜色贴图进行重复色彩转换。保存机床模型仍保留原始材质参数；灯光不会成为导出模型的一部分。
+
+验证：
+
+```bash
+PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.js \
+MACHINE_MANAGER_URL=http://127.0.0.1:5173/ \
+node scripts/test_machine_material_rendering.mjs
+```
+
+测试使用真实 `glb/m1.glb` 及红、绿、蓝、白、金属、深色球体，对比预览截图，并通过实际管理器导出 GLB 校验材质参数。控制面板直接导入 GLB 后也检查其渲染管线。结果与截图位于 `coverage/glb-machine-manager/material-rendering/`，其中 `m1-comparison.png`、`rgb-materials-comparison.png` 为本次修改前后的对比图。
--- a/docs/glb-machine-manager/model-selection.md
+++ b/docs/glb-machine-manager/model-selection.md
@@ -0,0 +1,22 @@
+# 导入模型的选择与删除
+
+在“三维机床管理”中导入 GLB 后，右侧“已导入 GLB 模型”列表按导入实例显示文件名、角色和关节数量。同名文件也可以独立选择、删除。
+
+- 点击模型列表中的文件名，或者在三维预览中单击模型，选择整份导入模型；黄色包围框标出选中对象。拖动仍用于旋转视角，不会更换选中模型。
+- 点击结构树中的节点，继续编辑内部关节；所属导入模型在列表中保持选中。
+- 点击工具栏“删除选中模型”，或模型行右侧“删除”，移除该份导入模型及其内部节点。另行导入并挂载到它的模型保留，解除父级关系。
+- 删除后自动选中相邻模型；删除最后一个模型后显示空白导入界面。
+- “撤销”恢复模型、关节绑定及父级关系，并选中恢复的模型；“重做”再次执行删除。
+- 实时跟随或文件操作进行中禁用删除。删除仅修改管理器草稿，不删除磁盘 GLB，也不会立即替换控制面板正在使用的模型。
+
+模型列表固定在右侧编辑区域顶部，可独立滚动；层级树或分析结果滚动不会隐藏模型选择入口。
+
+回归验证（先启动 `web/react` 的 Vite 服务）：
+
+```bash
+PLAYWRIGHT_MODULE=/absolute/path/to/playwright/index.js \
+MACHINE_MANAGER_URL=http://127.0.0.1:5173/ \
+node scripts/test_machine_model_selection.mjs
+```
+
+该测试覆盖同名模型、预览点击与拖动区分、定向删除、撤销/重做、父级解除、清空恢复、真实 m1.glb 的五轴绑定恢复和窄屏操作。