机器人软件与具身智能 · 专栏七:软件架构与 SDK 设计 · 第 2 篇
给八界写一个 move(0.03, 0, 0),到底想让机械臂做什么?它可能表示移动到基座原点前方 3 cm,也可能表示从当前位置沿夹爪方向再前进 3 cm。两种解释都能通过浮点数类型检查,最终目标却完全不同。
接口设计最难的地方,往往就在这些"看起来已经说清楚"的数据里。数值交给另一进程、另一种语言或半年后的开发者以后,原作者脑中的默认条件就丢失了。一个好用的机器人 API,需要把这些条件变成能保存、能检查、也能追问的数据。
沿着八界从观测玩具到移动末端的过程,我们会依次遇到值的含义、几何上下文、时间有效性和结果证据。它们决定一个请求能否被解释、能否进入规划,以及调用方收到失败后是否还能继续。本文的数值实验是独立教学实现;真实 SDK 只摘录必要的调用,避免把某个教学数据类误认为产品消息定义。

图 1|目标的位置、参考系和观测时刻需要一起交给执行系统。
1. 先确定这个值表达什么,再决定用什么类型
开发者常从 float、list、dict 开始设计参数。更有效的顺序,是先问这个对象在业务中代表什么:一个空间点、一段位移、一份姿态观测,还是一个已经转换到规划参考系的运动目标?它们可能拥有相同的三个平移分量,却不能互相替代。
对于八界看到的玩具中心,首先要知道它来自哪台相机、哪一帧、哪个坐标系。对于机械臂的目标位姿,还要知道旋转的表示方式,以及这个目标是绝对值还是相对当前工具的增量。对于已经接受的运动,则需要新的任务身份,不能继续把最初的检测编号当作执行编号。
可以把一个几何输入理解为"值+解释条件"。值回答多少,单位回答尺度,参考系回答相对谁,时间回答对应哪份状态,来源身份回答它属于哪一次运行。任何一项丢失,都可能使一个格式合法的对象失去可执行的含义。

图 2|三个坐标值只有结合单位、参考系、采样时刻和来源,才能成为可解释的目标。
接口实验把教学请求写成不可变对象,运行说明给出了依赖和各项输出。
python
@dataclass(frozen=True)
class PoseRequest:
xyz_m: tuple[float, float, float]
xyzw: tuple[float, float, float, float]
frame_id: str
stamp_s: float
source_epoch: int
字段名 xyz_m 和 xyzw 直接交代单位、四元数顺序;frame_id 与 stamp_s 保存解释所需的上下文。这里使用 tuple 保存数值,是为了避免调用者提交以后又修改同一列表。frozen=True 只限制属性重新赋值,并不会递归冻结一个对象里所有可变成员,不能代替对数据结构的选择。
不过,也不要为了减少参数数量,把所有概念塞进一个万能 Request。观测、规划输入和执行请求的有效条件不同。把它们分开,可以让"观测已解码""目标已解析""计划已接受"成为三个清楚的边界,而不是用一个不断增加可选字段的字典表达所有阶段。
2. 为什么字段名写了单位,入口还要继续检查
ROS 的 REP 103 给出了 SI 单位和右手坐标系等通用约定。1 统一约定减少了转换,但不会使错误自动消失。设八界需要前进 30 mm,正确米制输入是 0.03 m;写成 30.0 时误差为 1000 倍,而两者在 Python 中都是 float。
教学检查器把位置模长上限设为 2 m,可以拒绝这次明显错误。但这不是八界真实工作区,也不能识别所有单位混用:把 1 mm 写成 1 m,仍可能通过上限检查。范围是针对设备或任务的合理性约束,单位是数据含义,两者解决不同问题。
若一个系统确实需要接收多种单位,入口就应要求显式声明,再统一转为内部单位。不要根据数值大小猜测"这大概是毫米"。同样的 0.5,既可能是半米,也可能是半毫米;猜测会让调用方的错误变成服务端无法复现的隐式行为。
时间参数也有同样的问题。八界 demo 使用 timeout_ms,以名称区分毫秒。教学转换函数明确了舍入和零值处理:转换实现。
python
def seconds_to_timeout_ms(seconds):
if not math.isfinite(seconds) or seconds <= 0:
raise ValueError("timeout must be finite and positive")
# Round down so that conversion never silently enlarges the caller's budget.
milliseconds = math.floor(seconds*1000)
if milliseconds < 1:
raise ValueError("budget below one millisecond")
return milliseconds
0.1259 s 转为 125 ms,向下取整损失不足 1 ms,但不会扩大原预算。小于 1 ms 的正值直接拒绝,因为转成 0 之后,下游可能把它解释成不等待,也可能解释成无限等待。调用规则必须选择一种含义,不能靠每层各自理解。

