[Wayfinder] 机械臂实时关节状态自动投影到 Workbench 3D

[TablewareBox]

背景与已确认事实

pTLC 的 CR5 已经可以由 MoveIt 仿真执行，并由 joint_state_broadcaster 发布真实 /joint_states。Workbench 当前也能加载 CR5 URDF/STL；但是网页不会自动订阅并应用实时关节状态。现有截图是一次性读取控制器发布的 /joint_states，再通过浏览器侧 URDFRobot.setJointValue() 注入后得到的真实仿真姿态，不是产品链路的自动实时联动。

当前缺口位于：

1. 机器人运行时没有向 OS 暴露跨 MoveIt / TCP-SDK / PLC 的统一运动学遥测端口。
2. OS 当前 /api/v1/ws/device_status 是 1 Hz 标量设备状态投影，不承载结构化高频关节数组。
3. Backend 当前没有机械臂运动学事件的可选中继合同。
4. FE 的实时解析只覆盖 device_status；本地能力明确关闭 realtime.pushJointState。
5. Pascal 能加载 URDF，但没有按设备实例消费最新关节帧并调用 setJointValue() 的循环。

这与 #214 的 PointSet/点位资产不同：PointSet 是版本化目标几何；本 Issue 是只读、短寿命、不可作为控制证据的运行态观测。

目标数据流（候选，待 Grill 冻结）

MoveIt / TCP-SDK / PLC Adapter
        │
        ▼
RobotKinematicsTelemetryPort（统一、可选能力）
        │ canonical joint_ref/value_si + source witness
        ▼
Uni-Lab-OS 遥测投影（material.kinematics）
        ├── 本地模式：直接到 FE
        └── 远程模式：Backend 仅做短寿命中继
                         │
                         ▼
FE latest-value cache（按设备实例隔离）
        │
        ▼
Pascal URDFRobot.setJointValue()

强制边界

• 这是观测接口，不是动作（Action）接口；不得通过发布 /joint_states 或修改 FE 状态伪造机械臂已经运动。
• 生产控制仍走 RobotCommand / RobotCommissioningPort，并遵守维护租约、Claim/Fence、互锁和物理结算。
• 领域设备包不固化环境 UUID；作者态使用稳定 device_ref，OS 激活时解析当前实例身份。
• 不把每帧关节值写入 PointSet、物料图或调度写模型。
• PLC/SDK 不具备关节读回时必须声明能力缺失并关闭实时姿态，不允许猜测。

Grill 决策登记（D15–D24）

D15 首期交付拓扑

D15-1 本地 Edge→FE 先闭环，Backend 作为下一阶段可选中继（推荐）

• 优点：匹配当前本地工作台；最快消除手工浏览器注入；不引入网络依赖；先冻结通用合同。
• 缺点：首期不能从云端 Backend 远程观看实时姿态；后续需补中继验收。
• 影响：首期修改 Robotics、OS、FE/Pascal，不改 Backend。

D15-2 本地与远程四仓一次性闭环

• 优点：同一版本同时支持本地和云端查看，减少阶段性交付差异。
• 缺点：同时改 Robotics、OS、Backend、FE；安全、鉴权、断线、背压和兼容范围显著增大。

D15-3 Backend 优先，FE 必须经 Backend 获取

• 优点：拓扑单一、中心化。
• 缺点：本地可视化依赖网络与 Backend；不符合 Edge 本地优先，也扩大网络故障面。不推荐。

D16 驱动侧统一入口

D16-1 机器人包提供可选 RobotKinematicsTelemetryPort，MoveIt/SDK/PLC Adapter 各自实现（推荐）

• 优点：OS/FE 不知道厂商协议；单机械臂、导轨机械臂与不同后端复用；PLC 无读回能力时可明确降级。
• 缺点：需新增共享合同并分别实现/声明 Adapter 能力。

D16-2 OS 直接订阅 ROS /joint_states

• 优点：MoveIt 最快接通。
• 缺点：把 OS 绑定 ROS，SDK/PLC 仍需第二套路径；破坏通用机械臂包边界。

D16-3 各领域包自行发布自定义实时 Topic

• 优点：领域包可自由适配现场。
• 缺点：SZLab、pTLC 和以后领域包会重复协议，FE/OS 出现分支判断。不推荐。

D17 设备实例身份

D17-1 作者态 device_ref，OS 激活解析 node_uuid；帧携带 node_uuid + boot_id + sequence（推荐）

• 优点：领域包无环境 UUID；同型号多机械臂不串流；重启和乱序可判定。
• 缺点：需要激活映射和连接重建逻辑。

D17-2 在领域包/点位文件固化设备 UUID

• 优点：查找直接。
• 缺点：删除重建、换环境或重新上传后易失效；违背已冻结 D8b。不接受为推荐方案。

D17-3 线上帧只携带 device_ref

• 优点：报文更简单、可读。
• 缺点：多部署、多实例和热重建时可能歧义，无法可靠隔离同型号机械臂。

D18 驱动关节名与网页 URDF 关节名映射

D18-1 exact Arm 型号拥有两段显式映射：驱动名→canonical joint_ref→URDF joint name（推荐）

• 优点：不依赖字符串猜测；CR5/CR7/不同厂商可独立验证；两台 CR5 使用同一模型也不会重名，因为状态先按实例隔离再映射本地关节名。
• 缺点：每个 exact Arm 型号需维护并测试一份小型映射资产。

D18-2 FE 自动去除设备名前缀并猜测 joint1..joint6

• 优点：改动少。
• 缺点：命名稍变即错误，且可能把状态应用到错误关节；无法作为生产方案。

D18-3 每个设备实例动态生成一份关节名完全匹配驱动的 URDF

• 优点：线上无需第二段映射。
• 缺点：模型端点、缓存、摘要、同型号复用和 ToolContext 组合都会复杂化；静态资产不再稳定。

