机器人软件与具身智能 · 专栏七:软件架构与 SDK 设计 · 第 1 篇
给八界开发一个收纳应用,最容易开始的写法,是在一个脚本里依次完成识别、坐标转换、规划、机械臂移动和夹爪控制。第一次调通时,这种写法很直观:从上往下读,就知道机器人要做什么。
问题会在第二个应用出现。调试工具也需要移动机械臂,网页也要查询状态,另一个任务还希望复用抓取能力。三个程序开始各自检查坐标、处理超时、判断夹爪是否拿住物体。某次修复只改了其中一个入口,其他入口仍保留旧逻辑。此时,复杂度来自同一条规则有了多个主人。
分层要解决的就是这件事:把必须一起变化、必须共同维护的规则放在一起,让应用通过有明确含义的输入和结果使用它。 目录名、节点数量和类的继承关系,都应服务于这条边界。
本篇沿着"让八界末端到达一个目标"展开。先确定目标、状态、计划和任务分别由谁负责,再讨论检查放在哪里、并发时怎样接受,以及上层凭什么宣布完成。SDK 短片段依据作者提供的 demo;可运行的分层与竞争实验是独立实现,完整源码和运行方式会在对应位置给出。

图 1|业务提出目标,能力维护执行条件,观测结果决定任务能否继续。
1. 从一次需求变化判断边界是否合理
设八界要把桌上的玩具放进收纳盒。应用需要先决定"处理哪个玩具",随后获得它的位置,计算接近姿态,规划轨迹,执行并验证持物,最后决定下一步去哪里。这里混合了三类变化:业务策略会变,机器人能力的实现会变,底层设备也会变。
把"先收离自己最近的玩具"改成"先收挡住通道的玩具",不应迫使开发者理解控制器报文。把碰撞检查换成更准确的模型,不应要求网页重新编排取消流程。相机驱动重启之后需要更新来源身份,也不应由每个业务自行发明一套判断方式。能够局部修改,说明相关责任已经集中;每次改动都沿调用链扩散,则说明某些实现细节穿过了边界。
八界 Plus 的业务设计分为原子能力、动作能力、价值能力。原子能力提供单项可复用操作,例如查询坐标、计算几何或执行一份已检查的计划。动作能力组织一次有完整执行语义的操作,维护相关前提、子步骤、取消和结果。价值能力决定目标选择、处理顺序和恢复政策,demo 通过 SDK 组合这些能力。
SDK 开放原子与动作能力,demo 通过这些入口组织价值能力。SDK 负责把类型化请求交给系统、保留任务身份、等待并转换结果。它不应该因为离应用最近,就顺便接管"失败后换哪个玩具"这样的业务选择;也不应因为能连接服务端,就把规划算法复制到每种语言的客户端。

图 2|价值层通过 SDK 组织原子与动作能力,驱动和算法支撑实现。
标题里的驱动、算法、能力、动作和业务,是另一个观察角度。驱动处理设备读写;算法把确定输入变成计算结果;能力组织对调用者有意义的操作;动作维护一次执行的生命周期;业务选择为什么做和接下来做什么。这些职责可以落在不同模块,也可以由同一进程中的多个对象承担。不要把五类职责误画成必须部署的五台服务。
2. 一次请求要经过哪些对象
假设应用已经选中一个目标,希望末端从当前位置移动过去。沿调用链看,会遇到至少四类对象。
观测对象 保存当前知道的事实:关节位置、采样时间、参考系、来源运行代次。它描述过去某一时刻的测量。计划对象 保存基于这些事实算出的候选动作及适用条件。它描述一种未来方案。任务对象 保存这一次提交的身份、状态和结果。它描述执行的进展。业务检查点记录为什么执行、当前目标是什么、已经验证到哪一步。
这些对象的寿命并不相同。观测可能很快过期,计划可能只能消费一次,任务记录在执行结束后仍需保留以供查询,业务检查点则可能跨越应用重启。把它们合并成一个不断修改的大字典,会让"当前值"失去含义:位置是计划目标还是实测位置?success 是规划成功还是任务成功?时间是采样时间还是最后一次刷新页面的时间?
合理的数据流是:应用提供目标,能力入口读取并验证观测,算法产出计划,执行入口重新检查计划适用条件,执行任务保存身份与终态,业务根据结果和必要观测推进。数据沿链路向下细化,执行证据沿链路向上返回。每跨一层,都应能说明增加了什么判断,而不是只把参数转发了一次。
当前 Plus 的外部 SDK 传输可以使用 JSON 序列化,网关进入内部后转换为明确的 ROS 消息、服务或 Action 类型。内部算法因此不必理解网页的请求格式,网页也不必知道规划器的内部数据结构。类型转换集中在边界处,字段校验和错误定位才有稳定位置。

