# OTN-RCA-agent

**Repository Path**: sps1/OTN-RCA-agent

## Basic Information

- **Project Name**: OTN-RCA-agent
- **Description**: an agent for RCA in OTN
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2025-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OptiAgent - 光网络告警溯源和故障定位系统

## 📖 项目概述

OptiAgent是一个基于人工智能的光网络告警溯源和故障定位系统，采用先进的GraphRAG + Py2neo + Ollama架构，专门用于光通信网络的智能运维和故障诊断。系统结合知识图谱、语义搜索和机器学习技术，实现自动化故障根因分析。

### 🎯 核心特性

- **智能告警溯源**: 自动分析告警事件，追踪根本原因
- **知识图谱构建**: 基于Neo4j图数据库构建光网络专业知识库
- **混合搜索策略**: 结合关键词搜索、图遍历和语义相似度搜索
- **多类型实体支持**: 支持告警、节点、规则、术语、经验等多种实体类型
- **实时嵌入计算**: 使用Ollama进行实时向量嵌入生成和语义搜索
- **Web服务界面**: 提供现代化响应式前端，支持浏览器访问和交互式故障分析
- **LangGraph智能代理**: 基于LangGraph的告警溯源Agent，具备自主规划和推理能力

## 🏗️ 系统架构

```
OptiAgent Architecture:
┌─────────────────────────────────────────────────┐
│                 应用层 (Application)             │
│  ┌─────────────────────────────────────────────┐ │
│  │                主应用模块                  │ │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────────┐  │ │
│  │  │ 初始化  │→│ 告警溯源 │→│ 结果分析    │→ ... │ │
│  │  └─────────┘  └─────────┘  └─────────────┘  │ │
│  └─────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────┤
│                 服务层 (Services)               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
│  │ GraphRAG    │  │ 搜索引擎    │  │ 工具类   │ │
│  │ 知识库构建   │  │ (混合搜索)  │  │ (嵌入/LLM) │
│  └─────────────┘  └─────────────┘  └─────────┘ │
├─────────────────────────────────────────────────┤
│                 数据层 (Data)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────┐ │
│  │ 向量嵌入     │  │ 图数据库    │  │ 配置管理 │ │
│  │ (Ollama)    │  │ (Neo4j)     │  │ (Config)  │
│  └─────────────┘  └─────────────┘  └─────────┘ │
└─────────────────────────────────────────────────┘
```

## 📁 项目结构

```
optiagent/
├── core/                    # 核心数据模型
│   ├── __init__.py
│   ├── models.py           # Pydantic数据模型定义
│   └── reasoning_engine.py # 告警相关性推理引擎
├── knowledge_base/         # 知识图谱构建
│   ├── __init__.py
│   ├── graph_constructor.py # GraphRAG构建器 (主要实现)
│   └── docx_knowledge_builder.py # DOCX文档知识构建
├── rag/                    # 检索增强生成
│   ├── __init__.py
│   └── search_engine.py    # 混合搜索引擎 (主要实现)
├── utils/                  # 工具类
│   ├── embedding_utils.py  # 向量嵌入工具
│   ├── llm_utils.py       # LLM调用工具
│   └── docx_parser.py     # Word文档解析工具
├── data/                   # 数据目录
├── output/                 # 输出目录
├── file/                   # 文件处理模块（上传的文档存储）
├── api/                    # API接口模块
├── agents/                 # 智能代理模块
│   ├── __init__.py
│   ├── alarm_tracing_agent.py # OTN网络告警溯源Agent (主要实现)
│   └── deep_researcher.py     # 深度研究代理
├── prompts/                # 提示词模板模块
│   ├── __init__.py
│   └── alarm_tracing_prompts.py # 告警溯源提示词模板
├── workflows/              # 工作流模块
├── tests/                  # 测试模块
│   ├── __init__.py
│   └── test_alarm_tracing_agent.py # 告警溯源Agent测试
├── config.py              # 配置文件 (主要配置)
├── main.py                # 主应用入口 (主要实现)
├── main_docx_processor.py # DOCX文档处理器
├── check_relationships.py # 关系检查工具
├── debug_neo4j.py         # Neo4j调试工具
├── test_alarm_tracing.py  # 告警溯源测试
├── app_server.py          # Web服务主程序
├── start_server.py        # 服务启动脚本
├── test_web_service.py    # Web服务功能测试
├── service_manager.py     # 服务管理器
├── frontend/              # 前端文件目录
│   ├── index.html         # 主页面
│   ├── styles.css         # 样式文件
│   └── app.js             # 前端逻辑
├── demos/                 # 演示文件
├── optiagent.log          # 应用日志
└── README.md              # 项目说明
```

