first commit

AIEC-server/docs/API接口测试文档.md

@@ -0,0 +1,274 @@
+# 云大阁聊天系统 - API接口测试文档
+
+## 文档信息
+- 版本：1.0.0
+- 日期：2025-07-20
+- 测试环境：
+  - 前端：http://localhost:3000
+  - 后端：http://localhost:8080
+
+## 测试账号
+- 测试手机号：18362903328（或您的手机号）
+- 开发模式验证码：123456
+
+---
+
+## 一、认证模块测试
+
+### 1.1 发送验证码
+**接口地址**: `POST /api/auth/send-code`
+
+**测试步骤**:
+- [ ] 访问注册/登录页面
+- [ ] 输入手机号/邮箱
+- [ ] 点击"发送验证码"按钮
+
+**预期结果**:
+- [ ] 按钮显示倒计时60秒
+- [ ] 控制台显示验证码（开发模式）
+- [ ] 响应状态码：200
+
+**测试数据**:
+```json
+请求：
+{
+    "contact": "18362903328"
+}
+
+响应：
+{
+    "code": 200,
+    "message": "验证码已发送",
+    "data": {
+        "code": "123456"  // 开发模式返回
+    }
+}
+```
+
+### 1.2 用户注册
+**接口地址**: `POST /api/auth/register`
+
+**测试步骤**:
+- [ ] 访问注册页面
+- [ ] 输入用户名、手机号/邮箱
+- [ ] 输入验证码（123456）
+- [ ] 点击"注册"按钮
+
+**预期结果**:
+- [ ] 注册成功，自动跳转到首页
+- [ ] 本地存储token
+- [ ] 响应状态码：200
+
+**测试数据**:
+```json
+请求：
+{
+    "username": "testuser",
+    "phone": "18362903328",
+    "code": "123456"
+}
+
+响应：
+{
+    "code": 200,
+    "data": {
+        "token": "eyJhbGciOiJIUzI1NiJ9...",
+        "type": "Bearer",
+        "id": 2,
+        "username": "testuser",
+        "phone": "18362903328",
+        "email": null
+    }
+}
+```
+
+### 1.3 用户登录
+**接口地址**: `POST /api/auth/login`
+
+**测试步骤**:
+- [ ] 访问登录页面
+- [ ] 输入手机号/邮箱
+- [ ] 输入验证码（123456）
+- [ ] 点击"登录"按钮
+
+**预期结果**:
+- [ ] 登录成功，跳转到首页
+- [ ] 显示用户信息
+- [ ] 本地存储token
+
+**测试数据**:
+```json
+请求：
+{
+    "contact": "18362903328",
+    "code": "123456"
+}
+
+响应：同注册响应
+```
+
+---
+
+## 二、聊天模块测试
+
+### 2.1 发送消息（同步模式）
+**接口地址**: `POST /qa/ask`
+
+**测试步骤**:
+- [ ] 登录后在首页输入消息
+- [ ] 点击发送按钮
+- [ ] 等待AI回复
+
+**预期结果**:
+- [ ] 用户消息立即显示
+- [ ] AI回复完整显示
+- [ ] 新会话添加到侧边栏
+
+**测试数据**:
+```json
+请求：
+{
+    "mode": "chat",
+    "conversationId": null,  // 新会话
+    "message": "你好"
+}
+
+响应：
+{
+    "success": true,
+    "conversationId": "37",
+    "messageId": "75",
+    "answer": "你好！很高兴见到你...",
+    "tokensUsed": 100,
+    "timeMs": 2000
+}
+```
+
+### 2.2 发送消息（流式模式）
+**接口地址**: `POST /qa/ask/stream`
+
+**测试步骤**:
+- [ ] 发送较长的问题
+- [ ] 观察AI回复是否逐字显示
+
+**预期结果**:
+- [ ] AI回复实时流式显示
+- [ ] 显示打字效果
+- [ ] 完成后保存完整消息
+
+**SSE事件流**:
+```
+event: message
+data: {"type":"content","content":"你好","finished":false}
+
+event: message
+data: {"type":"content","content":"！","finished":false}
+
+event: finished
+data: {"type":"finished","conversationId":"37","messageId":"76","tokensUsed":150,"timeMs":3000,"finished":true}
+```
+
+### 2.3 深度检索模式
+**测试步骤**:
+- [ ] 点击"深度检索"按钮激活
+- [ ] 发送需要详细分析的问题
+- [ ] 检查是否返回引用资料
+
+**预期结果**:
+- [ ] 按钮高亮显示
+- [ ] 回复包含引用资料（research模式）
+
+---
+
+## 三、会话管理测试
+
+### 3.1 获取会话列表
+**接口地址**: `GET /qa/conversations`
+
+**测试步骤**:
+- [ ] 刷新页面
+- [ ] 检查侧边栏会话列表
+
+**预期结果**:
+- [ ] 显示所有历史会话
+- [ ] 按时间倒序排列
+
+**响应示例**:
+```json
+{
+    "code": 200,
+    "data": [
+        {
+            "id": 37,
+            "userId": 2,
+            "title": "你好",
+            "mode": "chat",
+            "createdAt": "2025-07-20T18:33:38",
+            "updatedAt": "2025-07-20T18:33:39"
+        }
+    ]
+}
+```
+
+### 3.2 获取会话消息
+**接口地址**: `GET /qa/conversations/{id}/messages`
+
+**测试步骤**:
+- [ ] 点击侧边栏的历史会话
+- [ ] 观察聊天窗口内容
+
+**预期结果**:
+- [ ] 正确加载历史消息
+- [ ] 保持消息顺序
+- [ ] 滚动到最新消息
+
+**响应示例**:
+```json
+{
+    "code": 200,
+    "data": [
+        {
+            "id": 74,
+            "conversationId": 37,
+            "sequence": 1,
+            "role": "user",
+            "content": "你好",
+            "createdAt": "2025-07-20T18:33:38"
+        },
+        {
+            "id": 75,
+            "conversationId": 37,
+            "sequence": 2,
+            "role": "assistant",
+            "content": "你好！很高兴见到你...",
+            "createdAt": "2025-07-20T18:33:39"
+        }
+    ]
+}
+```
+
+### 3.3 新建会话
+**测试步骤**:
+- [ ] 点击"新建对话"按钮
+- [ ] 发送第一条消息
+- [ ] 检查会话创建
+
+**预期结果**:
+- [ ] 清空当前聊天窗口
+- [ ] 发送消息后创建新会话
+- [ ] 新会话出现在侧边栏顶部
+
+---
+
+
+## 测试总结
+
+### 通过的测试项
+- [ ] 认证模块 (3/4)
+- [ ] 聊天模块 (3/3)
+- [ ] 会话管理 (3/3)
+
+
+**测试人员**：江争达  
+**测试日期**：2025-07-20  
+**签名**：_______________