D19 OS/FE 实时通道

D19-1 在统一实时 WebSocket 中增加 typed material.kinematics channel（推荐）

• 优点：连接、认证、重连和订阅统一；与设计文档中的 push_joint_state 方向一致；不污染 1 Hz 状态 DTO。
• 缺点：需扩展 OS、可选 Backend、FE 的协议版本和能力协商。

D19-2 把关节数组塞进现有 device_status

• 优点：接口数量少。
• 缺点：1 Hz 太卡；标量状态和高频数组耦合；所有设备承担机器人专有负担。

D19-3 新建专用 /ws/robot-joints

• 优点：首版实现直观、流量隔离。
• 缺点：第二套连接/鉴权/重连/背压；长期接口面更大。

D20 频率与背压

D20-1 默认向 UI 投影 30 Hz，可按设备配置上限；每实例 latest-value-wins，不排队、不逐帧持久化（推荐）

• 优点：3D 观感顺滑；慢浏览器不会积压历史帧；资源消耗可控。
• 缺点：中间帧会主动丢弃，不能直接用于精密轨迹分析。

D20-2 固定 10 Hz

• 优点：负载低。
• 缺点：快速关节运动可见阶跃，调试体验一般。

D20-3 使用控制器原始频率并排队每一帧

• 优点：表面上最完整。
• 缺点：延迟和内存会在慢消费者下持续增长，UI 最终看到旧姿态；不适合实时画布。

D21 过期、乱序与重连表现

D21-1 校验 source_timestamp + sequence + boot_id；过期时冻结最后姿态并显示“遥测已过期”，拒绝旧 boot/乱序帧（推荐）

• 优点：不伪造零位；维护人员能区分“机械臂停止”与“链路失联”；重连后不会倒放。
• 缺点：FE 需增加 stale 状态和可见提示。

D21-2 超时后模型回零

• 优点：实现简单。
• 缺点：会显示并不存在的物理姿态，危险且误导。

D21-3 超时后直接隐藏机械臂

• 优点：不会展示旧姿态。
• 缺点：用户失去最后可用上下文，也难以判断模型加载还是遥测故障。

D22 Backend 的职责

D22-1 本地首期不经过 Backend；远程阶段 Backend 只做鉴权后的短寿命中继（推荐）

• 优点：不把高频遥测当业务持久化；本地不依赖网络；Backend 容量边界清晰。
• 缺点：远程中继需要后续独立验收。

D22-2 首期强制所有遥测经过 Backend

• 优点：本地/远程路径一致。
• 缺点：延迟、网络和 Backend 可用性成为本地 3D 前置条件。

D22-3 Backend 持久化每一帧关节状态

• 优点：可完整回放。
• 缺点：写放大、存储和保留策略成本高；把观测历史混入业务数据。不推荐。若未来要轨迹分析，应另建采样时序存储。

D23 读写安全边界

D23-1 本 Issue 只实现只读遥测；网页控机继续走独立 RobotCommissioningPort（推荐）

• 优点：不会因 3D 联动绕过维护租约、Fence、互锁与动作回执；职责清晰。
• 缺点：网页“看”和“控”分两个交付阶段。

D23-2 同一条实时通道同时承载读与写

• 优点：表面接口少。
• 缺点：遥测连接获得控机能力，权限与安全审计复杂；不推荐。

D23-3 FE 直接写关节值驱动画面，不要求设备回读

• 优点：演示快。
• 缺点：只是在浏览器造姿态，无法证明机器人已执行；明确禁止作为实现。

D24 验收等级

D24-1 自动化验收“两台同型号机械臂不串流 + MoveIt 命令后网页自动更新 + 断线过期/重连恢复 + 零手工注入”（推荐）

• 优点：直接覆盖重名、实时性和断线三个核心风险。
• 缺点：需要跨 Robotics/OS/FE 的集成测试夹具。

D24-2 单台 CR5 能自动动起来并截图

• 优点：较快。
• 缺点：无法证明多实例隔离和重连正确，只适合作为演示证据。

D24-3 仅做各仓单元测试

• 优点：成本最低。
• 缺点：无法证明产品链路真正闭环，不足以验收。

候选实施阶段

1. 冻结 D15–D24。
2. Robotics：新增通用运动学遥测合同、CR5 MoveIt 实现、SDK/PLC 能力声明和 joint mapping 资产。
3. OS：新增 material.kinematics 投影、实例解析、latest-value 背压和能力协商；保留现有 device_status。
4. FE/Pascal：新增 typed parser、按实例 latest-frame cache、stale 状态和 URDF joint apply loop。
5. 本地 E2E：两台同型号机械臂、真实 MoveIt 仿真、无浏览器注入。
6. 若选择远程阶段：Backend 增加无持久化中继、鉴权、限流和重连 E2E。

关联

• 点位资产与 D1–D14：[Wayfinder] 机械臂、导轨与 Deck 设备点位资产模型 #214
• 前端统一接口、响应与实时通知：[功能目录] 前端统一接口、响应与实时通知 #130
• 静态模型/工作台加载：由本地 Wayfinder LOCAL-233 跟踪

当前只做规划与 Grill；未修改代码。

[github-actions]

GitHub → Feishu OKF synchronization

Feishu snapshot: Uni-Lab-Core #224
Knowledge stage: intake
Issue updated: 2026-08-13T19:56:45Z

[TablewareBox]

需求纠正：D17/D18 原表述作废，以运动学实例命名空间为本质

维护者明确指出：页面标签或 device.name 不是本质。真正需要保证的是，同一场景内即使存在多台完全相同型号的设备，每个运行时设备实例也必须拥有不同的 link、joint 及相关运动学身份，而且 OS 与 FE 都要满足，不能只靠 FE 对象容器隔离。

