2026 AI 空间智能体 - 设备语义管理 PRD (v3.1)

版本: v3.1 日期: 2026-04-15 目标: 构建统一的"设备语义管理"子中心，连接 IoT 物联平台与 AI Agent，实现物理设备资源到 AI 自然语言意图的灵活映射。通过将物理点位映射为 AI 动作意图，实现"脑手合一"。

1. 核心设计理念

1.1 物理与语义解耦

系统在 AI 层通过"语义增强"建立映射。设备的功能属性（Property）被转化为 AI 可识别的角色（RW-读写, RO-只读）。由于系统对接的是经过抽象的自控平台，AI 层面不再需要处理底层的点动（Write-Only）或状态分离逻辑。

1.2 核心设计准则

强空间依赖 (No Space, No Device): 任何设备接入前，其所属的空间路径必须已通过 AI 纳管（见空间语义管理）。
权限真相原则 (Physical Source of Truth): 设备功能的 可看/可控 权限由 IoT 物理点位的 AccessMode (R/W/RW) 最终决定。
交互安全根源 (Safety Origin): 对于数值调节类功能（如温控），设备层报送的"物理量程"是 AI 空间侧计算交互边界的 唯一凭证。严禁在空间层级硬编码量程。

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 别名（含原名、别称列表）为空，系统拦截并报错，确保纳管资源具备语义入口。
意图承接逻辑 (Intent Resolution): 针对空间级意图（如"调高 305 的温度"），系统优先匹配空间的"原生逻辑点位"（见空间管理 PRD）；设备层不再承担空间级群控的默认承接职责。
归属空间显式化: 由于支持级联展示，列表页新增"归属空间"列，用于标明设备所属的物理空间，辅助管理员在混合列表中快速定位。

6.1.3 权限真相原则 (Physical Source of Truth)

语义仅定义意图: 标准语义 (StandardSemantics) 仅代表 AI 的逻辑入口。
物理决定权限: 设备功能的 可看/可控 权限由 IoT 物理点位的 AccessMode (R/W/RW) 最终决定。系统在 UI 上需根据物理层权限动态调整映射表单的可编辑性。