## 🚀 快速开始

### 环境要求

- Python 3.8+
- Neo4j 5.x (图数据库)
- Ollama (用于本地向量嵌入和LLM服务)
- Flask (用于Web服务)

### 安装依赖

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\\Scripts\\activate    # Windows

# 安装所有依赖
pip install -r requirements.txt
```

### 配置设置

编辑 `config.py` 文件配置数据库连接和模型服务：

```python
# Neo4j图数据库配置（必须）
NEO4J_CONFIG = {
    "host": "127.0.0.1",
    "user": "neo4j", 
    "password": "sun1484090753",
    "port": 7687,
    "secure": False
}

# Ollama配置（嵌入模型）
OLLAMA_CONFIG = {
    "api_base_url": "http://localhost:11434/api/embeddings",
    "model": "nomic-embed-text",
    "timeout": 30,
    "embedding_dim": 768
}

# LLM配置
LLM_CONFIG = {
    "api_base_url": "http://localhost:11434/api/generate",
    "model": "qwen3:8b",  # 更新为更现代的模型
    "timeout": 60,
    "max_tokens": 4096,
    "temperature": 0.1
}

# 应用配置
APP_CONFIG = {
    "embedding_dim": 768,
    "search_max_results": 10,
    "similarity_threshold": 0.7,
    "max_research_steps": 5,
    "llm_timeout": 60,
    "llm_max_retries": 3
}
```

## 🌐 Web服务模块

OptiAgent提供完整的Web服务界面，支持浏览器访问和交互式告警溯源分析。

### 启动Web服务

#### 方式一：使用启动脚本（推荐）
```bash
# 启动服务
python start_server.py

# 带参数启动
python start_server.py --port 8080 --host 0.0.0.0 --debug

# 跳过依赖检查
python start_server.py --skip-checks
```

#### 方式二：直接启动
```bash
python app_server.py

# 指定参数
python app_server.py --port 8080 --host 0.0.0.0 --debug
```

### Web服务功能特色

#### 📊 核心功能模块

**左侧面板 - 知识库文档处理**
- 🔄 Word文档上传（拖拽支持）
- 🛠️ 文档解析和知识图谱构建
- 📈 实时统计信息展示

**右侧面板 - 告警溯源分析**
- 📝 多行告警日志输入
- 🔍 多步骤溯源过程展示
- 📋 完整溯源结果呈现

#### 🌟 技术特性
- **响应式设计**：适配桌面和移动设备
- **实时状态监控**：服务状态和数据库连接监控
- **异步处理**：文件上传和溯源分析的异步处理
- **错误友好界面**：完整的错误处理和用户提示

### 接口文档

详细API接口说明请参考 [API_DOCUMENTATION.md](API_DOCUMENTATION.md)

#### 主要API接口

**服务状态检查**
```bash
GET /api/status
```

**文件上传接口**
```bash
POST /api/upload/docx
Content-Type: multipart/form-data

file: Word文档文件
```

**文档解析接口**
```bash
POST /api/process/docx
Content-Type: application/json

{
    "filename": "文档文件名.docx"
}
```

**告警溯源接口**
```bash
POST /api/trace/alarm
Content-Type: application/json

