Master Agent：Chatbot MAS 中枢路由设计

文档版本：v2.1
更新日期：2026-08-25
所属体系：本文档描述 Chatbot MAS（对话式多智能体系统） 的中枢路由层，属于整个空间智能体项目的一个子系统。项目整体架构参见整体架构概览。

1. 核心定位与架构总览

1.1 角色定位

Master Agent 是 Chatbot MAS 对话式多智能体系统的中枢，承担以下职责：

意图分发：L1 意图识别后将用户请求路由至对应子 Agent
调度编排：维护子 Agent 注册清单与调用协议
记忆管理：维护跨 Agent 的 Short-term Memory，保证对话连续性
冲突协调：当多 Agent 指令冲突时执行全局裁定策略

核心原则：Master Agent 只做路由不执行业务，具体对话逻辑、槽位提取、业务编排全部下沉至子 Agent。

适用范围：仅覆盖 Chatbot MAS 内部。独立后台 Agent（智能整备、一键诊断）不经过 Master Agent 路由，详见整体架构概览。

1.2 Chatbot MAS 子 Agent 全景图

1.3 与现有文档的关系

文档	关系
`整体架构概览.md`	定义项目三大 Agent 体系及边界，本文档是其 Chatbot MAS 子体系的详细设计
`2026_AI空间智能体_权限体系设计.md`	定义两段式权限校验：Master Agent 负责功能准入（L1 路由前校验 `branch_id`）
`SA_空间预约_Agent设计.md`	Master Agent 的 MEETING 分支路由目标
`SA_设备控制_Agent设计.md`	Master Agent 的 IOT 分支路由目标
`QA_闲聊对话_Agent设计.md`	Master Agent 的 QA 分支路由目标
`Data_Query — ChatBI API`	Master Agent 的 DATA 分支路由目标，无独立 PRD，直接复用 ChatBI 工具
`FA_设备协同官_业务流程设计.md`	Master Agent 的 TICKET 分支路由目标

2. L1 意图识别与路由

2.1 意图分类定义

意图	标签	覆盖范围	路由目标
会议	`MEETING`	会议室预定、查询、修改、取消	SA_Reservation Agent
设备控制	`IOT`	环境调节、设备开关、模式切换	SA_Device_Control Agent
数据查询	`DATA`	动态数据：能耗报表、人流量、会议室利用率、设备运行统计、看板/图表查询等	Data_Query Agent (→ ChatBI)
闲聊/问答	`QA`	静态知识：寒暄、楼宇流程/规定、开放式问答、模糊输入	QA_Chat Agent

DATA 与 QA 的核心区分：DATA 查询的是实时/统计数据（走 ChatBI 结构化管道），QA 查询的是静态知识（走 KB RAG 非结构化管道）。两者管道不同，不宜合并。

2.2 L1 Router 提示词设计 (仅参考)

markdown

# 角色：智能中控路由
你的唯一任务是判断用户输入的意图类别。不要做槽位提取。

# 意图类别
1. **MEETING**: 涉及会议室预定、查询会议、修改日程、取消会议。
   - 示例："定个明天的会"、"查一下305有人吗"、"取消下周的例会"
2. **IOT**: 涉及物理环境控制、设备操作、环境调节。
   - 示例："太热了"、"把灯关一下"、"305 空调调到 25 度"
3. **DATA**: 涉及**动态数据查询**：数字、统计、趋势、排名、对比、同比环比，
   以及"看数据 / 看板 / 图表 / 指标"类表述。
   - 示例："上个月电费多少"、"昨天人流量大吗"、"305本周利用率"、"哪个楼层能耗最高"、
     "打开能耗看板"、"看下这个月的告警趋势"
   - **排除项**（看似数据实非数据，不判 DATA）：
     · 流程 / 规则 / 规定类（即使含数字）："会议室能坐几个人" → QA
     · 设备状态实时查询（走 IOT）："305空调多少度" → IOT
     · 空间 / 楼层静态属性（走 QA）："这栋楼有几层" → QA
   - **兜底原则**：不能确认是"可查询的动态业务数据"时，不判 DATA，宁归 QA，由 QA 侧引导。
4. **QA**: 涉及**静态知识**或非业务输入：
   - 流程/规定/方法/定义/说明：如"会议室怎么预约"、"停车费怎么收"、"什么是碳中和"
   - 问候/寒暄：如"你好"、"谢谢"
   - 模糊/无法归类：如"帮我看看"、"随便聊聊"