AIEC-server/docs/API接口测试文档.mdZone.Identifier

@@ -0,0 +1,2 @@
+[ZoneTransfer]
+ZoneId=3

AIEC-server/docs/backend-security-config-solution.md

@@ -0,0 +1,96 @@
+# 后端权限配置解决方案
+
+## 问题描述
+当前 `/api/users/me` 接口返回 403 Forbidden 错误，原因是 Spring Security 配置中没有明确指定该路径的权限规则。
+
+## 解决方案
+
+### 方案一：在 SecurityConfig 中添加用户API权限配置（推荐）
+
+在 `SecurityConfig.java` 的 `filterChain` 方法中，添加用户相关API的权限配置：
+
+```java
+.authorizeHttpRequests(authz -> authz
+    // ... 其他配置
+    
+    // 用户相关接口需认证
+    .requestMatchers("/api/users/**").authenticated()
+    
+    // 聊天相关接口需认证
+    .requestMatchers("/qa/**").authenticated()
+    
+    // 所有其他请求需认证
+    .anyRequest().authenticated()
+)
+```
+
+### 方案二：实现 /api/users/me 接口
+
+在 `UserController.java` 中添加获取当前用户信息的接口：
+
+```java
+@GetMapping("/me")
+@Operation(summary = "获取当前用户信息", description = "获取当前登录用户的详细信息")
+@ApiResponse(responseCode = "200", description = "成功获取用户信息")
+public ResponseResult<User> getCurrentUser(Authentication authentication) {
+    String username = authentication.getName();
+    User user = userMapper.selectOneByUsername(username);
+    
+    if (user == null) {
+        return ResponseResult.error("用户不存在");
+    }
+    
+    // 隐藏敏感信息
+    user.setPassword(null);
+    
+    return ResponseResult.success(user);
+}
+```
+
+### 方案三：使用 @PreAuthorize 注解（细粒度控制）
+
+如果需要更细粒度的权限控制，可以在控制器方法上使用 @PreAuthorize：
+
+```java
+@GetMapping("/me")
+@PreAuthorize("isAuthenticated()")
+public ResponseResult<User> getCurrentUser() {
+    // 实现代码
+}
+```
+
+## 前端降级方案（已实现）
+
+前端已经实现了智能降级方案：
+
+1. **首选方案**：调用 `/api/users/me` 获取最新用户信息
+2. **降级方案**：如果接口返回 403 或其他错误，使用本地缓存的用户信息
+3. **用户体验**：提供手动刷新按钮，让用户可以尝试更新信息
+
+## 建议步骤
+
+1. **短期方案**：先使用方案一，在 SecurityConfig 中配置权限规则
+2. **长期方案**：实现方案二，完善用户信息获取接口
+3. **测试验证**：使用前端测试程序验证接口是否正常工作
+
+## 安全考虑
+
+1. 确保 `/api/users/me` 只返回当前登录用户的信息
+2. 隐藏敏感字段（如密码、salt等）
+3. 考虑添加响应缓存，减少数据库查询
+4. 记录访问日志，监控异常访问
+
+## 测试命令
+
+修改后端配置后，可以使用以下命令测试：
+
+```bash
+# 获取token（先登录）
+curl -X POST http://localhost:8080/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"contact":"18362903328","code":"123456"}'
+
+# 使用token访问用户信息
+curl -X GET http://localhost:8080/api/users/me \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE"
+```

