2026 AI 空间智能体 - 设备语义管理 PRD (v4.0)
版本: v4.1 日期: 2026-07-13 目标: 设备级点位映射全面上移至产品管理。设备语义管理精简为：继承产品映射 + 设备级 per-signal 启用/禁用 + 语义别名管理。消除重复配置，减轻 LLM 上下文负担。
v4.1 变更: 引入弹窗重构为全量展示模式，新增物联平台空间树，引入时自动检测空间/产品依赖。
1. 核心设计理念
1.1 物理与语义解耦
系统在 AI 层通过"语义增强"建立映射。设备的功能属性（Property）被转化为 AI 可识别的角色（RW-读写, RO-只读）。由于系统对接的是经过抽象的自控平台，AI 层面不再需要处理底层的点动（Write-Only）或状态分离逻辑。
1.2 核心设计准则
- 强空间依赖 (No Space, No Device): 任何设备接入前，其所属的空间路径必须已通过 AI 纳管（见 空间语义管理）。
- 产品映射继承 (Product Mapping Inheritance): 设备的点位映射配置继承自所属产品的产品级映射（见 产品语义管理）。设备级不再维护完整映射配置，仅通过
disabled_signals[]实现差异覆盖。 - 设备级仅可控开关 (Device-Level Toggle Only): 设备级仅能控制产品已启用点位的开启/关闭，不得修改产品级定义的 label/range/step/AI指引。
1.3 核心术语表 (Terminology)
NOTE
设备资产 (IoT Devices): 管理具体执行终端，为 AI 提供控场能力映射。 语义别名 (Alias): AI 识别设备的自然语言凭证，如"主灯"、"空调"。 产品映射继承: 设备自动继承其所属产品的点位映射配置（label/range/step/AI指引），设备级仅存储差异禁用列表。 disabled_signals: 设备级禁用点位列表。设备有效点位 = 产品 enabled=true 的点位 - disabled_signals。
1.4 为什么要 disabled_signals：真实场景
同一产品型号部署在不同空间时，管理要求可能不同：
| 空间 | 设备 | 允许的操作 | 需禁用的信号 |
|---|---|---|---|
| CEO 办公室 | 大金空调_01 | 开关 + 温度 + 风速 + 模式 | — |
| 开放办公区 | 大金空调_02 | 仅开关 | hvac_target_temp, hvac_fan_speed, hvac_mode |
| 会议室 | 大金空调_03 | 开关 + 温度 | hvac_fan_speed, hvac_mode |
三台设备是同一产品（大金空调），但管理策略不同。靠产品分类无法解决——不可能为每个空间建一个产品 SKU。因此设备级需要 disabled_signals[] 数组做差异化控制，LLM 上下文中也由此出现了 enabled_device_count 和 current_values[]——每个点位启用的设备数不同，当前值数组长度自然也不同。
2. 管理模块概述 (Device Hub)
2.1 设备管理模块 (Device Hub)
设备管理是能力的"执行器"。将物理实体的属性映射为 AI 意图动作，实现精准控场。
2.2 核心特性
- 强关联接入 (Scoped Import): 设备必须在确定的空间环境下被引入。
- 产品映射自动继承: 引入时关联产品的映射配置，设备级仅需控制点位的启用/禁用。
- 默认别名继承: 首次引入时，AI 别名自动初始化为物理名称。
- 多维度异常感知: 包括物理位移、物模型属性漂移的全面检测。
3. 一致性管控逻辑 (Consistency Governance - Device Focus)
系统遵循 "列表防御性停用，抽屉阶梯式对账" 的分层治理原则。
3.1 异常感知与熔断
针对设备特有的异常触发逻辑：
- 物模型属性漂移 (Property Drift): 若底层物模型变更导致映射失效，系统触发异常并锁定为
⚪ 已停用。 - 💀 物联信息丢失 (Orphan): IoT 端物理删除设备，AI 端同步熔断。
3.2 采纳与闭环 (Stepped Adoption)
- 分支：采纳项: 支持一键同步名称变更、空间路径迁移。
- 分支：配置项: 对于属性漂移，不可自动采纳。管理员需前往 产品语义管理 重新配置产品级映射。
4. 全资源纳管与配置全流程 (Business Process - Device)
设备映射配置不再在设备级维护，而是继承自产品级映射。设备级仅做 per-signal 启用/禁用。
6. 设备资源管理 (Device Management UI)
核心原则: "无空间，不设备"。AI 系统仅纳管已明确归属到 AI 空间下的设备。
6.1 界面总览：强空间依赖
设备管理完全复用"空间管理"的三栏布局。左侧树为"已纳管的 AI 空间树"。
text
+----------------+--------------------------+-------------------------------------------------------------+
| [APP NAV] | [ 已纳管 AI 空间树 ] | 首页 / 设备资源管理 / 金螳螂 / 1楼 / 305会议室 |
| | +-------------------------------------------------------------+
| [🏢] 空间管理 | v 21默认项目 | [ 工作区: 305会议室 (已纳管设备) ] |
| | v 金螳螂 | |
| [💡] 设备管理 | v 1楼 | 产品品类: [ 全部 v ] 搜索: [ 设备名称/产品名称... ] |
| (Active) | 305会议室 <Active| [ + 引入 IoT 设备 ] |
| | > 4楼 | [ 已选 1 项 ] [ 批量生效 ] [ 批量失效 ] (有勾选项时列出) |
| | | +-------------------------------------------------------------------------------------------------+ |
| | | | [v] | 设备名称 | 归属空间 | 产品品类 | 产品名称 | 总点位 | 已启用 | 别名(语义) | 数据状态 | 异常 | 操作 | |
| | | |-----|----------|----------|----------|----------|--------|--------|------------|----------|------|------| |
| | | | [x] | 305主灯 | 305会议室| 照明 | 灯产品 | 10 | 1 | [主灯][灯] | 🟢生效 | - | 配置 | |
| | | +-------------------------------------------------------------------------------------------------+ |
| | | |
+----------------+--------------------------+-------------------------------------------------------------+注意：空间树，取自 `空间资源管理` 已维护的AI空间树6.1.2 关键交互说明
- 强行级联过滤: 列表中的设备，必须严格依据左侧空间树的选中节点进行过滤（选中父节点，将展示其下属所有层级的全部设备）。
- 状态列说明: 【数据状态】
🟢 生效: 设备基础数据在系统中正常生效，被意图引擎识别。⚪ 停用: 用户手动停用或因底层异常被系统熔断锁定。 【同步异常】[-]: 正常。[⚠️ 变更/漂移]: 物理层名称、空间路径修改，或物模型属性发生漂移。[💀 物联信息丢失]: 物理删除，强关联置为停用。
- 安全批量操作 (Batch Safety): 和空间管理一样，勾选执行批量生效时，自动过滤具有异常的设备。
- 生效前置校验: 点击
[生效]时，若该设备的 AI 别名（含原名、别称列表）为空，系统拦截并报错，确保纳管资源具备语义入口。 - 意图承接逻辑 (Intent Resolution): 针对空间级意图（如"调高 305 的温度"），系统优先匹配空间的"原生逻辑点位"（见空间管理 PRD）；设备层不再承担空间级群控的默认承接职责。
- 归属空间显式化: 由于支持级联展示，列表页新增"归属空间"列，用于标明设备所属的物理空间，辅助管理员在混合列表中快速定位。
- 总点位/已启用列逻辑:
- 总点位: 该设备所属产品在自控平台的全部信号点位数量（
product.mappings[]总长度），不论 AI 是否启用 - 已启用: 该设备实际启用给 AI 使用的点位数量（
产品 enabled=true的点位 -disabled_signals）。此值 ≤ 产品的已启用点位数量
- 总点位: 该设备所属产品在自控平台的全部信号点位数量（
6.1.3 权限真相原则 (Physical Source of Truth)
- 语义仅定义意图: 标准语义 (
StandardSemantics) 仅代表 AI 的逻辑入口。 - 物理决定权限: 设备功能的 可看/可控 权限由 IoT 物理点位的
AccessMode(R/W/RW) 最终决定。该权限在产品级映射中已定义，设备级继承。
6.2 核心流程 A：引入 IoT 设备 (Import Modal v4.1)
点击 [+ 引入 IoT 设备]。弹窗不再自动按主页面 AI 空间树过滤，改为展示物联中台全量设备，配合左侧物联平台空间树进行筛选。
text
+----------------------------------------------------------------------------------------+
| 引入 IoT 设备 [ X ] |
+----------------------------------+-----------------------------------------------------+
| [物联平台空间] | 品类:[全部 v] 产品:[全部 v] 搜索:[..........] |
| | ☐ 显示已纳管 |
| ▼ 金螳螂 | 已选 2 项 |
| ▼ 1楼 | +---------------------------------------------------+ |
| 305会议室 | | [x] 设备名称 | 归属空间 | 品类 | 产品 |编码| |
| 401大会议室 | |-----------------|-----------|-------|--------|-----| |
| ▶ 4楼 | | [x] 305#新风机 | 305会议室 | 暖通 | 新风系统|... | |
| ▶ 北楼 | | [x] 305#投影幕布| 305会议室 | - | 升降幕布|... | |
| | | [ ] 105#落地灯 | 105接待室 | 照明 | 智能灯控|... | |
| | | [已纳管] 105#环境宝|105接待室| 环境 | 传感器 |... | |
| | +---------------------------------------------------+ |
+----------------------------------+-----------------------------------------------------+
| [取消] [确定引入] |
+----------------------------------------------------------------------------------------+6.2.1 引入逻辑细节 (Import Specifics v4.1)
全量展示（去除自动空间过滤）: 弹窗不再根据主页面选中空间自动过滤设备，而是展示物联中台全部 IoT 设备。左侧「物联平台空间树」独立于页面的 AI 纳管空间树，数据源为物联中台原始空间层级。
物联平台空间树: 左侧树展示物联中台的完整物理空间层级（建筑→楼层→房间），与主页面 AI 纳管空间树无关。点击节点时级联筛选该空间及其所有子空间下的设备。
去重默认隐藏，可切换显示: 已纳管的设备默认不展示（避免重复引入），但提供「显示已纳管」复选框供管理员查看。已纳管设备在列表中显示为灰态（opacity 0.5），标签标注为"已纳管"，复选框禁用。
过滤条件: 弹窗支持"产品品类"下拉 + "产品"下拉 + "设备名称/编码"文本搜索三组条件联合过滤，所有条件下钻基于左侧物联平台空间树的筛选结果。
引入依赖检查（v4.1 新增）: 用户点击「确定引入」时，系统自动检查以下依赖关系：
- 空间依赖: 设备的归属房间是否已在 AI 空间管理中纳管
- 产品依赖: 设备关联的产品是否已在 AI 产品管理中导入
- 两者均为阻断性条件，缺失时将弹出确认摘要弹窗，用户必须确认后才能继续引入。
引入确认摘要弹窗:
text+------------------------------------------------------------------+ | 引入确认 | +------------------------------------------------------------------+ | | | 将引入 3 台设备至 AI 系统 | | | | ⚠ 以下关联项尚未纳入 AI 系统，将一并自动引入： | | · 空间 1 个（含父路径自动创建） | | · 产品 2 个（含点位属性） | | | +------------------------------------------------------------------+ | [取消] [确认引入（含关联项）] | +------------------------------------------------------------------+- 摘要不逐条列举设备和关联项，仅展示数量摘要
- 空间和产品不可选择排除（阻断性约束，必须全量自动引入）
- 若无任何缺失依赖，则直接执行引入，跳过确认弹窗
关联项自动引入行为:
- 空间自动引入: 对所缺空间执行递归父路径创建，在
managedAssets中建立完整空间链（建筑→楼层→房间），初始状态为disabled - 产品自动引入: 从物联中台产品数据源拉取产品信息，自动生成点位属性模板（与产品管理页面
IoTProductImportModal._generateMockSignals同逻辑），点位默认enabled=false，语义映射为空。后续需在产品管理中手动配置
- 空间自动引入: 对所缺空间执行递归父路径创建，在
别名继承机制: 设备初次引入，系统默认把
[原始名称]设为初始可用别名，确保能够即引入即服务。产品关联与抽屉适配:
- 引入时如果产品已在产品管理中配置完成，设备自动关联
product_id - 产品未导入: 设备抽屉显示"暂无产品映射，请先导入产品"
- 产品已导入但语义未配置: 设备抽屉显示"产品已导入但未配置语义映射，请先前往产品管理配置点位映射"
- 引入时如果产品已在产品管理中配置完成，设备自动关联
6.3 核心流程 B：设备级点位启用/禁用配置
设备级不再维护完整 Capability Mapping，改为继承产品映射 + per-signal 开关。
6.3.1 界面原型：设备配置抽屉 (v4.0)
text
+---------------------------------------------------------------+
| 设备配置详情: 走廊筒灯_01 [ X ] |
+---------------------------------------------------------------+
| |
| == 基础信息 (只读) == |
| 所属产品: 某品牌筒灯 (prod_light) |
| 归属空间: 走廊 (SP_CORRIDOR) |
| IoT 编码: DEV_L_001 |
| |
| == AI 语义增强 == |
| 语义别名: [ 走廊灯 x ] |
| |
| == 点位映射（继承自产品: 某品牌筒灯）== |
| 总点位: 10 产品已启用: 3 本设备已启用: 1 [查看产品映射] |
| |
| +-------------------------------------------------------------+ |
| | [ON ] 照明开关 (LightSwitch) 语义映射: 灯具开关 | |
| | [布尔(Bool)] [读写(RW)] 0→关闭, 1→开启 | |
| | AI指引: 控制灯具开关 | |
| +-------------------------------------------------------------+ |
| |
| +-------------------------------------------------------------+ |
| | [OFF] 亮度调节 (Brightness) 语义映射: 亮度调节 | |
| | [数值(Num)] [读写(RW)] min=0,max=100,step=1 | |
| | AI指引: 数值越大越亮 本设备已禁用 | |
| +-------------------------------------------------------------+ |
| |
| ──── 以下点位产品未启用，本设备不可单独开启 ──── |
| |
| +-------------------------------------------------------------+ |
| | [ — ] 色温调节 (ColorTemp) 语义映射: 色温调节 | |
| | [数值(Num)] [读写(RW)] 产品未启用 | |
| +-------------------------------------------------------------+ |
| |
+---------------------------------------------------------------+
| [ 取消 ] [ 保存生效 ] |
+---------------------------------------------------------------+图标说明：
| 图标 | 含义 | 设备能否操作 |
|---|---|---|
[ON ] | switch 开启状态，产品已启用 + 本设备已启用 | 可点击关闭 |
[OFF] | switch 关闭状态，产品已启用 + 本设备已禁用 | 可点击开启 |
[ — ] | switch 置灰状态，产品未启用 | 不可操作，引导去产品管理 |
6.3.2 点位映射列表规则
| 状态 | switch 显示 | 含义 | 设备能否操作 |
|---|---|---|---|
| 已启用 | [ON ] 滑块在右 | 产品已启用 + 本设备已启用 | 可点击关闭 |
| 已禁用 | [OFF] 滑块在左 | 产品已启用 + 本设备已禁用 | 可点击开启 |
| 产品未启用 | [ — ] 置灰锁定 | 产品级 enabled=false | 不可操作，引导前往产品管理 |
规则说明：
- 列表展示该产品所有点位（
mappings[]全部），按产品enabled状态分组：产品已启用的在上、产品未启用的在下 - 每个点位展示：switch 图标 +
signal_label (signal_name)+ 关联标准语义 + 数据类型 + 读写角色 + 摘要 + AI指引 - 每个点位的 switch 状态 = 产品
enabled=true&&signal_name ∉ disabled_signals - 产品
enabled=false的点位 switch 置灰不可操作，引导文案"产品未启用，如需使用请先前往产品管理开启" - 产品已启用的点位以分隔线分组，顶部统计"产品已开启 X/Y 个点位，本设备已启用 Z 个"
6.3.3 设备级数据治理与异常闭环
- 防御性状态保持与异常消警：
- 与 v3.1 保持一致。异常状态下点位列表整体置为只读。
- 产品映射变更感知：
- 设备下次打开抽屉时自动同步产品最新映射：
- 产品新增点位 → 追加到列表，switch 默认跟随产品
enabled - 产品删除点位 →
disabled_signals自动清理残留引用 - 产品修改 label/range → 详情面板自动更新
- 产品新增点位 → 追加到列表，switch 默认跟随产品
- 设备下次打开抽屉时自动同步产品最新映射：
- 降级只读模式：
- 设备遭遇
[💀物联信息丢失]→ 整个抽屉（含别名、点位 switch）强制 ReadOnly
- 设备遭遇
6.3.4 设备级保存逻辑
json
{
"product_id": "prod_light",
"disabled_signals": ["brightness", "color_temp"]
}运行时：有效点位 = 产品 enabled=true 的点位 - disabled_signals
7. 核心技术策略 (Technical Strategy - Device Focus)
7.1 向量化策略 (One-to-Many Vectorization)
采用拆分存储策略，一条 SQL 实体记录对应多条 Vector DB 记录，以覆盖不同的自然语言表达。
- ETL 触发: 用户点击配置抽屉的
[保存生效]。 - 拆分逻辑: 遍历
aliases数组（含原名、物理全路径名、人工别名）。 - 前置属性 (Pre-Filter Fields)：
entity_type: 固定为DEVICE。cap_tags: 通过产品级映射的enabled=true点位 + 设备级disabled_signals计算得来。例如仅开启了light_power→["light_power"]。
- 存储示例:
vec("走廊筒灯_01")-> Payload:{ "ref_id": "DEV01", "entity_type": "DEVICE", "product_id": "prod_light", "cap_tags": ["light_power"] }vec("走廊/走廊筒灯_01")-> Payload:{ "ref_id": "DEV01", "entity_type": "DEVICE", "product_id": "prod_light", "cap_tags": ["light_power"] }
7.2 数据一致性与冲突检查
- 弹性校验: 设备别名不在强制全项目唯一。系统支持同空间内别名去重，但允许跨空间共享相同别称（如每个办公室都有"灯"），具体匹配逻辑下沉至 Agent 推理层结合上下文处理。
- 后端存储: 保存时仅执行格式校验与同空间重名检查。
7.3 Agent 槽位填充策略 (Slot Filling)
解决用户指令中设备缺失的问题。
- 显式提取: LLM 直接从话语中提取设备标识（如 "打开 305 的空调"）。
- 隐式推理 (Implicit Inference):
- 若 Device 槽位缺失，Agent 锁定空间后，查找该空间下具备对应 Intent 能力（如
hvac_power）的设备。 - 设备的能力列表由
产品级 enabled 点位 - disabled_signals运行时计算得出。
- 若 Device 槽位缺失，Agent 锁定空间后，查找该空间下具备对应 Intent 能力（如
8. 数据模型 (Data Model - Device Focus)
8.1 实体基础表 (ai_entities - Device)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | UUID | Yes | AI 系统内部唯一主键 |
iot_ref_id | String | Yes | IoT 平台原始设备 ID |
parent_id | UUID | Yes | 归属空间 ID (指向 Space 的 AI ID) |
type | Enum | Yes | 固定为 DEVICE |
product_id | String | No | 关联产品 ID，运行时从产品管理查询映射配置 |
ai_status | Enum | Yes | ACTIVE (生效中), DISABLED (已停用) |
sync_error | Enum | No | CHANGED (名称/路径变更), ORPHAN (物理丢失), DRIFT (属性漂移) |
aliases | JSON | Yes | 字符串数组 ["空调", "AC"] |
disabled_signals | JSON | No | 本设备禁用的信号名称数组 ["brightness", "color_temp"] |
8.2 设备数据模型 (v4.0)
json
{
"id": "dev_light_01",
"iot_ref_id": "DEV_L_001",
"parent_id": "SP_CORRIDOR",
"type": "DEVICE",
"product_id": "prod_light",
"ai_status": "ACTIVE",
"sync_error": null,
"aliases": ["走廊灯"],
"disabled_signals": ["brightness", "color_temp"]
}运行时有效点位计算规则：
有效点位 = 产品 enabled=true 的点位 - disabled_signals| 场景 | switch 状态 | 结果 |
|---|---|---|
产品 enabled=true + 信号 ∉ disabled_signals | [ON ] | 点位在该设备生效 |
产品 enabled=true + 信号 ∈ disabled_signals | [OFF] | 点位在该设备禁用，可重新开启 |
产品 enabled=false | [ — ] 置灰 | 点位在该设备不可用，引导去产品管理开启 |