主题
工作台协议
工作台业务实现在 apps/server/src/pride_workbench/api/ 和 sessions/,客户端在 apps/workbench/。Python 保留模型、FK、MPLib/FCL 与独立物理 worker;React 不判定物理有效性或任务成功。用户操作见工作台教程。
前端工具链、渲染和交互实现见前端说明(apps/workbench/README.md),验收规则见前端指引(apps/workbench/AGENTS.md)。
显示忠实性
视觉重构必须同时忠于设计方案与领域事实。正式工作台沿用 R3F 和归档模型;HTML/SVG 交互草图只用于讨论布局,不能作为模型、求解或物理验收证据。
- 模型:显示、FK、IK 与碰撞使用同一模型包及实例变换。美术调整限于界面、观察相机、照明和辅助层;不得为构图改变安装尺寸、关节轴、厂家限位或器皿比例。视觉网格与碰撞几何明确标识。
- 状态:目标草稿、参考/求解 FK、mock、物理采样、实机反馈分别标明来源。命令应答和已发布输入不能冒充已执行运动;过期反馈显示年龄和失效状态,不通过预测或插值继续伪装实时运动。
- 判据:接触、支撑、抓持、到位、释放与稳定来自后端证据,保留真、假、未知及时间含义。界面状态机不产生物理结论;准备完成、物理有效性和任务成功分别呈现。
- 能力:单臂会话只提供对应单臂控制,未接入的相机、液体状态、语义对象和 episode 能力显式缺席或标为未接入。浏览器观察相机与实际传感器图像分开,真实数据与示例记录不得混用。
- 验收:首个正式视觉里程碑就使用现有归档模型与真实协议数据,核对所选实体、坐标系、单位、模型哈希、状态来源和版本匹配;同时复核设计中的布局、焦点、工具反馈与操作流程。好看的草图不能替代这一步。
标识与坐标
协议版本为 1。所有请求具有 UUID request_id;编辑、求解与仿真请求使用收据去重:相同 ID 与相同负载返回同一收据,ID 被不同负载复用返回 409,收据保存在当前 runs/workbench-*/commands/。遥操连续输入使用短期控制权和严格递增序号,不重放收据或自动重试运动。服务重启生成新的 session_id,客户端必须清除旧会话的请求与姿态。
model_sha256 是归档 model.json 的 SHA-256;model.id 同时保留生成器模型标识。URDF、SRDF、网格、厂家限位通过 job 的完整模型哈希校验。编辑、求解和仿真都引用同一个包,仿真复制包后再次校验。姿态是世界坐标 [x,y,z,w,x,y,z],单位 m/rad/s。界面 mm/° 和 Three.js xyzw 的转换分别在输入与渲染边界执行。
只读观察的 host_monotonic_ns / host_received_ns 在浏览器协议中编码为非负整数的十进制字符串,保留超过 JavaScript 安全整数范围的纳秒精度;原始采样、归档与后端时钟运算仍使用整数。前端显示年龄使用服务端计算的 age_s,不能把纳秒字符串转为 Number 后再推算精确时间。
命令与状态
edit:带 revision 的完整目标、侧别和参考关节字典。较旧 revision 被拒绝;客户端编辑立即使已有求解无效。solve:冻结完整编辑、种子、尝试次数和迭代预算。请求立即返回 solve_id,结果通过状态快照交付;前端同时匹配请求 ID 与 revision。新编辑到达后,旧求解可归档,但不能覆盖新编辑。not_found仅表示预算内未找到解。submit:普通关节目标运行引用当前 revision 的 feasible 求解、最大步数及墙钟预算。每个求解只允许提交一次;采用解作为关节驱动目标、结果标为未评估。pick_place 拒绝此命令。submit_task:仅用于 pick_place,携带模型哈希、最大步数和墙钟预算,不接受 solve_id 或 revision。物体与搬运目标由任务配置决定,策略内部继续使用 IK 和轨迹规划;不创建网页规划 worker。任务记录的 solve_id 为 null,结束后可用新的 request_id 再次执行;相同请求仍按收据去重。pick_place 会话拒绝 edit/solve,网页隐藏 IK 草稿与目标变换工具,默认进入运行面板。
两种提交都限制同一服务最多一个活跃物理任务。步数和墙钟默认读取当前会话的任务预算,用户修改在该会话内保留,不被后续快照或页签切换重置;输入不得超过任务配置。模型完整性、取消确认、执行结果与归档规则相同。
cancel:登记 cancel_requested 请求,不修改任务状态;执行端接受后为 canceling,完成停止与必需收尾后才返回 canceled。断线不等于取消,服务退出会请求停止所有 worker。export:归档完成后导出 RRD;导出失败保留错误,不能将部分轨迹宣称为完整记录。teleop_acquire/teleop_release:只用于独立遥操会话,绑定 session_id 与模型哈希,获取的控制权只返回请求方,不放入快照或记录。teleop_input:携带控制权、递增 sequence、关节/末端模式、坐标系、六维归一化输入、速度比例和 deadman。150 ms 内消费,ROS watchdog 检查控制权和反馈;应答中的 applied_input 是已发布的限幅后 Servo 输入,仍不代表物理执行。teleop_stop/teleop_reset:停止可由任意本地操作端触发并锁定控制权;复位要求有效反馈确认停稳,复位不会恢复之前的运动。
网页请求、应答与状态由 pride_workbench.api.protocol 的 Pydantic 模型装配;控制字段及约束继承 pride_core.control 的唯一 schema,不另写一份。FastAPI 声明请求体、响应、错误与 operation ID,从实际路由生成 apps/workbench/openapi.json,线上同一份契约由 /openapi.json 提供。SSE 的 data 使用 Snapshot,WebSocket 的 Poses 通过 x-websockets 引用同一文档的 components;不启动服务、CAD 或物理引擎也能导出完整契约。
锁定的 Hey API 从 OpenAPI 生成 src/generated/ 中的 TypeScript 类型、Fetch 客户端和 Zod 校验器。前端直接引用生成类型;protocol.ts 只适配错误及传输边界,不手写 schema。命令请求、HTTP JSON 成功/错误响应、SSE 快照和 WebSocket 姿态均经过生成校验器。错误姿态帧清除当前显示帧并断开该连接;命令不会自动重试。生成配置将 additionalProperties: false 转为严格对象,避免 Zod 默认静默丢弃未知字段。
GLB 模型与 RRD 录制下载声明各自的二进制媒体类型,响应 schema 从 Pydantic 的 bytes 类型生成。锁定 Fetch 生成器不能自动识别 model/gltf-binary,因此生成配置根据操作的二进制成功响应契约补充 parseAs: 'blob',生成 Blob 类型与解析选项;不手改 SDK,也不在调用方重复维护 URL 或下载 schema。错误响应仍按 JSON 处理。
契约和生成代码不得手改,也不保留另一套手写 schema。构建和 workbench 检查重新导出并比较 OpenAPI 与整个生成目录,检测内容差异以及缺失、多余文件;检查产物位于 artifacts/workbench/client/。协议变更后使用同一构建入口更新生成物:
sh
uv run pride build workbench --update-protocol普通构建只比较生成物,不自动改写。Python 传输测试与前端协议测试共享 tests/fixtures/workbench-wire.json,验证真实传输形状、可选值和生成校验行为。
快照使用 kind=editing/observation/teleoperation 区分会话,共享 ModelInfo、单位和预算结构。观察与遥操必须 editing=null,不能混入另一种会话的状态;任务准备阶段的结果可以为 null,未评估任务的 success 保持 null。snapshots.py 在各服务的锁内组装拥有独立数据的快照与姿态,排除内部 worker 对象;http.py 对 HTTP、SSE 和 WebSocket 使用同一套输出校验。输出字段错误属于服务缺陷,不能降为用户的 422 输入错误。遥操 lease 仅允许出现在获取控制权的命令应答中,不属于快照字段。
后端校验拒绝额外字段、非有限数、错误四元数和未知版本。前端生成校验器覆盖契约能表达的结构、常量、长度与数值范围;Python 自定义 validator(例如单位四元数)不会自动翻译成 Zod。厂家关节限位、revision、会话控制权与配置预算仍由服务依据当前模型和状态校验;前端输入反馈不能替代后端领域校验。
GET /api/snapshot 与 SSE /api/events 提供后端权威状态;每次 SSE 重连从完整快照开始,不依赖丢失的增量。WS /api/poses 是独立的 30 Hz 最新姿态流,含 session/model/sequence/source,断开后清除旧姿态并重连。浏览器摄像机和操作工具状态留在前端;求解、任务与归档状态来自后端。同源校验适用于命令和 WebSocket,默认仅监听本机。
每种流只运行一个采集循环,将同步采集放在线程中,并向所有订阅者分发;慢订阅者只保留最新待发帧。没有订阅者时停止采集。这是实时传输的背压机制,不改变原始记录,也不增加计算缓存。HTTP 传输只依赖 WorkbenchService 契约,三类服务各自负责命令与录制路径。
编辑会话的在线状态只保留最近任务、未结束任务及最多 64 个当前求解;结束的工作线程从集合移除。完整命令收据、求解和任务记录继续写入会话目录,旧录制仍可下载,已经提交的求解不能因状态裁剪而再次执行。新编辑和被拒绝的并发求解分别处理,拒绝请求不会改写当前编辑;规划通信失败后关闭失效连接,由下一次显式求解新建进程。
遥操的 isaac_physics_feedback 表示 Isaac 关节反馈经归档模型 FK 得到的显示姿态。反馈失效时,已有姿态使用 stale_feedback_fk 并显示“上次反馈姿态 · 当前反馈不可用”,不跳回初始姿态,也不维持控制就绪;还没有反馈才显示 reference_fk。feedback_age_s: null 表示当前没有可用的反馈时间基准。
错误返回 HTTP 409(冲突)、422(输入无效);worker 错误写入 solve/task 状态并保留 worker.log。求解进程有启动和请求超时。渲染用参考 FK 与实际物理采样明确区分,均不代表实机标定或路径安全。
遥操遥测预览
AUBO 会话的可选 teleoperation.telemetry 由同一协议生成流程提供。后端按归档关节顺序输出最近五秒的 输入、ROS 目标、SDK 目标、控制柜目标和实际反馈,以及保护、模式和停止事件;信号均携带工控机单调时间。 位置和速度分别以 rad、rad/s 显示,未提供的分量为 null,不从目标补造反馈。 网页默认查看 J6,可切换六轴;这是每来源约 10 Hz 的预览,完整频率保留在原始记录。 接收空洞不连线;低频预览不得用于确定速度峰值或判断运动验收通过。
健康状态与反馈年龄由后端计算。控制器退出后,遥测仍可展示其独立采集尾段;控制就绪状态继续来自原有控制链, 不会因为有只读数据就显示可控制。预览只读取有界日志尾部,不增加 SDK 连接。
同步、校验与资源加载约束
网页遥操通过 teleop_keyboard 提交完整按键快照、控制权、严格递增序号、模式、参考系和使能保持状态。服务在当前进程中用无状态函数转换按键,保留首次收到请求的单调时间,再把输出交给同一 ROS 门控。teleop_input 继续用于 LeRobot 和自动验收的数值动作接口;网页不再自行计算该六轴向量。两种输入共享控制权,不能并发控制设备。输入转换失败立即尝试释放控制权;失联时独立 ROS watchdog 仍有效。
状态快照的 editing 保存完整权威编辑:revision、side、target 与参考 positions。model.positions 和姿态流用于显示求解后的姿态,不能用来恢复参考编辑。只读硬件观察和遥操会话的 editing 为 null,并由 observation / teleoperation 区分。新会话、刷新与远端编辑都从 editing 恢复;加载快照不会再次回发相同 revision 的编辑。较旧快照不覆盖更高版本的本地输入;同版本冲突以服务已接受的编辑为准,并提供显式“重新同步服务端状态”恢复操作。
快照显式给出 active_task_id 与 latest_task_id。界面跟踪活跃任务,空闲时跟踪最近任务的记录;当前版本没有独立的历史记录选择器。新任务与终态的 SYNC 都驱动前端任务机转换,其他窗口请求取消时也进入等待确认状态,不复用前一个任务的下载链接。
参数校验错误返回 code、通用中文 message 和 fields(字段路径、中文说明),不返回内部 Pydantic 类型、输入回显或版本链接。前端同时检查数值范围和整数条件,提示放在对应字段附近;错误不因普通 SSE 快照被清除。仿真预算越界时明确拒绝,不静默缩小用户输入。
入口 HTML 与动态 API 返回 Cache-Control: no-store,更新后不复用旧入口文档。模型几何 URL 带资源 SHA256,使 Three.js 资源加载也按实际内容区分。首次从此前无缓存策略的版本升级时,旧标签页应重新加载页面。
姿态包另外携带 revision 与 task_id。接收器同时匹配会话、模型、编辑版本、当前任务;任务切换立即清除上一任务的帧。场景与采样时间标签从同一个受作用域约束的帧读取,不保留另一份可能滞后的 source/time 副本。取消于引擎准备阶段的任务不得显示上一任务的采样时间。
归档 Job 与准备职责
物理 IPC 每次交换核对响应结构和请求序号。超时、断流、畸形响应或序号错配会关闭连接并回收 worker,后续请求不得复用该通道;不自动重放可能已经执行的命令。正常匹配的业务拒绝不关闭连接。强制取消可以打断正在等待回复的请求,不等待请求锁释放。
浏览器协议和归档 Job 分别版本化。pride_core.configuration 维护设计、任务、物理配置的纯校验;pride_core.jobs 维护 Job 跨字段约束;pride_core.model_bundle 从生成资产组装 Job 并验证文件哈希与模型一致性;pride_core.provenance 记录代码和锁文件来源;pride_workbench.execution 负责准备/运行编排、超时与进程退出记录;任务终态由执行端提供。调用方直接导入职责所属模块,旧模块不提供重导出入口。
新任务准备要求当前执行限制,历史归档读取保留原接受条件;模块拆分不迁移旧 run,也不补造旧数据中缺失的限制。模型包复制后仍验证哈希,进程正常退出仍不等于物理有效或任务成功。
Worker 进程通信
本节描述当前传输及退出语义。机器人会话由 Launch 管理;规划/交互物理保留私有 gRPC。有限物理任务采用 ROS Action Goal 状态语义,但没有原生 ROS Action 传输或统一 systemd/cgroup 会话托管,见模块与执行状态。
规划与交互物理客户端通过私有临时目录中的 Unix domain socket 使用 gRPC; pride.Planning 提供 Ready / Evaluate,pride.Physics 提供 Ready / Command。 两者均为 unary RPC,客户端串行提交有状态命令,物理引擎只在其原执行线程推进。 gRPC handler 通过有界队列将命令交给该线程;执行端已观察到取消或过期、且尚未开始的调用不执行。 这条队列用于线程归属,不负责网络回复匹配。
载荷使用 gRPC 官方 serializer/deserializer 扩展传递 UTF-8 JSON 对象,保留现有业务结构, 不新增一套重复的 protobuf 领域模型。共享入口拒绝非对象与非有限数值; 物理 Ready/状态/错误及规划请求/Ready/结果外层由 core 的严格 Pydantic 模型校验,拒绝缺失字段、未知字段、布尔冒充整数及关节维度不一致。后端 diagnostics、相机和任务扩展仍保留 JSON 结构,由相应领域入口进一步解释,不宣称每个后端扩展都已强类型化。请求和回复的关联由 gRPC 管理, 不再携带客户端自增通信 ID。stdout/stderr 只写入该次运行的 worker.log。 浏览器侧 HTTP/SSE/WS 协议不受此变更影响。
每次 RPC 的单调 deadline 从调用入口开始,包含编码、等待请求锁和远端调用。不配置重试,并关闭 gRPC retry 支持。发送前排队过期不影响正在执行的另一条请求;已发送请求超时、连接错误、异常回复或取消启动会关闭 channel 并终止进程组。可识别的业务拒绝和本地校验失败不会使连接失效。请求预算耗尽后的强制清理有单独期限;超时不能证明命令未执行,也不会回滚已推进的物理步。
运行中取消先中断客户端等待并保留 channel,再发送 stop_task;停止确认最多等待十秒。执行端按物理步边界处理停止,无法在期限内确认的长原生调用会进入失败回收,不能显示已取消。取消等待不等于取消已执行命令,客户端不自动重放它。正常 close 的确认与进程退出共享一个默认六十秒的收尾期限;记录器将尾块入队与排空合并在自身三十秒期限内。超过外层期限会强制回收并抛出错误,不再吞掉错误。任务终态直接读取并校验 result.json.execution;完整 manifest 只证明归档完整。没有执行端结果的启动取消或强杀标记 result_state=unavailable,不伪造任务终态。工作台关闭也使用统一期限等待现有任务收尾,避免十五秒后截断合法归档。
强制关闭无需等待请求锁;正常物理关闭先确认 close 命令,再等待归档与退出。 进程清理由 RpcProcess 统一执行,包含 TERM/KILL 升级、等待回收与临时 socket 删除。 Linux worker 通过 pidfd 检测所属客户端进程退出,在当前批次结束后停止;这替代了旧 stdin EOF 的生命周期信号。 启动仍通过项目环境选择器完成,不需要常驻 broker 或网络端口。
轻量回归覆盖真实 gRPC 子进程的超时、退出、损坏回复、业务拒绝、并发关闭、启动取消、 迟到命令及进程组清理;原有物理会话契约测试也通过实际 socket 驱动。 真实规划与物理引擎的验证入口分别为 workspace 和 isaaclab 检查,见验证指南。
ROS 控制 gRPC
网页与 Launch 使用同一 pride.Control/Command unary RPC,地址为会话目录中的 control.sock(Unix domain socket,权限 0600)。端点通过目录描述符支持长路径; 服务端持有该目录的排他锁,重复绑定不能接管在用会话。客户端复用 channel,关闭客户端不会停止 ROS 会话。
控制命令、快照、应答与人工点动限额的唯一 schema 是 pride_core.control; 关闭结果沿用 pride_core.ros2.RosShutdownResult。网页命令只继承共享字段并添加 HTTP 元数据, OpenAPI、TypeScript 与运行时校验由模型生成。gRPC 使用共享 JSON 编解码, 删除了换行 JSON socket 协议;不维护平行的 protobuf 数据模型。 请求和回复均严格校验,拒绝未知字段、非有限值及隐式类型转换。ROS 内部传递已验证对象, 控制权、时钟新鲜度、序号递增与停稳判断由执行端负责。
ROS 的 gRPC handler 在有界线程池中调用控制入口;ROS executor 独立推进反馈与 watchdog。 执行端在获取控制锁后再次检查调用是否过期,尚未执行的过期输入不生效。 所有调用关闭自动重试;超时不能证明未执行,不能重发运动,也不会杀死 Launch。 Launch 关闭使用一次带 deadline 的 wait-for-ready 调用,确认停用后继续原有收尾顺序。 键盘转换保留原 HTTP 接收时间及原始按键来源;日志不保存控制权凭据。
单臂自主执行与有界归档
工作台提交一次 run,携带有限步数与实时节拍选项;普通关节目标运行另带求解后的关节位置,自动抓放先发送 start_task,不传网页关节目标。物理进程在唯一拥有引擎的线程中自主推进,业务进程只以 20 Hz 获取状态;停止订阅、慢显示或轮询间隔不再决定物理是否推进。实时节拍只限制运行不超前于墙钟,不跳过物理步、不改变 dt,也不保证过载时仍能实时。
pride_core.physics_commands 在入口严格校验命令。advance 保留为明确的手动有限步进,与自主运行互斥。stop_task 在步边界停止并冻结目标,非抓放任务也适用;终态拒绝继续运动,必须 reset。取消和 close 会补齐采样间隔内的实际末帧。业务端直接呈现执行端的 Goal 状态和最终结果;finalizing 是进度阶段,迟到取消不能覆盖已冻结的判定。
轨迹采用官方 RRD 的带序号数组块,结束标记校验块数、样本数与完整性;旧数组 RRD 继续由统一读取入口处理。数据与证据分块交给单写入线程,结束时排空并纳入原有 manifest 哈希。慢显示仍只保留最新帧;可靠记录队列耗尽则明确失败,不丢必需数据。
iS7 工作台默认使用 tasks/aubo_is7_workbench.yaml(Newton/Steel,最多 20 秒仿真时间)。现有单臂目标编辑与异步 IK 继续使用 revision 隔离迟到结果。此路径不新增视觉抓放能力,也不改变现有视觉抓放控制器的同步阶段重规划。入口与人工验收步骤见单臂运行验收,已执行的检查与浏览器证据见仿真与任务状态。
实测姿态进入显示投影时,先按任务测量已有的四元数有效范围(平方范数误差小于 1e-4)检查,再归一化为网页所要求的单位 wxyz;这处理 float32 坐标组合的舍入误差。损坏或非有限姿态仍拒绝,原始 RRD 不改写、不把显示归一化当作物理有效性证据。
Action 任务结果
物理快照携带 goal_id、status、phase,取消回复独立携带 cancel_response。 网页 Task 沿用相同 Goal 状态,result_state 区分等待结果、取得结果和结果不可取得。 准备/加载时尚未观察到执行端,status 为 null,phase 为 queued/starting;不能提前宣称 accepted。 result.json.execution 的 cancel_accepted、recording、cleanup 与错误直接透传,process_exit 由外部拥有者补充。 观察和连续遥操的归档使用独立 SessionRecord,不与有限任务的 Task 枚举混用。 完整状态及成功边界见任务生命周期。