点击 [+ 引入 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

+---------------------------------------------------------------+
|  设备配置详情: 305空调(中间)                           [ X ]  |
+---------------------------------------------------------------+
|                                                               |
|  == 基础信息 (只读) ==                                         |
|  所属产品:  变频空调 (ProductKey: ac_001)                     |
|  归属空间:  305会议室 (SP_01)                                  |
|  IoT 编码:  DEV_AC_005                                       |
|                                                               |
|  == AI 语义增强 ==                                            |
|  语义别名:  [ 空调 x ] [ 中间空调 x ] [ 中间那台 x ]          |
|                                                               |
|  == 点位映射 (Capability Mapping) ==                          |
|  [➕ 添加点位映射]                                             |
|                                                               |
|  [ 点位映射卡片 1 ] -------------------------------------------+  |
|  | 标准语义: [ (Search) 空调开关 (hvac_power)  v ]      |
|  |             类型: Boolean布尔 [控制][感知]          |
|  |             (💡 已匹配标准标识符: logic_switch)        |
|  | 逻辑信号: [ logic_switch (RW) v ]                       |  |
|  |    (下拉列表显示自控平台具备读写能力的逻辑信号)               |  |
|  | ═══ 状态映射 (展开) ══════════════════════════════════  |  |
|  |  * false (0) -> [ 关闭 ]            ← 必填             |  |
|  |  * true  (1) -> [ 开启 ]            ← 必填             |  |
|  |   AI 指引:    [ 开关状态含义说明... ]  (可选)           |  |
|  +---------------------------------------------------------+  |
|                                                               |
|  [ 点位映射卡片 2 ] -------------------------------------------+  |
|  | 标准语义: [ (Search) 运行模式 (hvac_mode)  v ]          |
|  |             类型: Enum枚举  [控制][感知]              |
|  | 逻辑信号: [ mode_reg (RW) v ]                           |  |
|  | ═══ 状态映射 (展开) ══════════════════════════════════  |  |
|  |  * 0     -> [ 制冷 ]              ← 必填                |  |
|  |  * 1     -> [ 制热 ]              ← 必填                |  |
|  |  * 2     -> [ 送风 ]              ← 必填                |  |
|  |   AI 指引:    [ 模式切换建议... ]    (可选)             |  |
|  +---------------------------------------------------------+  |
|                                                               |
|  [ 点位映射卡片 3 ] -------------------------------------------+  |
|  | 标准语义: [ (Search) 设定目标温度 (hvac_target_temp) v ]  |
|  |             类型: Number数值  [控制][感知]              |
|  | 逻辑信号: [ SupplyAirTemperatureSet (RW) v ]            |  |
|  | ═══ 数值调节 (展开) ════════════════════════════════════  |  |
|  |  * Step (步长): [ 1.0 ]            ← 必填               |  |
|  |  * Range (范围): [ 16 ] 至 [ 30 ]  ← 必填               |  |
|  |    ⓘ 物理约束: range [16, 30] | step ≥ 1.0              |  |
|  |   AI 指引:    [ 温度调节建议... ]     (可选)             |  |
|  +---------------------------------------------------------+  |
|                                                               |
|  [ 点位映射卡片 4 ] -------------------------------------------+  |
|  | 标准语义: [ (Search) 室内实时温度 (env_indoor_temp) v ] |
|  |             类型: Number数值 [感知]                  |
|  | 逻辑信号: [ ReturnAirTemperature (回风温度) v ]         |  |
|  | 显示配置: 实时数值透传显示                           |  |
|  +---------------------------------------------------------+  |
|                                                               |
|  [ 自动映射逻辑 (多品类) ]                                    |
|  - 当管理员选定标准语义时，系统读取该语义的 `default_props`（多品类映射表）。   |
|  - 根据当前设备的 `product`（产品品类）查找对应的默认逻辑点位标识符。|
|  - 若找到该品类的默认值，自动填充"逻辑信号"。                  |
|  - 若未找到（如当前品类未在 `default_props` 中配置），则不自动填充，留给管理员手动选择。|
|  - 极大减少海量同品类设备的重复配置工作量。                        |
|                                                               |
|                                      [ 取消 ]   [ 保存生效 ]  |
+---------------------------------------------------------------+

6.3.2 设备数据技术治理与异常闭环

防御性状态保持与异常消警：
- 当物理层产生 [⚠️变更] 异常（如名称或路径更换），抽屉区域顶部会呈现 Diff 对比。
- 状态防诈尸：若原本设备状态为"已停用"，用户点击 [采纳 IoT 更新] 后，系统必须保持停用状态不变，严禁擅自开启 AI 服务。
- 空间跃迁自动跟随：若设备物理位置变更，采纳更新后系统底层的左侧空间树需自动导航并高亮目标新空间，免除人工翻找。
物模型属性漂移应对：
- 若底层的物模型结构发生了更改（例如原本映射的 power_switch 字段在 IoT 平台被废弃），已配置的"映射卡片"将标红显示"点位已失效"。
- 管理员必须重新选择合法的物理属性进行映射，否则该设备将维持停用状态且无法被 AI 控制。
降级只读模式：
- 当设备遭遇 [💀物联信息丢失]（物理移除）异常时，抽屉内的别名、功能映射表单强制进入 ReadOnly 锁定状态（输入框置灰，按钮禁用）。
- 管理员仅保留信息查看权和底部的 [彻底移除] 操作，防止在无效实体上进行配置。

TIP

技术参考：具体的标准语义分类、属性定义及数据类型，请参阅独立的 📜 标准化语义映射集文档。

6.3.3 功能映射交互与逻辑准则 (v3.2)

为了进一步降低配置歧义并匹配物理实体的真实角色，系统遵循 "严格角色分流" 原则：

角色透传：系统即时显示标准语义的 数据类型 与 交互角色（如 Boolean [控制][感知]）。
绑定逻辑信号：
- [控制][感知] (RW): 必须且仅可选择具备 RW 权限 且类型兼容的逻辑信号。
- [感知] (RO): 必须且仅可选择具备 RO 权限 且类型兼容的逻辑信号。
编辑权限对账 (Editable Logic v3.2)：
- 数值型 (Float/Int): 步长 Step 与量程 Range 均为必填项。默认值从自控平台物模型带入（平台可缺省）。管理员可在此基础上调整，但受物理约束限制：
  - Range 仅允许在物理极限范围内缩窄（即 min ≥ physicalMin, max ≤ physicalMax）。当平台未提供物理量程时，无条件开放编辑。
  - Step 仅允许放大（即 step ≥ physicalStep），以确保 UI 滑块的操控精度不低于物理分辨率。当平台未提供物理步长时，无条件开放编辑。
  - 背景：移动端基于滑动组件（Slider）交互，Range 是滑动边界的唯一来源。即使自控平台缺省量程，管理员也必须手动配置以确保 UI 可用。
- 布尔/枚举型 (Bool/Enum): 系统自动提取物理值，管理员必须为每个值定义对应的 "AI 意图描述"（如：0=关, 1=开），提交时校验不可为空。
初始化映射逻辑：
- ControlMap: 针对 Bool/Enum 建立的"值 -> 意图"翻译表。
- DirectPass: 针对数值型执行的原始数据实时透传。

6.3.4 点位匹配与对账规则 (Technical Mapping Specs)

为了确保 AI 语义与物理实体的准确对账，系统在配置弹窗中执行以下自动化过滤规则：

1. 类型对账表 (Type Compatibility)

标准语义类型 (Standard)	兼容的物模型类型 (ThingModel)	说明
Boolean (布尔)	`bool`	二值映射 (0/1)
Enum (枚举)	`enum`	多值映射表
Number (数值)	`float`, `double`, `int`	数值透传，由 Step 定义展现精度 (1.0 为整数，0.1 为浮点)

2. 读写对账矩阵 (Access Mode Matrix)

标准语义角色	可绑定的物模型点位	理由
RW (控制+感知)	`RW`	必须具备双向指令下发与状态上报能力。
RO (感知)	`RO`	感知仅需具备只读能力，点对点匹配。

3. 唯一性约束

语义唯一性：同一设备 ID 下，禁止配置重复的标准语义 Key。系统将在配置时进行动态拦截并标红冲突项。
信号唯一性：建议（但不强制）同一设备信号不重复绑定到不同语义，以防止 AI 指引产生逻辑竞态。

6.3.5 配置流交互图 (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）的设备。

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"]`
`capabilities`	JSON	No	功能映射配置容器，内含 `mappings[]` 数组，每项包含 `action`（控制流）、`feedback`（反馈流）

8.2 设备插件能力配置 (`capabilities` JSON)

Capability Mapping (Key: capabilities)

json

{
  "mappings": [
    {
      "semantic_key": "hvac_power",   // 标准语义标识
      "signal": {                     // 逻辑信号配置
        "property": "switch",         // 自控平台逻辑点位标识符
        "type": "bool",               // 点位类型
        "access_mode": "RW",          // 权限
        "mapping": { "on": 1, "off": 0 } // AI 意图到物理值的映射
      }
    },
    {
      "semantic_key": "hvac_target_temp",
      "signal": {
        "property": "temp_set",
        "type": "float",
        "access_mode": "RW",
        "range": [16, 30],            // 数值调节的安全边界
        "step": 1.0                   // 调节步长
      }
    },
    {
      "semantic_key": "env_indoor_temp",
      "signal": {
        "property": "room_temp",
        "type": "float",
        "access_mode": "R"
      }
    }
  ]
}

2026 AI 空间智能体 - 设备语义管理 PRD (v3.1) ​

1. 核心设计理念 ​

1.1 物理与语义解耦 ​

1.2 核心设计准则 ​

1.3 核心术语表 (Terminology) ​

2. 管理模块概述 (Device Hub) ​

2.1 设备管理模块 (Device Hub) ​

2.2 核心特性 ​

3. 一致性管控逻辑 (Consistency Governance - Device Focus) ​

3.1 异常感知与熔断 ​

3.2 采纳与闭环 (Stepped Adoption) ​

4. 全资源纳管与配置全流程 (Business Process - Device) ​

6. 设备资源管理 (Device Management UI) ​

6.1 界面总览：强空间依赖 ​

6.1.2 关键交互说明 ​

6.1.3 权限真相原则 (Physical Source of Truth) ​

6.2 核心流程 A：引入 IoT 设备 (Import Modal) ​

6.2.1 引入逻辑细节 (Import Specifics) ​

6.3 核心流程 B：设备能力一体化映射 (Unified Capability Mapping) ​

6.3.1 界面原型：全量配置抽屉 ​

6.3.2 设备数据 技术治理与异常闭环 ​

6.3.3 功能映射 交互与逻辑准则 (v3.2) ​

6.3.4 点位匹配与对账规则 (Technical Mapping Specs) ​

1. 类型对账表 (Type Compatibility) ​

2. 读写对账矩阵 (Access Mode Matrix) ​

3. 唯一性约束 ​

6.3.5 配置流交互图 (Mermaid v3.1) ​

7. 核心技术策略 (Technical Strategy - Device Focus) ​

7.1 向量化策略 (One-to-Many Vectorization) ​

7.2 数据一致性与冲突检查 ​

7.3 Agent 槽位填充策略 (Slot Filling) ​

8. 数据模型 (Data Model - Device Focus) ​

8.1 实体基础表 (ai_entities - Device) ​

8.2 设备插件能力配置 (capabilities JSON) ​

2026 AI 空间智能体 - 设备语义管理 PRD (v3.1)

1. 核心设计理念

1.1 物理与语义解耦

1.2 核心设计准则

1.3 核心术语表 (Terminology)

2. 管理模块概述 (Device Hub)

2.1 设备管理模块 (Device Hub)

2.2 核心特性

3. 一致性管控逻辑 (Consistency Governance - Device Focus)

3.1 异常感知与熔断

3.2 采纳与闭环 (Stepped Adoption)

4. 全资源纳管与配置全流程 (Business Process - Device)

6. 设备资源管理 (Device Management UI)

6.1 界面总览：强空间依赖

6.1.2 关键交互说明

6.1.3 权限真相原则 (Physical Source of Truth)

6.2 核心流程 A：引入 IoT 设备 (Import Modal)

6.2.1 引入逻辑细节 (Import Specifics)

6.3 核心流程 B：设备能力一体化映射 (Unified Capability Mapping)

6.3.1 界面原型：全量配置抽屉

6.3.2 设备数据技术治理与异常闭环

6.3.3 功能映射交互与逻辑准则 (v3.2)

6.3.4 点位匹配与对账规则 (Technical Mapping Specs)

1. 类型对账表 (Type Compatibility)

2. 读写对账矩阵 (Access Mode Matrix)

3. 唯一性约束

6.3.5 配置流交互图 (Mermaid v3.1)

7. 核心技术策略 (Technical Strategy - Device Focus)

7.1 向量化策略 (One-to-Many Vectorization)

7.2 数据一致性与冲突检查

7.3 Agent 槽位填充策略 (Slot Filling)

8. 数据模型 (Data Model - Device Focus)

8.1 实体基础表 (`ai_entities` - Device)

8.2 设备插件能力配置 (`capabilities` JSON)