2026 AI 空间智能体 - 统一权限体系设计 PRD (v2.3)
版本: v2.3 日期: 2026-05-15 状态: 简化校验链，数据权限方案确定为"全量检索 + 代码层过滤"
1. 统一中台扩展现状分析
1.1 现有中台权限结构
permission_profile
├── web端 ← 菜单 → 页面 → 按钮（标准 RBAC）
│ ├── 项目管理
│ └── 应用
├── 移动端 ← 小程序页面
│ └── 小程序
└── 数据权限 ← 设备维度的数据范围
├── 设备单控
│ ├── 按设备类型
│ └── 按建筑空间
└── 设备群控1.2 本次接入策略
| 端 | 接入方式 | 控制粒度 |
|---|---|---|
| Web 管理后台 | 页面接入现有中台 web端 | 页面级即可，无需按钮级 |
| 小程序 Chatbot | 作为页面接入现有中台 移动端.小程序 | 一个 Chatbot 入口页面 |
| 智能体意图 | 新增横向模块 智能体 | 按意图分支 checkbox 控制 |
1.3 核心设计原则
- 不重复造轮子：数据权限复用现有"设备单控-按建筑空间"，智能体模块只管功能准入
- 分组仅用于展示：SA/FA 是中台管理界面的语义分组，不是真实 Dify Agent
- 权限在叶节点：真正的权限控制点是每个子智能体 checkbox，存储
master_agent_id+branch_id。branch_id为 null 表示独立 Agent - 最小权限原则：新用户默认零智能体权限，管理员按需勾选
2. 新增：智能体模块 (Agent Permission)
2.1 设计背景与架构关系
"空间智能体"是大项目概念，内部包含两大职责域：
| 职责域 | 说明 | 子智能体 |
|---|---|---|
| SA 空间运营官 | 控场、预约、整备 | 会议预定、设备控制、智能整备 |
| FA 设施协同官 | 报修、诊断 | 工单自动建单、一键诊断 |
子智能体分为两种形态，在中台用统一的 Schema 表达：
| 形态 | 说明 | 举例 |
|---|---|---|
| 分支意图 | 寄生于总 Agent（Master）内部，由意图识别节点路由 | 会议预定、设备控制、智能整备、工单自动建单 |
| 独立 Agent | 拥有自己的 Dify App ID，不经过总 Agent，由业务系统按钮直接调用 | 一键诊断 |
项目对外只有一个 Chatbot 入口（总 Agent），负责接收用户消息、意图识别并分发到对应的分支意图子Agent。一键诊断不走 Chatbot，嵌入工单系统页面按需触发。
2.2 中台扩展方案：智能体作为第四横向模块
permission_profile
├── web端 ← 现有（不变）
├── 移动端 ← 现有（不变）
├── 数据权限 ← 现有（不变）
└── 智能体 ← 新增模块
└── [分组] 空间运营官 (SA) ← 展示分组，不是真实 Agent
├── ☑ 会议预定 ← 子智能体 ← 真实权限点
├── ☑ 设备控制 ← 子智能体 ← 真实权限点
└── ☑ 智能整备 ← 子智能体 ← 真实权限点
└── [分组] 设施协同官 (FA) ← 展示分组
├── ☑ 工单自动建单 ← 子智能体
└── ☑ 一键诊断 ← 子智能体（独立 Agent）2.3 两种 Agent 形态的统一表达
叶节点通过 branch_id 是否为 null 天然区分两种形态：
| 形态 | master_agent_id | branch_id | 说明 |
|---|---|---|---|
| 分支意图（如设备控制） | 总 Agent 的 App ID | "branch_control" | 总 Agent 用这两个 ID 拼成权限查询 Key，调用中台校验当前用户是否有权执行该意图 |
| 独立 Agent（如一键诊断） | 独立 Agent 的 App ID | null | 业务系统直接调用该 Agent 前，同样用 master_agent_id 查询中台权限 |
2.4 叶节点（子智能体）数据 Schema
每个 checkbox 不只是"勾选/取消"，而是携带与 Dify 的真实绑定信息：
json
// 示例 1：分支意图
{
"name": "设备控制",
"master_agent_id": "app-master",
"branch_id": "branch_control",
"data_scope": { "inherit_from": "数据权限.设备单控.按建筑空间" }
}
// 示例 2：独立 Agent
{
"name": "一键诊断",
"master_agent_id": "app-diagnosis-agent",
"branch_id": null,
"data_scope": null
}| 字段 | 类型 | 说明 |
|---|---|---|
name | String | 中台管理界面展示的中文名 |
master_agent_id | String | Dify 中的 App ID（总 Agent 或独立 Agent） |
branch_id | String | null | 总 Agent 内部的意图分支 ID；null 表示独立 Agent |
data_scope | Object | null | 数据范围引用规则，null 表示不涉及（见 §2.5） |
2.5 数据权限引用机制
部分子智能体需要叠加数据范围，但不在智能体模块内重复定义，而是引用现有"数据权限"模块：
| 子智能体 | 数据范围策略 | 说明 |
|---|---|---|
| 会议预定 | ❌ 不涉及 | 由会议系统自身管理资源可用性 |
| 设备控制 | ✅ inherit → 数据权限.设备单控.按建筑空间 | 复用中台已有的空间数据权限 |
| 智能整备 | ❌ 不涉及 | 后台静默执行，面向空间而非用户 |
| 工单自动建单 | ❌ 不涉及（透传） | Agent 透传用户身份给工单系统，由工单系统自行校验 |
| 一键诊断 | ❌ 不涉及 | 嵌入业务页面，用户已在业务上下文中 |
2.6 一键诊断的特殊处理
一键诊断是一个独立 Dify Agent（有自己的 App ID），通过 branch_id: null 标记。它不是 Chatbot 对话触发，而是嵌入业务系统（如工单详情页）的一个按钮：
2.7 扩展规则
| 分支类型 | 说明 | 新叶节点加在哪 | branch_id |
|---|---|---|---|
| 分支意图（同一总 Agent 的新能力） | 总 Agent 编排中新增意图分支 | 放在现有分组下 | 非 null |
| 独立 Agent（全新的 Dify App） | 拥有独立 App ID | 放在现有分组下（若业务归属明确）或新建分组 | null |
分组只是管理界面的折叠容器。FA 分组下可以同时包含分支意图（工单自动建单）和独立 Agent（一键诊断），不强制组内共享
master_agent_id。权限校验只认叶节点，不关心它属于哪个分组。分组与分组的排序、分组内部叶节点的排序均为纯前端展示逻辑。
2.8 中台管理界面示意
┌─ 权限配置 ─────────────────────────────────────────────────────┐
│ │
│ Web 端 │ 移动端 │ 数据权限 │ [智能体] │ │
│ │
│ ┌─ ▼ 空间运营官 (SA) ──────────────────────────────────────┐ │
│ │ ☑ 会议预定 app-master / branch_meeting │ │
│ │ ☑ 设备控制 app-master / branch_control [数据范围: 继承自"设备单控-按建筑空间"] │
│ │ ☐ 智能整备 app-master / branch_prep │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌─ ▼ 设施协同官 (FA) ──────────────────────────────────────┐ │
│ │ ☑ 工单自动建单 app-master / branch_workorder [数据范围: 由工单系统管理] │
│ │ ☑ 一键诊断 app-diagnosis / (独立 Agent) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘管理员操作：勾选 checkbox = 赋予许可；取消勾选 = 回收许可。数据范围引用自动关联，无需重复配置。
3. Web 管理后台接入（页面级，接入现有 web端）
3.1 需接入的页面
| 页面 | 归属应用 | 权限级别 |
|---|---|---|
| 标准语义库 (iot-semantics.html) | 空间智能体管理后台 | 页面级 |
| 空间资产管理 (iot-assets.html) | 空间智能体管理后台 | 页面级 |
| 设备资产管理 (iot-devices.html) | 空间智能体管理后台 | 页面级 |
| 系统设置（预留） | 空间智能体管理后台 | 页面级 |
接入方式：在中台
web端下新增应用"空间智能体管理后台"，挂载以上页面。页面级控制即可，无需细化到按钮。
3.2 与智能体权限的关系
管理后台的配置操作（如启停空间能力插件）是另一个维度的权限，由现有的 web端 页面权限 + 数据权限（按建筑空间）控制。智能体模块的 checkbox 仅控制终端用户能否通过 Agent 使用该能力，二者独立。
4. 小程序 Chatbot 接入（页面级，接入现有 移动端）
在小程序现有 移动端.小程序.pages 下新增一个页面：
json
{
"移动端": {
"小程序": {
"pages": [
"...existing pages...",
"AI 空间管家"
]
}
}
}用户进入 Chatbot 后，具体能使用哪些 Agent 能力，由 §2 的智能体模块控制。
5. Agent 执行时的权限校验链
5.1 核心设计原则
先查权限，再意图识别。主Agent在意图识别前就知道用户能做什么，避免识别出无权限的意图后再告知失败。
两段式校验：
- 主Agent：负责功能准入——用户是否有权使用该意图（yes/no）
- 子Agent：负责数据权限——用户能在哪些空间/设备范围内操作（按需查询，不预取全量）
主Agent不做实体提取（slot filling），空间/设备的向量检索是子Agent的事。因此数据权限只能下沉到子Agent侧校验。
5.2 Chatbot 路径（分支意图）
前端已预取可用意图列表并注入 LLM 上下文，意图识别本身被约束在可用范围内，命中即代表已授权，无需主Agent再次调中台确认。
5.3 独立 Agent 路径（一键诊断）
5.4 数据权限的按需校验（子Agent 代码节点）
采用 "全量检索 + 代码层过滤" 方案：
方案要点：
| 步骤 | 说明 |
|---|---|
| 向量检索不做 payload 过滤 | 返回空间下所有匹配设备，保留全量信息 |
| 代码层逐个查中台 | 对每个候选调用数据权限接口，候选通常 3~5 个，开销极小 |
| 代码层区分三种结果 | 0候选 / 全部无权 / 部分有效，分别构造不同上下文给 LLM |
| LLM 仅接收有效候选 | 保证 LLM 不会推荐用户无权限的设备 |
与其他方案的对比：
| 方案 | 问题 |
|---|---|
| 检索时 payload 过滤 | 返回即有效，但无法区分"没设备"和"有设备但无权"，话术模糊 |
| 全量检索 + LLM 自行判断 | LLM 不知道权限边界，可能推荐无权设备 |
| 全量检索 + 代码层过滤（采用） | 话术精准、LLM 输入干净、候选少开销低 |
5.5 各意图校验矩阵
| 意图 | 功能准入（主Agent） | 数据范围（子Agent） | 附加校验 |
|---|---|---|---|
| 会议预定 | checkbox 勾选 | ❌ 不涉及 | 会议系统管理资源可用性 |
| 设备控制 | checkbox 勾选 | ✅ 按候选实体逐个查中台"设备单控-按建筑空间" | 语义物理量程约束 |
| 智能整备 | checkbox 勾选 | ❌ 不涉及 | 空间是否开启整备插件（系统级校验） |
| 工单自动建单 | checkbox 勾选 | ❌ 不涉及 | 建单类型权限由工单系统判断（透传 user_id） |
| 一键诊断 | checkbox 勾选 | ❌ 不涉及 | 用户需有该工单的查看权限（业务系统提供） |
5.6 语义化拒绝提示
| 失败原因 | 触发位置 | Agent 回复示例 |
|---|---|---|
| 意图未授权 | 主Agent-意图识别 | 用户输入的意图不在可用范围内，降级引导，不暴露权限信息 |
| 有设备但无权控制 | 子Agent-代码节点 | "305 会议室有相关设备，但你当前没有控制权限。你当前可控制的空间包括：301、302。" |
| 未找到匹配设备 | 子Agent-代码节点 | "305 会议室暂未找到可控设备，请确认空间名称或联系管理员纳管。" |
6. 角色与权限组（建议中台侧配置）
6.1 推荐角色模板
在中台配置角色时，建议按以下模板组合各模块权限：
| 角色 | web端 | 移动端-小程序 | 智能体 | 数据权限 |
|---|---|---|---|---|
| 超级管理员 | 空间智能体管理后台(全部页面) | AI 空间管家 | 全部 5 项 | 全部空间 |
| 物业经理 | 空间/设备管理 | AI 空间管家 | 会议预定、设备控制、智能整备、工单建单 | 管辖空间范围 |
| 运维工程师 | — | AI 空间管家 | 工单自动建单、一键诊断 | 管辖空间范围 |
| 普通员工 | — | AI 空间管家 | 会议预定、设备控制 | 所在空间 |
| 访客 | — | AI 空间管家 | 会议预定 | — |
6.2 设备控制的数据权限策略
对于设备控制，建议中台为不同用户组配置不同的"设备单控-按建筑空间"范围：
| 用户组 | 数据范围 | 典型说明 |
|---|---|---|
| 领导层 | 全部办公空间（排除机房/配电间） | 不能控制需要专业知识的关键设备 |
| 后勤组 | 全部空间（含机房/配电间） | 专业设备全覆盖 |
| 普通员工 | 仅所在空间或已预订空间 | 最小权限 |
配置方式：直接在中台"数据权限 → 设备单控 → 按建筑空间"中按用户/角色分配，无需在智能体模块重复定义。
7. 附录：中台权限结构完整示意
json
{
"permission_profile": {
"web端": {
"...existing...": "...",
"空间智能体管理后台": [
"标准语义库",
"空间资产管理",
"设备资产管理"
]
},
"移动端": {
"小程序": {
"pages": ["...existing...", "AI 空间管家"]
}
},
"数据权限": {
"设备单控": {
"按建筑空间": ["...existing building/floor tree..."]
}
},
"智能体": {
"groups": [
{
"group_key": "sa",
"group_name": "空间运营官 (SA)",
"intents": [
{
"name": "会议预定",
"master_agent_id": "app-master",
"branch_id": "branch_meeting",
"data_scope": null
},
{
"name": "设备控制",
"master_agent_id": "app-master",
"branch_id": "branch_control",
"data_scope": {
"inherit_from": "数据权限.设备单控.按建筑空间"
}
},
{
"name": "智能整备",
"master_agent_id": "app-master",
"branch_id": "branch_prep",
"data_scope": null
}
]
},
{
"group_key": "fa",
"group_name": "设施协同官 (FA)",
"intents": [
{
"name": "工单自动建单",
"master_agent_id": "app-master",
"branch_id": "branch_workorder",
"data_scope": null
},
{
"name": "一键诊断",
"master_agent_id": "app-diagnosis-agent",
"branch_id": null,
"data_scope": null
}
]
}
]
}
}
}