DORA Node Manifest 编写指南：用 dora-node.yml 为可复用节点定义类型化契约

DORA Node Manifest 编写指南用 dora-node.yml 为可复用节点定义类型化契约【免费下载链接】doraDORA (Dataflow-Oriented Robotic Architecture) is middleware designed to streamline and simplify the creation of AI-based robotic applications. It offers low latency, composable, and distributed dataflow capabilities. Applications are modeled as directed graphs, also referred to as pipelines.项目地址: https://gitcode.com/GitHub_Trending/do/dora导读本篇技术指南围绕 DORADataflow-Oriented Robotic Architecture的节点清单node manifest即dora-node.yml展开讲解如何把一段普通代码目录变成可被他人一行 YAML 接入的可复用节点包括清单的完整字段、输入/输出类型契约、自定义类型发布、脚手架命令与无索引本地开发流程。读完本文你将掌握如何为 DORA 节点编写、校验并本地验证类型化契约为后续发布到 Dora Hub 做好准备。Node Manifest 是什么node manifestdora-node.yml是 DORA 中一个可复用节点的类型化、带版本号的结构化描述它声明了节点的入口entrypoint、构建命令build、类型化的输入/输出契约contracts以及配置面configuration surface即env。它的存在让一个装满代码的文件夹变成别人可以搜索到、并用一行 YAML 接线的节点nodes: - id: detector hub: dora-yolo^0.5 # ← 从 manifest 解析而来无需关心 PATH inputs: image: camera/image outputs: - bboxmanifest 的定位原则是只保存语言原生 manifest 无法表达的内容DORA 契约与 DORA 接线信息。而名称、版本、依赖等信息继续留在pyproject.toml/Cargo.toml中manifest 从不重复这些内容。这与 guide/src/hub/overview.md 中描述的 Hub 模型一致——Hub 是 DORA 节点的包管理器而 manifest 正是其中的包描述文件。注意hub:是不稳定特性未来版本可能改变行为但 manifest 格式本身apiVersion: 1是稳定的即使不涉及任何索引只要在普通path:节点旁放置dora-node.yml就能获得契约校验见下文本地开发无需索引。一份完整的 manifest以下是一份完整的dora-node.yml示例位于pyproject.toml/Cargo.toml旁# dora-node.yml — lives next to pyproject.toml / Cargo.toml apiVersion: 1 # manifest schema version (currently 1) name: dora-yolo # defaults to [project].name / [package].name namespace: dora-rs # index namespace ( a GitHub org/user) description: YOLO object detection on camera frames categories: [ml-inference] # from the fixed category list keywords: [vision, detection, yolo] runtime: python # python | rust | c | cpp entrypoint: dora-yolo # what to run, relative to the nodes working dir build: pip install . # how to build it (run in the working dir) platforms: [] # optional allowlist, e.g. [linux-x86_64, # linux-aarch64]; empty all dora: 0.4 # optional supported dora version range inputs: image: type: std/media/v1/Image # type URN (see Type Annotations) required: true description: BGR frame to run detection on outputs: bbox: type: std/vision/v1/BoundingBox description: detected bounding boxes # a node may have zero inputs (a source) or zero outputs (a sink) env: # configuration surface, documented typed MODEL: default: yolov8n.pt description: model weights file CONFIDENCE: type: float default: 0.4 types: {} # optional custom type definitions, keyed by # type URN (see below); omit when there are none example: | # snippet shown by dora hub info - id: detector hub: dora-yolo^0.5 inputs: image: camera/image outputs: - bbox字段速查表字段必填说明apiVersion是manifest 模式版本当前为1name可缺省回退到[project].name/[package].name按 PEP 503 规范化namespace是索引键为namespace/name等同于一个 GitHub org/userruntime是python|rust|c|cppentrypoint是工作目录内的相对路径——不允许绝对路径、不允许..见下文build推荐构建命令在工作目录内执行pip install .、cargo build --release、cmake 调用等inputs、outputs是可为空sink 无输出source 无输入inputs.*.type等推荐类型 URN省略则该端口保持无类型校验会跳过它platforms、dora推荐平台白名单按os-arch形态校验驱动dora hub search --platform过滤 DORA 兼容版本范围description、categories、keywords推荐驱动dora hub searchenv、types、requirements、example可选配置面、随包发布的类型、声明的需求、文档片段从 JSON Schema 看字段细节该 manifest 模式以 JSON Schema 形式随仓库发布在 libraries/core/dora-node-schema.json可用于编辑器自动补全。从这份 Schema 中还能提取出若干实现级细节categories是固定枚举sensor、actuator、robot、transform、filter、ml-inference、llm、speech、communication、recorder、visualization、simulator、debugSchema 中标注扩展需通过 index PR 讨论。env支持类型化配置每个环境变量可声明type取值限定为string默认、int、float、booldefault必须是字面量。Schema 中特别说明manifest 会被原样发布进索引因此默认值不能使用$VAR引用展开必须能在每台机器上解析出相同结果。env有安全过滤PATH、PYTHONPATH、LD_*、DYLD_*等安全敏感的环境变量名在校验阶段会被拒绝。requirements仅为信息性声明可声明hardware如[cuda]v1 实际只探测cuda与system按包管理器/平台键控的系统包需求由dora hub info展示、构建开始时提示永远不会被自动安装。PortDef的required仅在 input 上有效校验会拒绝在 output 上使用required省略type的端口在校验时被跳过。entrypoint 规则entrypoint被校验为节点工作目录内的相对路径——绝对路径和包含..的路径都会被拒绝Python托管环境PATH上的控制台脚本即[project.scripts]中定义的名称例如dora-yolo。Rust / C / C构建产物例如target/release/dora-yolo或build/lidar。从 Hub 包解析时entrypoint只在节点自身的工作目录或托管环境中查找——不会去搜索宿主机的全局$PATH因此一个拼写错误会直接报错失败而不是静默运行宿主机上的某个同名二进制。类型化契约inputs / outputs输入和输出类型使用 DORA 既有的类型 URN 系统std/category/v1/TypeName支持嵌套结构体 Schema、参数化类型以及加宽兼容图。当hub:或相邻的path:节点被组合进 dataflow 时manifest 的inputs/outputs类型会作为该节点的input_types/output_types呈现并走常规校验管线dora validate dataflow.yml # producer/consumer URN 兼容性、字段差异检查 dora build dataflow.yml # 同样的检查在任何东西运行之前执行若发生不匹配——比如把std/vision/v1/BoundingBox输出接到期望std/media/v1/Image的输入上——会在组合compose阶段、任何进程启动之前以 producer/consumer 双方的 URN 报错。此外dataflow 作者自己在 YAML 中的注解优先级始终高于manifest 中的声明。关于类型系统的补充事实来自 guide/src/concepts/types.md类型 URN 形如std/category/vversion/TypeName例如std/core/v1/Float32、std/media/v1/Image、std/vision/v1/BoundingBox部分结构体类型支持参数以区分变体如std/media/v1/AudioFrame[sample_typef32,channels2]同基类 一侧未参数化视为通配兼容参数值不同则判为不匹配除精确匹配外类型检查器还支持隐式加宽转换如UInt8→UInt32→UInt64、Float32→Float64、任意类型→Bytes通用汇加宽传递深度上限为 3std/前缀为保留命名空间用户类型不得使用。随节点发布自定义类型节点可以在自己的 manifest 中携带自定义类型定义YAML 形状与 libraries/core/types/std/*/v1.yml 下的标准库类型一致。这些类型必须位于包自身的命名空间之下——std/及其他命名空间会被拒绝namespace: acme types: acme/lidar/v1/PointCloud: arrow: Struct fields: - name: x type: Float32 - name: y type: Float32 outputs: cloud: type: acme/lidar/v1/PointCloud随节点发布的类型会在解析resolution阶段被加载进 dataflow 的类型注册表因此消费者可以在自己的端口检查中引用这些类型。从 JSON Schema 的TypeDef定义可见类型声明支持arrowArrow 数据类型名如Float32、Struct、LargeBinary、fields仅 Struct 类型、metadata要求的元数据键与params类型参数声明如 AudioFrame 的sample_type。使用dora hub init脚手架dora hub init会在你的pyproject.toml或Cargo.toml旁写出一份初始dora-node.yml并尽可能从原生 manifest 预填内容名称、从[project.scripts]/ 二进制目标推导的 entrypoint、描述cd my-node dora hub init # writes ./dora-node.yml dora hub init path/to/node # or target a specific directory从源码 binaries/cli/src/command/hub/init.rs 可以看到脚手架的具体行为预填的名称、命名空间、entrypoint 若违反 manifest 的严格规则如std组织名、foo--bar形式的名字、奇特的 console-script 名称会被安全占位符替代——name回退为my-node、namespace回退为your-namespaceRust/C/C 节点的 entrypoint 回退为target/release/name脚手架生成后会调用NodeManifest::validate()自检而非仅parse()确保dora validate --node-manifest可以立即通过无需手工修正。填充你的inputs/outputs类型和env之后可以单独校验这份 manifestdora validate --node-manifest dora-node.yml该标志在 binaries/cli/src/command/validate.rs 中定义dora validate默认校验 dataflow--node-manifest则切换为校验dora-node.yml本身两者互斥。本地开发无需索引你不需要发布任何东西就能获得契约校验。只要把dora-node.yml放在一个普通path:节点旁它就会被自动识别nodes: - id: detector path: target/release/detector # dora-node.yml lives at the nodes root inputs: image: camera/imagedora build/dora validate会读取相邻的 manifest注入其类型化端口并检查你的接线——与 Hub 消费者获得的校验完全一致。这是编写节点契约时推荐的内循环inner loop工作流不需要任何索引参与即可反复迭代输入/输出契约。构建位置指引Build-location guidance从源码构建节点意味着运行它的机器上必须能完成编译。DORA 的多守护进程multi-daemon流程中每个 daemon 都负责构建自己的节点——在笔记本上没问题但在资源受限设备上可能极慢甚至无法完成例如 Jetson 编译重型节点时可能热降频或内存不足。目标机编译Compile-on-target默认适用于性能足够的机器与轻量节点。宿主机构建再分发Build-on-a-host-and-ship嵌入式推荐在性能足够的机器上为目标架构构建再通过离线缓存流程部署产物让机器人端永远不需要编译。经验法则不要在资源受限的 daemon 上运行重型构建。关于离线缓存与源码镜像可进一步阅读 guide/src/hub/reproducible-builds.md 与dora hub fetch。小结dora-node.yml是 DORA 生态中把代码变成可复用节点的关键一步它用稳定的apiVersion: 1格式承载了语言原生 manifest 无法表达的 DORA 契约与接线信息通过dora validate --node-manifest可在发布前独立校验通过相邻path:节点即可在本地获得完整的类型契约检查。无论是准备发布到 Hub 的正式节点还是仅在项目内部沉淀可复用组件编写一份准确的 node manifest 都是让 DORA 的类型系统真正端到端生效的起点。进一步阅读可参见 guide/src/hub/overview.mdHub 整体模型、guide/src/hub/using-nodes.md消费侧接线与 guide/src/hub/publishing.md发布与命名空间管理。【免费下载链接】doraDORA (Dataflow-Oriented Robotic Architecture) is middleware designed to streamline and simplify the creation of AI-based robotic applications. It offers low latency, composable, and distributed dataflow capabilities. Applications are modeled as directed graphs, also referred to as pipelines.项目地址: https://gitcode.com/GitHub_Trending/do/dora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考