external-source-adapter

该技能用于编写或评审 Scenescape 外部数据源转换/适配脚本，把 MAVLink、ROS 2、NMEA、CAN、UWB/RTLS 及专有协议的遥测转换并发布到 external/{publisher_id}/{thing_type}，source_id 等于 publisher_id，场景绑定单独处理。写入或改动前需依次阅读本技能、用户指南 docs/user-guide/how-to-guides/publish-external-source-adapter.md、契约文档 docs/user-guide/microservices/controller/data_formats.md 的外部源输入消息格式章节，校验负载时参考 controller/src/schema/metadata.schema.json；已有同类适配器（如 tools/external_source_adapters/mavlink_to_external_source.py）应先读再用。硬性规则是不得复制字段表、必填项、pose 信任规则、身份/碰撞说明、拒绝原因与完整 JSON 示例，只引用 data_formats.md 锚点；契约与代码冲突时以契约与 schema 为准。布局上，可运行示例放在 tools/external_source_adapters/，协议依赖写入该目录 requirements.txt，不并入核心运行时依赖；沿用 SCENESCAPE_* 环境变量命名，主题路径使用 SCENESCAPE_SOURCE_ID，复用 scene_common.mqtt.PubSub 与 PubSub.DATA_EXTERNAL。撰写检查清单：主题与负载 source_id 一致；source_id 持久稳定，不在每次重启生成新 UUID；使用源本地平移和正确的 reference_frame；将原生姿态转成四元数；使用 ISO 8601 UTC 时间戳；仅姿态源可发布空对象数组或把平台作为 [0,0,0] 单一对象；使用带认证的 MQTT 与 CA 证书；凭据放环境变量或密钥文件。范围之外包括空间绑定足迹交接、跨源融合、身份信任白名单、控制器侧 ID 重映射、broker mTLS/ACL 绑定及把协议库提升为核心依赖等。