已接受不变量 KIN-1

1. device.name 只用于显示，可以重复、可以修改，不参与任何运动学路由、模型限定或遥测匹配。

2. 型号包保留一份可复用的 canonical 源模型，例如 cr5_link_1、cr5_joint_1；这只是型号内局部身份。

3. OS 激活设备实例时建立不可编辑的 kinematic_instance_id。该值来源于运行时设备实例权威，而不是显示名，也不需要固化到领域包。

4. 该实例的所有 link、joint、controller、planning group、TF frame、Tool/attachment/collision object 身份都必须完整限定。例如：

   kin_A__cr5_link_1        kin_B__cr5_link_1
   kin_A__cr5_joint_1       kin_B__cr5_joint_1
   kin_A__cr5_controller    kin_B__cr5_controller
   

5. FE 场景也必须加载或构造带相同实例限定的运动学树。仅仅把两份裸 joint1 URDF 放在两个 Three.js Object3D 中，不再视为满足验收。

6. 遥测帧至少绑定 kinematic_instance_id + topology_digest + boot_id + sequence；FE 只允许把帧写入 identity 和 digest 均匹配的那棵 URDF，禁止按显示名、型号名或裸 joint 名查找。

7. 删除重建设备会产生新的运行时实例/epoch；旧帧不得应用到新实例。领域包仍然不持久化环境 UUID。

当前实现与缺口

• OS 当前实现部分满足：CR5 build_moveit_model() 已按 Graph 实例 ID 限定 URDF link/joint、controller 与 planning group；合并阶段会拒绝 controller/group/joint 参数冲突。
• OS 仍需加固：把“Graph id 前缀”提升为显式 kinematic_instance_id 合同；验证全部 link/joint/TF/tool/collision identity 全局唯一；避免任何显示名或易碰撞字符串归一化参与身份。
• FE 当前不满足 KIN-1：Pascal 为每个场景节点分别加载静态 rendering.model.path，对象容器虽不同，但 CR5 URDF 内部仍是 joint1…joint6；Xacro 实例化还可能使用 rosDeviceName || displayName，这不是权威实例身份。

修正版 D18R：实例限定模型由谁生成

D18R-1 单一编译权威生成执行视图和渲染视图（推荐）

• exact Arm 型号包提供同一个 InstanceKinematicsCompiler。
• OS 用一次实例限定产生一个 InstanceKinematicsBundle：
  • execution_urdf：供 MoveIt/ros2_control 使用，包含 world 安装关系；
  • render_urdf：供 FE/Pascal 使用，保持设备局部坐标，避免和场景 placement 重复变换；
  • 两者共享完全相同的 qualified link/joint 身份、kinematic_instance_id 和 topology_digest。
• FE 从 OS 取得该实例的 render_urdf/manifest，不自行猜名或重命名。
• 优点：OS 与 FE 不会漂移；一份源模型可安全生成任意数量实例；最容易证明无串流。
• 缺点：OS 需要增加运行时模型投影/端点和缓存；同一型号会产生多个很小的实例化 URDF 文本，但 mesh 仍可共享缓存。

D18R-2 型号包发布 canonical URDF + qualification manifest，OS 和 FE 各自实例化

• 型号包冻结统一的重命名规则和 canonical→qualified manifest；OS/Python 与 FE/TypeScript 分别应用。
• 优点：FE 不依赖 OS 提供动态 URDF；静态资源发布较简单。
• 缺点：两个语言各有一份树重写器，mimic/transmission/gazebo/tool 等引用很容易出现实现漂移；需要大量跨语言 golden tests。

D18R-3 只按 FE 场景对象隔离，内部继续使用裸 link/joint 名

• 优点：改动最少。
• 缺点：不满足维护者提出的 KIN-1；全局检索、调试工具、附件绑定或后续状态缓存稍有疏漏就可能串台。
• 结论：作为正式方案淘汰，仅可描述当前遗留行为。

该记录取代 Issue 正文中原 D17/D18 的描述。其他 D15、D16、D19–D24 继续有效。当前未修改代码。

[TablewareBox]

Grill 新增 D17N：实例 link/joint 的命名生成方案

该决策补充“同型号多实例必须拥有不同 link/joint”的具体命名方式。它位于 D18R 之前：先决定实例命名空间是什么，再决定由单一编译器还是 OS/FE 双端应用。

已冻结、无需再选的前提

• device.name/页面标签只负责显示，不进入名称生成。
• exact Arm/rail/tool 型号包拥有型号内 canonical 名称，例如 cr5_joint_1、cr5_link_1。
• 最终运行态名称统一采用 <instance_namespace>__<canonical_name> 结构。
• equality 和遥测路由不解析页面标签；OS 激活时必须拒绝任何重复 namespace、qualified link 或 qualified joint。
• 领域包不持久化环境 UUID；运行态 token 可以由 OS 使用实例权威生成。

D17N-1：OS 生成不透明短实例 token；可读名称只放 manifest（推荐）

示例：

kin_k7m2p4q9__cr5_link_1
kin_k7m2p4q9__cr5_joint_1
kin_x3d8n6v2__cr5_joint_1

生成规则：OS 在激活时根据冻结的运行时设备实例身份生成 collision-resistant token；同一实例正常重启保持不变，删除重建或重新绑定后生成新 token。device_ref、显示名称、型号名称作为 manifest 元数据展示，不进入 token。

优点：

• 身份与所有人类名称彻底解耦；重命名不会改变运动学树。
• 同型号、多领域、多工作区复制时仍不会串台。
• 删除重建后旧帧无法误投到新实例。
• 最符合维护者“名称不是本质”的要求。

缺点：

• 单看 ROS/URDF 名称不容易知道是哪台设备。
• 日志、RViz/调试工具必须同时显示 manifest 中的 device_ref/label。