# DATA vs QA 区分规则
- 涉及 动态业务数据 / 统计 / 趋势 / 排名 / 对比 / 看板 / 图表 → **DATA**
- 涉及 流程 / 规定 / 方法 / 定义 / 说明 / 静态属性 → **QA**
- 设备状态实时查询 → **IOT**
- 不确定时 → 不判 DATA，宁归 QA

# 输出格式
仅输出 JSON，包含 intent 和 confidence。
{
  "intent": "MEETING" | "IOT" | "DATA" | "QA",
  "confidence": 0.0 ~ 1.0
}

2.3 置信度策略

置信度区间	策略	说明
`>= 0.8`	直接路由	确信度高，直接分发至对应子 Agent
`0.5 ~ 0.8`	路由 + 澄清标记	分发至子 Agent，同时传递 `ambiguous: true`，子 Agent 可主动发起澄清反问
`< 0.5`	全部归入 QA	低置信度时不做强行分类，将模糊输入交由 QA_Chat Agent 统一处理

关于 DATA 分支：DATA 分支走 ChatBI 管道，与 QA 的 KB RAG 管道完全隔离。详见 §4.4。

2.4 权限前置校验

L1 路由完成后、分发至子 Agent 前，Master Agent 需执行一步权限检查：

根据当前用户的 permission_profile，确认其是否有权访问该 intent（即对应的 branch_id）
有权限 → 正常分发
无权 → 返回统一话术"抱歉，您没有使用此功能的权限，请联系管理员开通"

权限模型详细定义参见：2026_AI空间智能体_权限体系设计.md

两段式校验分工：Master Agent 只做功能准入（能/不能用这个意图），数据层面的过滤（用户能看哪些空间/设备）由子 Agent 代码层自行处理。

2.5 路由性能要求

L1 意图识别（含 LLM 调用）应控制在 2s 以内
L1 阶段不做知识库检索，仅依赖 LLM 自身分类能力，确保轻量快速
若后续需要接入知识库辅助意图增强（KB RAG for Intent Enhancement），仅在 confidence < 0.7 的边缘场景下选择性触发

2.6 UI 辅助意图分类：能力胶囊

能力胶囊（Capsule Bar）是聊天输入框上方的横向按钮组，为用户提供显式意图选择入口，在 UI 层面替代 Master Agent 的 L1 意图识别节点。

2.6.1 核心定位

┌─────────────────────────────────────┐
│ [📅 会议预定] [💡 设备控制] [📝 工单创建] │ ← 单选胶囊，选中后标明用户意图
├─────────────────────────────────────┤
│ 请输入您的需求...              🎤    │ ← 输入框
└─────────────────────────────────────┘

强制意图分类：用户通过胶囊明确告知系统"我要做什么"，Master Agent 不再需要 LLM 猜测意图
取代 L1 意图识别：当胶囊处于选中态时，用户输入绕过 §2.2 L1 Router 提示词，直接路由至对应子 Agent
单行横向滚动：胶囊数量可扩展，超出屏幕宽度时横向滚动

2.6.2 交互规则

规则	说明
单选	同一时间最多一个胶囊处于选中态，选中新胶囊自动取消上一个
切换逻辑	点击未选中胶囊 → 选中；点击已选中胶囊 → 取消选中，回到无意图状态
空态	无胶囊选中时，走标准 L1 意图识别流程（§2.2）
输入联动	选中胶囊仅标记意图，不自动触发查询或填充输入框

2.6.3 状态定义

状态	视觉	行为
未选中	细边框 + 灰色文字 + 透明背景	可点击
选中	品牌色边框 + 品牌色文字 + 浅色填充	可点击取消；后续用户输入直接路由至对应子 Agent
悬停/按压	背景微变深	—

2.6.4 路由流程

用户选中"会议预定"胶囊（intent = MEETING）
  → Master Agent 跳过 L1 意图识别
  → 采用 MEETING 作为当前会话意图标签
  → 等待用户输入
    → 用户输入文本后，跳过 §2.2 分类，直接路由至 SA_Reservation Agent

无胶囊选中时：
  → 走标准 L1 意图识别流程（§2.2 ∼ §2.5）

2.6.5 胶囊注册清单