{
    "alarm_log": "告警日志内容",
    "max_steps": 5
}
```

**知识图谱统计**
```bash
GET /api/graph/stats
```

### 访问地址

- **服务首页**: http://localhost:5000
- **前端界面**: http://localhost:5000/frontend/
- **API状态**: http://localhost:5000/api/status

### 服务管理

- **优雅停止**: 通过POST请求 `/api/shutdown` 停止服务
- **依赖检查**: `start_server.py` 自动检查依赖环境
- **进程管理**: 支持信号处理和自动重启

## 🎯 功能模块详解

### 1. 核心数据模型 (core/models.py)

定义系统使用的所有数据模型：

- `NetworkNode`: 网络节点模型（OLT、ONU、SWITCH、ROUTER、SERVER）
- `NetworkLink`: 网络链路模型（FIBER、COPPER、WIRELESS）
- `AlarmSeverity`: 告警严重程度模型
- `AlarmType`: 告警类型模型
- `AlarmEvent`: 告警事件模型
- `AlarmCorrelationRule`: 告警关联规则模型
- `FaultLocalizationResult`: 故障定位结果模型
- `KnowledgeGraphEntity`: 知识图谱实体（ALARM、NODE、RULE、TERM、EXPERIENCE）
- `KnowledgeGraphRelation`: 知识图谱关系模型
- `SearchQuery`: 搜索查询模型（LOCAL、GLOBAL、HYBRID）
- `SearchResult`: 搜索结果模型
- `ResearchStep`: 研究步骤模型
- `TracingResult`: 溯源结果模型
- `AlarmLogBatch`: 告警日志批处理模型（新增）

### 2. GraphRAG知识库构建器 (knowledge_base/graph_constructor.py)

构建和维护光网络知识图谱，支持多种数据导入：

```python
from knowledge_base.graph_constructor import GraphRAGConstructor
from core.models import NetworkNode, NetworkLink, AlarmType, AlarmEvent

# 初始化知识库
kb = GraphRAGConstructor()

# 初始化基础结构
kb.initialize_knowledge_base()

# 导入网络拓扑数据
nodes = [NetworkNode(node_id="olt-01", node_name="OLT-01", node_type="OLT")]
links = [NetworkLink(link_id="link-1", source_node_id="olt-01", target_node_id="onu-01")]
kb.import_network_topology(nodes, links)

# 导入告警类型
alarm_types = [AlarmType(alarm_code="ALM-001", alarm_name="光功率异常")]
kb.import_alarm_types(alarm_types)

# 导入告警事件
alarm_events = [AlarmEvent(alarm_id="alarm-001", alarm_code="ALM-001", node_id="olt-01")]
kb.import_alarm_events(alarm_events)

# 获取图谱统计信息
stats = kb.get_graph_stats()
print(f"实体总数: {stats['total_entities']}, 关系总数: {stats['total_relations']}")
```

### 3. 混合搜索引擎 (rag/search_engine.py)

支持多种搜索模式：本地搜索、全局搜索和混合搜索：

```python
from rag.search_engine import GraphSearchEngine
from core.models import SearchQuery

# 初始化搜索引擎
search_engine = GraphSearchEngine(knowledge_base)

# 本地搜索（关键词+图结构）
query = SearchQuery(
    query_text="光功率异常",
    search_type="LOCAL",  # 关键词和图遍历搜索
    max_results=10
)
results = search_engine.search(query)

# 全局搜索（语义相似度）
query = SearchQuery(
    query_text="光功率异常",
    search_type="GLOBAL",  # 语义相似度搜索
    max_results=5
)
results = search_engine.search(query)

# 混合搜索（推荐使用）
query = SearchQuery(
    query_text="光功率异常",
    search_type="HYBRID",  # 结合本地和全局搜索
    max_results=10,
    filters={
        "entity_type": "ALARM",
        "severity": "MAJOR"
    }
)
results = search_engine.search(query)

# 按实体类型搜索
alarm_results = search_engine.search_by_entity_type("ALARM", "光功率")

# 获取相关实体
related_entities = search_engine.get_related_entities("entity-alarm-001", "OCCURS_ON")
```

### 4. 主应用模块 (main.py)

核心应用类，集成所有组件并提供完整的工作流：

```python
from main import OptiAgent, create_sample_alarm

# 创建应用实例
app = OptiAgent()