影响：需要 OS 持久保存或可确定性恢复实例 token，并向 FE 投影 token→设备实例/显示名的只读 manifest。

D17N-2：稳定 device_ref 别名 + 短实例 token（可读性优先）

示例：

kin_robot_main_k7m2p4q9__cr5_joint_1
kin_robot_backup_x3d8n6v2__cr5_joint_1

其中短 token 才是防碰撞身份；robot_main 只是可读别名，绝不能单独用于匹配。

优点：

• ROS 日志、MoveIt group、控制器列表和现场调试更直观。
• 即使两个 device_ref 意外相同，token 仍可阻止冲突。

缺点：

• 名称更长。
• 修改 device_ref 后，若别名参与编译，整棵运动学树名称都会变化；需要重新激活并拒绝旧缓存。
• 容易让后续开发者错误地把可读别名重新当成身份，因此需要 lint/测试禁止按别名路由。

影响：OS/FE manifest 必须明确拆开 instance_token 与 diagnostic_alias，匹配时只认 token。

D17N-3：只使用作者态 device_ref（当前实现附近，但不推荐）

示例：

robot_main__cr5_joint_1
robot_backup__cr5_joint_1

优点：

• 最短、最可读。
• 与当前 CR5 device_id 前缀实现最接近，改动较少。
• 不需要运行时 token 存储。

缺点：

• 唯一性依赖人工命名和 Graph 校验。
• 复制设备、跨领域组合、改名、删除重建时不能可靠区分新旧实例。
• 旧遥测可能在同一 device_ref 被复用后命中新设备。
• 本质上仍让作者态名称承担运行时身份，不完全满足 KIN-1。

影响：必须把 device_ref 升级为全工作区不可复用的持久身份；这会扩大现有领域包合同，不建议。

D17N-4：完整运行时 UUID 直接进入每个名称

示例：

kin_550e8400_e29b_41d4_a716_446655440000__cr5_joint_1

优点：

• 全局唯一性最直接，不需要短 token 碰撞分析。
• 删除重建天然产生完全不同的名称。

缺点：

• link、joint、TF、controller、planning group 全部非常长，现场日志与调试体验差。
• ROS 工具输出、配置和测试快照噪声大。
• 把运行态 UUID 广泛泄露到界面和诊断字符串，虽然没有写回领域包，但没有必要。

影响：FE/OS 实现简单一些，但维护成本最高，不推荐作为默认。

明确淘汰：显示名/设备 name 前缀

例如 CR5机械臂__joint1 不进入正式选项：显示名可能重复、包含中文/空格、可随时修改，也不是运行时实例权威。

后续依赖

冻结 D17N 后，依次继续 Grill：

1. D17L：实例 token 在正常重启、Graph 修订、删除重建时的稳定周期。
2. D17C：Arm、rail、tool 是各自独立 namespace，还是组合时嵌套 namespace。
3. D17W：遥测帧传 instance_id + canonical joint_ref，还是直接传完整 qualified joint 名。
4. D18R：实例限定 URDF 由单一编译权威生成，还是 OS/FE 各自重写。

当前只新增并提出 D17N，不修改代码。

[TablewareBox]

补充状态校正：D17N 尚未由维护者选择，因此上一条中的 <instance_namespace>__<canonical_name> 只是候选结构，不是已冻结 wire/URDF 格式。当前唯一已接受的是 KIN-1（各实例在 OS/FE 都必须拥有独立 link/joint 身份）以及显示 name 不参与身份。命名来源、可读别名、token 形式、分隔符和稳定周期均等待逐项 Grill。

[TablewareBox]

Grill 决策冻结（2026-08-14）

已确认以下三项：

D15-1：本地链路优先

第一阶段只闭环 Robot 设备包 → Uni-Lab-OS → uni-lab-fe/Pascal 3D。本地工作台 3D 联动不得依赖 Backend、云端或额外网络服务。Backend 不作为本阶段的阻塞项。

D22-1：Backend 仅作为后续远程中继

本地模式直接绕过 Backend。后续远程模式中，Backend 只承担经过鉴权、限流且短生命周期的实时中继；不逐帧持久化关节遥测，也不把关节帧写入物料、点位或调度写模型。Local 与 Remote 使用同一份强类型遥测事件合同，但采用不同传输拓扑。远程中继作为第二阶段/后续 Issue，不阻塞本地闭环。

D24-1：双实例隔离 + 自动联动作为验收门槛

验收必须同时证明：

1. 同一场景放置两台同型号机械臂，每个运行时实例拥有不同的 link、joint、controller、planning group、TF、tool 身份，遥测不会串流；
2. 真实 MoveIt 控制命令执行后，网页 3D 自动更新，无浏览器手工注入、无人工复制 /joint_states；
3. 断链时遥测进入 stale，保留最后可信姿态；恢复后只接受符合新 boot/sequence 规则的数据（具体 stale UI 与重连规则仍由 D21 冻结）；
4. 建立 Robotics/OS/FE 跨仓 E2E。

此前单 CR5 截图只作为诊断证据，不算本项验收完成。

这些决策不改变既有边界：关节状态属于遥测投影（Telemetry Projection），不是调度器写模型，也不属于点位资产。当前 Issue 保持 backlog，待其余 Grill 决策完成后再进入实现。

[TablewareBox]

D19 历史链路核查 + D20/D21 决策冻结（2026-08-14）

已冻结

• D20-2：UI 投影上限默认 10 Hz。该选择只限制 OS→FE 的可视化投影频率，不要求驱动降到 10 Hz。每个运动学实例继续采用 latest-value-wins，不排队、不逐帧持久化；静止时仍须有新鲜度见证，不能因为死区过滤永久静默。
• D21-1：时序校验与 stale 表现。帧必须携带 boot_id + monotonic sequence + source timestamp/observation time；同一 boot 下丢弃重复/倒序帧，旧 boot 帧不得写入新实例。过期时冻结最后可信姿态并明确显示“遥测已过期”，不得回零或隐藏。具体 stale 阈值仍需作为后续子决策冻结。

