# 问题排查分析助手 (Troubleshoot AI Assistant)

> 本目录包含问题排查分析助手的所有相关代码、文档和配置文件

## 目录结构

```
troubleshoot-ai-assistant/
├── skill/                 # Claude Skill 代码
│   ├── SKILL.md           # Skill 定义文件
│   └── code/              # 核心代码
│       ├── web/           # Web服务代码（唯一源）
│       │   ├── server.py          # Flask服务器主程序
│       │   ├── search_engine.py   # 搜索引擎
│       │   ├── cache_manager.py   # 缓存管理
│       │   ├── auth.py            # 认证模块
│       │   ├── safety_filter.py   # 安全过滤
│       │   └── templates/         # HTML模板
│       ├── xlsx_to_md.py          # Excel转Markdown工具
│       ├── build_index.py         # 索引构建工具
│       ├── requirements.txt       # Python依赖
│       └── start.bat              # Windows启动脚本
│
├── deploy/                # 部署相关文件
│   ├── deploy.sh          # Linux部署脚本（从 skill/code/web/ 复制）
│   ├── 问题记录/          # 问题知识库（日常+项目）
│   ├── upload_to_server.py # 上传工具
│   ├── check_service.py   # 服务检查脚本
│   └── verify_deployment.py # 验证脚本
│
├── docs/                  # PRD文档
│   ├── PRD_需求文档_问题知识库智能排查助手.md
│   ├── PRD_需求文档_问题排查助手性能与功能优化.md
│   ├── PRD_需求文档_问题排查助手流式返回优化.md
│   ├── _PRD_Troubleshoot助手登录认证_需求文档.md
│   ├── _PRD_Troubleshoot助手功能优化_需求文档.md
│   ├── 技术实现文档_问题排查助手Web服务.md
│   ├── 部署指南_问题排查助手Web服务.md
│   └── 用户使用手册_问题排查助手.md
│
├── config/                # 配置文件
│   ├── troubleshoot.service  # systemd服务定义
│   └── troubleshoot-data.zip # 数据压缩包（如有）
│
├── .env.example           # 环境变量模板
├── .gitignore             # Git忽略配置
└── README.md              # 本说明文件
```

## 功能概述

问题排查分析助手是一个基于AI的智能问题分析工具，主要功能包括：

1. **智能搜索** - 通过关键词搜索问题知识库
2. **AI分析** - 使用Claude API进行问题分析和解决方案推荐
3. **流式返回** - 支持实时流式输出分析结果
4. **登录认证** - 用户认证和权限管理
5. **缓存管理** - 搜索结果缓存优化性能

## 快速使用

### Claude Skill调用

在Claude Code中使用 `/Troubleshoot` 命令调用此助手。

### Web服务部署

```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写实际配置

# 2. 安装依赖
pip install -r skill/code/requirements.txt

# 3. 启动服务
python skill/code/web/server.py

# Linux systemd部署
sudo cp config/troubleshoot.service /etc/systemd/system/
sudo systemctl enable troubleshoot
sudo systemctl start troubleshoot
```

## 环境变量配置

| 变量名 | 说明 | 必填 |
|--------|------|------|
| `SSH_HOST` | SSH服务器地址 | 否（测试用） |
| `SSH_USER` | SSH用户名 | 否（测试用） |
| `SSH_PASSWORD` | SSH密码 | 否（测试用） |
| `SECRET_KEY` | Flask Session密钥 | 是（生产环境） |
| `CLAUDE_API_BASE` | Claude API地址 | 是 |
| `CLAUDE_API_KEY` | Claude API密钥 | 是 |

## 相关链接

- [技术实现文档](docs/技术实现文档_问题排查助手Web服务.md)
- [部署指南](docs/部署指南_问题排查助手Web服务.md)
- [用户使用手册](docs/用户使用手册_问题排查助手.md)

## 迁移记录

本目录于 2026-07-12 从原仓库分散位置迁移至此统一目录结构：

- 原位置: `.claude/skills/Troubleshoot/` → 新位置: `skill/`
- 原位置: `Troubleshoot-deploy/` → 新位置: `deploy/`
- 原位置: `Docs/PRD/问题知识库/` → 新位置: `docs/`
- 原位置: `troubleshoot.service` → 新位置: `config/`

## 代码规范

- **单一数据源**: `skill/code/web/` 是唯一开发目录，`deploy/web/` 已删除
- **部署方式**: 通过 `deploy/deploy.sh` 从 `skill/code/web/` 复制文件
- **敏感信息**: 使用环境变量，禁止硬编码密码