first commit

AIEC-server/docs/troubleshooting-graph-rag.md

@@ -0,0 +1,97 @@
+# Graph-RAG-Agent 集成问题排查
+
+## 已完成的修改
+
+1. **chat-service.js 已修改**：
+   - 服务地址改为 `http://localhost:8000`
+   - API 接口路径已更新（`/qa/ask` → `/chat`）
+   - 请求/响应格式已适配
+   - 移除了强制的认证要求
+
+2. **修复了递归调用问题**：
+   - main.js 中的事件监听器不再导致递归
+
+## 当前问题及解决方案
+
+### 问题1：ChatAPIService 未定义
+**症状**：`Cannot read properties of undefined (reading 'sendMessageStream')`
+
+**可能原因**：
+1. 脚本加载顺序问题
+2. 认证相关的依赖未满足
+3. CORS 跨域问题
+
+**解决步骤**：
+1. 确保 graph-rag-agent 服务正在运行：
+   ```bash
+   cd ~/graph-rag-agent
+   python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+   ```
+
+2. 使用本地 HTTP 服务器访问前端（避免 file:// 协议的限制）：
+   ```bash
+   cd ~/yundage-backserver-test
+   ./start-local.sh
+   ```
+
+3. 访问测试页面验证 API：
+   ```
+   http://localhost:3000/test-graph-rag.html
+   ```
+
+### 问题2：认证依赖
+**症状**：TokenManager 相关错误
+
+**解决方案**：
+- chat-service.js 已修改为可选的 TokenManager 依赖
+- 如果不需要认证，可以直接使用
+
+### 测试步骤
+
+1. **验证 graph-rag-agent 服务**：
+   ```bash
+   curl http://localhost:8000/
+   ```
+
+2. **测试同步 API**：
+   ```bash
+   curl -X POST http://localhost:8000/chat \
+     -H "Content-Type: application/json" \
+     -d '{
+       "message": "什么是数字化转型？",
+       "session_id": "test_123",
+       "agent_type": "naive_rag_agent",
+       "debug": false
+     }'
+   ```
+
+3. **使用测试页面**：
+   - 打开 `http://localhost:3000/test-graph-rag.html`
+   - 测试服务状态、同步消息和流式消息
+
+## 注意事项
+
+1. **CORS 配置**：graph-rag-agent 需要允许来自前端的跨域请求（localhost:3000 或 file://）
+2. **Neo4j 依赖**：确保 Neo4j 数据库正在运行并包含必要的数据
+3. **会话管理**：当前实现依赖浏览器本地存储
+
+## 快速启动命令
+
+```bash
+# 终端1：启动 graph-rag-agent（Python后端）
+cd ~/graph-rag-agent
+python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+
+# 终端2：启动前端服务器（可选，用于避免CORS问题）
+cd ~/yundage-backserver-test
+./start-local.sh
+
+# 访问：http://localhost:3000
+# 或者直接用浏览器打开 index.html 文件
+```
+
+## 端口说明
+
+- **8000**: graph-rag-agent (Python FastAPI 后端)
+- **8080**: 原 Java 后端（现在不使用）
+- **3000**: 前端静态文件服务器（可选）