SpaceAgent 设计内参

Appearance

2026 AI 空间智能体 — 语义架构设计 ​

背景：在讨论"设备语义管理"与"空间语义管理"的映射配置问题时，发现当前设备级映射存在大量重复配置、LLM 上下文过重等问题。基于自控平台"产品品类→产品→设备实例"三层继承结构，在 AI 侧建立对应语义映射体系。

场景举例：某实验室装了同一型号 4 盏灯，归属同一个产品（灯），对应 4 个设备实例（灯-01～灯-04）。按设备级映射，每盏灯都要独立配置 light_power、light_brightness 等点位——4 盏灯 × 2 个通用点位 = 8 行完全相同的配置。推广到 50 盏灯、20 台空调、30 个窗帘的空间场景，重复配置量线性膨胀，LLM 上下文轻松破万 token。

更棘手的是设备自建信号（区别于产品继承的标准点位）：灯-04 额外挂了一个"闪烁模式"信号。这类信号不属于产品级定义的通用点位，设备级模式下每个实例各自维护，无法纳入产品复用体系。

关键约定——与自控平台：

  • 同产品 100% 继承：产品层配置的映射（value label / range / step 等）强制下发到所有设备实例，设备层不可修改。即同一产品的不同设备实例，点位映射完全一致
  • 同品类放行：同一产品品类下的不同产品，允许差异（如灯产品和灯带产品的 brightness range 可不同）

注：自控平台信号链（品类→产品→设备）当前无硬约束，每一层均可修改。上述规则为 AI 侧与自控侧的管理约定，后续需在自控平台落实为校验规则。

关键决策——设备自建信号：对于"闪烁模式"等设备自建信号，AI 侧完全无感，不纳入语义映射体系、不出现在 LLM 上下文中——以此换取 Agent 效率提升和逻辑处理复杂度的显著降低。

无完美方案原则：本次重构不做完美方案：将标准点位的映射配置从设备级上提到产品级，设备级只存极少量差异（别名 + disabled_signals），LLM 上下文从"全设备展开"压缩为"按产品聚合 + 仅 enabled 点位"。其中 disabled_signals 仅作用于标准点位（同一产品下各设备实例对标准点位的启停差异），与设备自建信号无关。

1. 总体架构 ​

1.1 角色重新定义 ​

层级当前职责重构后职责对应页面
🧬 标准语义管理定义 Key+品类+default_props不变，定义 Key 是什么 + 品类级自动对账建议iot-semantics.html
📦 产品管理❌ 不存在新增，定义 Key 的映射配置：label/range/step/AI指引iot-products.html
💡 设备语义管理设备级完整 Capability Mapping精简，引用产品映射 + 别名 + 生效开关iot-devices.html
🏢 空间逻辑映射统一齿轮配置分流：设备升维→👁️只读；群控点位→⚙️可编辑iot-assets.html

1.2 数据继承链路 ​

设备语义继承链（品类→产品→设备）：
  产品品类 (Category)     ← 标准语义 default_props（"接入时建议"）
    └── 产品 (Product)    ← 产品级映射配置（label/range/step/AI指引）
          └── 设备实例 (Device) ← 继承产品映射 + 别名 + disabled_signals

空间逻辑映射（独立，不挂在设备下）：
  ├── 设备升维行  → 来源：设备实例 → 引用其产品映射（👁️ 只读）
  └── 群控点位行  → 来源：空间级独立定义，自行配置映射（⚙️ 可编辑）

2. 核心变更：设备语义管理 ​

