droboticflow/docs/custom-operators

自定义算子 Markdown 体系

当前目录用于承载“自定义算子的详细 Markdown 文档”,目标不是只放一篇总手册,而是把设计、实现、验收和实例说明拆开。

目录结构:

使用方式:

  1. 先阅读 ../custom-operator-manual.zh-CN.md
  2. 用模板写出自己的算子说明
  3. 参考示例补齐输入输出契约、失败模式和验收章节
  4. 当环境中存在真实 custom 算子实例时,运行文档生成脚本把实例级 Markdown 导出到 instances/

自定义镜像使用约束:

  • 用户自己构建并推送镜像到可被集群拉取的容器仓库
  • 用户自己把完整镜像地址填写到算子的 image 字段
  • 平台不会帮你构建或推送自定义镜像
  • 建议填写明确 tag 的完整地址,例如 ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-<operator-name>:<tag>
  • 当前 wjzh 环境已经真实验证过 ccr-29eug8s3-pub.cnc.bj.baidubce.com/xspark/<image>:<tag> 这类私有镜像可正常拉取和执行,详见 百度云 CCR xspark 自定义算子接入指南
  • 不要把 droboticflow-operator-runner:* 当成自定义镜像填写

生成命令示例:

python3 scripts/generate_operator_docs.py

默认输入是仓库内的 internal/api/builtin_operators_catalog.json,不会隐式连接本机 API。如果要从某个真实环境导出自定义算子实例,显式传入目标 API:

python3 scripts/generate_operator_docs.py --api-base-url http://<api-host>:30080

如果你手上只有一个 AI 生成的单算子 JSON,也可以直接生成文档,不必先手工包装成 { "items": [...] }:

python3 scripts/generate_operator_docs.py --input-json /path/to/generated-operator.json

说明:

  • 当前线上算子目录里还没有稳定存在的 custom 实例,因此 instances/ 暂时只有索引页
  • 这并不影响先把自定义算子的文档模板和规范建立好