AIEC-server/docs/backend-security-config-solution.mdZone.Identifier

@@ -0,0 +1,2 @@
+[ZoneTransfer]
+ZoneId=3

AIEC-server/docs/connection-reset-fix.md

@@ -0,0 +1,117 @@
+# 连接重置问题解决方案
+
+## 问题描述
+
+- OPTIONS 请求成功（200 OK）
+- POST 请求失败（ERR_CONNECTION_RESET）
+
+这表明 CORS 配置已经生效，但是实际处理请求时服务崩溃了。
+
+## 可能的原因和解决方案
+
+### 1. 检查 Neo4j 数据库
+
+graph-rag-agent 需要 Neo4j 数据库运行：
+
+```bash
+# 检查 Neo4j 是否运行
+sudo systemctl status neo4j
+
+# 如果未运行，启动它
+sudo systemctl start neo4j
+
+# 或使用 Docker
+docker ps | grep neo4j
+```
+
+### 2. 检查 graph-rag-agent 的配置
+
+确保配置文件存在：
+```bash
+cd ~/graph-rag-agent
+ls -la config/
+# 应该有 settings.py 或类似的配置文件
+```
+
+### 3. 查看 graph-rag-agent 的错误日志
+
+在运行 graph-rag-agent 的终端中查看错误信息。常见错误：
+
+- **Neo4j 连接失败**：
+  ```
+  neo4j.exceptions.ServiceUnavailable: Unable to connect to localhost:7687
+  ```
+  解决：启动 Neo4j 数据库
+
+- **缺少 embedding 模型**：
+  ```
+  FileNotFoundError: [Errno 2] No such file or directory: 'path/to/embeddings'
+  ```
+  解决：确保已下载并配置了 embedding 模型
+
+- **Agent 初始化失败**：
+  ```
+  KeyError: 'naive_rag_agent'
+  ```
+  解决：检查 agent 配置和初始化
+
+### 4. 简化测试
+
+创建一个最小测试来确认服务基本功能：
+
+```bash
+# 测试根路径
+curl http://localhost:8000/
+
+# 测试文档
+curl http://localhost:8000/docs
+```
+
+### 5. 环境变量检查
+
+graph-rag-agent 可能需要某些环境变量：
+
+```bash
+# 检查是否需要 OpenAI API Key
+export OPENAI_API_KEY="your-key-here"
+
+# 检查 Neo4j 连接配置
+export NEO4J_URI="bolt://localhost:7687"
+export NEO4J_USER="neo4j"
+export NEO4J_PASSWORD="your-password"
+```
+
+### 6. 依赖检查
+
+确保所有依赖都已安装：
+
+```bash
+cd ~/graph-rag-agent
+pip install -r requirements.txt
+```
+
+### 7. 使用调试模式启动
+
+```bash
+cd ~/graph-rag-agent
+python -m uvicorn server.main:app --reload --log-level debug
+```
+
+## 临时解决方案
+
+如果上述方法都不能解决问题，可以：
+
+1. **使用模拟响应**：在前端创建一个模拟的响应来测试前端功能
+2. **检查 graph-rag-agent 的 README**：查看是否有特殊的启动要求
+3. **查看 graph-rag-agent 的测试代码**：了解正确的使用方式
+
+## 测试命令
+
+使用提供的测试脚本：
+
+```bash
+cd ~/yundage-backserver-test
+./test-curl.sh
+```
+
+观察输出，特别是错误信息。

