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

## 基本信息

| 项目 | 内容 |
|------|------|
| 文档类型 | 需求文档 |
| 创建日期 | 2026-07-11 |
| 负责人 | 研发组 |
| 优先级 | 高 |
| 状态 | 规划中 |

---

## 一、背景与目标

### 1.1 当前痛点

| 痛点 | 说明 |
|------|------|
| 现场排查门槛高 | 现场技术同事遇到问题时依赖研发组远程支持，效率低 |
| 知识库利用率低 | 472 条历史问题记录在 62MB Excel 中，实际排查时很少翻阅 |
| 排查步骤不规范 | 不同人排查同一类问题走不同的路，甚至出现危险操作 |
| 研发组被打断 | 重复回答同类问题，影响开发效率 |

### 1.2 目标

给现场同事一个 **Web 页面**，输入遇到的问题 → 系统自动：
1. 从 472 条历史问题中匹配最相似案例
2. 结合 Troubleshoot 排查套路（SKILL.md）生成步骤指引
3. **输出经过安全过滤的排查步骤**——绝不包含危险操作、绝不包含无关操作

---

## 二、核心场景（最重要）

### 现场同事的完整使用流程（闭环）

```
现场同事遇到问题（如"门口屏绑定失败"）
       ↓
浏览器打开：http://内网IP/排查助手
       ↓
填写信息：
  ┌────────────────────────────────────────────┐
  │ 项目名称：[ 厦门银行____________ ]          │  ← 输入框，可手动填写或从下拉选择
  │ 系统类型：[ 标准版预定2.0    ▼ ]            │  ← 下拉选择
  │ APK产品： [ 门口屏5.0__________ ]           │  ← 可选，填写 APK 产品名称
  │                                            │
  │ 问题描述：                                  │
  │ ┌────────────────────────────────────────┐ │
  │ │ 门口屏绑定失败，提示MQTT连接错误...      │ │
  │ └────────────────────────────────────────┘ │
  └────────────────────────────────────────────┘
       ↓
点击"帮我排查"
       ↓
系统：
  ① 搜索历史问题库（匹配相似案例 Top 5）
  ② 加载 Troubleshoot 排查套路（SKILL.md）
  ③ 调用 Claude API 综合分析
  ④ 应用安全过滤器：剔除危险命令 + 剔除无关操作
       ↓
输出：
  ┌─────────────────────────────────────────────┐
  │ 🔍 排查诊断结果                               │
  │                                              │
  │ 📋 匹配到 3 个相似历史案例                     │
  │                                              │
  │ 🔬 排查步骤（只读操作）                        │
  │  Step 1：检查门口屏版本是否最新                 │
  │  Step 2：查看设备日志确认报错信息               │
  │  Step 3：检查 EMQX 容器是否正常                 │
  │  Step 4：确认 MQTT 账号密码是否已配置           │
  │  ...                                         │
  │                                              │
  │ 🎯 最可能的根因（按概率排序）                   │
  │  70%：旧版门口屏没有默认 MQTT 账号密码          │
  │  20%：EMQX 容器未启动                          │
  │  10%：授权码变化                               │
  │                                              │
  │ ⚠️ 注意事项                                    │
  │  · 排查时只读操作，不要随意重启服务              │
  │  · 更新门口屏包后务必重启设备 APP               │
  │                                              │
  │ ┌──────────────────────────────────────────┐ │
  │ │ ✅ 问题解决了？点击提交记录入库              │ │
  │ │ ❌ 没解决？联系研发组                       │ │
  │ └──────────────────────────────────────────┘ │
  └─────────────────────────────────────────────┘
       ↓
如果点击"提交记录入库"：
       ↓
系统自动生成问题记录草稿 → 现场同事确认 → 
写入项目问题库（追加到 xlsx + 同步到 Markdown）→ 
下次同类问题可被 AI 匹配到
```

### 首页输入字段设计

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| **项目名称** | 输入框 + 下拉建议 | ✅ 是 | 手动填写或从已有项目列表选择 |
| **系统类型** | 下拉选择 | ✅ 是 | 固定选项 |
| **APK 产品** | 输入框 | ❌ 否 | 仅当涉及 APK 产品时填写，如门口屏5.0、无纸化、桌牌等 |
| **问题描述** | 多行文本框 | ✅ 是 | 详细描述遇到的问题现象 |

### 系统类型选项（固定）

