2026-05-15 变更日志¶

IoT-Agent 能力协商架构 v5 决策（全天单线程迭代）¶

起点：用户提出 4 个相互关联的需求——① 物模型功能开发文档 / ② 设备控制协议开发文档 / ③ Demo App 多 DP 展示 / ④ IoT 与 SaaS 平台打通设备控制协议。

两轮调研： - Step 0a：iot-docs + Conversational-AI-IOT-Sample 现状摸底——MQTT 协议规范齐全，4 个 DP 已实现（switch / volume_set / battery_percentage / charge_status），无 capability 上报链路 - Step 0b：DragonFlow 平台调研——独立 Java 三件套中间件（不是 Sentino Agent 子模块）；OpenAI tool calling schema + Product capability_config 已实现；控制下行走 Agora DataStream（不走 MQTT）；P1 单向无反馈；能力交集逻辑未实现

5 版决策迭代（全部保留在 raw/notes 作历史）： 1. v1（B+B'）：IoT 平台为 capability source + 显式映射表 → 用户推翻：DragonFlow 团队希望维护 product 能力 + C 更灵活 2. v2（C+A）：DragonFlow 维护 + 固件 dispatch + 独立 capability_report MQTT code → 用户揭示真实链路（Agora ConvoAI 透传机制），过度设计 3. v3（Agora customMetadata）：复用 Agora 透传通道 → 看到真实 API doc 后发现更直接路径 4. v4（device_info + Sentino API conversation 上下文）：完全在 Sentino API 内部解决 → 用户指出"跨团队接口"和"IoT 平台内部机制"应该分层 5. v5（两层分离 final）：Layer 1 跨团队接口锁定（device_info.supported_executors）+ Layer 2 IoT 平台内部 X/Y/Z 自决

决策核心：设备实际能力 ∩ 产品定义能力 = agent 实际可用工具集；per-conversation 透传 + 零持久化 + 老 fleet 天然兼容。详见 iot-agent-capability-bridging。

新建页面¶

• concepts/iot-agent-capability-bridging — 架构核心概念页。两套体系无内置桥（物模型 DP vs DragonFlow capability）+ 9 步完整链路 + 两层分离原则 + 决策演化简史 + Layer 2 三方案对比
• concepts/dragonflow-platform — DragonFlow 独立平台概念页。三件套架构 + 独立中间件定位（≠ Sentino Agent 子模块）+ Product 抽象 + Capability Schema 通用框架 + 设备控制 envelope 端到端实现 + 关键文档清单
• journal/2026-05-15 — 本日志

关键知识提取¶

1. DragonFlow ≠ Sentino Agent 平台——DragonFlow 是独立 Java 中间件（workflow-engine + workflow-api + workflow-web 三件套），是 Sentino Agent 的"事实核心实现"但概念上不同。意义：未来讨论 sentino-agent 能力时要区分"产品定位/API 契约"和"具体实现"两层。 → 与 sentino-agent 的连接：sentino-agent.md 应该提到 DragonFlow 是其当前事实实现（暂未在该页加链接，留作下次更新）

2. 物模型 DP 与 agent capability 是两套语义独立体系——物模型 volume_set: int 0-10 是低级属性，DragonFlow capability display_emotion(emotion_type) 是业务级行为。中间没有自动映射。意义：DP↔Capability 映射决策必须显式做（v5 选 C：固件 dispatch）。 → 与 mqtt-device-protocol 的连接：MQTT 协议层的 DP 字段（switch/volume_set/etc.）跟 DragonFlow capability 是两个层次，不要混淆

3. 设备控制协议有两个独立通道——物模型走 MQTT，agent 控制下行走 Agora DataStream（二进制广播）。意义：固件需要同时实现两套接收逻辑；MQTT 不承载 agent 控制 command。 → 与 agora-rtc-voice 的连接：DataStream 是 Agora RTC 频道里的辅助通道，不只是音频