胶囊	意图标签	路由目标
会议预定	`MEETING`	SA_Reservation Agent
设备控制	`IOT`	SA_Device_Control Agent
工单创建	`TICKET`	FA_Ticket Agent

胶囊清单与 §7.1 子 Agent 接入清单保持同步。新增子 Agent 如需胶囊入口，在此表注册。

3. 子 Agent 调度协议

3.1 输入协议（Master → Sub-Agent）

当 L1 判定意图后，Master 向子 Agent 传递以下结构：

json

{
  "query": "用户原始输入文本",
  "context": {
    "user_id": "用户标识",
    "current_space": "当前所在空间",
    "current_time": "当前系统时间",
    "chat_history": ["最近 N 轮对话摘要"],
    "cross_domain_memo": "跨域记忆摘要（如有）"
  },
  "intent_l1": "MEETING | IOT | DATA | QA",
  "confidence": 0.95,
  "ambiguous": false
}

字段	类型	说明
`query`	String	用户原始输入，子 Agent 可进一步做 NLU
`context`	JSON	全局上下文，包含空间/用户/时间信息
`intent_l1`	String	L1 判定的顶层意图
`confidence`	Float	L1 置信度
`ambiguous`	Boolean	是否处于置信度边缘区间，子 Agent 可据此决定是否主动澄清

3.2 输出协议（Sub-Agent → Master）

子 Agent 处理完毕后，向 Master 回传执行状态：

json

{
  "status": "COMPLETED | CLARIFY | REJECTED",
  "payload": {
    "text": "回复给用户的文本",
    "action": "ACTION_TYPE (可选，如 RENDER_CARD | TRIGGER_API)",
    "params": {}
  }
}

状态	说明
`COMPLETED`	子 Agent 正常完成处理，返回回复内容
`CLARIFY`	子 Agent 需用户进一步澄清，返回追问文案
`REJECTED`	子 Agent 无法处理（超出能力范围），Master 执行兜底

3.3 子 Agent 能力注册规范

每个子 Agent 必须在 Master Agent 中注册其能力标签，格式：

yaml

agent_name: QA_Chat
display_name: "闲聊对话助手"
capabilities:
  - casual_chat        # 寒暄社交对话
  - knowledge_qa       # 知识问答（含 KB RAG）
  - fuzzy_input        # 模糊输入处理
input_type: raw_text   # 输入类型：raw_text | structured_slots

4. 分支编排流程

4.1 MEETING → SA_Reservation Agent

用户输入 → L1 Router(MEETING)
  → 注入上下文 (当前空间、时间、用户)
  → 调用 SA_Reservation Agent
    ├── Slot Filling → 后端会议 API
    ├── 多轮澄清 (如有缺失槽位)
    └── 返回会议推荐/执行结果
  → Master 接收结果 → 返回用户

详细设计参见：SA_空间预约_Agent设计

4.2 IOT → SA_Device_Control Agent

用户输入 → L1 Router(IOT)
  → 注入上下文 (当前空间、设备状态摘要)
  → 调用 SA_Device_Control Agent
    ├── Slot Filling → 3x3 Composite Search
    ├── L3 深度注入 → 产品级聚合能力
    └── 返回控制卡片/执行结果
  → Master 接收结果 → 返回用户

详细设计参见：SA_设备控制_Agent设计

4.3 QA → QA_Chat Agent（本期核心）

用户输入 → L1 Router(QA 或 < 0.5 置信度)
  → 注入上下文 (对话历史、当前空间)
  → 调用 QA_Chat Agent
    ├── 场景分类 → 寒暄/知识/模糊
    ├── [知识类] KB RAG 检索 → 增强生成
    ├── [寒暄类] 直接 LLM 生成
    └── [模糊类] 澄清反问
  → Master 接收结果 → 返回用户

详细设计参见：QA_闲聊对话_Agent设计

4.4 DATA → Data_Query Agent

设计背景

公司已有 ChatBI 工具（纯 API），可以查询动态数据、召回仪表盘报表、动态生成数据报表，且不区分业务域（覆盖能耗、会议、人流等所有领域）。

Master Agent 将 DATA 意图路由至 Data_Query 子 Agent，由它调用 ChatBI API 完成数据查询。

参考实现：科技馆数字孪生大屏 Coze 工作流（docs/02_设计/90_大屏端设计/科技馆数字孪生大屏coze/）已验证"意图路由 → ChatBI 取数 → 统一输出"的完整链路，本小节编排沿用其成熟结构改造。

