AI 空间智能体 — 猜你想问配置管理 PRD v1.0
版本记录：
- v2.0 (2026-07-15)：重大重构——移除「可见角色」体系，替换为「子智能体（能力）数据字典」；Agent ID 从单值文本输入改为能力多选；数据模型
roles→agent_ids- v1.3 (2026-07-13)：同步原型变更——表格/筛选/表单统一分组列在角色前；批量操作栏新增批量启用/禁用按钮；表单新增分组字段；新增变更人/变更时间列；新增查询按钮。
- v1.2 (2026-07-13)：移除用户角色定义章节，左侧导航布局修正，增加问题文本模糊查询，优先级改为 1-100 默认 50。
- v1.1 (2026-07-13)：Agent 改为文本输入（不与 Dify 打通），角色改用搜索式标签多选（中台中文角色名），移除 Chatbox 端集成章节。
- v1.0 (2026-07-13)：初稿
- v1.0 (2026-07-13)：初稿
1. 产品定位
目标用户：运营人员 / 实施人员（配置各 AI 智能体 Chatbox 的默认推荐问题）。
核心功能：管理「猜你想问」问题列表——每一条问题绑定到一或多个子智能体（能力），用户在空对话状态下看到关联了当前激活能力的推荐问题，点击即可快速发起对话。
设计原则：
- 轻量配置：只有一套列表页面 + 单个弹窗表单 + 导入导出，不做复杂交互
- 能力关联：问题通过「子智能体（能力）」多选关联，一个问题可同时属于多个能力（如「闲聊」和「会议预定」）
- 数据字典驱动：子智能体名称 ↔ Agent ID 的映射由中台数据字典统一维护，页面只显示名称
- 前端截取：各端按屏幕尺寸自行决定展示数量，后端不做截断
2. 页面设计
2.1 整体布局
┌──────────┬───────────────────────────────────────────────────────────┐
│ 左侧导航 │ 首页 > AI 设置 > 猜你想问 │
│ │ │
│ 🧬语义 │ ┌──────────────────────────────────────────────────┐ │
│ 📦产品 │ │ [问题...] [能力 ▼] [标签...] [状态 ▼] [查询] │ │
│ 🏢空间 │ │ [+ 新建] [📥 导入] [📤 导出] [📋 下载空模板] │ │
│ 💡设备 │ ├──────────────────────────────────────────────────┤ │
│ 🔧诊断 │ │ □ 问题文本 │ 能力/智能体 │标签│优先│启用│...│ │
│ 💬引导 │ │ ──────────────────────────────────────────────── │ │
│ ⚙️ │ │ □ 帮我查.. │ [会议预定] │会议│ 50 │ ✅│...│ │
│ │ │ □ C-304... │ [设备控制] │ — │ 50 │ ✅│...│ │
│ │ │ □ 今天待办工单 │ [工单创建] │ 维修 │ 50 │ ☑️ │...│ │
│ │ │ □ 巡更流程 │ [闲聊] │ — │ 40 │ ☑️ │...│ │
│ │ │ ... │ │
│ │ │ │ │
│ │ │ 共 12 条 1/1 页 │ │
│ │ └──────────────────────────────────────────────────┘ │
│ │ │
│ │ 📌 问题可关联多个能力/子智能体，选择后 Chatbox 端按匹配展示│ │
└──────────┴───────────────────────────────────────────────────────────┘左侧导航：
- 遵循现有管理后台左侧导航布局，
💬 引导图标入口与其他模块并列 - 点击「猜你想问」进入当前页面
2.2 筛选栏
- 问题搜索：文本输入框，对
question_text进行模糊匹配（LIKE 查询），默认空 - 能力筛选：下拉多选面板，选中一或多个子智能体名称后，仅展示关联了其中任一能力的问题。不选 = 全部（默认「全部」）
- 标签筛选：文本输入框，对
tags进行模糊匹配（LIKE 查询），默认空 - 状态筛选：下拉选择「全部 / 仅启用 / 仅禁用」，默认「全部」
- [查询] 按钮：触发筛选刷新（输入框支持
oninput即时过滤，按钮提供显式触发） - 各筛选条件间为 AND 关系
2.3 操作按钮
| 按钮 | 功能 |
|---|---|
[+ 新建] | 打开新建问题弹窗 |
[📥 导入] | 上传 CSV/JSON 文件，追加式导入（见 §4 导入导出） |
[📤 导出] | 下载当前筛选结果（见 §4 导入导出） |
[📋 下载空模板] | 下载空模板 CSV 文件（仅表头 + 一行示例） |
勾选表格行后出现批量操作栏：
| 按钮 | 功能 |
|---|---|
[批量编辑] | 打开批量能力编辑弹窗 |
[批量启用] | 直接将选中记录全部启用（无需弹窗确认） |
[批量禁用] | 直接将选中记录全部禁用（无需弹窗确认） |
[批量删除] | 删除选中记录（需确认） |
2.4 表格列
| 列 | 说明 |
|---|---|
| 多选框 | 支持批量操作（批量编辑、批量启用、批量禁用、批量删除） |
| 问题文本 | 问题内容，过长时省略展示 |
| 能力/智能体 | 关联的子智能体名称标签（来自中台数据字典），可多选。以蓝色标签展示，一个标签 = 一个能力 |
| 标签 | 业务自定义分类标签，仅管理界面展示和筛选用（如「会议」「设备」「工单」） |
| 优先级 | 数值越小越靠前展示 |
| 启用 | 启用/禁用开关 |
| 变更人 | 最近修改该条记录的用户 |
| 变更时间 | 最近修改时间 |
| 操作 | 编辑 / 删除按钮 |
2.5 新建/编辑弹窗
点击 [+ 新建] 或某行的编辑按钮，弹出表单弹窗：
┌──────────────────────────────────────────┐
│ 新建猜你想问 [✕] │
├──────────────────────────────────────────┤
│ │
│ 问题文本 * │
│ ┌──────────────────────────────────┐ │
│ │ 帮我查一下今天的会议 │ │
│ └──────────────────────────────────┘ │
│ │
│ 标签（可选） │
│ ┌──────────────────────────────────┐ │
│ │ 会议 │ │
│ └──────────────────────────────────┘ │
│ │
│ 关联能力/子智能体 * │
│ ┌──────────────────────────────────┐ │
│ │ [会议预定 ✕] [闲聊 ✕] │ │
│ │ [🔍 搜索能力名称添加... ] │ │
│ ├──────────────────────────────────┤ │
│ │ 📋 从以下列表选择能力： │ │
│ │ 闲聊 │ │
│ │ 设备控制 ← 点击选择 │ │
│ │ 会议预定 │ │
│ │ 工单创建 │ │
│ │ 数据查询 │ │
│ └──────────────────────────────────┘ │
│ （可多选，选择后该问题将关联到对应的 │
│ 子智能体 Chatbox） │
│ │
│ 优先级 │
│ ┌──────────────────────────────────┐ │
│ │ [50 ] │ │
│ └──────────────────────────────────┘ │
│ │
│ 启用状态 │
│ ○ 已启用 ○ 已禁用 │
│ │
│ [取消] [保存] │
└──────────────────────────────────────────┘表单规则：
- 问题文本 *：必填，最长 200 字符
- 关联能力/子智能体 *：搜索式标签多选——点击输入框弹出搜索面板，显示数据字典中所有可用子智能体（中文名称）；支持键盘输入过滤；选中的能力以标签形式展示在输入区，点击标签 ✕ 移除。必选至少一个能力
- 优先级：必填，正整数，范围 1-100，默认 50
- 启用状态：开关，默认「已启用」
能力数据来源：中台统一「子智能体数据字典」提供 KV 映射（name ↔ agent_id）。配置时存储
agent_ids数组，页面展示名称。
2.6 批量编辑
选中多条记录后，操作栏出现「批量编辑」按钮：
┌──────────────────────────────────────────┐
│ 批量编辑 (已选 3 条) [✕] │
├──────────────────────────────────────────┤
│ │
│ 以下字段若不填写，则保持原有值不变 │
│ │
│ 关联能力/子智能体 │
│ ┌──────────────────────────────────┐ │
│ │ [会议预定 ✕] [闲聊 ✕] │ │
│ │ [🔍 搜索添加能力... ] │ │
│ ├──────────────────────────────────┤ │
│ │ 📋 从以下列表选择能力： │ │
│ │ 闲聊 │ │
│ │ 设备控制 ← 点击 │ │
│ │ 会议预定 │ │
│ │ 工单创建 │ │
│ │ 数据查询 │ │
│ └──────────────────────────────────┘ │
│ （修改后将覆盖所有选中记录的能力配置） │
│ │
│ [取消] [保存] │
└──────────────────────────────────────────┘批量编辑规则：
- 仅支持批量编辑「关联能力/子智能体」字段
- 选择了新的能力 → 直接覆盖所有选中记录的
agent_ids字段（不做合并） - 留空不修改
批量启用/禁用独立为快捷按钮（在批量操作栏中直接展示），无需弹窗：
4. 导入导出
4.1 导出
点击 [📤 导出]，下载当前筛选条件下的结果集。
CSV 格式：
csv
问题文本,能力名称,优先级,标签
帮我查一下今天的会议,会议预定,50,会议
C-304 的空调开了吗,设备控制,60,设备
今天有什么待办工单,工单创建;闲聊,30,工单- 编码：UTF-8 with BOM（兼容 Excel 中文）
能力名称列：多个子智能体名称用英文分号;分隔，映射自中台数据字典- 字段包含
标签（业务自定义标签），导出一定有该列，导入时可缺省 - 导入默认启用，CSV 中不包含启用状态列
- 兼容旧版英文表头（
question_text/agent_ids/priority/tags）
JSON 格式（备选）：
json
[
{
"question_text": "帮我查一下今天的会议",
"agent_ids": ["会议预定"],
"priority": 50,
"tags": "会议"
}
]注：JSON 格式字段名保持英文（
question_text/agent_ids/priority/tags），agent_ids的值填写子智能体中文名称。
4.2 导入
点击 [📥 导入]，选择 CSV 或 JSON 文件上传。
导入规则：
- 追加式导入：上传文件的问题逐条插入，不清除已有数据
- 去重覆盖：以
agent_ids + question_text为唯一键，文件中若与已有记录重复 → 覆盖该记录的agent_ids、priority、enabled、tags - 批量一次性提交：文件内所有记录解析验证后，一次性提交事务，全部成功或全部回滚
导入流程：
用户选择文件 → 系统解析验证 → 在页面显示预览 ─→ 用户确认 → 执行导入
│
├ 成功 N 条
├ 跳过 M 条（重复且数据不变）
└ 错误 K 条（展示错误行号+原因）文件校验规则：
| 规则 | 处理方式 |
|---|---|
| 缺少必填列（问题文本 / 能力名称） | 报错，不执行 |
| 某一行的「问题文本」为空 | 跳过该行，记入错误统计 |
| 「能力名称」为空或包含无法识别的能力名称 | 跳过该行，记入错误统计 |
| 「优先级」不是 1-100 的正整数 | 跳过该行，记入错误统计 |
4.3 空模板
点击 [📋 下载空模板] 下载，内容：
csv
问题文本,能力名称,优先级,标签
示例：帮我查一下明天的会议,会议预定,50,会议- 首行为表头
- 第二行为示例行（带数据），供用户参考格式后删除替换
- 模板有 BOM 头，Excel 直接打开不乱码
5. 数据模型
5.1 数据库表：faq_questions
| 字段 | 类型 | 约束 | 说明 |
|---|---|---|---|
id | UUID | PK | 主键 |
agent_ids | JSON / TEXT[] | NOT NULL | 关联的子智能体 Agent ID 列表（至少一个），映射自中台数据字典 |
question_text | VARCHAR(200) | NOT NULL | 问题文本 |
priority | INT | NOT NULL DEFAULT 50 | 排序优先级 1-100，值越小越靠前 |
enabled | BOOLEAN | NOT NULL DEFAULT true | 启用/禁用 |
tags | VARCHAR(64) | DEFAULT NULL | 业务自定义标签，仅管理界面展示和筛选用 |
updated_by | VARCHAR(64) | DEFAULT NULL | 最近修改人 |
created_at | TIMESTAMP | NOT NULL | |
updated_at | TIMESTAMP | NOT NULL | 最近修改时间 |
唯一约束：(agent_ids, question_text) — 同一组能力下不允许重复问题文本。
索引：
(agent_ids, enabled, priority)— Chatbox 端查询（GIN 索引）(agent_ids, question_text)— 唯一键 + 导入去重
5.2 子智能体数据字典
中台维护一张独立的数据字典表，用于子智能体名称与 Agent ID 的映射：
| 显示名称 | Agent ID | 说明 |
|---|---|---|
| 闲聊 | qa-agent | QA_Chat 闲聊对话 |
| 设备控制 | device-control | SA_Device_Control 设备控制 |
| 会议预定 | meeting-admin | SA_Reservation 空间预约 |
| 工单创建 | ticket-agent | FA_Ticket 工单建单 |
| 数据查询 | data-query | Data_Query → ChatBI 数据分析 |
管理前端页面只展示「显示名称」，不展示 Agent ID。多选时存储
agent_ids数组。
6. API 设计
6.1 客户端接口（Chatbox 端调用）
GET /api/v1/faq-questions?agent_ids={agentId1,agentId2}说明：返回指定子智能体（可多个）关联的已启用问题列表。Agent ID 与数据字典一致。
查询逻辑：
sql
WHERE agent_ids CONTAINS ANY :agentIds
AND enabled = true
ORDER BY priority ASC, created_at ASC响应示例：
json
{
"code": 0,
"data": [
{ "id": "uuid-1", "question_text": "帮我查一下今天的会议", "priority": 1 },
{ "id": "uuid-2", "question_text": "C-304 空调开了吗", "priority": 2 }
]
}6.2 管理端接口
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/v1/faq-questions | 列表查询（支持 agent_ids / enabled 筛选 + 分页） |
POST | /api/v1/faq-questions | 新建问题 |
PUT | /api/v1/faq-questions/:id | 编辑问题 |
DELETE | /api/v1/faq-questions/:id | 删除问题 |
POST | /api/v1/faq-questions/batch-delete | 批量删除（传 ID 数组） |
PUT | /api/v1/faq-questions/batch-edit | 批量编辑（传 ID 数组 + 要修改的字段） |
POST | /api/v1/faq-questions/import | 导入（上传 CSV/JSON 文件） |
GET | /api/v1/faq-questions/export | 导出（支持当前筛选条件参数） |
GET | /api/v1/faq-questions/import-template | 下载空模板 |
7. 边界场景与错误处理
| 场景 | 处理方式 |
|---|---|
| 同能力下配置了 100+ 个问题 | 管理端分页正常展示；Chatbox 端按 priority 取前 N 条，N 由各端自定 |
| 能力/子智能体在数据字典中被删除 | 管理页面仍展示已关联的能力名称（保留原值），但标记为「已删除」灰色标记；新增时不再出现在可选列表中 |
| 导入文件编码非 UTF-8 | 服务端检测编码，非 UTF-8 报错提示用户重新导出 |
| 导入文件超过 1MB | 服务端前置校验，超过则拒绝并提示 |
| 导入数据全部合法 | 全部导入，返回成功计数 |
| 导入数据部分合法部分非法 | 合法部分导入，非法部分跳过并展示错误明细（行号 + 原因） |
| 同时多人编辑同一问题 | 乐观锁（updated_at 比对），提交时版本冲突则提示用户刷新 |