# 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. 可以实现真正的会话持久化，而不仅仅依赖浏览器本地存储