D19 新增强制约束：有序实时合同

WebSocket 只保证单次连接内的到达顺序，不能独自解决断线重连、旧连接迟到帧、多实例混流或进程重启。因此 D19 的正式合同必须同时具备：

1. 单连接有序传输；
2. 报文内显式的实例身份、topology_digest、boot_id、单调 sequence 和观测时间；
3. 每实例 latest-value-wins 背压，允许跳号但禁止倒放；
4. Backend 后续中继时原样保留上述时序身份，不重新编号；
5. 该实时帧属于遥测投影（Telemetry Projection），不是时序持久化、调度写模型或物理完成证据。

旧 OS→Cloud/Backend 关节链路的代码事实

历史提交 Uni-Lab-OS@48e13a7b 曾实现：

• HostNode 直接订阅 ROS /joint_states；
• 按 device_id_ 字符串前缀分组；
• 20 Hz 全局抑频和 1e-4 rad 死区；
• 经 BaseCommunicationClient.publish_joint_state() / WebSocketClient.publish_joint_state() 发送：
  {"action":"push_joint_state","data":{"node_uuid", "joint_states", "resource_poses"}}；
• 旧 Uni-Lab-Cloud/web 当前仍存在 push_joint_state 的消费代码。

但当前目标分支中：

• 上述 HostNode、communication、ws_client 桥接代码不在当前分支；只剩未被引用的 joint_republisher.py；
• 当前 Go uni-lab-backend 未发现 push_joint_state 接收或中继合同；
• 当前 uni-lab-fe 的 realtime.ts 只消费 1 Hz device_status，realtime.pushJointState=false，Pascal 也未应用关节帧。

旧实现不能原样恢复：它没有 boot_id、sequence、topology_digest 或 stale 语义；依赖显示/Graph device_id 前缀与单设备 fallback；全局节流会使多机械臂互相影响；只向旧远端 WebSocket 发送，不满足 D15-1 的本地直连；并把 resource_poses 与关节帧混在一个更新因果中。

修订候选 D19-1R（推荐，尚待维护者选择）

新增统一、版本化、本地优先的 realtime WebSocket（候选路由 /api/v1/ws/realtime），使用 typed material.kinematics envelope；保留 push_joint_state 作为兼容事件名只在适配边界解析，不沿用旧裸 payload。OS 本地直接发布；Backend 第二阶段只鉴权并原样短寿命中继。

本轮只有调查、决策记录和 Issue 更新，没有修改业务代码。

[TablewareBox]

Grill 决策更新：复用 publish_joint_state，但不复活旧语义（2026-08-14）

已确认

• D20-2 修订：历史 publish_joint_state 可继续以最高 20 Hz 产生/传输关节遥测；网页 Pascal 只以最高 10 Hz 应用到模型。两端均为每运动学实例 latest-value-wins，不排队历史帧，不逐帧持久化。这样保留控制侧平滑采样，同时限制网页渲染负载。
• D23-1：本 Issue 只实现只读遥测。网页控制机械臂仍走独立的 RobotCommissioningPort、维护租约、Fence 与互锁，不允许经 push_joint_state 写设备。

D19 维护者倾向：兼容式恢复原接口

维护者希望复用 OS 历史 publish_joint_state() 方法和 push_joint_state 动作名，减少 OS、Backend、FE 的新增概念与迁移成本。该方向可行，但“复用接口名称”不等于“原样恢复旧合同”：

• 保留：publish_joint_state() 公共方法、action: push_joint_state 事件分类、控制侧最高 20 Hz；
• 必须升级：版本化 envelope，以及 kinematic_instance_id + topology_digest + boot_id + sequence + observed_at；
• 必须移除：按显示名/Graph device_id_ 前缀猜测实例、单设备 fallback、全局节流、多实例共享最后发送时间；
• 必须隔离：resource_poses 不与关节高频遥测共享同一事实语义；
• 本地阶段：OS 必须把同一事件投影给本地 FE，不依赖 Backend；
• 远程阶段：Backend 只鉴权、限流并原样转发生产者序列，不重新编号、不逐帧持久化。

当前剩余 D19 子决策是：复用现有 /api/v1/ws/device_status 连接承载版本化 push_joint_state，还是保留同一方法/动作名但使用独立 realtime WebSocket。当前未修改业务代码。

[TablewareBox]

Grill 输出要求补充（2026-08-14）

维护者要求：除 D19 外，所有剩余决策也必须使用同等颗粒度说明，不能只给一行选项。

后续每个决策按依赖顺序一次只审一个，并必须包含：

1. 当前实现与仓库证据；
2. 要解决的问题和不可违反的不变量；
3. 每个方案保留、删除、新增的合同；
4. payload/目录/调用链示例；
5. Robotics、OS、FE、Backend 分别修改的具体文件和方法；
6. 对单机械臂、多机械臂、MoveIt、SDK、PLC、本地与远程模式的影响；
7. 优点、缺点、迁移风险、安全风险和兼容性；
8. 单元、集成与跨仓 E2E 验收；
9. 推荐方案及推荐原因；
10. 维护者确认后再冻结，不在 Grill 完成前修改业务代码。

待审顺序暂定：D19 传输复用细节 → D16 驱动遥测端口 → D17N/L/C/W 实例身份族 → D18R 执行/渲染模型编译 → D21 stale 阈值。

[TablewareBox]

D17 批量 Grill：token 生命周期、可读性与点位执行器身份（2026-08-14）

维护者新增两个强约束：