图 3|得到计划、接受命令、观测确认到达,是不同阶段产生的事实。
这一链路同时解释了为什么"调用成功"需要分层理解。网络收到回复,只说明某次请求得到处理;规划成功说明当前输入下找到了方案;控制端受理说明命令进入执行体系;目标关系被确认,才可能满足上层任务的完成条件。每层返回的结果必须保留自己的含义,不能逐层缩成同一个 True。
3. 先把可计算的部分从设备交互中拿出来
分层不一定从引入框架开始。一个更直接的动作,是先找出不需要设备副作用的计算。
在分层实验中,末端移动先简化为一维恒速模型。当前位置为 0.30 m,目标为 0.55 m,速度为 0.10 m/s,因此时长是 |0.55−0.30|/0.10=2.5 s。这里故意不处理加速度和碰撞,只用来检验计算与执行是否真的分离。运行说明包含输入和预期结果。
python
def interpolate_plan(sample, target_m, speed_mps=0.10):
"""Pure scalar model: no acceleration or collision checking."""
if not all(math.isfinite(x) for x in (sample.tcp_m, target_m, speed_mps)) or speed_mps <= 0:
raise ContractError("algorithm", "INVALID_INPUT")
if not 0.0 <= target_m <= 0.80:
raise ContractError("algorithm", "OUTSIDE_MODEL")
return Plan(target_m, abs(target_m-sample.tcp_m)/speed_mps,
sample.world_revision, sample.source_epoch)
函数只接收数值与上下文,不持有连接,不访问控制器。计算失败可以直接定位到输入或算法;成功也只是得到 Plan,不会让八界发生运动。这使它能够被规划预览、参数检查和离线测试共同使用。

图 4|0.25 m 位移在 0.10 m/s 的设定下需要 2.5 s。
将目标改为 0.45 m,结果变成 1.5 s,上层只是换了目标。以后若加入加速度约束,算法和计划表示会改变,业务"到达这个目标"的意图仍可保留。反过来,如果函数内部读取当前位置、切换工作模式并发送命令,它就很难单独回答"规划需要多久",也无法在不连接机器人的情况下复算结果。
纯计算并不意味着不需要上下文。碰撞规划需要机器人模型和环境快照,逆解需要关节约束,目标转换需要参考系。重要的是把这些依赖以明确输入或受控服务提供,而不是藏在任意全局变量里。同一份输入究竟指向哪版模型、哪份场景,应当能够被记录和核对。
4. 能力入口增加的价值,是整理计算成立的条件
算法知道一个数是否有限、一个目标是否在它的搜索域内,却未必知道这份数据是否还新鲜,或者是否来自当前运行的数据源。能力入口要把外部事实整理成算法能够使用的输入。
基础实验的 observe() 先读取状态,再检查年龄:对应实现。
python
def observe(self, now_s):
sample = self.driver.read()
age = now_s-sample.stamp_s
if not math.isfinite(age) or not 0 <= age <= 0.20:
raise ContractError("observation", "STALE_SAMPLE")
return sample
样本产生于 10.00 s,在 10.05 s 使用,年龄为 0.05 s;到 10.21 s 就超过示例的 0.20 s 上限。即使坐标值没有变化,后者也不能被当作同等可靠的输入。若数据源重启,旧 epoch 中的样本还可能与新样本重号,单比较时间或序号都不够。
在真实八界调用中,查询接口可以把这些状态组织成类型化结果。例如诊断调用的几个对象可以拆开理解:精选 SDK 片段。
python
from eco_sdk import CheckArmStateRequest
request = CheckArmStateRequest(timeout_ms=5000)
task = client.eco_checkArmState(request)
state = task.eco_wait()
request 是检查要求,task 是本次调用的句柄,state 是终态返回的结果。查询本身不发送运动,但服务端仍可进行模型与几何计算。应用不必自己订阅全部底层话题、拼接关节快照,再复制一份模型一致性检查。
封装也要控制尺度。如果能力入口只是把十几个底层参数原封不动转发,调用者仍需要掌握全部内部知识;如果它把来源、年龄和检查结果全部隐藏,调用者又失去了决策依据。应当隐藏实现细节,同时保留会改变后续行为的事实。比如"数据过期"应允许刷新观测,"目标不可达"应允许更换目标,二者不适合统一成一个没有阶段信息的异常。
5. 为什么规划结束后,执行入口仍要检查
设八界在时刻 t₀ 根据关节 q₀ 和场景 S₀ 生成计划 P。执行请求到达时已经是 t₁,当前关节为 q₁,场景为 S₁。规划可行只说明 P 对当时的输入成立;要开始执行,还要判断当前事实是否仍满足计划的起始要求。
最直接的条件可以写成:来源相同、场景允许沿用、租约相同、计划未过期、起点偏差在范围内。它们约束的是不同变化。来源重启会改变数据身份;场景变化会改变碰撞关系;租约变化会改变谁能执行;关节变化会使轨迹第一点与实测状态不一致;有效期则限制计划等待过久。

