SA 设备控制 - 物理执行逻辑与寻址方案 (Engineering Layer)

文档目的：描述工程侧如何在“检索召回”阶段实现“复合 3x3”全谱上下文注入，并在执行阶段支持双轨路由。

---

1. 核心寻址策略 (Addressing Strategy)

为了保证响应速度与决策灵活性，工程侧执行 “双轨复合召回” 模式，打包“脑层真相”与“手层资产”。

召回轨道	检索目标	业务说明
轨道 1 (Space)	空间级逻辑点位	提取 Top 3 空间的 SSOT 信号骨架。
轨道 2 (Asset)	物理资产实体	提取上述空间下 3x3 的物理设备骨架。

NOTE

双轨已收敛为单轨（当前实现仅轨道 2 物理实体）：早期设计因尚无独立的“空间面板”意图，面板只能被动触发（如会议室准备带出），Agent 无法预判用户是要设备级控制还是空间级控制，故在检索阶段同时拉取“空间逻辑点位(SSOT)”与“物理设备”两条轨道。意图识别丰富后，已单独拆分 PANEL（空间面板）意图，control / query 分支一上来即确定只需物理设备，不再需要空间逻辑点位参与决策。因此当前 Dify 实现中，检索阶段仅保留物理实体层单轨（先 spaces/resolve 定位空间，再 devices/resolve 取该空间物理设备），空间逻辑层(SSOT)双轨已去除——此为意图拆分后的合理取舍，非缺陷。空间逻辑层仅在 PANEL 短路径的“空间逻辑映射检查”中仍被消费。

---

2. 工程全生命周期流 (Engineering Lifecycle)

我们将工程逻辑严格拆分为：复合检索召回 (面向 Agent 推理) 与 指令下发 (面向物理/逻辑触达)。

1.1 场景 A：显式精准检索流 (3-Slot Path)

当用户指令包含明确的 [空间 + 设备名 + flavor] 时执行。

1.3 场景 C：显式指令下发流 (Post-HITL Execution)

展示在用户完成人工确认后的最终物理下压。

---

2. 检索召回阶段逻辑 (Stage A: Search & Recall)

2.1 合法性沙箱 (Legality Sandbox)

检索第一原则：所有进入召回漏斗的实体必须满足“合法性”前置条件。

• 逻辑硬过滤：检索语句必须包含 cap_tags CONTAINS 'control' 且 is_active == true。

2.2 检索漏斗与置信度

1. 空间定界：基于 target_space 过滤，命中 Top 3 空间。
2. 复合提取：同时提取命中的空间逻辑点位（SSOT）与物理设备原语（Flavor 过滤）。
3. 语义打分：结合 device_keyword 对物理实体进行打分排序。

2.3 SSOT 剪枝与去重逻辑 (SSOT Pruning)

为了防止 Agent 面对重复的控制路径（既有空间点位，又有升维前的物理点位），工程侧在组装 Step 1 返回包时必须执行以下剪枝逻辑：

• 判定准则：若物理设备 $D$ 的属性 $P$ 已在当前空间的 [空间逻辑映射] 中被绑定为 SSOT 信号。
• 动作：强制从设备 $D$ 的骨架属性列表中删除 $P$。
• 目的：确保每个语义属性在上下文中具备唯一性，Agent 优先通过空间级逻辑路径进行调控（实现“脑控优先”）。

NOTE

当前 control / query 路径不执行本剪枝：因意图拆分后 control / query 仅检索物理实体层（见 §1 说明），不拉取空间逻辑点位，故不存在"空间点位与物理点位重复"的场景，SSOT 剪枝逻辑在当前实现中不参与。本剪枝仅在"双轨"场景（未来空间逻辑层恢复）或 PANEL 短路径相关能力落地时生效。

---

3. 指令下发阶段逻辑 (Stage B: Final Execution)

3.1 产品级指令拆解 (Product-Level Dispatch)

Engine 收到 Agent 输出的 renderSAControl（含 product_id + 标准语义值）后，按产品映射拆解为逐设备物理指令：

Agent 输出	Engine 拆解
{product_id: "prod_ac_daikin", hvac_mode: 1}	查产品映射 → 大金 制热=1 → 下发 power_switch=true, mode_reg=1
{product_id: "prod_ac_midea", hvac_mode: 2}	查产品映射 → 美的 制热模式=2 → 下发 power_switch=true, mode_reg=2
{product_id: "prod_ac_daikin", hvac_target_temp: 22}	按 step 对齐 → 大金 step=1.5 → 对齐至 22.5 再下发

3.2 物理边界保护 (Boundary & Step)

• 计算逻辑：target_val 受产品级 mapping 中的 min/max 约束保护。
• 拦截准则：若 target_val 超出 product 定义的 min/max，执行熔断并回传状态 BOUNDARY_HIT。

3.3 语义反馈协议 (Outcome Mapping SSOT)

语义状态	触发时机	物理触发条件
SUCCESS	执行期	网关确认执行成功（状态发生改变）
OFFLINE	检索/执行期	心跳离线或连接超时
BOUNDARY_HIT	执行期	计算值触及 min/max 极限
ALREADY_ON	执行期	设备已处于开启状态，用户再次发送开启指令
ALREADY_OFF	执行期	设备已处于关闭状态，用户再次发送关闭指令
ALREADY_AT_VAL	执行期	当前数值已等于目标设定值（如：室温 26℃，设定 26℃）

---

4. 渐进式发现协议接口定义

4.1 Step 1: 复合摘要召回 (Composite Skeleton)

• 输出：{ spaces: [{id, ssot_props: [...] }], devices: [{id, name, role, props: [{name, flavor, mcp_desc}] }] }

4.2 Step 2: 深度注入 (Product-Level Capability Injection)

• 输出：产品级聚合 JSON（详见 Agent 设计文档 §4.1 L3 注入结构）
• 按 product_id 聚合，每产品下 capabilities[] 各点位独立挂 enabled_device_count + current_values[]

4.3 指令执行路由 (Execution Routing)

目标 ID 类型	执行路径	执行中枢
空间逻辑 ID	委托分发	自控平台 (CP)
物理资产 ID	点位直控	物联网关 (IoT)

---

5. 相关设计参考

• SA_设备控制_Agent设计.md
• 产品语义管理 PRD
• 设备语义管理 PRD