图 3|把预算转换成整数毫秒时,要同时明确舍入方式和零值含义。
还需要区分"本次等待时长"和"整个操作的截止时间"。如果规划、执行、查询分别获得完整 5 s,业务的总耗时就不再受 5 s 约束。更合理的组合方式是在父操作开始时确定预算,每次进入子调用前计算剩余量。这一计算使用本机单调时钟;相机采样时间可能属于 ROS 时间域,不能与它直接相减。字段都叫 time,并不表示可以参与同一个公式。
3. 点、向量和位姿,要沿不同的变换规则解释
设工具坐标系相对基座绕竖直轴转了 90°。沿工具 x 轴移动 0.03 m,转换到基座后是 (0, 0.03, 0) m;沿基座 x 轴移动同样距离,则是 (0.03, 0, 0) m。差别来自方向,不是精度。
对一个局部位移向量,只有旋转参与变换:Δp_base = R_base_tool · Δp_tool。在水平面展开就是:
Δx_base = cosθ · Δx_tool − sinθ · Δy_tool
Δy_base = sinθ · Δx_tool + cosθ · Δy_tool
如果转换的是一个空间点,还要加上坐标原点位置:p_base = R_base_tool · p_tool + t_base_tool。向量没有固定原点,点有;把两者混淆,会把工具原点错误地加到一个相对移动量上。完整位姿还包含旋转复合,因此"各个分量都加一点"并不是通用姿态运算。

图 4|工具旋转 90° 后,工具 x 方向对应基座 y 方向。
作者提供的八界 demo 先查询坐标配置和当前 TCP 位姿。精选调用保留这段最小用法:
python
from eco_sdk import GetFrameConfigRequest, GetTcpPoseRequest
config = client.eco_getFrameConfig(GetFrameConfigRequest()).eco_wait()
current = client.eco_getTcpPose(GetTcpPoseRequest(timeout_ms=3000)).eco_wait()
工具方向的偏移在 config.tcp_frame 中构造,以局部平移和单位旋转表达;基座方向的偏移则复制当前 TCP 位姿,在规划参考系中增加米制位置分量。它们没有把同一个对象随意改个 frame_id 就交出去。标签不会替数据完成坐标变换,改标签而不改值,只是把原来的数值解释错了。
规划返回的 resolved_goal 可以帮助调用者检查:原始输入最终被解析到哪里,是否符合预期。预览工具应显示这一结果,不能只显示未经变换的输入,再让用户确认一个实际不会执行的目标。
通用 ROS PoseStamped 组合了 Header 和 Pose,提供参考系、时间和位姿字段。2 但消息结构还不足以回答"工具系按何时的姿态解释"。八界移动期间,查询时、提交时和规划时的工具方向可能不同。API 需要选择明确的采样或解析规则,并在结果里留下依据;否则同一个请求重放两次,也可能因为当前工具姿态变化而指向两个位置。
4. 合法姿态、可达姿态和允许执行,是三种判断
四元数是很好的例子。教学接口采用 xyzw 顺序,单位旋转为 (0,0,0,1)。入口先检查长度和有限性,再检查模长是否接近 1。全零四元数没有旋转意义;NaN 也不能进入后续阈值比较。
为什么不能只写"模长大于上限就拒绝"?因为 NaN 与正常数值比较不会像普通大小关系那样工作,NaN > limit 为 False,错误可能直接绕过分支。有限性检查必须先于范围判断。至于很小的归一化误差,接口可以选择容差内接受,或明确归一化并返回实际使用值;不能默默修正一个严重错误后仍让调用者以为输入原封不动地执行了。