# 异步初始化（加载知识库数据）
await app.initialize()

# 创建示例告警
alarm = create_sample_alarm()

# 执行告警溯源
result = app.trace_alarm(alarm)

print(f"告警ID: {result.alarm_id}")
print(f"根因分析: {result.root_cause}")
print(f"置信度: {result.confidence_score}")
print(f"处理建议: {result.recommendations}")

# 批量处理告警
alarms = [create_sample_alarm() for _ in range(3)]
batch_results = app.batch_trace_alarms(alarms)

# 获取系统状态
status = app.get_system_status()
print(f"系统状态: {status}")
```

### 5. OTN网络告警溯源Agent (agents/alarm_tracing_agent.py)

基于LangGraph的OTN网络告警溯源智能代理，具备完整的告警溯源能力：

```python
from agents.alarm_tracing_agent import AlarmTracingAgent
from core.models import AlarmEvent

# 创建告警溯源Agent实例
agent = AlarmTracingAgent()

# 创建告警事件
alarm_event = AlarmEvent(
    alarm_id="alarm-otn-001",
    alarm_code="OTN-ALM-001", 
    alarm_type="OTN链路中断",
    node_id="otn-node-01",
    severity="CRITICAL",
    description="OTN链路信号丢失，影响业务传输",
    additional_info={"port": "1/0/1", "interface": "100GE"}
)

# 执行告警溯源
result = agent.trace_alarm(alarm_event, max_steps=5)

print(f"溯源结果: {result.root_cause}")
print(f"置信度: {result.confidence_score}")
print(f"推荐措施: {result.recommendations}")

# Agent的主要功能包括：
# 1. 规划能力：自动拆解多步骤处理计划
# 2. 工具调用：集成local/global搜索
# 3. 反思能力：自动检查结果合理性
# 4. 提示词链：多阶段提示词序列
# 5. 推理能力：多步逻辑推理
```

该Agent实现了以下核心能力：

#### 5.1 规划能力
- 自动分析告警日志，拆解为多步骤处理计划
- 每个步骤明确具体操作（如步骤1：提取告警日志中的关键信息；步骤2：调用local search查询历史告警关联数据等）
- 根据当前进展动态调整后续计划

#### 5.2 工具调用能力  
- 集成local search和global search搜索工具
- 调用config.py中配置的大模型进行自然语言处理
- 使用embedding模型进行告警文本的向量转换与相似性匹配

#### 5.3 反思能力
- 自动检查当前结果的合理性（是否匹配历史案例、逻辑是否自洽）
- 生成修正建议（如"当前检索到的关联告警时间跨度超过阈值，建议补充设备拓扑信息重新检索"）
- 基于建议优化下一轮操作

#### 5.4 提示词链能力
- 将告警溯源任务分解为多阶段：告警信息提取→检索条件生成→搜索结果解析→根因推理→报告生成
- 每个阶段使用专用提示词模板（提取阶段强调实体识别，推理阶段强调因果关系分析）
- 前一步输出作为后一步输入

#### 5.5 推理能力
- 基于告警日志、知识图谱数据及历史案例进行多步逻辑推理
- 分析告警间的时序关系及设备拓扑关联性
- 推断告警间的因果关系（如"A为B的触发源"）
- 处理不确定性信息（如"若告警C出现概率>70%，则优先纳入根因分析"）

### 6. 推理引擎模块 (core/reasoning_engine.py)

专门的告警相关性推理引擎，提供基于时序和拓扑关系的因果推理：

```python
from core.reasoning_engine import AlarmCorrelationReasoningEngine

# 创建推理引擎实例
engine = AlarmCorrelationReasoningEngine()

# 执行因果关系推理
reasoning_result = engine.perform_causal_reasoning(
    alarm_event=alarm,
    search_results=search_results,
    time_window_minutes=60
)

