编程笔记

lifelong learning & practice makes perfect

智元灵犀X2机器人二开01:认识灵犀 X2 与二开全景，端侧、云端与灵心平台

发表于 更新于 分类于
本文字数： 3k 阅读时长 ≈ 3 分钟
本文介绍灵犀X2二次开发的整体架构，包括端侧AIMDK和云端AgentSDK，并给出了需求判断依据和系统全景。

本系列：从 0 到 1 入门智元灵犀 X2 二次开发
本篇要解决的问题：给定一个需求，判断它应该落在端侧还是云端。

灵犀X2是智元机器人发布的搭载情感计算引擎的双足智能交互人形机器人,旗舰版整体具备 30 个自由度,标配 激光雷达、前视双目 RGB 摄像头、RGBD 相机与后视 RGB 摄像头，并配备高算力板 Nvidia Orin NX 计算单元，标配 4G/5G 模块。具备全量的二次开发能力，同时支持灵创平台使用。

一、两条二开路径

智元把二开能力拆成了两套并行、且可以协同的体系。选错路径的代价不是多写几行代码，整个技术方案会拧着走。

端侧开发 云端开发
开发框架 AIMDK（任务编程与扩展框架） 灵心 AgentSDK（LinkSoul）
代码运行位置 机器人本体 你的服务器 / 云主机
通信方式 ROS 2（service / topic） WebSocket 长连接
支持语言 Python、C++ Python、Java
核心能力 控制、感知、交互 语义理解、LLM、TTS
版本 AIMDK 1.0（接口 v0.8） AgentSDK v1.4.0

一句话概括职责边界：端侧管身体，云端管脑子。

但”管身体 / 管脑子”这种说法容易掩盖真正的判断依据。下面给出可操作的判据。

1
2
3
4
5
6
7
8
flowchart TD
    S["需求"] --> Q1{"需要毫秒级实时闭环？"}
    Q1 -->|是| E["端侧 AIMDK"]
    Q1 -->|否| Q2{"涉及语义理解 / LLM / 知识库？"}
    Q2 -->|是| C["云端 AgentSDK"]
    Q2 -->|否| Q3{"需要多步动作编排或离线可用？"}
    Q3 -->|是| E
    Q3 -->|否| C

真实系统几乎都会落到”两者协同”：云端负责听懂并决定，端侧负责执行并反馈。第 05 篇专门处理两者的接缝。

二、灵犀 X2 硬件约束

写代码前需要先接受几个硬约束，它们会直接限制程序能做什么。

计算单元。X2 有两套计算单元：标配计算单元，以及面向二开的开发计算单元（Orin NX / RK3588）。二开程序部署在开发计算单元上，通过千兆以太网（RJ45）访问。

⚠️ 硬约束：运控计算单元（PC1，10.0.1.40）上不可部署二开程序。该单元承担运控等高实时任务，占用其算力会直接影响机器人行走安全。这不是性能建议，是安全边界。

传感器。X2 配备多路传感器（相机、麦克风阵列、触觉等），官方文档给出能力、视场角与参数。注意部分传感器属于选装——写依赖视觉的代码前，先确认目标机器是否装配。

关节活动范围。文档分别给出手臂、腿部、头部、腰部的可保证活动空间。超出范围的关节指令轻则执行失败，重则损伤硬件。动作类程序必须以此为边界。

坐标系。AIMDK 有明确的坐标系约定，所有位姿与导航点位都基于它。导航和位姿相关代码上线前必须先读这一节——否则会出现”坐标数值正确、但机器人朝向反了”这类难以定位的问题。

三、端侧 AIMDK

AIMDK 是智元为二开提供的机器人开放接口与配套工具，基于 ROS 2 Humble。

接口按模块划分：

模块 内容
控制模块 运动模式切换、走跑控制、MC 控制信号与输入源、预设动作、灵创动作、末端执行器、关节控制
交互模块 语音控制（ASR / TTS / MIC 音频流）、屏幕控制、灯带控制
感知模块（选装） 视觉等感知能力
硬件抽象模块 底层硬件统一抽象
故障与系统管理 标注”待发布”
开发者模式 开发者相关配置

接口命名规范（后续会反复用到）：

类型 前缀
Service /aimdk_5Fmsgs/srv/
Topic /aima/
消息包 aimdk_msgs

⚠️ 已知缺陷：ROS 的 service 机制在跨板通信时存在待优化问题。官方明确要求二开时”参考例程添加异常处理、快速重试等保护机制”。

四、云端灵心 AgentSDK

AgentSDK 是对话智能层。程序以 WebSocket 长连接接入灵心开放平台网关，机器人端侧把音频 / 视频 / 文本推给二开程序，处理后回传。

两种交互模式，方向相反：

  • 被动交互：机器人发起（音频 / 视频 / 文本）→ 二开程序处理 → 返回结果（ASR / LLM / VLM / TTS）
  • 主动交互：二开代码主动发起 → 平台转发 → 机器人响应。v1.4.0 起公开入口收敛为”任务流”，即可编排的多步任务序列

五、系统全景

1
2
3
4
5
6
7
8
9
10
11
12
13
14
graph TB
    subgraph Cloud["灵心平台 LinkSoul Platform"]
        LG["LinkskyGateway<br/>二开网关"]
        BR["Bridge 桥接器<br/>控制面 / 数据面"]
        IGW["交互网关<br/>连接机器人终端"]
        LG <--> BR
        BR <--> IGW
    end

    APP["二开应用<br/>AgentSDK"]
    ROBOT["机器人终端<br/>MIC / Camera / Speaker / Motor"]

    APP <-->|"WebSocket (wss)"| LG
    IGW <-->|"WebSocket / TCP"| ROBOT

两条数据流的方向差异，是理解整套体系的关键。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
sequenceDiagram
    autonumber
    participant R as 机器人
    participant G as 交互网关
    participant B as Bridge
    participant L as LinkskyGateway
    participant A as AgentSDK，二开程序

    Note over R,A: 被动交互（机器人 → 你）
    R->>G: 音频 / 视频 / 文本
    G->>B: 转发
    B->>L: 转发
    L->>A: on_request()
    A->>L: response.on_*()
    L->>B: 转发
    B->>G: 转发
    G->>R: 屏幕显示 + 扬声器播放

    Note over R,A: 主动交互（你 → 机器人）
    A->>L: register_task_flow() / start_request()
    L->>B: 转发
    B->>G: 转发
    G->>R: 执行任务
    R->>G: 执行结果
    G->>B: 转发
    B->>L: 转发
    L->>A: on_*_ack()

注意：agent_id 不是机器人硬件编号，是灵心平台上配置的智能体 ID（形如 AGENT_0000001）。机器人在端侧绑定某个智能体后上线，SDK 通过 on_robot_online(agent_id, ...) 收到通知。一个 SDK 实例可以同时服务多个 agent_id——这个设计直接影响状态管理方式，后续会展开讲解。

下一篇进入实操：端侧环境搭建，以及第一个自己写的 AIMDK 节点。

声明

本文首发智元AIMA平台，并在博客同步

欢迎关注我的其它发布渠道