| 选项 | 说明 |
|------|------|
| 标准版预定2.0 | 会议室预定系统标准版 |
| 标准版运维集控系统 | IoT 设备运维管控系统 |
| 新统一平台 | 新版统一管理平台 |
| 统一平台 | 旧版统一管理平台 |

### APK 产品示例

| APK 产品 | 所属系统 | 说明 |
|----------|----------|------|
| 门口屏5.0 | 标准版预定2.0 | 会议室门口显示屏 APK |
| 门口屏4.0 | 标准版预定2.0 | 旧版门口屏 |
| 无纸化 | 标准版预定2.0 | 无纸化会议系统 |
| 桌牌 | 标准版预定2.0 | 电子桌牌 |
| 展厅巡检 | 标准版运维集控系统 | 展厅设备巡检 APK |
| ... | | |

### 问题入库闭环

当现场同事点击"提交记录入库"时：

```
┌─────────────────────────────────────────────┐
│ 📝 提交问题记录                              │
│                                              │
│ 项目：厦门银行（自动带入）                     │
│ 现象：门口屏绑定失败，提示MQTT连接错误         │
│ （可编辑补充）                                │
│                                              │
│ 排查过程：（自动填充刚才的排查步骤）            │
│ （可编辑补充）                                │
│                                              │
│ 实际根因：旧版门口屏无默认MQTT账号密码         │
│ （现场同事填写）                              │
│                                              │
│ 解决方案：升级门口屏pak                        │
│ （现场同事填写）                              │
│                                              │
│ 记录人：张三                                  │
│ 联系方式：（可选）                             │
│                                              │
│        [ 取消 ]    [ 确认提交 ]               │
└─────────────────────────────────────────────┘
```

提交后：
1. 自动追加到 `问题反馈跟踪表.xlsx` 的"项目问题记录"工作表
2. 定时同步脚本将其转换为 Markdown
3. 下次同类问题可被 AI 匹配到，形成知识闭环

---

## 三、安全约束（最高优先级）

### 3.1 输出内容过滤规则

AI 生成的排查步骤必须经过以下规则校验，**不合格的输出不展示**：

#### 禁止输出（硬约束）

| 类别 | 示例 | 理由 |
|------|------|------|
| 删除操作 | `rm -rf`、`docker rm -f`、删除文件/目录 | 不可逆 |
| 重启系统 | `reboot`、`shutdown`、`systemctl restart docker` | 影响所有服务 |
| 修改数据库 | `DELETE`、`DROP`、`TRUNCATE`、`UPDATE` | 不可逆 |
| 修改权限 | `chmod 777`、`chown` | 安全风险 |
| 停止关键服务 | `docker stop umysql`、`systemctl stop nacos` | 影响业务 |
| 写入敏感文件 | 修改 `/etc/fstab`、`/etc/ssh/sshd_config` 等 | 可能导致系统不可用 |
| 清空数据 | `redis-cli FLUSHALL` 等 | 数据丢失 |

#### 允许输出（白名单）

| 类别 | 示例 |
|------|------|
| 查看状态 | `docker ps -a`, `systemctl status`, `ss -tln` |
| 查看日志 | `docker logs --tail 100 xxx`, `tail -f xxx.log` |
| 连通性测试 | `nc -z ip port`, `curl -s url`, `ping` |
| 系统信息 | `df -h`, `free -h`, `date`, `ps aux` |
| 配置查看 | `cat 配置文件`, `grep 关键词 文件` |

### 3.2 输出内容相关性约束

- **禁止**：输出与当前问题无关的操作。例如问"门口屏不显示"不能给出"检查数据库表 xxx 的字段"
- **禁止**：用一个通用模板回复所有问题（如每次都从"先检查网络"开始）
- **强制**：每步操作必须能说清楚"这步是查什么、查到什么异常说明是什么问题"
- **强制**：操作步骤必须按"从最可能到最不可能"排序

---

## 四、影响范围

### 4.1 涉及现有文件

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `.claude/skills/Troubleshoot/SKILL.md` | 更新 | 增加 Web 排查模式 + 安全约束 |
| `.claude/skills/Troubleshoot/code/Troubleshoot助手.html` | 废弃 | 被新 Web 应用替代 |
| `Docs/PRD/问题知识库/问题反馈跟踪表.xlsx` | 维护 | 继续作为数据源 |
| `Docs/PRD/问题知识库/PRD_计划执行_问题知识库自动化同步与智能排查.md` | 更新 | 执行计划调整 |

