# PRD_计划执行_问题知识库智能排查助手优化

## 基本信息

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

---

## 总览

### 核心优化项

| 优先级 | 需求 | 预计工作量 | 状态 |
|--------|------|-----------|------|
| 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 | ✅ 已完成 |

### 涉及文件

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `server.py` | 更新 | Prompt 增强、SKILL.md 路径、APK 产品字段 |
| `index.html` | 更新 | 进度提示、渐进式展示 |
| `SKILL.md` | 无变更 | 已存在于 `.claude/skills/Troubleshoot/SKILL.md`，部署时上传到服务器 |

---

## 阶段一：P0 响应速度优化（渐进式展示）

### 技术方案

**当前问题**：用户点击"帮我排查"后需等待 25-27 秒才看到结果，体验差。

**优化方案**：渐进式展示（不使用 SSE，避免引入新依赖）

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

### 实施步骤

- [ ] **步骤 1**：修改后端 `server.py`，拆分 `/api/troubleshoot` 为两个阶段：
  - `/api/search` — 仅搜索匹配案例（快速返回，<3s）
  - `/api/analyze` — 接收匹配结果，调用 AI 分析（慢速返回）

- [ ] **步骤 2**：修改前端 `index.html`，实现两阶段请求：
  1. 先调用 `/api/search`，展示匹配案例
  2. 再调用 `/api/analyze`，展示 AI 分析结果

- [ ] **步骤 3**：测试验证：
  - 用户点击后 3 秒内看到匹配案例
  - 完整响应在 30 秒内返回

### 验收标准

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

---

## 阶段二：P1 Prompt 增强优化

### 技术方案

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

**优化方案**：在 `build_prompt()` 中增加排查域映射表。

### 实施步骤

- [ ] **步骤 1**：在 `build_prompt()` 中添加排查域映射表：

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

# APK 产品 → 特性关注映射
APK_PRODUCT_HINTS = {
    "门口屏5.0": "设备主动上报心跳，内置默认 MQTT 凭据，只同步参会人人脸",
    "门口屏4.0": "Web 端主动刷新，并发量过大时可能断连，建议升级到 5.0",
    "无纸化": "座位编排需与会议室绑定一致，平板缓存需定期清理",
    "桌牌": "绑定授权码后才能使用，检查 JWT 校验是否正常",
}
```

- [ ] **步骤 2**：在 Prompt 中动态注入相关信息：

```python
# 构建系统类型排查域提示
domain_hint = ""
if system_type and system_type in SYSTEM_TYPE_DOMAINS:
    domain_hint = f"\n\n**{system_type} 重点排查域**：{SYSTEM_TYPE_DOMAINS[system_type]}"

# 构建 APK 产品特性提示
apk_hint = ""
if apk_product and apk_product in APK_PRODUCT_HINTS:
    apk_hint = f"\n\n**{apk_product} 特性**：{APK_PRODUCT_HINTS[apk_product]}"
```

### 验收标准

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

---

## 阶段三：P1 更新 SKILL.md 路径

### 技术方案

**当前问题**：服务器部署时 SKILL.md 路径与开发环境不同。

**优化方案**：更新 `get_skill_md()` 函数，按优先级查找 SKILL.md。

### 实施步骤

- [ ] **步骤 1**：修改 `get_skill_md()` 函数，支持多路径查找：

```python
def get_skill_md():
    """加载 Troubleshoot SKILL.md — 按优先级查找"""
    global SKILL_MD
    if SKILL_MD is not None:
        return SKILL_MD

    # 路径优先级（部署环境 → 开发环境）
    skill_paths = [
        Path("/opt/troubleshoot/SKILL.md"),           # 部署环境
        SCRIPT_DIR.parent / "SKILL.md",               # 开发环境：code/SKILL.md
        SCRIPT_DIR.parent.parent / "SKILL.md",        # 备用：skills/Troubleshoot/SKILL.md
    ]

    for skill_file in skill_paths:
        if skill_file.exists():
            SKILL_MD = skill_file.read_text(encoding='utf-8')
            # 只保留排查套路部分（不包含 frontmatter）
            if '---' in SKILL_MD:
                parts = SKILL_MD.split('---', 2)
                if len(parts) >= 3:
                    SKILL_MD = parts[2].strip()
            print(f"加载 SKILL.md: {skill_file}")
            return SKILL_MD

    SKILL_MD = ""
    print("警告：未找到 SKILL.md")
    return SKILL_MD
```

### 验收标准

- [ ] 开发环境能正常加载 SKILL.md
- [ ] 部署环境（/opt/troubleshoot/SKILL.md）能正常加载
- [ ] AI 输出中引用 SKILL.md 中的排查套路

---

## 阶段四：P2 前端进度提示优化

### 技术方案

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

**优化方案**：分阶段显示进度。

### 实施步骤

- [ ] **步骤 1**：修改前端加载状态显示：

```html
<div class="loading" id="loading">
    <div class="spinner"></div>
    <span class="loading-text" id="loadingText">🔍 正在搜索历史案例...</span>
</div>
```

- [ ] **步骤 2**：动态更新进度文本：

```javascript
// 阶段一：搜索
document.getElementById('loadingText').textContent = '🔍 正在搜索历史案例...';
// 搜索完成后
document.getElementById('loadingText').textContent = '📋 找到 5 个相似案例，正在进行 AI 分析...';
// 完成后
document.getElementById('loadingText').textContent = '✅ 分析完成';
```

### 验收标准

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

---

## 阶段五：P3 APK 产品字段生效

### 技术方案

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

**优化方案**：已在阶段二（Prompt 增强）中一并实现。

### 实施步骤

- [x] 已在阶段二实现

### 验收标准

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

---

## 风险与应对

| 风险 | 应对 |
|------|------|
| 前端两阶段请求增加复杂度 | 保持代码简洁，封装为函数 |
| 排查域映射表可能不完整 | 后续根据实际使用反馈持续补充 |
| 部署时忘记上传 SKILL.md | 在部署脚本中增加检查步骤 |

---

## 执行记录

| 日期 | 内容 | 结果 | 备注 |
|------|------|------|------|
| 2026-07-11 | 创建计划执行文档 | ✅ 完成 | |
| 2026-07-11 | P0-P3 全部优化实施 | ✅ 完成 | server.py + index.html 全部更新 |
| 2026-07-11 | 同步更新到 Deploy-deploy 目录 | ✅ 完成 | 部署目录与开发目录保持一致 |

---

## 变更记录

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|----------|--------|
| 2026-07-11 | v1.0 | 初始版本 | Claude |
| 2026-07-11 | v1.1 | 全部 5 项优化实施完成 | Claude |
