SpaceAgent 设计内参

Appearance

2026 AI 空间智能体 - SA 设备控制语义解析与执行逻辑方案 ​

文档目的：描述 空间运营官 (SA) 在完成 NLU 槽位提取后，如何通过级联检索、能力反查及物理映射实现设备的精准控制。本文档侧重于 “槽位填充 (Slot Filling)” 后的工程化执行逻辑。

1. 语义底座对齐 (Semantic Foundation) ​

1.1 统一实体模型 (ai_entities) 数据示例 ​

Agent 执行逻辑严格基于 ai_entities 表。以下为典型的实体数据行示例：

id (UUID)parent_idaliases (JSON)typecap_tags (Indexed)capabilities (JSON)
SP_001BLDG_01["305", "305房间"]SPACE["control", "meet"]{"control": {"enabled": true}, "meet": {...}}
DEV_101SP_001["空调", "大金空调"]DEVICE["control"]{"control": {"actions": [...]}}
DEV_102SP_001["顶灯", "大灯"]DEVICE["control"]{"control": {"actions": [...], "is_default": true}}

1.2 空间能力集成 (capabilities) ​

空间实体的 capabilities 定义了该区域开放的 AI 服务。

  • 示例：305 会议室挂载了 control 插件，代表其在该空间具备“能动性开关”。
json
{
  "meeting": {
    "platform": "feishu",
    "calendar_id": "feishu_cal_305_xyz",
    "capacity": 12 
  },
  "control": {
    "is_enabled": true,            // 作为 cap_tags: ["control"] 的来源
    "description": "允许 AI 控场"
  }
}

1.3 控制意图元数据示例 (capabilities.control) ​

定义标准意图如何翻译为物理网关 Payload。以 空调 (DEV_101) 为例：

json
{
  "control": {
    "actions": [
      {
        "intent": "turn_on",
        "type": "bool",
        "property": "power_switch",
        "mapping": { "on": 1, "off": 0 }
      },
      {
        "intent": "set_temperature",
        "type": "step",
        "property": "target_temp",
        "params": { "step": 1.0, "min": 16, "max": 30 }
      }
    ]
  }
}

2. 向量检索与能力标签 (cap_tags) ​

为了实现高效过滤，我们在向量库中引入了 能力标签 (cap_tags) 机制。

2.1 capabilities 与 cap_tags 的关系 ​

  • 数据关联：cap_tags 是从 capabilities JSON 的 Keys 提取出的字符串数组。
    • 示例：若 capabilities = {"control": {...}, "meeting": {...}}
    • 则：cap_tags = ["control", "meeting"]
  • 目的：利用向量数据库对数组枚举的 “硬过滤 (Hard Filter)” 能力，在召回阶段快速隔离无相关能力的资产。

2.2 向量别名展平存储 (Alias Flattening) ​

由于向量检索（Embedding Search）是针对单条短文本进行的，而实体支持多个别名，因此在 ETL 写入向量库时必须执行 “展平 (Flattening)” 策略：

  • 逻辑描述：1 个 ai_entities 记录（包含 N 个别名） -> 生成 N 条独立的向量库索引。
  • 示例： 若 305 会议室有别名 ["305", "VIP室"]：
    • Vector Row 1: vec("305") | Payload: { "ref_id": "SP_01", ... }
    • Vector Row 2: vec("VIP室") | Payload: { "ref_id": "SP_01", ... }
  • 目的：确保无论用户提及哪个别称，都能通过语义相似度定位到同一个底层 ref_id。

2.3 存储结构布局 ​

  • Vector Index: 对 aliases 各项进行分行 Embedding。
  • Payload (元数据): { "ref_id", "entity_type", "parent_id", "cap_tags" }。

3. 级联召回策略 (Recursive Recall) ​

3.1 为什么选择“逐级锁定”而非“全量并行”？ ​

  • 空间安全 (Spatial Safety)：先锁定 Space 再在 ParentID 下找 Device，能绝对避免跨物理分区的误操作（例如 3 楼和 5 楼都有同名的“顶灯”）。
  • 召回率优化：在单一空间候选池（通常设备 < 50）中检索，准确度与召回率（F1 Score）远高于全局模糊搜索。
  • 路由逻辑清晰：符合人类“先找地方，再操作东西”的直觉认知。

3.2 显式召回流程 (Explicit Control) ​

3.3 隐式召回流程 (Implicit/Capability-Based) ​

