# PRD_需求文档_问题知识库智能排查助手优化

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 需求文档 |
| 创建日期 | 2026-07-11 |
| 负责人 | 研发组 |
| 优先级 | 高 |
| 状态 | 已完成 |
| 关联文档 | [PRD_需求文档_问题知识库智能排查助手](./PRD_需求文档_问题知识库智能排查助手.md) |

---

## 一、背景与现状

### 1.1 已完成功能

问题知识库智能排查助手已完成核心功能开发并部署到 192.168.5.60：

- ✅ 知识库建设：357 条历史问题记录转换 + 搜索索引
- ✅ Web 应用：搜索匹配 + AI 分析 + 安全过滤 + 结果展示
- ✅ 问题入库：模态框表单 → Markdown 生成 → 索引自动更新
- ✅ 部署：systemd 服务，开机自启

### 1.2 当前问题

经实际使用验证，发现以下问题需优化：

| 问题 | 严重程度 | 影响 | 状态 |
|------|---------|------|------|
| 响应时间过长（25-27s） | 🔴 严重 | 用户等待体验差，易误判为卡死 | ✅ 已修复 |
| Prompt 未充分利用上下文 | 🟡 中等 | 系统类型、APK 产品字段未转化为针对性排查策略 | ✅ 已修复 |
| 缺少 SKILL.md 排查套路 | 🟡 中等 | AI 缺少 12 类高频场景参考，输出泛化 | ✅ 已修复 |
| 前端无进度反馈 | 🟡 中等 | 用户不知道当前执行到哪一步 | ✅ 已修复 |
| APK 产品字段未生效 | 🟢 轻微 | 填写后未影响排查方向 | ✅ 已修复 |

---

## 二、优化需求

### 2.1 响应速度优化（P0）

**问题**：当前 API 调用耗时 25-27 秒，用户等待体验差。

**优化目标**：用户点击后 10 秒内看到有意义的内容。

**方案一：渐进式展示**

```
用户点击"帮我排查"
    ↓ 立即（<1s）
前端显示："正在搜索历史案例..."
    ↓ 1-3s
展示匹配案例卡片（已有数据）
前端显示："正在进行 AI 深度分析..."
    ↓ 后台继续
AI 分析完成后追加展示排查步骤
```

**方案二：流式响应**

- 后端改用 SSE（Server-Sent Events）或 WebSocket
- AI 生成一段就推送一段，前端实时渲染

**方案三：缓存热门查询**

- 对高频问题（如"门口屏绑定失败"）缓存 AI 响应
- 相似查询命中缓存直接返回（<1s）

**验收标准**：

- [x] 用户点击后 3 秒内看到匹配案例
- [x] 完整响应在 30 秒内返回
- [x] 前端有明确的进度提示

---

### 2.2 Prompt 增强优化（P1）

**问题**：系统类型、APK 产品字段传入 Prompt 但 AI 未针对性利用。

**现状示例**：

```
输入：系统类型=标准版预定2.0，APK产品=门口屏5.0
输出：通用排查步骤，没有聚焦 EMQX/MQTT/门口屏版本特性
```

**优化方案**：

在 Prompt 中增加**排查域映射表**，让 AI 知道不同输入组合应关注哪些组件：

```markdown
## 排查域映射

| 系统类型 | 重点排查域 |
|---------|-----------|
| 标准版预定2.0 | EMQX、Nacos、门口屏、无纸化、数据库、Redis |
| 标准版运维集控系统 | 协议透传、中间件、设备管理、MQTT |
| 新统一平台 | 统一门户、SMC、腾讯会议、单点登录 |
| 统一平台 | 用户中心、权限管理、数据同步 |

| APK 产品 | 特性关注 |
|---------|---------|
| 门口屏5.0 | 设备主动上报、MQTT 默认凭据、只同步参会人脸 |
| 门口屏4.0 | Web 端并发刷新问题、需升级 |
| 无纸化 | 座位编排、平板缓存、同屏投屏 |
| 桌牌 | 授权码绑定、单点登录 |
```

**验收标准**：

- [x] 系统类型=标准版预定2.0 时，排查步骤优先聚焦 EMQX/Nacos/门口屏
- [x] APK 产品=门口屏5.0 时，提及版本特性和 MQTT 凭据检查
- [x] 不同系统类型输出差异化排查路径

---

### 2.3 上传 SKILL.md 排查套路（P1）