1. 运动学实例 token 不得因普通 OS 启动而改变；
2. 两台同型号机械臂不能只暴露无语义 token，现场必须能明确分辨；
3. 每台机械臂的 global/transit/interaction/rail 点位可能不同，点位不能按型号或显示名误共享。

当前代码事实

• CR5/CR7 build_moveit_model() 当前直接使用 Graph device_id 作为 link/joint/controller/group 前缀，没有持久 token registry、生命周期或 boot identity 分离。
• PointSet v3 的 components.arm 只锁定 model_ref/tool_context_ref；没有 executor_ref。分组内 device_ref 表示被访问的 Deck 工位，不表示执行机械臂。
• RobotCellManifest 的 deployment_id 当前随 backend/profile 变化，例如 moveit-sim 与 tcp-sdk-sim 使用不同 deployment_id，不能直接作为稳定物理机械臂身份。
• SiteAccessDeclaration 已使用 owner_resource_ref + slot_key，方向正确；但当前激活快照没有完整冻结 executor_ref/kinematic_instance_id/PointSet digest。
• PointSet/ActivationStore 仍未接入 OS 的真实实例注册和 WorkflowTask/PhysicalSettlement 生命周期。

推荐身份拆分

• installation_ref：可读、稳定的安装/工站引用；
• executor_ref：可读、稳定的执行机械臂引用，例如 robot-main/robot-backup；
• display_name：可编辑展示名，不参与匹配；
• kinematic_instance_id：OS 本地持久保存的防碰撞身份，普通重启不变，删除重建/换机/重新绑定后变化；
• boot_id：每次遥测生产者进程启动变化，只负责拒绝旧连接帧；
• topology_digest：Arm/Rail/Tool/URDF 拓扑或成员变化时变化。

推荐 qualified 名称同时包含可读别名与短 token，例如：
ptlc_robot_main__k7m2p4q9__cr5_joint_1
ptlc_robot_backup__x3d8n6v2__cr5_joint_1

路由只认 kinematic_instance_id/topology_digest；日志、RViz、FE 同时展示 installation_ref/executor_ref/display_name/token 后缀，禁止让人只面对无语义 token。

推荐 PointSet 绑定

点位文件不保存 token、环境 Device UUID 或 Site UUID。每个物理 executor 的 RobotCell manifest 绑定自己的 exact PointSet、Calibration、ToolContext、SiteAccessDeclaration/ProgramSet。完整目标身份是：

installation_ref + executor_ref + kinematic_instance_id + point_set revision/digest + target_ref + calibration/tool/profile digests

MoveIt/SDK 使用该 executor 的 PointSet；PLC 不使用外部几何 PointSet，使用该 executor 的 PLCProgramSet/AdapterProfile。SiteAction 先完成 ExecutorAssignment，再在该 executor 的激活快照内解析 SiteAccess。两台机械臂即使 target_ref 都叫 group-rack.r1c1，也因 executor/activation/digest 不同而不会混用。

待批量确认

• D17N：推荐可读 alias + 防碰撞短 token；
• D17L：推荐 token 跨正常 OS restart 保持，仅显式删除重建/换机/重新绑定时变化；
• D17C：推荐 Arm/Rail/Tool 独立实例身份，组合关系由 topology_digest/activation 冻结；
• D17W：为兼容 publish_joint_state，推荐报文发送完整 qualified joint name，同时保留 envelope 的 kinematic_instance_id/topology_digest；
• D18R：推荐一个共享编译权威同时生成 execution_urdf 与 render_urdf；
• Point ownership：推荐一个 executor manifest 锁定一份完整 PointSet/ProgramSet，不在一个 YAML 内嵌多台机械臂；
• Point binding：推荐作者态只使用 installation_ref/executor_ref，激活时解析 token，运行任务冻结本次结果；
• Replacement：推荐 token 变化使旧激活失效；点位源文件可以保留，但必须重新完成安装标定和生产资格，不能静默继承。

详细逐项优缺点、文件影响与验收由当前对话一次性给出。当前未修改业务代码。

[TablewareBox]

D19-A1 已接受：兼容式复用 publish_joint_state/push_joint_state（2026-08-14）

维护者正式选择 D19-A1。

冻结合同

1. OS 保留/恢复公共方法 publish_joint_state() 和事件分类 action: push_joint_state。
2. 本地模式复用现有 /api/v1/ws/device_status WebSocket；按 action 多路复用低频 device_status 与关节遥测，首期不新增第二条 realtime 连接。
3. 旧 payload 不原样复活。新报文使用 schema_version: 2，至少携带 kinematic_instance_id、topology_digest、boot_id、单调 sequence、observed_at 和 joint_states。
4. 关节发布最高保留 20 Hz；Pascal 最多 10 Hz 应用。OS/FE 均按运动学实例 latest-value-wins，不排队历史帧、不逐帧持久化。
5. 禁止按显示名、裸型号名或旧 device_id_ 前缀猜测实例；禁止单设备 fallback 和多实例共享全局节流。
6. 关节遥测属于遥测投影（Telemetry Projection），不得写入设备状态 DTO、PointSet、物料（Material）、库位（Site）或调度写模型。
7. 该连接只读；机械臂控制仍经 RobotCommissioningPort、维护租约、Fence 与互锁。
8. Backend 仍按 D22-1 延后；远程阶段只鉴权/限流并原样中继生产者身份和序列，不重新编号、不持久化。

实现约束

现有 OS api.py 和 host_node.py 已过大；后续实现应新增内部 realtime hub / joint-state projector，让既有 route 只做接线，不把高频逻辑继续堆入大文件。

D19 已关闭；下一批仍待维护者选择 D16、D17N/L/C/W、D18R、D21S、D25A/B/C。当前不修改业务代码，Issue 保持 backlog。

[TablewareBox]

2026-08-14 D17 命名方案收敛：撤销持久随机 token 候选