维度改前改后
映射配置位置设备级完整 Capability Mapping（选择标准语义 + 绑定逻辑信号 + label/range/step/AI指引）上移至产品级，设备级继承产品映射
设备抽屉内容基础信息 + 别名 + 完整映射卡片（齿轮可编辑）基础信息 + 别名 + 产品映射继承展示 + per-signal switch 启用/禁用（👁️只读查看）
映射编辑方式设备级任意编辑 label/range/step/AI指引设备级不可编辑，仅通过 disabled_signals[] 控制点位开关
设备自建信号支持❌ 放弃支持
列表页原始名称、归属空间、别名、状态、异常新增：产品品类、产品名称、总点位、已启用列
列表搜索设备名称新增：产品品类下拉筛选
数据模型capabilities.mappings[] 存完整映射product_id + disabled_signals[] 仅存差异

3. 空间逻辑映射：按来源分流 ​

3.1 数据模型 ​

json
{
  "semantic_key": "light_power",
  "signal_name": "灯具-照明开关 (LightSwitch)",
  "signal_source": "device",           // "device" | "space_logic"
  "source_device_id": "dev_1",         // 仅 source="device" 时
  "source_product_id": "prod_light",   // 仅 source="device" 时
  // 以下仅 source="space_logic" 时有意义
  "mapping_config": {
    "values": { "0": "关闭", "1": "开启" },
    "range": [0, 100],
    "step": 1,
    "ai_instruction": "群控开关，控制空间内所有灯"
  }
}

3.2 行为变更 ​

场景改前改后
点击设备升维行的齿轮打开可编辑详情改为 👁️ 图标，展开只读详情
点击群控点位行的齿轮同左不变
保存逻辑所有映射行完整序列化设备升维行只存 signal_source + device_id，不存 mapping_config
重新扫描装载Case A 自动升维，详情可编辑Case A 自动升维，标记 signal_source=device，详情只读

4. LLM 上下文数据结构（L3 产品级聚合描述） ​

设备控制 Agent 在 Stage 3 通过 get_product_caps 按需注入的产品级聚合 JSON。每个 capability 独立挂 enabled_device_count 和 current_values[]，同产品设备共享一份 mapping，LLM 无需看到逐设备 ID 列表：

json
[
  {
    "product_id": "prod_light",
    "product": "灯产品",
    "category": "照明",
    "capabilities": [
      {
        "key": "light_power",
        "name": "灯具开关",
        "data_type": "bool",
        "access": "rw",
        "semantic_desc": "控制灯具的通断电状态",
        "mapping": {
          "values": { "0": "关闭", "1": "开启" },
          "ai_instruction": "控制灯具开关"
        },
        "enabled_device_count": 5,
        "current_values": [1, 0, 1, 1, 0]
      },
      {
        "key": "light_brightness",
        "name": "亮度调节",
        "data_type": "number",
        "access": "rw",
        "semantic_desc": "调节灯具的亮度输出",
        "mapping": {
          "min": 0,
          "max": 100,
          "step": 1,
          "unit": "%",
          "ai_instruction": "数值越大越亮"
        },
        "enabled_device_count": 3,
        "current_values": [80, 50, 100]
      }
    ]
  },
  {
    "product_id": "prod_strip",
    "product": "灯带产品",
    "category": "照明",
    "capabilities": [
      {
        "key": "light_power",
        "name": "灯带开关",
        "data_type": "bool",
        "access": "rw",
        "semantic_desc": "控制灯带的通断电状态",
        "mapping": {
          "values": { "0": "关闭", "1": "开启" },
          "ai_instruction": "控制灯带开关"
        },
        "enabled_device_count": 4,
        "current_values": [1, 1, 1, 0]
      }
    ]
  }
]

设计要点：

  • enabled_device_count 与 current_values.length 对齐——灯产品 5 台设备全都启用了 light_power，但只有 3 台启用了亮度调节，LLM 可直接感知
  • 每个 capability 独立挂 current_values（不含设备 ID），结构紧凑
  • 控制执行时 Engine 根据 product_id + 语义值拆解为逐设备物理指令
  • 空间级群控点位的映射配置视为"特殊产品"（空间号_群控），补充在同一结构或单独段中

Released under the Private License.

Copyright © 2026-present SpaceAgent Team