图 5|世界状态或来源代次改变后,原来的目标数值不能证明计划仍适用。
八界当前笛卡尔 demo 将规划与执行分开:查询坐标配置和 TCP,组织目标,获得所需控制条件,规划后得到 resolved_goal 与 plan_id,再显式执行。resolved_goal 帮助查看输入最终被解释成什么;plan_id 让服务端保存轨迹与相关上下文,客户端不需要取回并修改整条轨迹。明确执行的路径会先处理工作模式,再创建短期计划,避免准备过程白白消耗计划有效期。
计划标识也带来责任:缓存归谁所有,什么时候失效,消费失败能否重试,结果未知时如何查询,都要说清。当前 Plus 资料说明计划绑定租约、起始状态与场景条件,并限定单次消费;在线模型版本跟踪不能从这个接口自行推断,模型变更仍需要使旧计划失效。
只在客户端检查一遍无法封住窗口。它可能检查成功后被调度暂停,另一任务改变状态,再恢复发送旧命令。最终接受必须由掌握当前状态、能够约束执行入口的权威模块完成。客户端检查有助于快速报错,执行端检查负责维护最终条件,二者解决的位置不同。
6. 错误应该沿层次保留原因,而不是沿层次失去信息
八界目标移动失败,至少可能发生在输入解释、观测获取、规划、接受、执行和结果核验几个位置。恢复选择取决于失败位置,也取决于已经产生的效果。
输入参考系不认识,可以修改请求;样本过期,可以重新观察;规划不可行,可能需要换目标或站位;命令已经接受但结果丢失,应先查询原任务。若错误返回时机器人仍未确认停止,就不能因为上一层函数已经抛异常而允许下一任务接管。

图 6|错误类别保留发生阶段,上层才能选择刷新、修改目标或核对原执行。
一个常见写法是在每层 catch 所有异常并返回 False。它使表面接口整齐,却把恢复需要的信息删掉了。另一个极端是把最底层异常对象原样穿透到业务,让业务依赖驱动库的类名和错误文字。更稳妥的做法是在边界处映射到稳定的领域类别,同时保留原始原因用于诊断;任务身份、可能已产生效果、停止是否确认等字段不能在映射中丢失。
基础实验用 stage 与 code 区分失败,执行提交后再用观测验证目标:0.548 m 与 0.55 m 相差 0.002 m,在教学阈值 0.005 m 内;0.52 m 则相差 0.03 m;没有观测时保持 UNKNOWN。验证结果不会改写"命令已经提交"的历史。真实八界还需要匹配观测身份和时刻,正是后面证据篇要继续展开的部分。
7. 模块边界和进程边界,应当分两次决定
当数据责任已经清楚,再讨论如何部署。把能力拆成模块,有助于限制依赖、明确输入输出;把模块拆成进程,则增加了序列化、发现、通信失败和部署管理,也带来故障隔离与独立调度的可能。二者不能混在一次命名决定里。
例如,几何计算与规划都需要同一份状态,放在同一宿主可能减少数据搬运;耗时算法若占住唯一接收执行器,又会阻塞取消和状态服务。拆进程未必是唯一修复,也可以分配独立回调组和受控工作线程。选择依据是执行资源、共享状态与故障影响,而不是"一个能力对应一个节点"这种固定比例。
上层依赖也应停在它真正需要的接口。例如业务只需要读取状态、提交动作和查询结果,就不应该亲自创建串口或 ROS subscription。连接对象由外层装配,测试时提供内存适配器,运行时提供设备适配器。端口与适配器架构讨论的正是这类核心逻辑和外部技术之间的隔离。1

