具身智能机器人人工智能大模型模型推理服务本地部署计算机视觉ROS【免费下载链接】IB_RobotSave the code of IB-Robot, an AI robot execution framework developed by openEuler Embedded for embodied intelligence scenarios. It includes references to the forked version of tensormsg, references to lerobot fork, code references to the lerobot_ros2:ros2_ws branch, as well as some code related to development usability.项目地址https://gitcode.com/openeuler/IB_Robot点击查看免费下载本文聚焦 IB-RobotopenEuler Embedded 具身智能机器人执行框架中机器人技能skill的description:契约。该契约是 Agent/Hermes 调用方与确定性规则解析器在近义技能之间做出正确选择的核心依据也是robot_config加载器强制校验的架构级约束。读完本文你将掌握description:块的完整字段 Schema、近义技能消歧disambiguation的写作规范、时长估算规则以及从 YAML 声明到加载器校验、再到robot-skillCLI 验证的完整链路。1. 契约的定位为什么description:是架构约束而非风格选择在 IB-Robot 的技能体系里每个新增或修改的技能必须在其 SSOT YAML与primitive_sequence同处一个文件中携带description:块。它描述了Agent/Hermes 调用方和规则解析器如何从一组近义技能中选中当前这个技能是整个技能选路逻辑的单一事实来源Single Source of TruthSSOT。省略这个块不是一种风格选择而是一种架构违规architecture violation。原因在于上层调用方如 Hermes、CLI、LLM Agent依赖summary、when_to_use、do_not_use等字段在多个行为相近的技能之间做选择确定性规则解析器依赖aliases_zh配合rule_entry开关完成中文触发词到技能名的固定短语匹配技能目录catalog的文档由description:块自动合成不再需要人工维护每技能的介绍文字。因此在设计流程design flow中description:的编写与校验通常发生在第 5 步Step 5: Author the Description Contract而在第 7 步实现技能时同样必须携带该块任何模板都不能遗漏。2. 完整 Schemadescription 块字段总览契约的完整结构如下该结构由robot_config.loader._validate_skill_description校验见 loader.pyskill_name: description: summary: 120 chars, intent-first, not a mechanical description category: observation|recovery|gripper|translation|rotation|dance|social_greeting|social_affirmation|social_emotion|... when_to_use: [short phrases describing when to pick this skill] do_not_use: # MANDATORY for any skill with near-synonyms - condition: when NOT to pick this one instead_use: existing_skill_name # must be a real skill in the same config aliases_zh: [中文触发词] # ALSO drives the rule parser (single keyword source) aliases_en: [english triggers] motion_scope: [base|shoulder|elbow|wrist|gripper|arm] anchor_pose: named pose | none # must exist in embodied.named_poses unless none intensity: subtle|moderate|large # safety-relevant: large motions near people need care duration_sec_estimate: float 0 requires_motion_params: bool # true if it needs motion_direction/distance from the caller rule_entry: bool # true exposes aliases_zh to the deterministic rule parser2.1 各字段的源码级约束从加载器_validate_skill_description的实现可以提炼出每个字段的硬性校验规则字段类型/取值约束源码行为summary非空字符串去除首尾空白后不超过 120 字符为空或超长均报错summary must be a non-empty string/at most 120 characterscategory非空字符串must be a non-empty stringwhen_to_use非空字符串列表每个元素必须是去除空白后非空的字符串aliases_zh/aliases_en/motion_scope字符串列表可选字段元素必须非空motion_scope的取值必须属于_VALID_MOTION_SCOPES {base, shoulder, elbow, wrist, gripper, arm}loader.py未知 token 会被逐一点名报错intensity可选字符串必须属于_VALID_INTENSITIES {subtle, moderate, large}其他值报错anchor_pose可选字符串若非none则必须存在于embodied.named_poses中引用未定义 pose 会报references undefined poseduration_sec_estimate有限数值且大于 0非有限数nan/inf、布尔值、字符串、负数都会被拒绝must be greater than zerorequires_motion_params可选布尔非布尔报错rule_entry可选布尔非布尔报错do_not_use可选列表每个 entry 必须是 mappingcondition非空字符串instead_use必须引用同配置中真实存在的技能名且不能指向技能自身must not reference the same skill值得一提的是加载器对description的校验发生在加载阶段而非调用阶段源码 docstring 明确写道structural fields are enforced here rather than at call time这意味着配置不合法时技能在系统启动/加载时就会被拒绝而不是等到运行时才暴露。2.2 技能目录侧的双重校验除robot_config.loader外技能目录包skill_catalog/skill_catalog/validator.py也维护了一套DESCRIPTION_FIELDS白名单summary、category、when_to_use、motion_scope、intensity、aliases_zh、aliases_en、anchor_pose、duration_sec_estimate、requires_motion_params、rule_entry、do_not_use并做了更细的约束motion_scope不允许重复值len(set(motion_scope)) ! len(motion_scope)报错aliases_zh/aliases_en必须是无重复的字符串列表aliases must be a unique string listdo_not_use每个 entry 的键集合必须严格等于{condition, instead_use}不能多也不能少duration_sec_estimate必须有限且为正。这套校验与robot_config加载器形成互补前者面向技能目录源树后者面向机器人配置里的技能模板两层一起保证了契约在任何消费入口都不会被绕过。3. 消歧规则近义技能如何互相让路契约存在的全部意义就是消歧。三条核心规则必须同时遵守正向引用在最终确定一个新技能前先列出它与既有技能之间的近义关系并针对每个近义技能添加一条do_not_use记录把调用方引向正确的替代技能反向引用当技能边界发生变化时也应在既有近义技能上添加指向新技能的反向重定向add反向 redirects on the existing synonym skills pointing at the new one单一关键词源aliases_zh是中文触发词和目录别名的唯一事实来源严禁在embodied_common.command_parser里再硬编码一份平行关键词表。3.1 aliases_zh 如何进入规则解析器extract_skill_aliases只在两个条件同时满足时把aliases_zh注入确定性规则解析器rule_entry: true AND requires_motion_params: false也就是说只有规则入口开启且不需要调用方额外提供 motion 参数的技能其中文触发词才会被用于固定短语匹配。这避免了两类误用需要参数如方向、距离的技能不应通过纯关键词直接触发否则会因缺少参数而失败未被rule_entry授权的技能关键词不应出现在规则路径中。在技能目录编译阶段compiler.pyaliases_zh与aliases_en会被一并取出并去空白组装成该技能的别名元组aliases[skill_name] tuple( str(value).strip() for key in (aliases_zh, aliases_en) for value in description.get(key, []) )这印证了aliases_zh与aliases_en是同一份别名体系的组成部分只是分别面向中英文触发场景。3.2 summary 必须意图优先summary的写作准则是意图驱动而非机械描述。例如正确示例Wave hello/goodbye with the wrist意图用腕部打招呼/告别错误示例Sinusoidal joint-5 motion机械描述关节 5 正弦运动理由是 Agent/LLM 调用方依据意图文本做语义选路机械的运动学描述既无法表达做什么也难以与近义技能区分。3.3 悬空引用必须为零do_not_use.instead_use指向的技能必须在同一份配置中真实存在加载器会拒绝悬空重定向dangling redirect。测试 test_skill_description_contract.py 验证了两种典型错误instead_use: ghost_skill不存在的技能→ 报references unknown skill ghost_skillinstead_use指向技能自身 → 报must not reference the same skill。同目录下的集成测试还会遍历 SO101 单臂配置启用技能集合逐一断言每个启用技能都携带summary/category/when_to_use/motion_scope/intensity五个必备字段intensity取值必须落在{subtle, moderate, large}社交手势类技能wave_hello、nod_yes、shake_no、celebrate、greet_observe_raise、act_cute、happy_spin_upright等必须声明do_not_use消歧记录每条do_not_use的instead_use目标必须是同一 profile 启用的技能。4. 完整示例问候技能簇的消歧契约文档给出了wave_hello挥手问候的完整写法。该示例在仓库中已经落地为真实配置 wave_hello/manifest.yaml并扩展出了英文别名wave_hello: description: summary: Wave hello or goodbye with the wrist (casual greeting gesture). category: social_greeting when_to_use: [greet someone, say hi or bye, wave to a person] do_not_use: - condition: agree or say yes instead_use: nod_yes - condition: formal raise-hand greet at the observe pose instead_use: greet_observe_raise - condition: dance rhythmically instead_use: dance_basic aliases_zh: [打招呼, 挥手, 挥挥手, 再见, 嗨] aliases_en: [hello, hi, wave, goodbye, bye] motion_scope: [wrist] anchor_pose: home intensity: moderate duration_sec_estimate: 8.0 requires_motion_params: false rule_entry: true这个例子展示了消歧的完整形态三条do_not_use分别划清边界点头同意→nod_yes、正式举手问候→greet_observe_raise、有节奏的舞蹈→dance_basicaliases_zh覆盖了中文口语变体打招呼 / 挥手 / 挥挥手 / 再见 / 嗨其中再见与嗨是问候场景的常见说法motion_scope: [wrist]表明动作局限于腕部与其wave_hand等近义技能形成区分维度anchor_pose: home引用的是机器人配置中真实存在的命名位姿见下节。4.1 anchor_pose 必须落在 embodied.named_poses以 SO101 单臂配置 so101_single_arm.yaml 为例embodied.named_poses下定义了三个命名位姿home安全/回位位姿observe_table观察桌面位姿对应设计流程中的观察位置 / 看桌面 / 观察位锚点zero零位。因此anchor_pose只有两种合法取值none或这些已定义 pose 之一。任何未定义的名字都会触发加载器报错。4.2 duration_sec_estimate 的估算规则duration_sec_estimate不是拍脑袋而是有明确覆盖口径的确定性手臂运动时长 1.0 秒若存在 open/closed 的 initial_gripper_state 每一条显式 open_gripper / close_gripper 原语 1.0 秒 余量margin也就是说只要技能涉及夹爪开合无论是初始夹爪状态还是序列中途的显式夹爪原语都必须在手臂运动估算之外为每段夹爪动作预留至少 1.0 秒并整体留出余量避免实际执行超时或与上层任务预算冲突。5. 校验与实测测试用例如何锁定契约契约文档引用的校验函数_validate_skill_description由 test_skill_description_contract.py 全面覆盖这些用例本身就是最好的字段取值速查表测试场景期望行为结构完整的 description含do_not_use零错误通过instead_use指向不存在技能报unknown skillinstead_use指向自身报same skillmotion_scope: [knee]、intensity: extreme、负数时长、未定义 pose、rule_entry: yes全部被拒summary为 dict、category为布尔、anchor_pose为数字报必须是字符串类错误duration为nan/inf/-inf/超大数/布尔/字符串报must be a finite numberdescription缺失报description is required测试还特别断言了 SO101 配置启用的全部技能都必须携带完整契约以及社交手势簇必须声明消歧记录——这与设计流程Step 5 强制的要求一致。6. 从 YAML 声明到运行验证的完整链路6.1 技能执行的受控路径IB-Robot 中任何真实机器人技能执行都必须经过安全守卫路径不得绕过直接调用硬件、/task_executor/*、MoveIt、ros2_control或控制器Hermes / Agent / CLI - /embodied/execute_skill - skill_executor - safety_guard - existing primitive executor6.2 通过 robot-skill CLI 验证技能技能完成description:编写后可用robot-skill命令行工具做验证与执行命令取自 ibrobot-robot-skill-design 技能说明robot-skill --config-name NAME validate SKILL ARGS robot-skill --config-name NAME execute SKILL --task-id ID robot-skill --config-name NAME execute recover_safe_pose --task-id ID其中validate子命令只校验技能而不执行定义于 cli.pyexecute需要显式提供--task-id。真实机器人测试结束后除非用户明确要求停在最终位姿否则应当执行recover_safe_pose让机械臂回到安全位姿。6.3 实操中的验证检查清单结合契约与设计流程的 Validation Checklist新增/修改技能后应逐项确认技能名位于planning_policy.allowed_skills若希望 planner 可生成它该 allowlist 不影响 catalog 暴露每个原语都在SUPPORTED_PRIMITIVES内每个命名位姿都存在于embodied.named_posesdescription:块包含summary/category/when_to_use/motion_scope/intensity加载器强制校验并拒绝悬空的do_not_use.instead_use每个近义技能至少有一条do_not_use重定向如 wave_hello 与 greet_observe_raise、nod_yes 之间中文触发词只存在于description.aliases_zh不得在command_parser中硬编码平行关键词表catalog 文档由description:块自动合成不手工维护逐技能 prose。7. 小结description:契约把技能该在什么场景被选中、绝不该在什么场景被选中这件事从隐式的调用逻辑中剥离出来变成一份显式、可校验、可自动生成文档的 YAML 声明。它以robot_config.loader._validate_skill_description为强校验入口以skill_catalog的目录校验为第二道防线以aliases_zh rule_entry为规则解析器的单一触发词来源最终通过robot-skill validate/execute完成端到端验证。遵循这份契约Agent/Hermes 才能在wave_hello、nod_yes、greet_observe_raise、dance_basic等近义技能之间稳定、准确地完成选路。赞分享具身智能机器人人工智能大模型模型推理服务本地部署计算机视觉ROS【免费下载链接】IB_RobotSave the code of IB-Robot, an AI robot execution framework developed by openEuler Embedded for embodied intelligence scenarios. It includes references to the forked version of tensormsg, references to lerobot fork, code references to the lerobot_ros2:ros2_ws branch, as well as some code related to development usability.项目地址https://gitcode.com/openeuler/IB_Robot点击查看免费下载相关推荐IB-Robot 公共运行时接口绑定Interface Binding从逻辑接口到 ROS 契约的声明式消费方案IB Robot 公共运行时接口绑定Interface Binding从逻辑接口到 ROS 契约的声明式消费方案 导读 本文面向 IB Robotope具身智能机器人人工智能大模型模型推理服务本地部署计算机视觉ROSopenEulerOpenHarmony深度学习语音AI AgentAscendexpress-validator 中的 Schema 校验checkSchema 声明式校验完全指南express validator 中的 Schema 校验checkSchema 声明式校验完全指南 本篇指南围绕 express validator 的后端IB-Robot 机器人运行时契约层robot_runtime深度解析契约命名、运行时剖面、Facade 门面与一致性测试IB Robot 机器人运行时契约层robot_runtime深度解析契约命名、运行时剖面、Facade 门面与一致性测试 robot_runtime 是具身智能机器人人工智能大模型模型推理服务本地部署计算机视觉ROSopenEulerOpenHarmony深度学习语音AI AgentAscend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考