定义¶

Sentino 架构里有两套独立的"设备能力"体系——物模型（device ↔ IoT 平台，MQTT 层 DP 属性）和DragonFlow capability（device ↔ agent，OpenAI tool calling schema）——它们语义不同、维护方不同、传输通道不同、且没有内置桥。"能力协商"指的是把这两套体系桥起来：让 agent 在对话过程中只能调用"产品定义支持 ∩ 设备实例实际声明支持"的能力子集，避免 LLM 调一个设备做不到的工具。

2026-05-15 锁定的 v5 方案 = per-conversation 透传 + 两层分离：跨团队接口（Layer 1）走 Sentino API device_info.supported_executors 字段；IoT 平台内部机制（Layer 2）由 IoT 团队自决（X/Y/Z 三选项）。

关键要点¶

• 两套体系无内置桥：物模型 DP（switch / volume_set / battery_percentage）是低级属性，DragonFlow capability（emotion / display_emotion / play_music）是业务级行为；中间无自动映射
• 设备控制下行走 Agora DataStream，不走 MQTT；这是跟物模型协议完全独立的通道
• agent 实际可用工具集 = device.supported_executors ∩ product.capability_config——交集逻辑在 Sentino API 端做（chat 回调时执行）
• v5 = per-conversation 透传：能力声明跟 device_info.battery / wifi_rssi 一起每次会话启动时由设备透传，不持久化、无缓存一致性问题
• 两层分离原则：Layer 1 跨团队接口（Sentino API spec）已锁，Layer 2 IoT 平台内部"如何获取设备 capability"是 IoT 团队自决，不阻塞 V1 启动
• DP↔capability 映射用固件 dispatch（不用 1:1 自动镜像，也不用持久化映射表）——固件 SUPPORTED_EXECUTORS const 数组 + executor switch/case 翻译成 DP 操作
• 老 fleet 天然兼容：缺 supported_executors 字段 → Sentino API 默认取 product 全集，不会突然失能

完整链路（9 步）¶

① 用户按设备按钮
       ↓
② 设备 MQTT publish: agora_agent_device_access
   data: { agent_id, capability: ["set_volume", ...] }      ← Layer 2 方案 X
       ↓
③ IoT 平台调 Sentino API
   POST /api/v1/conversations
   { device_info: { ..., supported_executors: [...] } }     ← Layer 1 接口
       ↓
④ Sentino API 存进 conversation 上下文 + 启动 ConvoAI agent
       ↓
⑤ 返回 RTC 参数 → IoT 平台 → MQTT 回设备
       ↓
⑥ 设备 RTSA SDK 加入 Agora RTC 频道
       ↓ 对话进行中
       ↓
⑦ Agora 回调 /api/v1/agent/chat (含 conversation_id)
       ↓
⑧ Sentino API 按 conversation_id 查 supported_executors
   ∩ DragonFlow product.capability_config
   = 注入 LLM tool calling schema
       ↓
⑨ LLM tool call → DragonFlow envelope → Agora DataStream → 设备 dispatch executor

两层分离原则¶

Layer 2 候选方案： - X：MQTT-on-start 透传（最简，零持久化）—— agora_agent_device_access 上报附加 capability 字段，IoT 平台映射到 API - Y：MQTT-once + DB-cached（fleet 可见性）—— 设备独立上报，IoT 平台 DB 缓存 - Z：X + Y hybrid（最稳健）—— X 主路径 + Y 兜底

与早前矩阵方案的对比¶

mqtt-device-protocol 早前 design.md §4 设计的 "PID + firmware → capability 矩阵" + 设备 fingerprint 兜底方案在 v5 已降级为对比表里的"早前方案"。两种方案的关键差异：

未来如需 fleet 可见性，可在 v5 主链路上叠加独立的"设备 capability 持久化上报"机制，不影响主链路。

决策演化简史（5 版迭代）¶

完整决策备忘见 2026-05-15-iot-agent-capability-decision-memo-v5-final（其余 4 版作为决策历史保留）。

工程量（v5）¶

• Layer 1 跨团队：Sentino API ≈ 1 周 + DragonFlow 暴露 product.capability_config ≈ 1 天 + API doc 更新 ≤ 0.5 天 = ≈ 1.5 周
• Layer 2 选 X：固件 ≈ 1 周 + IoT 平台映射 ≈ 1-2 天 = ≈ 1.5 周
• 三轨道并行总计 ≈ 1.5-2 周（关键路径）

相关概念¶

• mqtt-device-protocol — MQTT 是 device ↔ IoT 平台通道；Layer 2 方案 X 在此通道上加 capability 字段
• dragonflow-platform — DragonFlow 是 SaaS 平台层，维护 product.capability_config；提供 device-control-application.md 作为上游设计 SOT
• sentino-iot — IoT 平台是 Layer 2 实施方
• sentino-agent — Agent 平台维护 Sentino API（Layer 1 实施方），DragonFlow 是其核心实现
• embedded-firmware-layering — 固件 dispatch 落在 SDK 层 + 业务层，per-product SUPPORTED_EXECUTORS const 数组