处理流程

用户输入 → L1 Router(DATA)
  → 注入上下文 (用户身份、当前空间、时间范围)
  → 调用 Data_Query Agent
    ├── ① 拼接历史问题（Code 节点：最近 N 轮用户消息用 `;` 拼接，补全指代）
    ├── ② 调用 ChatBI API（HTTP Request：query + project_id + agent_id + chat_id + client_type）
    ├── ③ 解析 + 统一输出（Code 节点：透传 dataset/chart 数据，提取 summary）
    └── ④ 返回用户（文字播报 + 前端图表渲染）
  → Master 接收结果 → 返回用户

多轮对话处理（v2.1 新增）：ChatBI 为无状态查询（chat_id=-1 新建会话），多轮指代（如"那上个月呢"）由 Dify 层拼接最近 N 轮用户问题后一并传入 ChatBI，不依赖 ChatBI 侧会话管理。拼接规则参考 Coze 工作流"拼接历史问题"节点（159627）。

与 QA 分支的管道对比

维度	DATA（动态数据）	QA（静态知识）
数据源	ChatBI API（实时数仓/报表系统）	KB 知识库（文档/FAQ）
查询方式	结构化查询（SQL/API）	向量检索 + LLM 生成
返回形态	数字、趋势图、报表	文字说明、流程指引
典型问题	"本月电费"、"305利用率"、"人流量排名"	"怎么预约"、"收费标准"、"管理制度"

实现方式

Data_Query Agent 为轻量子 Agent，Dify Chatflow 三段式编排（参考 Coze chatbi_super_sonic 子流程）：

节点一：拼接历史（Code）—— 取最近 3 轮用户消息拼接（; 分隔），补全指代、去除口语杂质，输出改写后的 query
节点二：调 ChatBI API（HTTP Request）—— POST {api_base}/chatbi/query，参数：query / project_id / agent_id=1 / chat_id="-1" / client_type（BS/移动/Web 区分端）
节点三：统一输出（Code）—— 解析 ChatBI 返回，提取 summary（文字播报）+ dataset（图表数据），包装为统一输出协议；ChatBI 返回空/错误时降级话术

输出协议（v2.1 新增，跨端统一）：

json

{
  "summary": "文字播报摘要",
  "display_type": "chatbi",
  "dataset": [],
  "chart_type": "bar | line | pie | table",
  "config": {}
}

注：大屏端额外含 action 字段（dashboard 联动），见 大屏端_Dify_Agent_设计；Web / 移动端本期无此字段。

异常兜底：ChatBI 超时（>10s）/ 空数据 / 报错 → Data_Query 返回统一话术，不回退 QA（避免跨管道语义混淆）。识别兜底（L1 置信度 < 0.5 归 QA）由 §2.3 负责。

权限：遵循两段式校验——Master 做功能准入（DATA 分支可用性），数据行级过滤由 ChatBI 侧按 project_id + 用户身份完成（待与 ChatBI 团队确认其权限模型）。

无独立 PRD，直接复用 ChatBI 现有能力；集成层 PRD 见 docs/02_设计/50_ChatBI_集成/PRD/。

4.5 冲突协调策略

冲突场景	策略
Agent A 要关灯，Agent B 表示会议进行中	会议优先：环境控制需确认用户意图
用户同时发控制+问答混合指令	单意图优先：仅路由 L1 最高置信度意图，另一意图在回复中提示

5. 全局上下文与记忆管理

5.1 Short-term Memory（会话级）

Master Agent 维护当前对话线程的 Short-term Memory，包括：

当前用户身份与所属空间
最近 10 轮对话摘要
本轮已调用的子 Agent 记录

5.2 跨域记忆共享

当用户在不同子 Agent 间切换时，Master Agent 负责跨域记忆的传递：

用户： "帮我把305的灯关掉"       → L1: IOT → SA_Device_Control
用户： "顺便帮我订个会议室"       → L1: MEETING → SA_Reservation
                                    (注入：用户刚在 305 关了灯)

跨域记忆摘要由 Master Agent 维护，每次切换 Agent 时注入至目标子 Agent 的 context.cross_domain_memo 字段。

5.3 主动述职机制（预留）

Master Agent 每日汇集各子 Agent 离线执行的任务（预热、调优、定时策略等），生成数字员工日报。本期不实现，预留接口。