4. Per-conversation 透传是 sentino API 的设计模式——device_info 已经包含 battery / wifi / location 等"per-session 新鲜状态"字段，capability 加进去完全 idiomatic。意义：架构选型时要先看现有系统的设计模式，不要凭空创造新基础设施。 → v5 决策的关键思路转折就是这一点（v3 → v4 → v5 三版迭代后才看到）

5. 跨团队接口和平台内部机制必须分层——v4 把"agent 平台需要什么 spec"和"IoT 平台用什么方式获取 capability"混在一起讨论，导致 A vs B 对比看似关键但其实是 IoT 平台内部决策。v5 拆开后 Layer 1 锁定+ Layer 2 IoT 团队自决，路径立刻清晰。 → 这个分层经验适用于一切跨团队架构讨论（不限于 capability 协商）

6. 设备控制协议在 iot-docs 现状审计：5 份文档共 3209 行 - device-control-firmware-implementation-guide.md（927 行）：直接用 ✅ - device-control-protocol.md（981 行，张鹏稿）：从未实施 + 与 v5 架构冲突 → 已加 DEPRECATED banner - design.md（530 行）：§4 改写为 v5 路径 + §9.5 v5 进展段 - product-capability-guide.md（548 行）：保留主用 - Sentino Device Control Doc.md（223 行）：历史保留

更新页面¶

• concepts/mqtt-device-protocol — 新增"Capability 字段（Layer 2 方案 X，2026-05-15 v5 决策）"段；相关概念加 2 条新链接（iot-agent-capability-bridging / dragonflow-platform）；sources 加 v5 memo；updated → 2026-05-15
• projects/sentino-iot — 新增"IoT-Agent 能力协商架构（2026-05-15 v5 决策）"段（含 Layer 1/Layer 2 + 三轨道并行 + 核心认知刷新）；相关概念加 2 条新链接；sources 加 v5 memo；updated → 2026-05-15
• wiki/index.md —「Sentino / 平台与基础」段在 beken-at-server 之后新增 2 条（dragonflow-platform / iot-agent-capability-bridging）；最近更新加 1 行 2026-05-15

配套修改 iot-docs/control/¶

不在 obs 知识库内但跟今日决策强相关，记录：

• device-control-protocol.md — 加 DEPRECATED 2026-05-15 banner（保留张鹏 author 归属，引证代码 zero 引用 + §A.4 否决 + v5 决策）
• design.md §3.2 — "demo 文档"改为引用 DragonFlow device-control-application.md + device-control-firmware-integration-guide.md
• design.md §4.2 + §4.3 — 整段改写为 v5 per-conversation 透传方案（早前 PID×firmware 矩阵方案降为对比表里的"早前方案"）；mermaid 重画
• design.md §7 — 文档关系表拆两块（iot-docs 内部 + DragonFlow 上游 4 份文档）
• design.md §9 — 标题去"待跨团队对齐"；§9.4 4 条建议按进展打 ✅；新增 §9.5 v5 责任域归属表
• design.md 附录 B 未决问题 #4#6#7 — 按 v5 进展更新

任务系统¶

• 关闭 task #7（综合需求 + 拍板关键设计决策）
• 关闭 task #3（设备控制协议开发文档：经审计发现 iot-docs/control/device-control-firmware-implementation-guide.md 已覆盖固件视角，本轮改为 review-and-update 6 项）
• task #4（IoT ↔ DragonFlow 能力协商打通）描述更新到 v5 final spec
• 新增 task #8（W：沉淀 v5 进 obs wiki）
• task #2（① 物模型功能开发文档）转 in_progress

新增 memory¶

• feedback_sentino_decision_authority.md — 用户在 Sentino 内部技术架构决策上有 proxy authority；偏好高速单线程讨论而非多人共识建立。Why：今日讨论 capability 协商时用户拒绝"escalate 给 Chris/姜涛/子昕"，全程单线程拍板 5 版迭代；明显比"产出方案 → 等会议反馈"快得多

事实核查记录¶