print(f"触发源: {reasoning_result['causal_inference']['primary_trigger']}")
print(f"传播路径: {reasoning_result['causal_inference']['propagation_path']}")
print(f"置信度: {reasoning_result['confidence_score']}")
```

### 7. 提示词模板模块 (prompts/alarm_tracing_prompts.py)

多阶段提示词序列，用于告警溯源任务的各个处理阶段：

```python
from prompts.alarm_tracing_prompts import AlarmTracingPrompts

# 获取信息提取阶段的提示词
extraction_prompt = AlarmTracingPrompts.get_extraction_prompt(alarm_event)

# 获取根因推理阶段的提示词
reasoning_prompt = AlarmTracingPrompts.get_root_cause_reasoning_prompt(
    alarm_event, analysis_data, search_context
)
```

### 8. Word文档解析 (utils/docx_parser.py)

支持华为告警文档的智能解析功能：

```python
from utils.docx_parser import parse_huawei_alarm_docx

# 解析Word文档
entities, relations = parse_huawei_alarm_docx("huawei_alarms.docx")

print(f"提取实体: {len(entities)} 个")
print(f"提取关系: {len(relations)} 个")
```

### 9. 工具类模块 (utils/)

提供向量嵌入和LLM调用功能：

```python
from utils.embedding_utils import get_embedding, cosine_similarity
from utils.llm_utils import call_llm

# 向量嵌入功能
text = "光功率异常故障"
embedding = get_embedding(text)
print(f"嵌入维度: {len(embedding)}")

# 相似度计算
similarity = cosine_similarity(embedding1, embedding2)
print(f"相似度: {similarity:.3f}")

# LLM调用
response = call_llm("分析光功率异常的可能原因")
print(f"LLM响应: {response}")
```

## 🎮 使用方法

### 单次告警溯源

```bash
# 运行主应用
python main.py

# 输出示例:
# 启动OptiAgent光网络告警溯源系统...
# 初始化OptiAgent应用组件...
# 开始异步初始化...
# 知识库样本数据加载完成
# 异步初始化完成
# 示例告警: alarm_id='alarm-20250101203045' alarm_code='ALM-001' ...
# 开始执行告警溯源工作流...
# 告警溯源完成: alarm-20250101203045
# 根因分析: 光纤连接问题导致光功率异常
# 置信度: 0.92
```

### 批量处理模式

```python
from main import OptiAgent, create_sample_alarms

# 初始化应用
app = OptiAgent()

# 创建批量告警
alarms = create_sample_alarms()

# 批量处理
results = app.batch_trace_alarms(alarms)

for i, result in enumerate(results):
    print(f"告警 {i+1}: {result.alarm_id}")
    print(f"  根因: {result.root_cause}")
    print(f"  置信度: {result.confidence_score}")
    print(f"  建议: {result.recommendations[:2]}")
```

### Web服务交互

```python
import requests

# 上传文档
with open('华为告警文档.docx', 'rb') as f:
    files = {'file': f}
    response = requests.post('http://localhost:5000/api/upload/docx', files=files)
    print(response.json())

# 执行告警溯源
data = {
    "alarm_log": "2024-01-15 10:30:25 [MAJOR] ALM-001 光功率异常",
    "max_steps": 5
}
response = requests.post('http://localhost:5000/api/trace/alarm', json=data)
print(response.json())
```

### 交互式调试

```bash
# 调试Neo4j连接
python debug_neo4j.py

# 检查知识库关系
python check_relationships.py

# 处理DOCX文档知识
python main_docx_processor.py