AIEC-server/docs/cors-solution.md

@@ -0,0 +1,80 @@
+# CORS 问题解决方案
+
+## 问题描述
+
+当前端（运行在 localhost:3000）尝试访问 graph-rag-agent（运行在 localhost:8000）时，浏览器会阻止请求，因为违反了同源策略。
+
+错误信息：
+```
+Access to fetch at 'http://localhost:8000/chat/stream' from origin 'http://localhost:3000' has been blocked by CORS policy
+```
+
+## 解决方案
+
+### 方案1：修改 graph-rag-agent 的 CORS 配置（推荐）
+
+我已经修改了 `/home/jzhengda/graph-rag-agent/server/main.py`，添加了 CORS 中间件：
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # 允许所有源
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+**使用方法**：
+1. 重启 graph-rag-agent 服务：
+   ```bash
+   cd ~/graph-rag-agent
+   # 先停止现有服务 (Ctrl+C)
+   # 然后重新启动
+   python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+   ```
+
+### 方案2：使用更安全的 CORS 配置
+
+如果需要更安全的配置，可以使用 `main_cors_specific.py`，它只允许特定的源：
+
+```bash
+cd ~/graph-rag-agent/server
+python -m uvicorn main_cors_specific:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 方案3：使用浏览器插件（临时测试）
+
+安装浏览器 CORS 插件（如 "CORS Unblock" 或 "Allow CORS"），仅用于开发测试。
+
+### 方案4：配置反向代理
+
+创建一个简单的反向代理，将前端和后端都代理到同一个端口下。
+
+## 验证 CORS 配置是否生效
+
+1. 重启 graph-rag-agent 后，访问测试页面：
+   ```
+   http://localhost:3000/test-graph-rag.html
+   ```
+
+2. 或使用 curl 测试：
+   ```bash
+   curl -I -X OPTIONS http://localhost:8000/chat \
+     -H "Origin: http://localhost:3000" \
+     -H "Access-Control-Request-Method: POST"
+   ```
+
+   应该看到响应头中包含：
+   ```
+   Access-Control-Allow-Origin: *
+   Access-Control-Allow-Methods: *
+   ```
+
+## 注意事项
+
+1. **生产环境**：不要使用 `allow_origins=["*"]`，应该指定具体的允许域名
+2. **开发环境**：当前配置允许所有源，方便开发测试
+3. **SSE（服务器发送事件）**：流式响应需要特别注意 CORS 配置

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

@@ -0,0 +1,104 @@
+# Graph-RAG-Agent 集成说明
+
+## 修改概述
+
+本次修改将 yundage-backserver-test 前端从调用原有的 Java 后端（localhost:8080）改为调用 graph-rag-agent 的 FastAPI 后端（localhost:8000），使用 naive_search_tool 进行问答。
+
+## 主要修改
+
+### 1. chat-service.js 修改
+
+修改文件：`/services/api/chat-service.js`
+
+#### 基础配置修改
+- **服务地址**：从 `http://localhost:8080` 改为 `http://localhost:8000`
+- **会话管理**：添加了会话ID生成功能，因为 graph-rag-agent 需要 session_id
+
+#### API 接口映射
+
+| 原接口 (Java) | 新接口 (graph-rag-agent) | 说明 |
+|--------------|-------------------------|------|
+| POST `/qa/ask` | POST `/chat` | 同步问答接口 |
+| POST `/qa/ask/stream` | POST `/chat/stream` | 流式问答接口 |
+| GET `/qa/conversations` | 本地存储 | graph-rag-agent 无此接口，改为从 localStorage 读取 |
+| GET `/qa/conversations/{id}/messages` | 本地存储 | 同上 |
+
+#### 请求参数转换
+
+**原请求格式**：
+```json
+{
+    "mode": "chat",
+    "conversationId": null,
+    "message": "用户消息"
+}
+```
+
+**新请求格式**：
+```json
+{
+    "message": "用户消息",
+    "session_id": "生成的会话ID",
+    "debug": false,
+    "agent_type": "naive_rag_agent",
+    "use_deeper_tool": false,
+    "show_thinking": false
+}
+```
+
+#### 响应格式适配
+
+由于前端期望特定的响应格式，在 `sendMessage` 方法中进行了格式转换：
+
+```javascript
+// 转换响应格式以适配前端
+return {
+    code: 200,
+    data: {
+        conversationId: messageData.conversationId || this.sessionId,
+        messageId: Date.now().toString(),
+        content: response.answer,
+        reference: response.reference,
+        kg_data: response.kg_data
+    },
+    message: '成功'
+};
+```
+
+#### 流式响应处理
+
+graph-rag-agent 的流式响应格式与原后端不同，主要修改：
+- 解析 SSE 数据格式从 `event:` + `data:` 改为直接解析 `data:`
+- 处理不同的状态类型：`start`、`token`、`done`、`error`
+- 累积完整内容并在完成时返回
+
+### 2. 新增功能
+
+- **generateSessionId()**：生成唯一的会话ID
+- **clearConversation()**：调用 graph-rag-agent 的 `/clear` 接口清除会话历史
+
+### 3. 本地存储集成
+
+由于 graph-rag-agent 不提供会话列表和历史消息接口，修改为：
+- 从 `window.chatManager` 读取本地存储的会话数据
+- 保持与原有前端逻辑的兼容性
+
+## 使用说明
+
+1. 确保 graph-rag-agent 服务运行在 `http://localhost:8000`
+2. 确保 Neo4j 数据库已启动并包含必要的数据
+3. 前端会自动使用 `naive_rag_agent` 进行问答
+4. 会话历史保存在浏览器本地存储中
+
+## 注意事项
+
+1. **认证**：graph-rag-agent 可能不需要 JWT 认证，但代码中保留了 Authorization header 以备后用
+2. **会话管理**：每个用户会生成唯一的 session_id，格式为 `{username}_{timestamp}_{random}`
+3. **错误处理**：保留了原有的错误处理逻辑，包括认证失败跳转等
+4. **深度搜索**：当前配置使用 naive_search_tool，如需使用 deep_research_tool，可修改 `agent_type` 参数
+
+## 后续优化建议
+
+1. 可以根据用户选择动态切换 agent_type（naive_rag_agent / deep_research_agent）
+2. 可以添加配置项控制是否显示思考过程（show_thinking）
+3. 可以实现真正的会话持久化，而不仅仅依赖浏览器本地存储