• 代码核查 device-control-protocol.md 的版本协商机制是否实施：grep protocol_version|device_capability|capability_ack 在设备代码（Conversational-AI-IOT-Sample/device/projects/common_components/sentino_interface/sentino_conv_ai_command.c）中均无命中——确认从未实施。这是 deprecation banner 的关键证据
• 代码核查 4 个已实现 DP：Conversational-AI-IOT-Sample/device/projects/beken_genie/main/app_dp_handler.{h,c} 实证 switch / volume_set / battery_percentage / charge_status 四个 DP 已实现（snapshot 报告 + 阈值触发 + 周期采样）。其中 volume_set + switch 是"可下发可上报"，对应 LLM 可控候选
• API doc 现状核查 ~/local/memovis/api-gateway/docs/api.md：/api/v1/conversations 已有 device_info 字段（battery / wifi_rssi / mac / location 等 per-session 透传）；/api/v1/agent/chat 接受 conversation_id 用作 chat 回调上下文 lookup key——印证 v4/v5 的 conversation 上下文存储路径可行

待办¶

• D1（task #2）：写 ~/local/iot-docs/guides/guide-thing-model-firmware.md 或类似位置的物模型固件开发指南（不依赖任何决策）
• D3（未建 task）：检查 iot-docs 整库其他相关页是否需要 v5 同步（如 architecture.md §7 / §8 修正）
• 等 IoT 团队拍板 Layer 2（X/Y/Z）→ 给 doc ② 加 capability 协商章节
• 等 Layer 1 spec 实施完成 → 启动 task #4（4a-4e 五子任务）
• task #6 ③ Demo App 3a UI 暴露已上报 DP（独立可启动）/ 3b net+signal DP 上报

蓝牙音频协议入库（晚间补充）¶

起点：用户问"蓝牙耳机蓝牙音箱和手机交互的协议"。知识库已有 ble-classic-vs-le（入门区分页）但缺 audio profile 这层细节，决定补一个 concept 页。

新建页面¶

• concepts/bluetooth-audio-profiles — 经典蓝牙音频协议栈完整页：A2DP/HFP/AVRCP/HSP/PBAP 五 profile 分工 + ACL vs SCO 链路差异 + 配对生命周期 + LE Audio (BAP/LC3/Auracast) 替代轨道 + 反向论证 Sentino 不走蓝牙音频的三个原因

更新页面¶

• concepts/ble-classic-vs-le — 相关概念加 1 条：bluetooth-audio-profiles
• wiki/index.md — Sentino/平台与基础段在 ble-classic-vs-le 之后插入 1 条新页；最近更新加 1 行

关键知识提取¶

1. A2DP vs HFP 不同链路：A2DP 走 ACL（异步可重传，~700 kbps，单向音乐），HFP 走 SCO/eSCO（同步不重传，64-128 kbps，双向通话）。这是"AirPods 一接电话音质就崩"的物理层原因——切了链路。
2. AVRCP 是控制信令通道：耳机按键能控制手机播放器，跑在 AVCTP 之上，跟音频流分开。1.6 之后支持 browsing。
3. HFP AT 命令：跑在 RFCOMM 上，把蓝牙耳机当 modem 用。AT+CHUP 挂断、AT+VGS 调音量。这是早期 Headset Profile 历史包袱。
4. LE Audio 推翻"BLE 不能跑高质量音频"：5.2 引入 BAP + LC3 + Auracast，蓝牙音频整体在从 Classic 迁到 LE 侧。AirPods H2 / Galaxy Buds3 / Pixel Buds Pro 2 已支持，但 Classic 仍是当前事实标准。
5. Sentino 反向决策：蓝牙音频只能 P2P 不能上云 + BLE 配网功耗优势 + RTC 才能接 LLM → Sentino 不实现 A2DP source / HFP AG。如果未来要做"蓝牙耳机直连 Agent"形态需双协议栈 + 仍需上行 RTC，工程量不划算。