维护者指出正确：此前 installation_ref + executor_ref + short token 属于过度设计。KIN-1 要求的是同一活动 Graph 内可读、唯一、稳定的设备实例命名空间，并不要求不透明身份或持久 token 注册表。

取代 D17N/D17L token 候选的简化方案（待最终确认）

• 以 Graph 的稳定 device_id（即节点 id；执行上下文中也作为 executor_ref）作为唯一运动学实例命名空间。
• display_name/name 仅用于界面显示，允许修改，永不参与路由。
• qualified 名称保持可读，例如 robot_main__cr5_joint_1、robot_backup__cr5_joint_1；link/controller/planning group/TF/tool attachment 使用同一 namespace。
• 不新增 token 注册表、持久 token、installation-token 映射或迁移生命周期。
• boot_id 仍保留，但只表示本次 Adapter 激活会话；每次 OS 启动或设备重新激活都变化，用于拒绝旧会话帧，不参与人类识别或 ROS 名称。
• sequence 只在同一 boot_id 内单调递增；topology_digest 校验 URDF/关节/工具/导轨拓扑版本。这三者与稳定命名职责分离。
• 删除再用同一 device_id 创建实例时，新的 Adapter 激活必须生成新的 boot_id；旧帧因此无法命中新会话。
• Graph/OS 启动前必须拒绝重复、非法或规范化后碰撞的 device_id；禁止 robot-main 与 robot_main 经静默 sanitize 后碰撞，禁止单设备 fallback。
• PointSet/PLC ProgramSet 继续按每个 executor_ref 的 manifest 绑定，不写 token 或环境 UUID；同名 target_ref 可以存在于不同机械臂的不同已锁定资产中。

现有代码证据

• unilab_arm_cr5.moveit_model.build_moveit_model(device_id=...) 已用 Graph device_id 为 URDF/SRDF、joint、link、controller、planning group 添加前缀。
• OS package_moveit_model.load_package_moveit_model() 已把 Graph node.id 传给 Provider；参数合并路径已拒绝 controller/group/joint-limit 名称冲突。
• InstanceSynchronizer.sync_graph() 已拒绝重复 node id；遗留 resources/graphio.py 标准化路径仍需补同等的关闭失败校验，避免字典覆盖。

因此后续实现只需加固现有 identity seam，并让 push_joint_state schema v2 使用 device_id + topology_digest + boot_id + sequence 精确投影到 FE，不创建新的 token 子系统。此前关于持久随机 token 的评论明确标记为候选作废；尚未修改业务代码。

[TablewareBox]

2026-08-14 D16-2R 已选择：以 ROS JointState 作为三类 Adapter 的统一遥测出口

维护者选择 D16-2，并明确要求沿用 D19-A1：不新增 RobotKinematicsTelemetryPort，而是让 MoveIt、TCP/SDK、PLC 最终都把真实读取到的关节状态规范化为统一 JointState 出口，再由 OS 恢复的 publish_joint_state() 投影为 action: push_joint_state schema v2。

这不是 Issue 正文中“只为 MoveIt 直接订阅 /joint_states”的狭义 D16-2，而是覆盖三种执行后端的修正版 D16-2R；正文旧 D16-1/2 对比由本记录取代。

冻结数据流

MoveIt joint_state_broadcaster ─┐
TCP/SDK 真实关节读回 Adapter ───┼→ ROS sensor_msgs/JointState `/joint_states`
PLC 真实关节读回 Adapter ───────┘
                                      ↓
                         OS JointStateProjector
                                      ↓
                         publish_joint_state()
                                      ↓
              /api/v1/ws/device_status action=push_joint_state v2
                                      ↓
                              FE / Pascal

名称与多实例规则

• exact Arm/Rail 型号资产维护 driver joint name → canonical joint_ref 映射。
• Adapter 发布前将厂商字段顺序/名称转换成 OS 编译得到的 qualified joint name，例如 robot_main_cr5_joint_1。
• MoveIt 已直接发布 qualified 名称；SDK/PLC 必须产生完全相同的标准结果。
• OS 不按字符串前缀猜设备，而是使用启动时冻结的 qualified joint name → device_id 拥有关系表分组；未知、重复、跨设备重叠名称关闭失败。
• 同一 /joint_states 允许来自多个 publisher，消息可以只包含单台设备的 joint 子集；OS 按 exact ownership 投影。
• 导轨若需要网页联动，按同一机制发布 prismatic joint；ROS JointState position 对旋转关节使用 rad、移动关节使用 m，单位由已冻结拓扑的 joint type 决定，不在每帧重复传。

时序职责

• D19-A1 的 boot_id + sequence 由 OS 的 JointStateProjector/publish_joint_state 生产，因为它是本地 FE 遥测事件生产者；设备 Adapter 重启不需要改变 ROS joint/link 命名。
• JointState header.stamp 作为源观测时间；OS 拒绝同一 joint 的时间倒退，并在没有新鲜观测时进入 stale。
• topology_digest 来自本次 OS 编译并冻结的运动学拓扑，不由 PLC/SDK 自报。

强制安全边界

• 统一的是只读关节状态遥测，不是动作执行：MoveIt、PLC、SDK 仍分别经自己的 RobotExecutionBackend/RobotCommissioningPort 控制。
• /joint_states 和 push_joint_state 不是命令完成证据、互锁许可、物理结算或 PointSet。
• PLC/SDK 只有实际提供完整或明确可归属的关节读回时才允许发布。
• 只有程序号、目标点位、Home、完成码或命令回显的 PLC 不得反推/伪造 JointState；该 profile 必须声明实时关节遥测不可用，FE 显示静态模型或遥测不可用。

当前代码差距