# 测试Web服务
python test_web_service.py
```

## 🔧 配置说明

### Neo4j数据库配置

1. **安装和启动Neo4j**:
   ```bash
   # 使用Docker运行Neo4j（推荐）
   docker run -d \
     --name neo4j \
     -p 7474:7474 -p 7687:7687 \
     -e NEO4J_AUTH=neo4j/sun1484090753 \
     -v neo4j_data:/data \
     neo4j:5.18
   
   # 或者使用Neo4j Desktop客户端
   # 下载地址: https://neo4j.com/download/
   ```

2. **验证连接**:
   ```bash
   # 浏览器访问: http://localhost:7474
   # 用户名: neo4j
   # 密码: sun1484090753
   
   # 测试连接
   python -c "
   from py2neo import Graph
   g = Graph('bolt://127.0.0.1:7687', auth=('neo4j', 'sun1484090753'))
   result = g.run('RETURN 1 AS test').data()
   print('Neo4j连接成功:', result)
   "
   ```

### Ollama配置

1. **安装和启动Ollama**:
   ```bash
   # 下载安装Ollama
   # 地址: https://ollama.ai/download
   
   # 启动Ollama服务
   ollama serve
   
   # 安装嵌入模型
   ollama pull nomic-embed-text
   
   # 安装LLM模型（推荐）
   ollama pull qwen3:8b
   ```

2. **验证Ollama**:
   ```bash
   # 测试嵌入服务
   curl http://localhost:11434/api/embeddings -d '{
     "model": "nomic-embed-text",
     "prompt": "测试文本"
   }'
   
   # 测试生成服务
   curl http://localhost:11434/api/generate -d '{
     "model": "qwen3:8b", 
     "prompt": "你好"
   }'
   ```

## 🧪 测试验证

### 运行功能测试

```bash
# 测试主应用流程
python main.py

# 测试知识库功能
python -c "
from knowledge_base.graph_constructor import GraphRAGConstructor
kb = GraphRAGConstructor()
kb.initialize_knowledge_base()
stats = kb.get_graph_stats()
print(f'知识库统计: {stats}')
"

# 测试搜索功能  
python -c "
from rag.search_engine import GraphSearchEngine
from knowledge_base.graph_constructor import GraphRAGConstructor
from core.models import SearchQuery

kb = GraphRAGConstructor()
search_engine = GraphSearchEngine(kb)

query = SearchQuery(query_text='光功率异常', search_type='HYBRID')
results = search_engine.search(query)
print(f'搜索完成: {len(results)} 个结果')
for result in results[:3]:
    print(f'  - {result.entity.entity_id}: {result.score:.3f}')
"

# 测试告警溯源
python test_alarm_tracing.py

# 测试Web服务功能（确保服务已启动）
python test_web_service.py

# 测试连接性
python test_connectivity.py

# 集成测试
python test_main_integration.py
```

### 验证测试结果

测试成功后应该看到：

```
✅ Neo4j连接成功
✅ 知识库初始化成功  
✅ 搜索功能正常
✅ 告警溯源流程正常
✅ 结果输出格式正确
✅ Web服务接口正常
```

## 📊 性能指标

系统设计性能目标：

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 单次溯源时间 | < 30秒 | 从告警输入到结果输出 |
| 知识库实体数 | 10,000+ | 支持大规模知识图谱 |
| 搜索响应时间 | < 2秒 | 混合搜索性能 |
| 向量嵌入维度 | 768 | nomic-embed-text模型 |
| 结果置信度 | > 0.8 | 高可靠性输出 |
| Web API响应 | < 1秒 | API接口响应时间 |
| 文件上传速度 | < 30秒 | 支持大文件上传 |

## 🔍 故障排查

### 常见问题

1. **Ollama连接失败**
   ```bash
   # 检查Ollama服务是否运行
   curl http://localhost:11434/api/tags
   
   # 安装nomic-embed-text模型
   ollama pull nomic-embed-text
   
   # 检查模型是否已安装
   ollama list
   ```

2. **Neo4j连接失败**
   ```bash
   # 检查Neo4j服务是否运行
   docker ps | grep neo4j
   
   # 检查端口是否开放
   netstat -tlnp | grep 7687
   
   # 测试连接
   python -c "
   from py2neo import Graph
   try:
       g = Graph('bolt://127.0.0.1:7687', auth=('neo4j', 'sun1484090753'))
       result = g.run('RETURN 1 AS test').data()
       print('✅ Neo4j连接成功:', result)
   except Exception as e:
       print(f'❌ Neo4j连接失败: {e}')
   "
   ```

3. **知识库初始化失败**
   ```bash
   # 检查Neo4j约束
   python -c "
   from knowledge_base.graph_constructor import GraphRAGConstructor
   kb = GraphRAGConstructor()
   kb._initialize_neo4j_constraints()
   print('Neo4j约束初始化完成')
   "
   ```

4. **向量嵌入生成失败**
   ```python
   # 在 config.py 中调整超时时间
   OLLAMA_CONFIG['timeout'] = 60  # 增加到60秒
   
   # 检查Ollama服务状态
   curl http://localhost:11434/api/embeddings -d '{"model": "nomic-embed-text", "prompt": "test"}'
   ```

5. **Web服务启动失败**
   ```bash
   # 检查端口占用
   netstat -tlnp | grep 5000
   
   # 检查Flask依赖
   pip list | grep Flask
   
   # 手动启动并查看错误
   python -m flask run --port 5000
   ```

### 日志查看

```bash
# 查看应用日志
tail -f optiagent.log

