EWOS 生态 SDK
接入具身世界操作系统的开发入口。让你的机器人、设备或软件代理,第一次拥有身份、感知、判断、记忆和责任。
SDK 是什么
EWOS SDK 是连接硬件 / 软件代理与 EWOS 运行时的桥梁——屏蔽硬件差异,统一注册身体、上报感知、发起行动、沉淀经验。一次接入,跨身体、跨模型、跨场景复用。
接入 EWOS = 实现三件契约,选一条传输路径。契约是标准,与传输解耦——换路径不改契约。
三件契约
| 契约 | 声明什么 | 标准工件 |
|---|---|---|
| body-profile | 我有什么身体:标识、类型、传感器与执行器清单、能力边界 | embodied/body-profile.v0 |
| capability | 我能做什么:能力 ID、类型(感知/行动/上报)、风险等级、验证器 | embodied/capability.v0 |
| 四类消息 | 身体与内核之间说什么:describe 自述 / observe 上报观察 / act 请求行动 / report 回报结果 |
四类载荷契约均已冻结 |
high / critical 的能力(机械臂运动、急停解除一类)需要 EWOS 内核侧评审签发,厂家写个 low 不会当 low 处理。
两条接入路径
同一套契约的两个传输绑定。按你的场景选,选哪个都不改 body-profile 与 capability。
路径 A · dora-rs 绑定(高性能)
传感器与执行器直接挂在跑 EWOS 的机器上。基于 Arrow 共享内存零拷贝,与内核同语言(Rust),延迟最低。官方维护参考实现。
诚实的覆盖范围:官方零代码模板目前只覆盖 UVC 摄像头、麦克风、扬声器。深度相机(RealSense / Orbbec)、LIDAR、关节电机 / CANopen、IMU 需要自行编写采集节点——我们提供脚手架生成骨架与 Arrow 契约,采集 API 由你的硬件 SDK 决定。
路径 B · HTTP/JSON 绑定(传输中立)
你的身体跑在自己的控制器上——ROS2 节点、专有 RTOS、Python 脚本、只开放 HTTP API 的商业机器人——跑不了或不想跑 dora。任意语言都能接入,这是让 ROS2 / RTOS / 黑盒设备进入 EWOS 的通用绑定。
内核暴露单一端点 POST /api/stp,四类消息共用同一信封:
{
"message_type": "observe | describe | act | report",
"body_id": "your-body-001",
"timestamp": "2026-08-12T12:00:00Z",
"payload": { ... }
}
客户端库
Python 有现成的:零依赖(只用标准库),拷一个文件进你的工程即可,不必照着文档手写请求。它把三条红线做进了 API 形状——见下节。
Rust / C++ 目前需要自行生成:我们提供 OpenAPI 3.0.3 机器可读规格,喂给 openapi-generator 之类的工具即可产出你那门语言的类型化客户端。路径 B 传输中立,任意语言可接。
act 被拒时返回的是 200 而不是 4xx,用响应体的 ok 字段区分。因为"未获准入"是一次完整且已落账的业务结果,不是请求出错——真正的 4xx 只留给协议层错误。生成的客户端会把"没获批准"和"批准了"混成同一条成功路径,这个区分需要你自己补上。我们手写 Python 客户端而不用生成器,正是为了把它做成类型和异常。
红线做进了 API 形状
Python 客户端不靠注释提醒你守规矩,而是让不守规矩在类型上做不到:
- 回报结果不是客户端上的方法,而是
act()返回的许可对象上的方法——拿不到护照,就没有对象可以调用它 - 准入未通过时回报会当场抛异常,请求根本不会发出去。此时护照仍已落账供审计,但不是执行凭据
- 发起主体不开放为参数,恒为你自己。我们不提供一个让人误以为可以冒充他人的入口
行动怎么发生
这是 EWOS 与"远程控制 SDK"最本质的区别:act 是请求执行许可,不是直接驱动你的执行器。
- 你发
act,声明意图、能力 ID 与发起主体 - 内核过行动准入;只有判定为放行才签发行动护照
passport_id - 你凭护照在自己的控制器上执行——EWOS 不接管你的实时控制
- 你发
report回填结果;它必须能回溯到那本已签发的护照
接入认证
内核给每具身体签发接入令牌,每个请求携带 Authorization: Bearer <令牌>。三条约束都返回明确错误码,不静默放过:
| 情况 | 结果 |
|---|---|
| 缺令牌 / 格式不对 / 令牌无效 | 401 |
| 令牌所属身体与信封声明的身体不符 | 403(防冒名上报) |
act 的发起主体不是你自己 | 403(防套取他人授权) |
最后一条常被问到:发起主体是权限查表的键。若允许自报他人身份,任何持令牌的设备都能冒充高权限主体,授权表就形同虚设。要以人类操作员名义发起行动,需要独立的委托机制,不能靠调用方自称。
当前限制(我们主动说明)
- 客户端库只有 Python——Rust / C++ 成品库未发布,需用 OpenAPI 规格自行生成,并自行处理上面提到的
ok语义 - Python 客户端不含重试与退避——何时该重试取决于你的控制回路时序,我们不替你决定;尤其
act,盲目重试一个被拒的行动是在反复撞安全边界 - 路径 A 零代码模板只覆盖标准音视频设备——深度相机 / LIDAR / 电机需自行编写采集节点
- 执行器末端的护照强制校验随真机试点落地——当前参考身体无执行器,只验证了感知侧链路
- 动态身体注册只完成一半——你
describe之后可查询到自己已被登记;dora 路径的运行时热接入仍在路线图上 - 接入令牌为静态预共享——暂无轮换、过期与吊销机制
EWOS 不做什么
EWOS 停在监督层。急停、碰撞保护、实时闭环控制仍然是你身体侧独立安全岛的职责,我们不承诺替代它们,也不建议你把功能安全交给一个网络另一端的系统。这不是能力不足,是分层设计的边界。
快速上手与 API 参考
完整的 Quickstart(从零接入一具软件身体到发起第一次可信行动)与逐接口 API 参考正在整理。在此之前,需要接入文档与 OpenAPI 规格请直接联系我们。
状态:整理中 · 接入契约本身已冻结可用