• MoveIt 已经从 /joint_states 读取 qualified joints，CR5 MoveIt2ClientPort.read_commissioning_state() 可复用现有观测。
• 当前 CR5 TcpSdkBackend 的 RobotSDKPort 只有 execute/query/stop，没有连续关节读回接口；具体厂商 SDK port 需要增加 read callback/poller 并发布 JointState。
• 当前 PLCBackend.PLCVariablePort 只有变量 read/write/wait，ProgramBinding 也没有关节变量映射；仅对现场 PLC 确实提供关节反馈的 profile 增加 joint_feedback_variables，否则关闭该能力。
• OS 当前目标分支缺少旧 HostNode 的 /joint_states→publish_joint_state() 桥；实现时新增独立 JointStateProjector/realtime hub，由既有 WebSocket route 接线，不继续堆入 HostNode 大文件。

D16-2R 与 D19-A1 一起冻结；未修改业务代码。

[TablewareBox]

2026-08-14 剩余 Grill 决策清单（D16-2R 后）

已冻结并不再重复选择：D15-1、D16-2R、D19-A1、D20-2 修订、D21-1 主策略、D22-1、D23-1、D24-1。当前剩余 9 项：D17S、D17C、D17W、D18M、D18R、D21S、D25A、D25B、D25C。

D17S 稳定设备身份来源

• 1：活动 Edge/Graph 内唯一的可读 device_id=node.id 是唯一运动学命名空间；远程时只在 envelope 外层增加 edge_id。推荐。
• 2：把 workspace_ref + device_id 同时编入所有 link/joint 名称。跨工作区更明确，但名称更长、迁移工作区会整体改名。
• 3：使用 Backend Material/Site UUID。全局唯一但不可读、重建易变，并违背领域包不固化环境 UUID。

D17C Arm/Rail/Tool 命名关系

• 1：Arm 与 Rail 各自保持独立 device_id namespace；Tool 是 Arm 下的 attachment identity，组合由 Coordinator + topology_digest 冻结。推荐。
• 2：组合工站拥有一个 cell namespace，Arm/Rail/Tool 都嵌入 cell；组合直观，但独立复用或换轨时全部改名。
• 3：全部吸收到 Arm namespace；单设备显示简单，但 Rail 无法独立复用/观测，Tool/Rail 生命周期耦合。

D17W /joint_states 中的名称形式

• 1：所有 Adapter 发布完整 qualified joint name；OS 用启动时冻结的 exact ownership table 分组。推荐，直接匹配 D16-2R。
• 2：每台设备使用 /devices/<device_id>/joint_states，消息内只放 canonical local names；需重发 MoveIt 状态并维护多 Topic 生命周期。
• 3：Adapter 发布厂商原始名字，OS 识别厂家并翻译；让 OS 依赖厂商协议，不推荐。

D18M 厂商关节名映射归属

• 1：exact Arm/Rail 型号包拥有 canonical joint specs 和各 Adapter raw→canonical 映射；实例编译器再 canonical→qualified。推荐。
• 2：映射放 HardwareProfile；现场可调，但配置错误可能交换关节，且同型号重复维护。
• 3：映射集中到 OS；OS 会累积 CR5/CR7/以后厂家分支，不推荐。

D18R OS 与 FE 的实例 URDF 如何保持一致

• 1：型号包一个编译权威，从同一 canonical URDF 生成 execution_urdf + render_urdf；两者共享 qualified names 与 topology_digest。推荐。
• 2：发布 canonical URDF + rename manifest，Python OS 与 TypeScript FE 各自重写；发布方便，但双语言实现易漂移。
• 3：FE 直接加载 execution_urdf；文件最少，但 world mount/ros2_control/场景 placement 耦合，容易重复变换。

D21S stale 阈值

• 1：所有设备固定 1 秒无新帧即 stale。最简单，但慢 PLC 与快 MoveIt 不能分别调节。
• 2：HardwareProfile 声明 stale_after_s，默认 1.0 秒并限制在 0.5–5.0 秒；OS 将已验证阈值放入 envelope，FE 只执行。推荐。
• 3：按最近帧率动态计算。自适应但抖动、暂停和异常降频会改变阈值，排障困难。

D25A 不同机械臂的点位资产粒度

• 1：每个 device_id 的部署 manifest 锁定一份完整 PointSet；PLC 则锁定自己的 ProgramSet。允许同 target_ref 不同数值。推荐，简单且安全。
• 2：一个 PointSet 增加 executors/device 层保存多台机械臂。文件集中，但恢复了维护者已要求去掉的 device 层，文件会随设备增长。
• 3：共享 BasePointSet + 每执行器 calibration/override，激活时编译为独立 PointSet。重复少，但继承、摘要、joint target 和资格规则更复杂。

D25B device_id 与点位资产在哪里绑定

• 1：Graph 节点用 exact path+digest 选择 robot-cell manifest；激活快照冻结 device_id + manifest/PointSet/Calibration/Tool/Profile digests。Workflow 只给业务 target_ref。推荐。
• 2：Workflow 每次选择 PointSet/manifest。灵活，但同一 Workflow 可能给机械臂选错点位资产。
• 3：Backend/FE 动态选择当前点位集。操作方便，但本地运行依赖网络/可变状态，破坏可复现性。

D25C 更换同一安装位的机械臂后如何处理

• 1：安装角色不变可保留 device_id，但必须生成/锁定新的 calibration 与 qualification；旧激活立即失效。笛卡尔业务结构可复用，joint target 必须重新资格。推荐。
• 2：每次换硬件强制新 device_id。隔离最彻底，但 Graph、Workflow、监控、点位绑定全部改名。
• 3：保留 device_id 并静默继承全部旧资产。操作少，但可能把旧关节构型/标定用于新设备，淘汰。

推荐组合：D17S-1、D17C-1、D17W-1、D18M-1、D18R-1、D21S-2、D25A-1、D25B-1、D25C-1。当前只做 Grill，不修改业务代码。