6. 与独立后台 Agent 的关系

以下 Agent 不经过 Master Agent 路由，属于独立的 Agent 体系，详见整体架构概览：

SA_Prep（智能整备）：时间/事件驱动的后台定时任务，会前自动预热预冷
FA_Diagnosis（一键诊断）：嵌入工单系统的独立 Agent，工单详情页按钮触发

详细设计参见：SA_主动整备_Agent设计

7. 附录

7.1 子 Agent 接入清单

Agent	编号	能力标签	接入状态	依赖文档
SA_Reservation	SA-01	resource_booking, availability_check, conflict_recommendation	✅ 已接入	`SA_空间预约_Agent设计.md`
SA_Device_Control	SA-02	device_control, environment_control, implicit_recovery	✅ 已接入	`SA_设备控制_Agent设计.md`
Data_Query	DA-01	data_query, report_recall, dynamic_chart	🆕 本期新增（编排见 §4.4）	ChatBI API + 集成层 PRD（`50_ChatBI_集成/PRD/`）
QA_Chat	QA-01	casual_chat, knowledge_qa, fuzzy_input	🆕 本期新增	`QA_闲聊对话_Agent设计.md`
FA_Ticket	FA-01	ticket_creation, multimodal_input	🔜 本期新增	`FA_设备协同官_业务流程设计.md`

设计方案

语料

Master Agent：Chatbot MAS 中枢路由设计 ​

1. 核心定位与架构总览 ​

1.1 角色定位 ​

1.2 Chatbot MAS 子 Agent 全景图 ​

1.3 与现有文档的关系 ​

2. L1 意图识别与路由 ​

2.1 意图分类定义 ​

2.2 L1 Router 提示词设计 (仅参考) ​

2.3 置信度策略 ​

2.4 权限前置校验 ​

2.5 路由性能要求 ​

2.6 UI 辅助意图分类：能力胶囊 ​

2.6.1 核心定位 ​

2.6.2 交互规则 ​

2.6.3 状态定义 ​

2.6.4 路由流程 ​

2.6.5 胶囊注册清单 ​

3. 子 Agent 调度协议 ​

3.1 输入协议（Master → Sub-Agent） ​

3.2 输出协议（Sub-Agent → Master） ​

3.3 子 Agent 能力注册规范 ​

4. 分支编排流程 ​

4.1 MEETING → SA_Reservation Agent ​

4.2 IOT → SA_Device_Control Agent ​

4.3 QA → QA_Chat Agent（本期核心） ​

4.4 DATA → Data_Query Agent ​

设计背景 ​

处理流程 ​

与 QA 分支的管道对比 ​

实现方式 ​

4.5 冲突协调策略 ​

5. 全局上下文与记忆管理 ​

5.1 Short-term Memory（会话级） ​

5.2 跨域记忆共享 ​

5.3 主动述职机制（预留） ​

6. 与独立后台 Agent 的关系 ​

7. 附录 ​

7.1 子 Agent 接入清单 ​

Master Agent：Chatbot MAS 中枢路由设计

1. 核心定位与架构总览

1.1 角色定位

1.2 Chatbot MAS 子 Agent 全景图

1.3 与现有文档的关系

2. L1 意图识别与路由

2.1 意图分类定义

2.2 L1 Router 提示词设计 (仅参考)

2.3 置信度策略

2.4 权限前置校验

2.5 路由性能要求

2.6 UI 辅助意图分类：能力胶囊

2.6.1 核心定位

2.6.2 交互规则

2.6.3 状态定义

2.6.4 路由流程

2.6.5 胶囊注册清单

3. 子 Agent 调度协议

3.1 输入协议（Master → Sub-Agent）

3.2 输出协议（Sub-Agent → Master）

3.3 子 Agent 能力注册规范

4. 分支编排流程

4.1 MEETING → SA_Reservation Agent

4.2 IOT → SA_Device_Control Agent

4.3 QA → QA_Chat Agent（本期核心）

4.4 DATA → Data_Query Agent

设计背景

处理流程

与 QA 分支的管道对比

实现方式

4.5 冲突协调策略

5. 全局上下文与记忆管理

5.1 Short-term Memory（会话级）

5.2 跨域记忆共享

5.3 主动述职机制（预留）

6. 与独立后台 Agent 的关系

7. 附录

7.1 子 Agent 接入清单