AIEC-server/docs/neo4j-connection-fix.md

@@ -0,0 +1,116 @@
+# Neo4j 连接问题解决方案
+
+## 问题描述
+
+前端成功调用了 graph-rag-agent API，但后端在处理时报错：
+```
+搜索过程中出现错误: Connection error.
+```
+
+这表明 graph-rag-agent 无法连接到 Neo4j 数据库。
+
+## 解决步骤
+
+### 1. 检查 Neo4j 服务状态
+
+```bash
+# 检查 Neo4j 是否在运行
+sudo systemctl status neo4j
+
+# 或者如果使用 Docker
+docker ps | grep neo4j
+```
+
+### 2. 启动 Neo4j（如果未运行）
+
+```bash
+# 使用系统服务
+sudo systemctl start neo4j
+
+# 或使用 Docker
+docker run -d \
+  --name neo4j \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/password \
+  neo4j:latest
+```
+
+### 3. 检查 Neo4j 连接配置
+
+查看 graph-rag-agent 的配置文件：
+```bash
+cd ~/graph-rag-agent
+cat config/settings.py | grep -i neo4j
+```
+
+确保配置正确：
+- URI: `bolt://localhost:7687` 或 `neo4j://localhost:7687`
+- 用户名: 通常是 `neo4j`
+- 密码: 你设置的密码
+
+### 4. 测试 Neo4j 连接
+
+使用 Neo4j 浏览器：
+```
+http://localhost:7474
+```
+
+或使用 cypher-shell：
+```bash
+cypher-shell -u neo4j -p your-password
+```
+
+### 5. 检查数据库内容
+
+确保 Neo4j 中有必要的数据：
+```cypher
+// 在 Neo4j 浏览器中运行
+MATCH (n:__Chunk__) RETURN count(n) as chunk_count;
+MATCH (n:__Entity__) RETURN count(n) as entity_count;
+```
+
+如果返回 0，说明需要先构建知识图谱。
+
+### 6. 构建知识图谱（如果需要）
+
+```bash
+cd ~/graph-rag-agent
+# 查看是否有数据导入脚本
+ls build/
+ls scripts/
+```
+
+通常需要运行类似这样的命令：
+```bash
+python build/build_graph.py --input your_documents_folder
+```
+
+## 临时解决方案
+
+如果暂时无法解决 Neo4j 问题，可以：
+
+1. **使用 mock 数据**：修改 naive_search_tool 返回模拟数据
+2. **切换到其他 agent**：尝试不依赖 Neo4j 的 agent 类型
+3. **使用内存数据库**：配置 graph-rag-agent 使用内存模式
+
+## 验证修复
+
+修复后，使用测试页面验证：
+```
+http://localhost:3000/test-graph-rag.html
+```
+
+或直接测试 API：
+```bash
+curl -X POST http://localhost:8000/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "测试问题",
+    "session_id": "test",
+    "agent_type": "naive_rag_agent"
+  }'
+```
+
+## 前端显示问题
+
+如果看到原始 JSON 而不是格式化的文本，这是因为后端返回了包含错误信息的响应。一旦 Neo4j 连接问题解决，前端会正常显示格式化的回答。