图 5|全零四元数无效,单位四元数的正负表达却可以代表同一旋转。
q 与 −q 表示同一旋转,所以实验接受 (0,0,0,-1)。判断两个姿态是否相近,也不应比较四个分量是否分别相等。对已经归一化的四元数,可以用 2 arccos(min(1, |q₁·q₂|)) 计算最短旋转角;绝对值处理正负等价,数值截断避免浮点误差把 arccos 的输入推到 1 之外。
即使数学表示完全合法,八界的机械臂也可能到不了这个姿态,或到达过程中会发生碰撞。表示检查、运动学求解和执行条件检查需要分别给出原因。输入错误应让调用方修改数据;不可达可能要求换姿态;场景已变则需要重新观察或规划。把这些情况合并成 False,调用方只能用猜测决定下一步。
5. 一个失败,可能同时携带几种事实
考虑八界夹取玩具时客户端等待超时。可能是请求没有送达,也可能机械臂已经运动、结果却没有回来。此时"调用失败"描述的是调用方没有获得预期回答,不能直接推导"机器人没有动作"。
结果结构至少需要分开表达接受情况、执行状态、可能效果、停止证据和业务验证。它们不是一条从失败到成功的单轴刻度。任务可以执行失败但已经改变夹爪位置,也可以已停止却没有成功持物,还可以报告某个阶段完成但最终结果尚未形成。
结果实验用一个简化对象保留这些差别:
python
@dataclass(frozen=True)
class Outcome:
task_id: str | None
status: str
has_result: bool
holding: bool | None
stopped: bool | None
这里 holding=None 表示未知,holding=False 表示有证据认为没有持物。两者的业务分支不能一样。尤其不能把网络缺包后生成的默认 False,当成"夹爪已确认空"。
python
def next_step(outcome):
if outcome.status == "REJECTED":
return "FIX_REQUEST"
if outcome.status == "TIMEOUT" or not outcome.has_result:
return "QUERY_ORIGINAL" if outcome.task_id else "RECONCILE_BY_REQUEST_ID"
if outcome.stopped is not True:
return "CONFIRM_STOP"
if outcome.holding is None:
return "OBSERVE_HOLDING"
return "KEEP_SUPPORTED" if outcome.holding else "READY_TO_REPLAN"
这段判断先处理拒绝,再处理超时或结果缺失,然后核对停止与持物。顺序有实际意义:TIMEOUT 即使带着某些旧字段,也应该先凭原任务身份补查;停止未确认时,不应进入可能与原运动冲突的新动作。代码里的任务查询是后续建议,不是偷偷把原动作再执行一次。

图 6|结果缺失、明确未持物和明确持物,会导向不同的后续操作。
对应作者提供的 Plus 说明,EcoError.status 的 may_have_effects 与 stop_confirmed 分别回答是否可能产生效果、停止是否确认;查询任务时,还要先看 has_result 等存在标记,再解释结果字段。这些事实不能压缩成一个"是否成功",也不能互相推出。
业务结果还要回答"验证了什么"。夹爪张开不证明玩具进入指定盒子;空夹爪不证明物体没有掉落;持物判断也不自动提供目标身份。若上层要宣布收纳完成,就需要与目标和容器对应的新观测。API 不必替业务决定所有标准,但应该准确说明自己提供的证据覆盖了哪一步。
6. 输入检查应当分阶段,错误也应能定位阶段
一个合理入口可以先做解码:必需字段是否存在,数字能否表示,列表长度是否正确。接着做语义检查:单位、参考系、时间和来源是否符合要求。随后才把输入交给求解器检查可行性,最后在接受执行时核对租约、计划有效期和当前状态。