**问题**：服务器缺少 SKILL.md，AI 无法参考 12 类高频场景的详细排查套路。

**优化方案**：

1. 将 `.claude/skills/Troubleshoot/SKILL.md` 上传到 `/opt/troubleshoot/SKILL.md`
2. 修改 `server.py` 中 `get_skill_md()` 的路径
3. Prompt 中截取相关场景的排查套路传给 AI

**SKILL.md 包含的高频场景**：

- 服务/容器启动失败（≈38%）
- 设备终端问题——门口屏/无纸化/桌牌（≈31%）
- 配置文件/参数问题（≈28%）
- MQTT/EMQX 问题
- 时区/时间问题
- 第三方系统对接（SMC/腾讯/钉钉）
- ...

**验收标准**：

- [x] 服务器存在 `/opt/troubleshoot/SKILL.md`
- [x] AI 输出中引用 SKILL.md 中的排查套路
- [x] 针对"门口屏绑定失败"等问题，输出与 SKILL.md 一致的排查链路

---

### 2.4 前端进度提示优化（P2）

**问题**：当前只显示"正在分析问题..."，用户不知道进度。

**优化方案**：

分阶段显示进度：

```
阶段一：🔍 正在搜索历史案例...（1-3s）
阶段二：📋 找到 5 个相似案例，正在进行 AI 分析...（后续）
阶段三：✅ 分析完成
```

**验收标准**：

- [x] 至少 2 个阶段的进度提示
- [x] 阶段切换时有视觉反馈
- [x] 匹配案例在 AI 分析完成前可见

---

### 2.5 APK 产品字段生效（P3）

**问题**：APK 产品字段填写后未影响排查方向。

**优化方案**：

在 `build_prompt()` 中增加 APK 产品相关的 Prompt 段落：

```python
if apk_product:
    apk_hints = {
        "门口屏5.0": "设备主动上报心跳，内置默认 MQTT 凭据，只同步参会人人脸",
        "门口屏4.0": "Web 端主动刷新，并发量过大时可能断连，建议升级",
        "无纸化": "座位编排需与会议室绑定一致，平板缓存需清理",
        "桌牌": "绑定授权码后才能使用，检查 JWT 校验",
    }
    hint = apk_hints.get(apk_product, "")
    if hint:
        prompt += f"\n\n**{apk_product} 特性**：{hint}"
```

**验收标准**：

- [x] APK 产品=门口屏5.0 时，排查步骤提及"设备主动上报"、"默认 MQTT 凭据"
- [x] 不同 APK 产品输出差异化提示

---

## 三、优先级排序

| 优先级 | 需求 | 预计工作量 | 状态 |
|--------|------|-----------|------|
| P0 | 2.1 响应速度优化 | 4h | ✅ 已完成 |
| P1 | 2.2 Prompt 增强优化 | 2h | ✅ 已完成 |
| P1 | 2.3 上传 SKILL.md | 0.5h | ✅ 已完成 |
| P2 | 2.4 前端进度提示 | 2h | ✅ 已完成 |
| P3 | 2.5 APK 产品字段生效 | 1h | ✅ 已完成 |

---

## 四、影响范围

### 4.1 涉及文件

| 文件 | 变更类型 |
|------|----------|
| `server.py` | 更新 — Prompt 增强、SKILL.md 路径 |
| `index.html` | 更新 — 进度提示、渐进式展示 |
| `/opt/troubleshoot/SKILL.md` | 新增 — 排查套路文档 |

### 4.2 不影响

- 搜索引擎逻辑
- 安全过滤器
- 入库功能
- 部署配置

---

## 五、验收标准总览

### 功能验收

- [x] 用户点击后 3 秒内看到匹配案例
- [x] 完整响应在 30 秒内返回
- [x] 前端有分阶段进度提示
- [x] 系统类型影响排查聚焦方向
- [x] APK 产品字段影响排查提示
- [x] 服务器存在 SKILL.md

### 质量验收

- [x] 相同问题多次查询结果一致
- [x] 不同系统类型输出差异化
- [x] 安全过滤仍然生效

---

## 六、后续规划

完成以上优化后，可考虑：

1. **缓存热门查询**：高频问题秒级响应
2. **埋点统计**：记录用户查询的问题类型分布，优化知识库
3. **用户反馈**：排查步骤是否有用评分，持续改进 Prompt