2026 AI 空间智能体 - 设备语义管理 PRD (v2.8)
版本: v2.8 日期: 2026-03-27 状态: 逻辑重构与治理增强完成 目标: 构建统一的“设备语义管理”子中心，连接 IoT 物联平台与 AI Agent，实现物理设备资源到 AI 自然语言意图的灵活映射。通过将物理点位映射为 AI 动作意图，实现“脑手合一”。
1. 核心设计理念
1.1 物理与语义解耦
系统在 AI 层通过“语义增强”建立映射。设备的功能属性（Property）被转化为 AI 可识别的角色（Control, Perception）。
1.2 核心设计准则
- 强空间依赖 (No Space, No Device): 任何设备接入前，其所属的空间路径必须已通过 AI 纳管（见 空间语义管理）。
- 权限真相原则 (Physical Source of Truth): 设备功能的 可看/可控 权限由 IoT 物理点位的
AccessMode(R/W/RW) 最终决定。
1.3 核心术语表 (Terminology)
NOTE
设备资产 (IoT Devices): 管理具体执行终端，为 AI 提供控场能力映射。 语义别名 (Alias): AI 识别设备的自然语言凭证，如“主灯”、“空调”。 功能映射 (Capability Mapping): 将物理点位 (Property) 映射为标准语义 (Semantic Key) 的过程。
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)
- 分支：采纳项: 支持一键同步名称变更、空间路径迁移。
- 分支：配置项: 对于属性漂移，不可自动采纳。管理员必须重新进入
Capability Mapping重新映射。
4. 全资源纳管与配置全流程 (Business Process - Device)
6. 设备资源管理 (Device Management UI)
核心原则: “无空间，不设备”。AI 系统仅纳管已明确归属到 AI 空间下的设备。
6.1 界面总览：强空间依赖
设备管理完全复用“空间管理”的三栏布局。左侧树为“已纳管的 AI 空间树”。
text
+----------------+--------------------------+-------------------------------------------------------------+
| [APP NAV] | [ 已纳管 AI 空间树 ] | 首页 / 设备资源管理 / 金螳螂 / 1楼 / 305会议室 |
| | +-------------------------------------------------------------+
| [🏢] 空间管理 | v 21默认项目 | [ 工作区: 305会议室 (已纳管设备) ] |
| | v 金螳螂 | |
| [💡] 设备管理 | v 1楼 | 搜索: [ 设备名称... ] [ + 引入 IoT 设备 ] |
| (Active) | 305会议室 <Active| |
| | > 4楼 | [ 已选 1 项 ] [ 批量生效 ] [ 批量失效 ] (有勾选项时列出) |
| | | +-----------------------------------------------------------------+ |
| | | | [v] | 原始名称 | 归属空间 | 别名(语义) | 状态 |异常| 操作 | |
| | | |-----|----------|----------|------------|------|----|------| |
| | | | [x] | 305主灯 | 305会议室| [主灯][灯] |🟢生效| - | 配置 | |
| | | +-----------------------------------------------------------------+ |
| | | |
+----------------+--------------------------+-------------------------------------------------------------+注意：空间树，取自 `空间资源管理` 已维护的AI空间树6.1.2 关键交互说明
- 强行级联过滤: 列表中的设备，必须严格依据左侧空间树的选中节点进行过滤（选中父节点，将展示其下属所有层级的全部设备）。
- 双轴状态模型 (与空间资源一致): 【轴1：AI 状态】
[🟢 生效中]: 正常被意图引擎调用。[⚪ 已停用]: 用户手动停用或因底层异常被系统临时熔断锁定。 【轴2：同步异常】[-]: 正常。[⚠️ 变更/漂移]: 物理层名称、空间路径修改，或物模型属性发生漂移。[💀 物联信息丢失]: 物理删除，强关联置为停用。
- 安全批量操作 (Batch Safety): 和空间管理一样，勾选执行批量生效时，自动过滤具有异常的设备。
- 生效前置校验: 点击
[生效]时，若该设备的 AI 别名（含原名、别称列表）为空，系统拦截并报错，确保纳管资源具备语义入口。 - 意图默认承接者: 对于一个空间内的同类设备（如 3个灯），允许将其中某一个设为
isDefault。当用户未指明具体设备名（例如只说“开灯”）时，优先下发给此设备。 - 归属空间显式化: 由于支持级联展示，列表页新增“归属空间”列，用于标明设备所属的物理空间，辅助管理员在混合列表中快速定位。
6.1.3 权限真相原则 (Physical Source of Truth)
- 语义仅定义意图: 标准语义 (
StandardSemantics) 仅代表 AI 的逻辑入口。 - 物理决定权限: 设备功能的 可看/可控 权限由 IoT 物理点位的
AccessMode(R/W/RW) 最终决定。系统在 UI 上需根据物理层权限动态调整映射表单的可编辑性。
6.2 核心流程 A：引入 IoT 设备 (Import Modal)
点击 [+ 引入 IoT 设备]。系统根据主页面左侧选中的空间 ID（如 SP_01）自动过滤 IoT 侧的设备。
text
+-----------------------------------------------------------------------------------+
| 引入 305会议室 下的 IoT 物理设备 [ X ] |
+-----------------------------------------------------------------------------------+
| (自动执行: GET /iot/devices?location=SP_01) |
| |
| [ 待引入设备列表 ] |
| +-----------------------------------------------------------------------------+ |
| | [ ] 设备名称 | 编码 | IoT 产品类型 | |
| |-----------------------------|---------------------|-------------------------| |
| | [x] CH-01#冷却侧阀门 | DEV_V_001 | 开关阀 | |
| | [x] CH-01#空调内机 | DEV_AC_001 | 变频空调 | |
| +-----------------------------------------------------------------------------+ |
| |
| [ 取消 ] [ 确定引入 (2) ] |
+-----------------------------------------------------------------------------------+6.2.1 引入逻辑细节 (Import Specifics)
- 精确空间锚定: 确保设备引入时自动根据 物联平台设备-空间原始绑定关系 进行绑定。
- 别名继承机制: 设备初次引入，系统默认把
[原始名称]设为初始可用别名，确保能够即引入即服务。 - 去重不展示: 已经被纳管过的设备，在引入弹窗中不可再见，避免重复纳管。
6.3 核心流程 B：设备能力一体化映射 (Unified Capability Mapping)
在配置设备时，管理后台采用以语义为中心 (Semantic-First) 的卡片式配置流程。每一个“标准语义”对应一个独立的配置卡片。
IMPORTANT
一个语义 = 一个卡片：虽然我们实现了读写映射的闭环，但“语义”本身是不合并的。例如：设定温度 (目标值) 与 室内温度 (实时观测值) 依然是两张独立的配置卡片，因为它们代表了 AI 的两个不同意图入口。
6.3.1 界面原型：全量配置抽屉
text
+---------------------------------------------------------------+
| 设备配置详情: CH-01#变频空调机组 [ X ] |
+---------------------------------------------------------------+
| |
| == 基础信息 (只读) == |
| 所属产品: 变频空调 (ProductKey: ac_001) |
| 归属空间: 305会议室 (SP_01) |
| IoT 编码: DEV_AC_123456 |
| |
| == AI 语义增强 == |
| 语义别名: [ 空调 x ] [ 中央空调 x ] [ 305的空调 x ] |
| |
| 默认标记: [ ] 设为该空间的“意图默认设备” |
| |
| == 功能映射 (Capability Mapping) == |
| [➕ 添加功能映射] |
| |
| [ 功能卡片 1 ] -------------------------------------------+ |
| | 1. 标准语义: [ (Search) 电源总开关 (hvac_power) v ] |
| | (参照 docs\02_设计\01_管理后台\标准化语义映射集.md) | |
| | ==> 类型: Boolean布尔 [控制][感知] | |
| | 2. 控制点位: [ p_switch (W) v ] | |
| | (下拉列表仅显示 Boolean类型且含W可写点位) | |
| | 3. 反馈配置: [ p_switch (R) v ] [🔗 复用控制点] | |
| | (下拉列表仅显示 Boolean类型且含R可读点位) | |
| | 4. AI意图（Boolean映射）: | |
| | false (0) -> [ 关闭 ] | |
| | true (1) -> [ 开启 ] | |
| +---------------------------------------------------------+ |
| |
| [ 功能卡片 2 ] -------------------------------------------+ |
| | 1. 标准语义: [ (Search) 设定目标温度 (hvac_target_temp) v ] | |
| | ==> 类型: Float浮点 [控制] | |
| | 2. 控制点位: [ SupplyAirTemperatureSet (W) v ] | |
| | (下拉列表仅显示 数值/Float类型且含W可写点位) | |
| | 3. AI 意图 (数值调节): | |
| | Step (步长): [ 1.0 ] | |
| | Range (范围): [ 16 ] 至 [ 30 ] | |
| +---------------------------------------------------------+ |
| |
| [ 功能卡片 3 ] -------------------------------------------+ |
| | 1. 标准语义: [ (Search) 室内实时温度 (hvac_indoor_temp) v ] | |
| | ==> 类型: Float浮点 [感知] | |
| | 2. 反馈配置: [eturnAirTemperature (回风温度) ] | |
| | (下拉列表仅显示 Boolean类型且含R可读类型点位) | |
| | | |
| | 3. 显示配置: 实时数值透传显示 | |
| +---------------------------------------------------------+ |
| |
| [ 取消 ] [ 保存生效 ] |
+---------------------------------------------------------------+6.3.2 设备数据 技术治理与异常闭环
- 防御性状态保持与异常消警：
- 当物理层产生
[⚠️变更]异常（如名称或路径更换），抽屉区域顶部会呈现 Diff 对比。 - 状态防诈尸：若原本设备状态为“已停用”，用户点击
[采纳 IoT 更新]后，系统必须保持停用状态不变，严禁擅自开启 AI 服务。 - 空间跃迁自动跟随：若设备物理位置变更，采纳更新后系统底层的左侧空间树需自动导航并高亮目标新空间，免除人工翻找。
- 当物理层产生
- 物模型属性漂移应对：
- 若底层的物模型结构发生了更改（例如原本映射的
power_switch字段在 IoT 平台被废弃），已配置的“映射卡片”将标红显示“点位已失效”。 - 管理员必须重新选择合法的物理属性进行映射，否则该设备将维持停用状态且无法被 AI 控制。
- 若底层的物模型结构发生了更改（例如原本映射的
- 降级只读模式：
- 当设备遭遇
[💀物联信息丢失]（物理移除）异常时，抽屉内的别名、功能映射表单强制进入 ReadOnly 锁定状态（输入框置灰，按钮禁用）。 - 管理员仅保留信息查看权和底部的
[彻底移除]操作，防止在无效实体上进行配置。
- 当设备遭遇
TIP
技术参考：具体的标准语义分类、属性定义及数据类型，请参阅独立的 📜 标准化语义映射集 文档。
6.3.3 功能映射 交互与逻辑准则 (v3.1)
为了进一步降低配置歧义并匹配物理实体的真实角色，系统遵循 “严格角色分流” 原则：
- 选择标准语义：管理员选择标准语义后，系统即时显示其 数据类型 与 理论角色标签（如
Boolean [控制] [反馈]）。 - 分支 A：控制流 (Role includes Control)：
- 触发: 语义定义包含
control或both。 - 物联对账: 仅可选择具备 写入权限 (W / RW) 且数据类型兼容的物理属性。
- 严格排除: 若语义角色仅为
perception(如反馈指令)，此区域不应显示，避免无效配置。
- 触发: 语义定义包含
- 分支 B：反馈流 (Role includes Perception)：
- 触发: 语义定义包含
perception或both。 - 物联对账: 仅可选择具备 读取权限 (R / RW) 且数据类型兼容的物理属性。
- 严格排除: 若语义角色仅为
control(如动作指令)，此区域不应显示，避免无效配置。
- 触发: 语义定义包含
- 智能关联建议 (Smart Linkage)：
- 条件: 仅当语义角色为
both且已选定的“控制点位”为物理RW(读写合一) 时触发。 - 交互: 在反馈点位区展示“复用控制点位”快捷键，实现一键同传。
- 条件: 仅当语义角色为
- 初始化映射规则：
- 控制优先: 只要包含控制逻辑，基于控制点位定义（Enum/Bool）生成“状态→意图”映射表。
- 感知透传: 仅在纯感知语义下且选定反馈点位后，执行数据实时透传，跳过规则映射。
6.3.4 配置流交互图 (Mermaid v3.1)
7. 核心技术策略 (Technical Strategy - Device Focus)
7.1 向量化策略 (One-to-Many Vectorization)
采用拆分存储策略，一条 SQL 实体记录对应多条 Vector DB 记录，以覆盖不同的自然语言表达。
- ETL 触发: 用户点击配置抽屉的
[保存生效]。 - 拆分逻辑: 遍历
aliases数组（含原名、物理全路径名、人工别名）。 - 前置属性 (Pre-Filter Fields)：
entity_type: 固定为DEVICE。cap_tags: 该设备拥有的能力标签数组（如["control"]）。
- 存储示例:
vec("305空调")-> Payload:{ "ref_id": "DEV01", "entity_type": "DEVICE", "cap_tags": ["control"] }vec("金螳螂/1楼/305会议室/305空调")-> Payload:{ "ref_id": "DEV01", "entity_type": "DEVICE", "cap_tags": ["control"] }
7.2 数据一致性与冲突检查
- 弹性校验: 设备别名不在强制全项目唯一。系统支持同空间内别名去重，但允许跨空间共享相同别称（如每个办公室都有“灯”），具体匹配逻辑下沉至 Agent 推理层结合上下文处理。
- 后端存储: 保存时仅执行格式校验与同空间重名检查。
7.3 Agent 槽位填充策略 (Slot Filling)
解决用户指令中设备缺失的问题。
- 显式提取: LLM 直接从话语中提取设备标识（如 "打开 305 的空调"）。
- 隐式推理 (Implicit Inference):
- 若 Device 槽位缺失，Agent 锁定空间后，查找该空间下具备对应 Intent 能力（如
hvac_power）的设备。 - 优先级策略: 优先匹配标记为
is_default=true的设备（如某一空间的主灯或总控网关）。
- 若 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 |
ai_status | Enum | Yes | ACTIVE (生效中), DISABLED (已停用) |
sync_error | Enum | No | CHANGED (名称/路径变更), ORPHAN (物理丢失), DRIFT (属性漂移) |
aliases | JSON | Yes | 字符串数组 ["空调", "AC"] |
is_default | Boolean | Yes | 默认 false。是否为该空间内同类意图的默认承接者 |
capabilities | JSON | No | 功能映射配置容器 (详见下文) |
8.2 设备插件能力配置 (capabilities JSON)
Control Plugin (Key: control)
json
{
"mappings": [
{
"semantic_key": "hvac_power", // 标准语义标识
"action": { // 控制流配置
"property": "switch", // 物理点位标识符
"type": "bool", // 物理点位类型
"access_mode": "RW", // 物理权限回填
"mapping": { "on": 1, "off": 0 } // AI 意图到物理值的映射
},
"feedback": { // 反馈流配置
"property": "switch",
"sync_with_action": true // 是否复用控制点位
}
},
{
"semantic_key": "hvac_target_temp",
"action": {
"property": "temp_set",
"type": "float",
"range": [16, 30], // 业务缩限范围
"step": 1.0 // 调节步长
},
"feedback": {
"property": "temp_set",
"sync_with_action": true
}
}
]
}