AIEC-server/docs/service-not-running-fix.md

@@ -0,0 +1,148 @@
+# Graph-RAG-Agent 服务未运行问题解决方案
+
+## 问题描述
+
+错误信息：
+```
+连接错误: HTTPConnectionPool(host='localhost', port=8000): Max retries exceeded with url: /chat/stream 
+(Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x000001DD24E19F60>: 
+Failed to establish a new connection: [WinError 10061] 由于目标计算机积极拒绝，无法连接。'))
+```
+
+这表明 graph-rag-agent 服务没有在 8000 端口运行。
+
+## 解决步骤
+
+### 1. 首先恢复 CORS 支持
+
+由于你恢复了原始文件，需要重新添加 CORS 支持：
+
+```bash
+cd ~/graph-rag-agent/server
+cp main.py.cors_backup main.py
+```
+
+或者手动编辑 main.py，在导入部分添加：
+```python
+from fastapi.middleware.cors import CORSMiddleware
+```
+
+在 `app = FastAPI(...)` 之后添加：
+```python
+# 配置 CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # 允许所有源
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+### 2. 检查依赖是否安装
+
+```bash
+cd ~/graph-rag-agent
+pip install -r requirements.txt
+```
+
+### 3. 检查 Neo4j 是否运行
+
+```bash
+# Windows PowerShell
+netstat -an | findstr 7687
+
+# 或在 WSL/Linux 中
+sudo lsof -i :7687
+```
+
+### 4. 启动 graph-rag-agent 服务
+
+在 Windows 中：
+```bash
+cd C:\path\to\graph-rag-agent
+python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+在 WSL/Linux 中：
+```bash
+cd ~/graph-rag-agent
+python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 5. 常见启动问题
+
+#### 问题 1：ModuleNotFoundError
+```
+ModuleNotFoundError: No module named 'xxx'
+```
+解决：安装缺失的模块
+```bash
+pip install xxx
+```
+
+#### 问题 2：Neo4j 连接失败
+```
+neo4j.exceptions.ServiceUnavailable: Unable to connect to localhost:7687
+```
+解决：
+1. 启动 Neo4j 服务
+2. 检查 config/settings.py 中的 Neo4j 配置
+
+#### 问题 3：端口被占用
+```
+[Errno 48] Address already in use
+```
+解决：
+1. 查找占用端口的进程：
+   ```bash
+   # Windows
+   netstat -ano | findstr :8000
+   
+   # Linux/Mac
+   lsof -i :8000
+   ```
+2. 终止进程或使用其他端口
+
+### 6. 验证服务是否启动
+
+1. 在浏览器访问：
+   ```
+   http://localhost:8000/docs
+   ```
+   应该看到 FastAPI 的 API 文档页面
+
+2. 使用 curl 测试：
+   ```bash
+   curl http://localhost:8000/
+   ```
+
+3. 测试 CORS：
+   ```bash
+   curl -I -X OPTIONS http://localhost:8000/chat \
+     -H "Origin: http://localhost:3000" \
+     -H "Access-Control-Request-Method: POST"
+   ```
+
+### 7. 完整启动流程
+
+1. **启动 Neo4j**（如果需要）
+2. **恢复 CORS 配置**
+3. **启动 graph-rag-agent**：
+   ```bash
+   cd ~/graph-rag-agent
+   python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
+   ```
+4. **启动前端**（在另一个终端）：
+   ```bash
+   cd ~/yundage-backserver-test
+   python -m http.server 3000
+   ```
+5. **访问前端**：http://localhost:3000
+
+## 调试建议
+
+1. 查看 graph-rag-agent 的启动日志，看是否有错误
+2. 确保所有依赖都已正确安装
+3. 检查防火墙设置是否阻止了 8000 端口
+4. 如果在 WSL 中运行，确保 Windows 防火墙允许 WSL 访问

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**: 前端静态文件服务器（可选）

AIEC-server/docs/流式接口问题分析.md

@@ -0,0 +1,115 @@
+# 流式接口不稳定问题分析
+
+## 问题现象
+- 流式接口时好时坏
+- 错误信息：`Remote host terminated the handshake`
+- 有时正常返回流式数据，有时连接失败
+
+## 可能原因
+
+### 1. API服务稳定性
+- `jzhengda-api.com` 可能存在间歇性连接问题
+- SSL证书或握手过程偶尔失败
+- API服务负载或限流
+
+### 2. 网络因素
+- 网络延迟或丢包
+- 防火墙或代理干扰
+- DNS解析问题
+
+### 3. 并发限制
+- 浏览器对同域名并发连接数限制（通常6个）
+- 后端线程池资源限制
+- SSE长连接占用资源
+
+### 4. 配置问题
+- 超时设置不合理
+- 缓冲区设置问题
+- Keep-alive配置
+
+## 监控建议
+
+### 前端监控
+```javascript
+// 添加连接状态监控
+let connectionStats = {
+    total: 0,
+    success: 0,
+    failed: 0,
+    errors: []
+};
+
+// 记录每次请求结果
+function logStreamResult(success, error) {
+    connectionStats.total++;
+    if (success) {
+        connectionStats.success++;
+    } else {
+        connectionStats.failed++;
+        connectionStats.errors.push({
+            time: new Date().toISOString(),
+            error: error
+        });
+    }
+    
+    // 计算成功率
+    const successRate = (connectionStats.success / connectionStats.total * 100).toFixed(2);
+    console.log(`流式接口成功率: ${successRate}%`);
+}
+```
+
+### 后端监控
+- 添加请求日志记录
+- 监控API调用延迟
+- 记录失败原因统计
+
+## 临时解决方案
+
+### 1. 前端降级策略
+- 流式失败自动切换到同步模式
+- 添加重试机制（已在代码中实现）
+- 显示降级提示
+
+### 2. 优化建议
+- 增加连接超时时间
+- 添加心跳检测
+- 实现断线重连
+
+### 3. 后端优化
+- 添加连接池管理
+- 实现请求排队机制
+- 优化线程池配置
+
+## 测试步骤
+
+1. **稳定性测试**
+   - 连续发送10次请求
+   - 记录成功率
+   - 分析失败模式
+
+2. **压力测试**
+   - 多用户同时访问
+   - 观察失败率变化
+   - 找出瓶颈
+
+3. **网络测试**
+   - 不同网络环境测试
+   - 使用VPN测试
+   - 测试不同时间段
+
+## 长期解决方案
+
+1. **使用更稳定的API服务**
+   - 考虑使用官方OpenAI API
+   - 或搭建自己的中转服务
+   - 添加多个备用API
+
+2. **改进架构**
+   - 使用消息队列缓冲请求
+   - 实现负载均衡
+   - 添加缓存机制
+
+3. **监控告警**
+   - 实时监控API可用性
+   - 失败率超过阈值告警
+   - 自动切换备用方案

AIEC-server/docs/流式接口问题分析.mdZone.Identifier

@@ -0,0 +1,2 @@
+[ZoneTransfer]
+ZoneId=3