4. 步进控制与边界逻辑 (Step & Boundary) ​

在 SA_设备控制_Agent 执行逻辑中，必须读取映射配置中的边界值：

  • 执行前：计算 target_val = current + step。
  • 边界判定：
    • 若 target_val > max，执行熔断并回复：“已经为您设到最高限度 30℃。”
    • 若 target_val < min，执行熔断并回复：“目前已是最冷了呢 (16℃)。”

5. 异常预检与闭环 ​

  • 活跃状态：ai_status != ACTIVE 则触发回复“设备维护中”。
  • 同步校验：sync_error == ORPHAN 则触发回复“该设备目前无法控制，可能已被移除或处于离线状态”。

6. 全链路 User Cases (测试用例) ​

Case 1: 显式精准控制 (Explicit) ​

  • 用户指令：“帮我把 305 的空调开了。”
  • NLU 槽位：space: "305", device: "空调", instruction: "开了"。
  • 推理过程：
    1. 锁定 Space: 305 (SP_001)。
    2. 在 parent_id=SP_001 下锁定 Device: 空调 (DEV_101)。
    3. 匹配意图 turn_on，下发 power_switch: 1。
  • Agent 回复：“好的，已经帮您开启了 305 的空调。”

Case 2: 隐式意图推断 (Implicit - Ambiguity) ​

  • 用户指令：“把 305 关了。”
  • NLU 槽位：space: "305", device: NULL, instruction: "关了"。
  • 推理过程：
    1. 锁定 Space: 305。
    2. 发现该空间下有 3 个可控设备：空调、顶灯、插座。
    3. 均未标记 is_default 或均支持 turn_off。
  • Agent 回复：“请问您是想关闭 305 的哪个设备？（选项：空调、照明、电源）”

Case 3: 边界保护拦截 (Boundary Hit) ​

  • 用户指令：“305 的空调再调低一点。”
  • NLU 槽位：space: "305", device: "空调", instruction: "调低一点" (意图: lower_temp)。
  • 推理过程：
    1. 当前温度 16℃。空调 min 值为 16。
    2. target = 16 - 1.0 = 15 < 16。
  • Agent 回复：“空调已经调到最低温度 16℃ 了哦，不能再低了。”

Case 4: 安全沙箱拦截 (Security Sandbox) ​

  • 用户指令：“打开 110 接待厅的灯。”
  • NLU 槽位：space: "110 接待厅", device: "灯", instruction: "打开"。
  • 推理过程：
    1. 搜索 110 接待厅，其 capabilities 中未挂载 control 插件。
  • Agent 回复：“抱歉，110 接待厅暂未开启 AI 控制权限。”

7. 动态能力发现接口 (Capability Discovery) ​

为了支持 Agent 层的“双阶段意图绑定”，后端除直接执行外，还需提供 能力查询 接口。

7.1 接口职责 ​

后端提供本接口，协助 Agent 完成“晚绑定”。接口需根据输入参数的完整度返回对应的能力集合：

  • 精准发现：当传入 target_space + target_device 时，返回该特定设备的能力。
  • 隐式发现 (空间级)：当仅传入 target_space 时，返回该空间下所有具备 control 插件的设备能力集合。

7.2 交互契约 (Locator & Discovery) ​

输入 (Input) ​

json
{
  "target_space": "305",
  "target_device": "空调" | null // 为 null 时触发隐式发现
}

输出 (Output - 隐式/空间级示例) ​

json
[
  {
    "ref_id": "DEV_101",
    "device_name": "大金空调",
    "available_actions": [
      { "intent": "turn_on", "params_desc": "..." },
      { "intent": "set_temperature", "params_desc": "..." }
    ]
  },
  {
    "ref_id": "DEV_102",
    "device_name": "顶灯",
    "available_actions": [
      { "intent": "turn_on", "params_desc": "..." }
    ]
  }
]

7.3 后端执行边界重申 ​

仅当 Agent 传递了确定的 intent 及 parameters 后，后端才执行最终的物理映射（如生成 Modbus 第 12 号点位的 Write 操作）。

8. 总结与角色分工 ​

  • Agent 层：负责根据上述 available_actions 与用户 instruction 进行二次语义匹配。
  • 执行层 (本文件)：负责实体精准召回、能力数据透传、以及最终物理指令的压发与校验。

Released under the Private License.

Copyright © 2026-present SpaceAgent Team