# 查看Web服务日志
tail -f optiagent.log

# 查看详细调试信息
export LOG_LEVEL=DEBUG
python main.py
```

### 前端调试

```bash
# 检查前端目录
ls frontend/

# 检查静态资源
python -c "from app_server import app; print(app.static_folder)"

# 测试API连接
curl http://localhost:5000/api/status
```

## 📈 扩展开发

### 添加新的实体类型

1. 在 `core/models.py` 中定义新实体类型
2. 在 `knowledge_base/graph_constructor.py` 中添加导入和处理逻辑
3. 在 `rag/search_engine.py` 中更新搜索和过滤逻辑
4. 在 `_generate_search_text()` 方法中添加新类型的文本生成逻辑

### 集成新的LLM/嵌入服务

1. 在 `utils/llm_utils.py` 中添加新的服务客户端
2. 在 `utils/embedding_utils.py` 中更新嵌入生成逻辑
3. 在 `config.py` 中配置新的服务参数

### 自定义搜索策略

1. 修改 `rag/search_engine.py` 中的搜索算法
2. 调整混合搜索的权重参数
3. 添加新的过滤器类型和支持

### 数据导入扩展

1. 支持更多数据格式导入（JSON、CSV、XML等）
2. 添加实时数据流处理
3. 支持外部系统集成（网管系统、监控平台）

### 扩展告警溯源Agent功能

1. 在 `agents/alarm_tracing_agent.py` 中添加新的处理步骤
2. 在 `prompts/alarm_tracing_prompts.py` 中定义新的提示词模板
3. 在 `core/reasoning_engine.py` 中扩展推理逻辑
4. 在 `tests/test_alarm_tracing_agent.py` 中添加新功能的测试

### 前端功能扩展

1. 在 `frontend/` 目录中添加新的UI组件
2. 扩展 `app.js` 中的前端逻辑
3. 添加新的API接口调用

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启Pull Request

### 开发环境设置

```bash
# 克隆项目
git clone <repository-url>
cd optiagent

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate    # Windows

# 安装开发依赖
pip install -r requirements.txt

# 创建开发分支
git checkout -b feature/my-feature
```

### 代码标准

- 遵循PEP 8 Python代码风格
- 使用类型提示
- 编写单元测试
- 更新文档

## 🏆 致谢

- [Py2neo](https://py2neo.org/) - Neo4j Python驱动
- [Ollama](https://ollama.ai/) - 本地模型服务
- [Pydantic](https://pydantic-docs.helpmanual.io/) - 数据验证和设置管理
- [Neo4j](https://neo4j.com/) - 图数据库
- [Flask](https://flask.palletsprojects.com/) - Web框架
- [LangGraph](https://langchain-ai.github.io/langgraph/) - 智能代理框架
- [Python-Docx](https://python-docx.readthedocs.io/) - Word文档处理

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持

如有问题或建议，请检查以下资源：

1. 查看项目日志: `tail -f optiagent.log`
2. 测试Neo4j连接: `python debug_neo4j.py`
3. 检查系统状态: 在main.py中调用 `get_system_status()`
4. 参考API文档: [API_DOCUMENTATION.md](API_DOCUMENTATION.md)

或者联系维护团队获取技术支持。

---

**OptiAgent** - 让光网络运维更智能！ 🌐✨