图 7|同一组输入和结果规则可以连接内存适配器或设备适配器。
但接口可替换需要行为一致。内存适配器如果立即返回成功,真实适配器只返回接受,两者即使方法签名相同也不能互换。测试替身应该保留正在执行、结果未知和取消等待等状态,才能检查业务是否依赖了现实中不存在的捷径。
另一个实际问题是状态归属。两份模块各缓存一份"当前租约",谁负责更新?一个模块换了目标,另一个模块里的计划是否自动失效?明确谁拥有权威状态,其他模块只读快照或通过接口修改,比盲目拆更多目录更能减少歧义。
8. 把"检查后再执行"缩成一个可以观察的临界区
并发计划实验用 PlanStore 保存计划、当前上下文和起始关节。set_state() 与 consume() 使用同一把锁;消费入口如下。
python
def consume(self, plan_id, lease, now):
with self.lock:
plan = self.plans[plan_id]
if self.states[plan_id] != "READY":
raise ValueError("ALREADY_CONSUMED")
if lease != plan.lease:
raise ValueError("WRONG_LEASE")
if self.context != plan.context:
raise ValueError("CONTEXT_CHANGED")
if not math.isfinite(now) or now >= plan.expires_at:
raise ValueError("PLAN_EXPIRED")
deviation = max(abs(a-b) for a, b in zip(self.joints, plan.start_joints))
if deviation > 0.01:
raise ValueError("START_STATE_CHANGED")
self.states[plan_id] = "EXECUTING"
self.dispatches.append(plan_id)
return "ACCEPTED"
按执行顺序读这段代码。首先检查 READY,防止同一计划再次进入;然后核对租约与上下文;接着检查过期与起始关节偏差;全部满足才把状态改为 EXECUTING,并记录一次分发。重要的不是某一行使用了锁,而是所有相关读写都位于同一个不可交错的区间内。
如果只锁最后的 append,两个调用者可能都先读到 READY。若状态更新不用同一把锁,刚比较完的上下文也可能在提交前改变。另一方面,耗时规划和网络等待不应放进这把锁里,否则一个慢请求会占住其他请求的状态检查。先计算,再用短临界区接受,是把一致性限制在真正需要的位置。
实验让 8 个线程通过 Barrier 竞争同一计划,得到 1 次 ACCEPTED、7 次 ALREADY_CONSUMED 和 1 条分发记录。另一个反例先让客户端检查通过,再把一轴偏移到 0.02 rad;执行端以 0.01 rad 为阈值拒绝,分发仍为 0。有效期从 10.0 s 到 12.0 s,恰好到期也拒绝。

图 8|一份计划只发生一次 READY 到 EXECUTING 的转换,其他调用得到明确拒绝。
这份锁只约束本进程的状态。内存丢失后怎样恢复,分发记录与设备执行之间怎样协调,仍是下一层问题。实验额外保存的 model_revision 也是教学输入,用来说明模型变化影响计划,不能据此声称当前 SDK 已有自动在线版本管理。
9. 用一次真实需求检查抽象是否过粗或过细
现在给应用增加"移动前展示目标,用户确认后再执行"。若接口只有一个隐藏了全部步骤的 do_everything(),应用拿不到预览所需结果;若只开放每个关节的底层写入,应用又必须重做规划与停止管理。规划结果加受约束的执行入口,正好暴露了这次交互需要的边界。
再增加"失败后换另一个玩具"。这项选择适合留在价值层,因为目标优先级随业务而变;但"结果未知时先保留原任务身份""停止未确认时不释放资源"不应由每个业务自行决定,它们属于能力实现的稳定条件。
设计能力粒度,可以连续问三个问题:这段逻辑是否依赖业务目标选择?它是否必须和某份状态原子维护?多个应用是否需要一致处理它?答案会帮助确定哪些内容留给应用,哪些内容下沉到能力。把所有东西塞进 SDK 和把所有东西丢给应用,都容易使责任变得模糊。
迁移已有脚本时,也不必一次推倒。先把读、算、写分开,给数据补齐单位和身份,再集中计划与执行条件,最后替换连接适配器。每一步都保留可运行路径,并用拒绝分支检查没有提前产生副作用。这样的改造顺序让架构变化可以被验证,而不是只在结构图上显得整洁。
下一篇继续把边界写进参数和结果:同样三个浮点数,怎样才能完整表达参考系、时间和失败后的事实。欢迎关注科沃斯八界 AtomGit,相关代码将逐步释放,实际开放内容与使用说明以仓库为准。
参考链接
1 Alistair Cockburn:Hexagonal Architecture,用于理解核心逻辑通过端口连接外部适配器。