图 7|解码、语义、可行性和执行前提分别排除不同类型的错误。
顺序既影响成本,也影响可解释性。一个缺少参考系的请求不该触发昂贵规划;一个已过期的观测不能因为格式合法就进入抓取候选。与此同时,入口检查通过不能替代执行端检查,因为排队与规划期间状态还会变化。上一篇讨论的计划消费临界区,正是在最后一个边界再次确认这些条件。
错误最好保留字段路径、阶段与可追踪身份,例如指出第几个目标的尺寸未知,而不是只说"输入错误"。但错误信息本身不等于恢复建议:提示重新观察可以是合理建议,服务端不应未经调用者选择就自动换目标,再把另一件物体的成功伪装成原请求成功。
7. 批量接口首先要确定"这一批"是否共享同一个世界
八界同时看到几个玩具,业务按离桌面的高度选择目标。教学几何采用 bottom = z − h/2:中心高 0.05 m、尺寸高 0.08 m,底部就是 0.01 m。它假设尺寸沿当前参考系的竖直方向表达,不是任意旋转包围盒都可以直接取第三个尺寸。
计算很短,但它依赖尺寸有效、中心与尺寸属于同一对象、多个对象可以在同一状态下比较。如果第一个目标来自旧帧,第二个来自新帧,把它们放进同一个 list,并不会使它们变成一致快照。
批量实验把共享身份写成 (epoch, snapshot, frame, calibration),限定一批 1--32 个对象、相同采样时刻,且本地可比较时间下年龄不超过 0.20 s。这是独立教学格式,不是 SDK 消息复刻。
python
def validate_batch(rows, now_s):
if not 1 <= len(rows) <= 32:
raise ValueError("BATCH_SIZE")
observations = tuple(decode(row) for row in rows)
reference = observations[0]
for observation in observations:
if observation.identity != reference.identity:
raise ValueError("MIXED_SOURCE")
if observation.stamp_s != reference.stamp_s:
raise ValueError("MIXED_SAMPLE_TIME")
if not 0 <= number(now_s) - observation.stamp_s <= 0.2:
raise ValueError("STALE_SAMPLE")
return observations
函数先解码所有行,再比较跨行条件,全部通过才返回不可变对象。classify() 在此之后统一生成输出。因此最后一项出错时,前两项不会提前进入上层候选集合,调用方能把它当作一次整体操作。
数值入口也值得单独看一眼:
python
def number(value):
if type(value) not in (int, float) or not math.isfinite(value):
raise ValueError("FINITE_NUMBER_REQUIRED")
return float(value)
Python 的 bool 是 int 的子类,普通 isinstance 检查可能把 True 当成 1 m。本例限定原生 int/float 并检查有限性,目的是让这个 JSON 风格输入边界可预测。若要支持 NumPy 数值等其他类型,应另行明确转换规则,不能声称这个小函数接受一切数值对象。

图 8|最后一项的错误也会阻止整批输出,避免先产生部分候选再抛异常。
正常两对象都得到 bottom_m=0.01。随后实验只修改最后一项,分别注入布尔坐标、NaN、未知尺寸、毫米单位、不同来源、参考系、快照和时间;八种拒绝都检查 partial_outputs=0。关键证据是输出集合没有被污染,而不仅是捕获到了一个异常。
8. 什么时候应该允许部分结果
整体拒绝适合必须共同成立的几何输入,却不一定适合所有识别接口。八界的一次观测可能只有部分目标能形成完整几何,业务仍希望处理其中可靠的目标。此时接口可以返回逐项状态、稳定索引和共享观测上下文,明确哪些结果可用,以及本次观测是否完整。
作者提供的 Plus 说明中,同批目标、包围信息和选择信息需要按索引对应;observation_complete=False 不妨碍使用已经有效返回的目标,但空列表不能据此证明视野中没有目标。它表达的是观测覆盖不足,而不是世界为空。这与上面的整体拒绝实验是两种不同设计,不能把实验规则套成 SDK 的真实返回语义。
同理,只有三维中心不能当作完整物体姿态;尺寸有效标记为假时,不能拿默认尺寸做包围几何;一次检测的编号也不必然是跨帧稳定物体身份。把这些边界说清楚,上层才能决定重新观察、只做中心接近,还是要求更充分的几何证据。
设计批量接口时,应先确定调用者需要什么一致性。如果业务要比较整组对象之间的关系,就需要足够一致的集合;如果业务可以逐项处理,则可以接受部分结果,但必须保存每项的来源和失败。最危险的做法是在底层遇错就 continue,既不报告缺失,也不改变"本批完整"的标记。
接口设计最后落到一个很具体的标准:调用方拿到输入检查结果或执行结果后,能否说明自己知道什么、还不知道什么,以及下一步允许做什么。下一篇把这些类型和行为带到 Python 与 C++ 之间,继续看跨语言转换会不会悄悄改变它们。欢迎关注科沃斯八界 AtomGit,相关代码将逐步释放,实际开放内容与使用说明以仓库为准。