### 4.2 新增文件

| 文件 | 说明 |
|------|------|
| `.claude/skills/Troubleshoot/code/web/` | Web 应用目录 |
| `.claude/skills/Troubleshoot/code/web/index.html` | 主页面 — 项目输入+系统类型选择+APK产品输入+结果展示 |
| `.claude/skills/Troubleshoot/code/web/server.py` | 后端服务（Flask） |
| `.claude/skills/Troubleshoot/code/web/search_engine.py` | 问题匹配引擎 |
| `.claude/skills/Troubleshoot/code/web/safety_filter.py` | 安全过滤器 |
| `.claude/skills/Troubleshoot/code/xlsx_to_md.py` | Excel→Markdown 转换 |
| `.claude/skills/Troubleshoot/code/build_index.py` | 索引生成 |
| `.claude/skills/Troubleshoot/code/config.json` | 系统类型列表、Claude API 等配置 |
| `Docs/PRD/问题知识库/问题记录/` | 从 Excel 转换的 Markdown 知识库 |

---

## 五、系统架构

```
┌──────────────────────────┐
│  浏览器（现场同事）        │
│  http://内网IP:端口       │
│                          │
│  ① 填写项目名称（输入框）   │  ← 手动填写
│  ② 选择系统类型（下拉）     │  ← 标准版预定2.0/标准版运维集控/新统一平台/统一平台
│  ③ 填写APK产品（可选）     │  ← 仅APK产品需填写
│  ④ 描述问题               │
│  ⑤ 点击"帮我排查"          │
│  ⑥ 查看排查结果           │
│  ⑦ 问题解决了？提交入库    │  ← 反馈闭环
└──────────┬───────────────┘
           │ HTTP POST
           ▼
┌──────────────────────────┐
│  Flask Web Server        │
│  server.py               │
├──────────────────────────┤
│  1. 接收完整信息          │  ← 项目名称+系统类型+APK产品+问题描述
│  2. 调用 search_engine    │  ← 从 Markdown 问题库匹配相似案例
│  3. 组装 Prompt           │  ← 全量信息 + 匹配案例 + SKILL.md 套路
│  4. 调用 Claude API       │  ← 生成排查指引
│  5. 调用 safety_filter    │  ← 过滤危险操作 + 无关操作
│  6. 返回排查结果           │
│  7. 接收问题记录提交       │  ← 接收反馈并入库
│  8. 追加写入问题库         │  ← xlsx + Markdown 双写
└──────────────────────────┘
           │
    ┌──────┴──────┬─────────────┐
    ▼             ▼             ▼
┌─────────┐  ┌──────────┐  ┌──────────────┐
│ 问题知识库 │  │ SKILL.md │  │ 项目名称历史  │
│ Markdown │  │ 排查套路   │  │ (从问题库自动 │
│ (472条)  │  │           │  │  提取下拉建议) │
└─────────┘  └──────────┘  └──────────────┘
```

### 5.1 输入字段对 Prompt 的增强

提交给 Claude 的信息将不仅包含问题描述，还包含上下文信息：

```
项目名称：厦门银行         → 优先匹配该项目的历史问题，使用该项目的环境特征
系统类型：标准版预定2.0    → 确定排查域范围（EMQX/Nacos/门口屏/数据库...）
APK产品：门口屏5.0        → 进一步缩小排查范围（MQTT版本、人脸同步策略...）
问题描述：门口屏绑定失败    → 核心排查目标
```

这样 AI 可以做出更精准的判断，例如：
- 系统类型是"标准版预定2.0"→ 排查时优先关注 EMQX/门口屏/Nacos，而不是运维集控的协议透传
- APK 产品是"门口屏5.0"→ 知道是 5.0 版本，设备主动上报，不考虑 4.0 的并发刷新问题
- 项目名称是"厦门银行"→ 知道该项目的特定配置和企业微信对接方式

### 5.2 系统类型配置

```json
{
  "system_types": [
    {"value": "std20", "label": "标准版预定2.0"},
    {"value": "ops", "label": "标准版运维集控系统"},
    {"value": "new_unified", "label": "新统一平台"},
    {"value": "unified", "label": "统一平台"}
  ]
}
```

### 5.3 项目名称输入方式

| 方式 | 说明 |
|------|------|
| **手动输入** | 输入框直接填写，支持新项目名称 |
| **下拉建议** | 输入时从已有项目列表（自动从问题库提取）中联想匹配 |

