SA 设备控制：Agent 设计方案 (Semantic/AI Layer)
文档目的：描述设备控制专家（IoT Specialist）如何通过多轮对话完成槽位提取、意图澄清，并结合后端实时回传的设备/环境能力（Capabilities）实现精准控制。
1. 核心业务流程 (Happy Path Sequence)
IMPORTANT
开发阶段说明：空间级控制与感知能力（如：空间级 SSOT 映射、群控分发等）目前深度依赖 自控平台的空间逻辑信号升级。在信号底座完成升级前，系统将以“物理实体资产直控”作为主要交付路径。
本流程描述在 “多空间干扰” 与 “感知渐进式披露” 背景下，如何通过两阶段工程检索实现精准控制的标准路径。
2. 第一阶段：意图与槽位提取 (Stage 1: Slot Filling)
Agent 在首回合完成 NLU，锁定控制的“物理边界”与“核心实体”。
2.1 槽位定义 (Slots)
| 槽位名称 | 必填性 | 类型 | 说明 |
|---|---|---|---|
target_space | 必填 | String | 物理位置（如 "305", "VIP室"）。 |
device_keyword | 选填 | String | 设备名。缺失时触发“隐式能力聚类”逻辑。 |
target_flavor | 自填 | Enum | [核心] 场景原语：BOOLEAN (开关), NUMERICAL (Float/Int 数值), ENUM (模式)。 |
instruction | 必填 | String | 原始操作话术用。 |
2.2 澄清追问与拦截策略 (Interception Policy)
Agent 必须根据槽位填充的完备性，在 Stage 1 结束时决定是进入工程检索还是发起交互追问。
2.2.1 决策矩阵 (Policy Matrix)
| 场景 | 槽位组合 | Agent 决策策略 | 响应示例 (拦截话术) |
|---|---|---|---|
| 1. 全量路径 | Space + Device + Flavor | 直接通过: 执行 3x3 精准检索 | (静默执行) |
| 2. 隐式路径 | Space + Flavor | 自愈召回: 触发原语嗅探逻辑 | (静默执行候选嗅探) |
| 3. 意图路径 | Space + Device | 逻辑通过: 语义补全 Flavor 后检索 | (静默执行) |
| 4. 关键缺失 | 仅 Space | 强制拦截: 交互追问 Instruction | “请问您想对 [Space] 执行什么操作？” |
3. 第二阶段：工程化分层检索 (Stage 2: Composite 3x3 Search)
IMPORTANT
双轨复合检索：Stage 2 必须并联拉取“空间逻辑层”与“物理实体层”骨架，为 Agent 提供完整的脑手上下文。
3.1 复合 3x3 检索逻辑
- 空间定界：基于
target_space定位 Top 3 空间，并提取其 空间骨架 (含 SSOT 逻辑映射信号及其属性菜单)。 - 资产召回：在上述 3 个空间内，各检索满足语义及能力要求的 Top 3 设备骨架 (含物理实体及其全量属性菜单)。
- [核心] 属性剪枝 (Pruning)：若某个设备属性已通过“资产自动升维”映射至空间逻辑信号，则从该设备的属性清单中剔除该项。
- 结果输出：Engine 向 Agent 返回去重后的复合列表。确保每个语义属性在上下文中具备“唯一入口”，Agent 优先通过 SSOT 逻辑路径实现“脑控优先”。
3.2 隐式意图解析 (Implicit Recovery)
当用户指令缺失 device_keyword（如“305 调到 18 度”）时，Agent 自动进入 “自愈嗅探” 分支。该分支在工程实现上与 Happy Path 完全一致（仅 kw 传空），其核心差异在于 Agent 的决策逻辑：
- 全谱属性嗅探：Agent 从
Step 1回传的已去重的复合骨架列表中，扫描所有匹配指令原语（Flavor）的属性项。 - 择优决策逻辑：
- SSOT 优先（脑控）：得益于剪枝逻辑，如果用户指令匹配了已升维的属性，Agent 只会看到空间级的入口。
- 物理资产（手控）：若该属性未升维（非唯一资产或未配置），Agent 则通过物理设备入口进行控制。
- 冲突决策：若存在多个候选资产（如：305 既有空调又有地暖，且两者都支持数值调节，且均未升维），Agent 在 Stage 4 弹出多选协同卡片供用户抉择。
4. 渐进式披露与感知策略 (Stage 3 & Progressive Strategy)
本章定义了在 Reasoning 阶段（Stage 3）如何通过两阶段信息注入，解决上下文压力与决策精度之间的矛盾。
4.1 渐进式信息注入协议 (L1-L3)
| 层级 | 信息类别 | 包含内容示例 | 注入阶段 | 目的 |
|---|---|---|---|---|
| L1 | 环境感知摘要 | 空间代表温度、灯光状态 (来自 SSOT) | Step 1 默认注入 | 提供空间的“单一真相”现状。 |
| L2 | 复合实体骨架 | ID、名称、角色、能力标签；[核心] MCP 标准语义描述 (llm_desc) | Step 1 默认注入 | 用于初步意图对齐（如：基于标准语义理解“调冷”该找哪个点位）。 |
| L3 | 深度实例描述 | 物理量程 (min/max)、步长 (step)、0/1 枚举定义、实例级 AI 指引 | Step 2 按需注入 | 针对锚定目标执行精准物理计算与边界校验。 |
4.2 环境感知的决策增强场景
当前阶段， 暂不实现 环境感知相关的 环境上下文注入
Agent 必须利用 L1/L3 级感知数据实现高价值逻辑闭环：
| 场景类型 | 逻辑判断 | Agent 反应 (示例) |
|---|---|---|
| 联动辅助建议 | [控 A 察 B] 用户控制投影仪，Agent 感知环境光强 (Lux)。 | “已为您准备好投影仪，当前环境光线较强，建议为您 [关闭并拉帘] 以获得更佳观看效果？” |
| 空间能效闭环 | [控 A 察 B] 用户开启空调，Agent 感知窗户状态。 | “空调已准备就绪，但 305 的窗户目前处于开启状态，建议先 [关闭窗户] 以提升制冷效率？” |
| 动态步进感知 | [综合判定] 用户要求“305空调再冷点”，Agent 结合 室温-设定值 差值计算步进。 | [室温 28℃, 设定 26℃] “当前室温较高，已为您将温度下调至 23℃ 以快速降温。” |
| 环境引导建议 | 基于室温播报，向用户推荐最合理的下一步操作。 | [室温 28℃] “当前室内 28℃ 较热，建议开启制冷。已为您准备好开关卡片。” |
| 操作矛盾预警 | 在渲染控制卡片前，先对物理矛盾进行口语化播报。 | “当前室温已是 20℃，若执行 [制冷 26℃] 压缩机可能无法启动，建议改为自动？” |
| 感官纠偏引导 | 针对体感与数据不一致，引导用户确认目标。 | “传感器显示当前已是 16℃ 极低温度，您确定还要继续 [调低温度] 吗？” |
| 无人节能 | [未来规划] 需接入占用传感器 | (待硬件就位后开发) |
| 自动逻辑 | [未来规划] 需多传感器联动 | (待硬件就位后开发) |
4.3 语义对齐与筛选逻辑 (Reasoning Task)
- 边界校验：对比用户要求的
18度与 L3 注入的min: 20。 - 状态对齐：参考 L3 的当前开关状态。若设备已在目标状态（如已开启），则按“状态冗余”逻辑处理。
- 数值计算：利用 L3 回传的实时值完成相对调节（如“调高 2 度” ->
current + 2）。 - 语义执行 (MCP Logic)：参考由后台
llm_desc注入的指令参考。例如用户说“再冷点”，Agent 需匹配llm_desc中定义的数值负向调节逻辑。 - 跨设备关联 (Cross-Device)：当
instruction命中 A 类设备（如投影）时，Agent 自动检查与其具备语义关联的 B 类环境指标（如 Lux）。若 B 指标异常，则在回复语中加入对 B 的操作建议。(规划中)
5. 第四阶段：前端组件渲染 (Stage 4: Rendering)
Agent 决策完成后，不直接执行物理指令，而是输出渲染协议至前端。
5.1 渲染组件与交互契约
Agent 输出的 renderSAControl 指令必须完全对齐端侧的交互规范与组件状态。
- 交互原型 (UI Reference): device-control.html
- 交互规范 (PRD): 微信小程序_SA_设备控制_交互设计PRD.md
6. 异常场景处理 (Exception Path)
TIP
检索沙箱化策略：由于 Stage 2 已过滤无权资产，Agent 层仅需处理位置/实体客观缺位的场景。
6.1 异常处理时序图
6.2 状态冗余与逻辑背离 (Status Awareness & Logical Conflicts)
当 Agent 收到 Stage 2 注入的深度状态或 Stage 4 物理层的语义状态回传时，执行以下反馈：
| 冲突分类 | 物理/语义特征 | Agent 反馈策略 | 话术示例 |
|---|---|---|---|
| 状态冗余 (开关) | 物理层返回 ALREADY_ON / ALREADY_OFF | 直接告知现状: 不执行物理动作，仅同步状态。 | “空调已经是开启状态了，无需重复执行。” |
| 状态冗余 (数值) | 物理层返回 ALREADY_AT_VAL | 拒绝并引导: 告知已在目标值。 | “当前已处于 [26℃]，无需重复设置。” |
7. 语义状态消费协议 (Feedback Protocol)
Agent 不处理原始物理错误码，仅消费工程侧在《物理执行逻辑》中映射出的 语义状态：
| 语义状态 | Agent 预期话术响应 |
|---|---|
| SUCCESS | "好的，已经帮您处理好了。" |
| ALREADY_ON | "空调（设备名）已经是开启状态了哦。" |
| ALREADY_AT_VAL | "当前环境已经是设定目标，无需调整。" |
| BOUNDARY_HIT | "已经为您调到允许的极限值（[边界值]）了哦。" |
| OFFLINE | "设备目前处于离线状态，建议检查网关。" |
| PERMISSION_DENIED | "抱歉，由于策略限制，该操作目前无法完成。" |
8. 异构设备逻辑代偿 (Implicit Intent Recovery)
8.1 设计背景
在真实项目交付中，暖通空调（HVAC）等设备的物模型存在严重的碎片化，Agent 必须处理以下三种典型的异构控制逻辑：
- 类型 A：标准分离型（如大金/主流多联机）：具备独立的
power(BOOLEAN) 属性，开关逻辑清晰。 - 类型 B：模式聚合型（如约克/部分中央空调）：无独立开关属性，开关机逻辑被合并入
mode(ENUM) 枚举中。例如：0=关机，1=制冷，2=制热。此时，“开启”意图需要转换为对特定模式的选择。 - 类型 C：边界模拟型（如老旧非标设备）：无开关也无模式，通过物理数值的极端边界来模拟开关。例如：
target_temp = 0℃(或 1℃) 约定为关机。
这个一个真实的美的空调例子，关机 = 8
由于底层物模型的“杂乱”，Agent 绝对不能死板地寻找 hvac_power 点位，否则会导致大量异构设备无法被 AI 驱动。因此，必须引入“逻辑代偿”机制。
8.2 核心实现路径 (活用逻辑)
为了在不修改物理驱动的前提下支持此类设备，Agent 采取 “弱化前期 Key 过滤，强化后期能力发现” 的策略：
- 意图兼容性搜索 (Search Broadening)：
- 在 Stage 2 阶段，若按
BOOLEAN过滤后无命中实体，工程侧应放宽过滤条件，拉取该空间下匹配关键字（如“空调”）的所有CONTROL角色能力。
- 在 Stage 2 阶段，若按
- 语义描述引导 (MCP Description)：
- 利用
Standard Semantic Hub中hvac_mode或hvac_target_temp的llm_desc进行逻辑埋点。 - 注入信息示例：“该设备通过运行模式控制启停。当需执行关闭意图且无独立开关时，请将本属性设为 0。”
- 利用
- LLM 逻辑推理代偿：
- Agent (Stage 3) 在感知到设备全量 Capabilities 后，通过 LLM 逻辑推演寻找替代路径：
- 路径 A (Mode 代偿)：
Intent: Off->Search: No Power->Reason: Mode(0=Off)->Action: hvac_mode=0。 - 路径 B (Temp 代偿)：
Intent: Off->Search: No Power->Reason: Temp(0=Off)->Action: hvac_target_temp=0。
- 路径 A (Mode 代偿)：
- Agent (Stage 3) 在感知到设备全量 Capabilities 后，通过 LLM 逻辑推演寻找替代路径：
8.3 交互渲染一致性 (UI Consistency)
即便物理层由 mode 承载开关功能，后端在 Stage 4 组装 renderSAControl JSON 时，应根据 Mapping 关系，虚拟出一个 power 状态字段 给 UI 组件。确保用户在前端看到的依然是标准的“开关拨码”或“电源按钮”，维持交互直觉。
9. TODO 列表
- [ ] 多模态异常反馈：针对离线设备在 UI 上的置灰渲染逻辑。
9. 相关设计参考
- 管理后台: 标准语义管理 PRD
- 原型对齐: 标准语义管理 UI
- 底层底座: 空间语义管理
- 执行协议: SA_设备控制_物理执行逻辑