项目名称的用途：
1. **匹配优先**：优先匹配同项目的同类问题
2. **入库标记**：新问题提交时自动关联到对应项目
3. **统计追溯**：后续可按项目统计问题分布和解决率

---

## 六、Prompt 设计核心

发给 Claude API 的 System Prompt 必须包含以下约束：

```markdown
你是一个问题排查专家助手。你需要：
1. 根据用户描述的问题，从提供的历史案例中匹配最相关的
2. 按照 Troubleshoot 排查套路生成逐步排查指引
3. 每步操作必须是**只读**的（查看状态、查看日志、探测连通性）
4. 严禁给出任何**修改、删除、重启、停止**等操作
5. 每步操作必须**直接关联**用户描述的问题，不允许给出泛化模板
6. 排查步骤按**最可能→最不可能**排序
7. 给出各可能根因的**概率估计**（基于历史案例频率）

安全原则（违反任意一条则整条回复作废）：
- 不 rm/mv/DROP/TRUNCATE/DELETE 任何东西
- 不 restart/stop/kill 任何服务或容器  
- 不修改任何配置文件
- 不执行任何会改变系统状态的操作
- 如果排查结论是需要以上操作，标记为"请联系研发组执行：[具体操作]"
```

### 6.1 用户查询模板

```
## 用户问题
项目名称：{project_name}
系统类型：{system_type}
APK产品：{apk_product}          (如未填写则省略此行)
问题描述：{user_query}

## 历史相似案例（按匹配度排序）
{matched_cases}

## 排查套路参考
{skill_md_excerpt}
```

### 6.2 上下文利用策略

| 字段 | 对排查的影响 |
|------|-------------|
| 项目名称 | 优先匹配该项目的案例；可参考该项目的已知配置特征 |
| 系统类型=标准版预定2.0 | 排查域聚焦：EMQX、Nacos、门口屏、无纸化、数据库 |
| 系统类型=标准版运维集控 | 排查域聚焦：协议透传、中间件、设备管理、MQTT |
| 系统类型=新统一平台 | 排查域聚焦：统一门户、SMC、腾讯会议、单点登录 |
| APK产品=门口屏5.0 | 版本特征：设备主动上报、MQTT默认凭据、只同步参会人脸 |
| APK产品=无纸化 | 排查重点：座位编排、平板缓存、同屏投屏 |

---

## 七、验收标准

### 功能验收

- [ ] Web 页面可以通过内网访问
- [ ] 首页包含项目名称输入框（手动填写+下拉建议）
- [ ] 首页包含系统类型下拉选择（标准版预定2.0/标准版运维集控/新统一平台/统一平台）
- [ ] 首页包含 APK 产品名称输入框（可选）
- [ ] 输入问题后 30 秒内返回排查指引
- [ ] 返回的排查步骤全部是只读操作
- [ ] 返回的每一步都与输入问题直接相关
- [ ] 历史案例匹配准确率 > 70%（人工抽检 20 条）
- [ ] 排查结果页面有"提交记录入库"按钮
- [ ] 提交后问题记录正确追加到问题库并在下次查询时可被匹配

### 安全验收

- [ ] 输出中不包含 rm、DROP、DELETE、restart、stop、kill、reboot 等危险操作
- [ ] 输出中不包含与问题无关的操作步骤
- [ ] 返回结果前自动扫描并过滤危险命令

---

## 八、非功能需求

| 需求 | 说明 |
|------|------|
| 部署方式 | 支持在内网 Windows 服务器上运行 |
| 响应时间 | 用户请求到返回结果不超过 30 秒 |
| 并发支持 | 支持 5 人同时使用 |
| 日志审计 | 记录每次排查的问题和结果，用于质量分析和优化 |
| 运维成本 | 无需专人维护，Python 服务开机自启 |

---

## 九、与现有系统的关系

```
现场同事使用 Web 排查助手（新）
         ↓ 结论需要修复操作时
    联系研发组执行
         ↓
研发组在 ERP/ONLYOFFICE 上记录问题（不变）
         ↓
定时脚本同步 xlsx → Markdown（新）
         ↓
Web 排查助手自动读取最新知识库（新）
```

研发组的日常工作流**完全不变**，继续在 ONLYOFFICE 表格中记录问题。现场同事通过 Web 获得的是基于最新数据的排查指引。
