docs: 优化 README
This commit is contained in:
@@ -1,277 +1,426 @@
|
|||||||
# knowledge-graph-agent
|
# knowledge-graph-agent
|
||||||
|
|
||||||
🤖 以知识图谱为核心的学习辅助对话智能体，集成 层级记忆、自省反馈、CoT、邮件自动化等技术
|
知识图谱驱动的学习辅助对话智能体项目。
|
||||||
|
|
||||||
|
这个项目的目标不是单纯做一个聊天机器人，而是把“知识图谱”“对话”“记忆”“检索”“自动化”组合成一个可演进的智能体系统：
|
||||||
|
|
||||||
|
- 以知识图谱作为核心数据结构
|
||||||
|
- 以图谱查询作为对话上下文补充
|
||||||
|
- 以图谱编辑作为知识沉淀方式
|
||||||
|
- 以后续的记忆、自省、任务编排作为增强方向
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## MVP 开发任务清单
|
## 一、项目目标
|
||||||
|
|
||||||
### 技术栈
|
### 1.1 解决什么问题
|
||||||
|
|
||||||
**后端**
|
传统问答系统通常只有“输入文本 -> 生成回答”的链路，缺少可追溯、可扩展、可持续积累的知识结构。
|
||||||
|
|
||||||
- 语言: Go 1.26.1
|
本项目希望补上这几个部分：
|
||||||
- 框架: Gin 1.12.0
|
|
||||||
- 数据库: Neo4j 5.x
|
|
||||||
- AI 服务: 硅基流动 OpenAI Completion
|
|
||||||
|
|
||||||
**前端**
|
- 把知识拆成节点和边，形成图谱
|
||||||
|
- 让用户可以查询、编辑、扩展知识
|
||||||
|
- 让对话不仅依赖模型参数，还能依赖图谱上下文
|
||||||
|
- 为后续的记忆层、自省层、任务层预留架构
|
||||||
|
|
||||||
- 框架: React 19.2.4 + TypeScript 5.9.3
|
### 1.2 核心能力
|
||||||
- 图谱可视化: AntV G6 5.1.0
|
|
||||||
- 状态管理: Zustand 5.0.12
|
|
||||||
- 样式: Tailwind CSS 4.2.2
|
|
||||||
- HTTP 客户端: Axios 1.14.0
|
|
||||||
|
|
||||||
---
|
当前设计中的核心能力包括：
|
||||||
|
|
||||||
## 阶段一： Neo4j 数据库集成
|
1. 图谱查询
|
||||||
|
- 查询整图
|
||||||
|
- 查询节点详情
|
||||||
|
- 查询邻居关系
|
||||||
|
- 搜索节点
|
||||||
|
- 获取统计信息
|
||||||
|
|
||||||
### 1.1 环境搭建
|
2. 图谱编辑
|
||||||
|
- 创建节点
|
||||||
|
- 更新节点
|
||||||
|
- 删除节点
|
||||||
|
- 创建边
|
||||||
|
- 删除边
|
||||||
|
|
||||||
- [x] 连接 Neo4j 5.x 服务器（http://47.121.181.112/）
|
3. 对话增强
|
||||||
- 使用服务器提供的数据库实例
|
- 基于图谱检索上下文
|
||||||
- 验证服务运行状态
|
- 为 LLM 提供简化图数据
|
||||||
- 配置基础认证（用户名/密码）
|
- 为后续 Chat API 预留能力
|
||||||
- 记录连接信息（bolt://47.121.181.112:7687）
|
|
||||||
- [ ] 选择并安装 Go Neo4j 客户端库
|
|
||||||
- 评估候选库（如 github.com/neo4j/neo4j-go-driver）
|
|
||||||
- 添加到 go.mod
|
|
||||||
- 运行 `go mod tidy`
|
|
||||||
|
|
||||||
- [ ] 配置数据库连接字符串
|
4. 后续扩展
|
||||||
- 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
|
- 层级记忆
|
||||||
- 在 `main.go` 中读取并验证连接
|
- 自省反馈
|
||||||
- 实现简单的健康检查接口（GET /db/health）
|
- CoT 推理增强
|
||||||
|
|
||||||
### 1.2 数据模型设计与迁移
|
|
||||||
|
|
||||||
- [ ] 设计 Neo4j 节点与边的属性模型
|
|
||||||
- 节点标签（例如：Concept、Tool、Application）
|
|
||||||
- 节点属性：id、label、type、properties（JSON）、x、y、style（JSON）
|
|
||||||
- 关系类型：RELATIONSHIP、DEPENDENCY等
|
|
||||||
- 关系属性：id、label、type、properties、style（JSON）
|
|
||||||
|
|
||||||
- [ ] 编写数据迁移脚本 `scripts/migrate_to_neo4j.go`
|
|
||||||
- 读取现有 `data.json`
|
|
||||||
- 创建 Neo4j 节点（批量 CREATE）
|
|
||||||
- 创建 Neo4j 关系（批量 CREATE）
|
|
||||||
- 添加唯一约束：`CREATE CONSTRAINT FOR (n:Node) REQUIRE n.id IS UNIQUE`
|
|
||||||
- 输出迁移统计（节点数、边数）
|
|
||||||
|
|
||||||
- [ ] 执行迁移并验证数据完整性
|
|
||||||
- 运行迁移脚本
|
|
||||||
- 在 Neo4j Browser 中执行 Cypher 验证：
|
|
||||||
- `MATCH (n) RETURN count(n) AS totalNodes`
|
|
||||||
- `MATCH ()-[r]->() RETURN count(r) AS totalEdges`
|
|
||||||
- 对比原始 JSON 的统计
|
|
||||||
|
|
||||||
### 1.3 Neo4j 数据服务层
|
|
||||||
|
|
||||||
- [ ] 创建 `services/neo4j_service.go`
|
|
||||||
- 实现 `NewNeo4jService(uri, username, password)`
|
|
||||||
- 实现基础 CRUD 接口：
|
|
||||||
- `GetAllNodes() ([]Node, error)`
|
|
||||||
- `GetAllEdges() ([]Edge, error)`
|
|
||||||
- `GetNodeByID(id string) (Node, error)`
|
|
||||||
- `GetNeighbors(nodeID string) (nodes []Node, edges []Edge, error)`
|
|
||||||
- `SearchNodes(query string) ([]Node, error)`
|
|
||||||
|
|
||||||
- [ ] 在 `services/data_service.go` 中切换数据源
|
|
||||||
- 移除 JSON 文件加载逻辑
|
|
||||||
- 注入 `Neo4jService` 依赖
|
|
||||||
- 更新现有方法委托给 Neo4j 查询：
|
|
||||||
- `GetGraphData()`
|
|
||||||
- `GetNodeByID()`
|
|
||||||
- `GetNeighbors()`
|
|
||||||
- `SearchNodes()`
|
|
||||||
- `GetStats()`
|
|
||||||
|
|
||||||
- [ ] 添加并发安全与连接池管理
|
|
||||||
- 使用 Neo4j 驱动会话管理
|
|
||||||
- 确保连接池合理设置
|
|
||||||
- 添加重试机制（简单指数退避）
|
|
||||||
|
|
||||||
### 1.4 API 验证与测试
|
|
||||||
|
|
||||||
- [ ] 后端单元测试
|
|
||||||
- 为 `neo4j_service.go` 编写测试
|
|
||||||
- Mock Neo4j 驱动（如有工具支持）或使用集成测试
|
|
||||||
- 测试搜索与邻居查询
|
|
||||||
|
|
||||||
- [ ] API 契约测试
|
|
||||||
- 使用 Postman 或 curl 验证：
|
|
||||||
- GET /api/graph
|
|
||||||
- GET /api/nodes/:id
|
|
||||||
- GET /api/nodes/:id/neighbors
|
|
||||||
- GET /api/search?q=query
|
|
||||||
|
|
||||||
- [ ] 前端兼容性验证
|
|
||||||
- 服务端无需修改即可兼容现有前端
|
|
||||||
- 验证图谱渲染、搜索、节点详情、邻居加载
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 阶段二：图谱构建功能增强
|
|
||||||
|
|
||||||
### 2.1 后端 CRUD API
|
|
||||||
|
|
||||||
- [ ] 创建节点 API
|
|
||||||
- POST /api/nodes
|
|
||||||
- 请求体：`{label, type, properties, x, y, style}`
|
|
||||||
- 实现：调用 Neo4j CREATE 节点
|
|
||||||
- 返回：新建节点的完整信息
|
|
||||||
|
|
||||||
- [ ] 更新节点 API
|
|
||||||
- PUT /api/nodes/:id
|
|
||||||
- 请求体：`{label, type, properties, x, y, style}`
|
|
||||||
- 实现：调用 Neo4j SET 更新指定节点属性
|
|
||||||
- 返回：更新后节点
|
|
||||||
- 错误处理：节点不存在返回 404
|
|
||||||
|
|
||||||
- [ ] 删除节点 API
|
|
||||||
- DELETE /api/nodes/:id
|
|
||||||
- 实现：先删除相关关系，再删除节点（或使用 DETACH DELETE）
|
|
||||||
- 返回：204 No Content 或 404
|
|
||||||
|
|
||||||
- [ ] 创建边（关系）API
|
|
||||||
- POST /api/edges
|
|
||||||
- 请求体：`{source, target, label, type, properties, style}`
|
|
||||||
- 实现：使用 Cypher MATCH + CREATE 创建关系
|
|
||||||
- 返回：新建边的完整信息
|
|
||||||
- 验证 source 和 target 节点是否存在
|
|
||||||
|
|
||||||
- [ ] 更新边 API
|
|
||||||
- PUT /api/edges/:id
|
|
||||||
- 请求体：`{label, type, properties, style}`
|
|
||||||
- 实现：使用 Cypher 找到边并 SET 属性
|
|
||||||
- 返回：更新后边
|
|
||||||
|
|
||||||
- [ ] 删除边 API
|
|
||||||
- DELETE /api/edges/:id
|
|
||||||
- 实现：Cypher DELETE 关系
|
|
||||||
- 返回：204 No Content 或 404
|
|
||||||
|
|
||||||
### 2.2 批量操作 API
|
|
||||||
|
|
||||||
- [ ] 批量创建节点 API
|
|
||||||
- POST /api/nodes/batch
|
|
||||||
- 请求体：`{nodes: [...]}`
|
|
||||||
- 实现：事务批量创建，任一失败则全部回滚
|
|
||||||
- 返回：成功与失败清单
|
|
||||||
|
|
||||||
- [ ] 批量创建边 API
|
|
||||||
- POST /api/edges/batch
|
|
||||||
- 请求体：`{edges: [...]}`
|
|
||||||
- 实现：事务批量创建边
|
|
||||||
- 返回：创建成功数量与失败清单
|
|
||||||
|
|
||||||
### 2.3 前端编辑界面
|
|
||||||
|
|
||||||
- [ ] 新增编辑状态与管理
|
|
||||||
- 在 `graphStore.ts` 中添加 `editingNode` 与 `editingEdge`
|
|
||||||
- 添加方法：`startEditingNode(node)`、`startEditingEdge(edge)`、`cancelEditing()`、`saveNode/Edge()`
|
|
||||||
|
|
||||||
- [ ] 节点编辑 Dialog 组件
|
|
||||||
- 表单字段：label、type、properties（JSON 编辑器）、x、y、style（JSON 编辑器）
|
|
||||||
- 用于新建与更新节点
|
|
||||||
- 集成到节点详情面板或右键菜单
|
|
||||||
|
|
||||||
- [ ] 边编辑 Dialog 组件
|
|
||||||
- 表单字段：label、type、properties、style
|
|
||||||
- 用于新建与更新边
|
|
||||||
- 集成到边点击交互或右键菜单
|
|
||||||
|
|
||||||
- [ ] 增强图谱视图交互
|
|
||||||
- 支持从工具栏拖拽创建节点
|
|
||||||
- 支持通过连线工具创建边（点击两个节点）
|
|
||||||
- 实时回显编辑结果
|
|
||||||
|
|
||||||
### 2.4 数据持久化与刷新
|
|
||||||
|
|
||||||
- [ ] 前端自动刷新机制
|
|
||||||
- CRUD 操作后自动调用 `loadGraphData()` 刷新图谱
|
|
||||||
- 优化：对于增量更新，避免全量重绘
|
|
||||||
|
|
||||||
- [ ] 添加撤销与重做
|
|
||||||
- 维护操作历史栈
|
|
||||||
- 提供 Undo/Redo 方法与按钮
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 阶段三：智能对话基础功能
|
|
||||||
|
|
||||||
### 3.1 AI 客户端封装
|
|
||||||
|
|
||||||
- [ ] 安装 Go HTTP 客户端库（如 resty 或使用标准库）
|
|
||||||
- [ ] 创建 `services/ai_service.go`
|
|
||||||
- 方法：`NewAIService(apiKey, baseURL)`
|
|
||||||
- 核心方法：`ChatCompletion(messages []Message) (string, error)`
|
|
||||||
- 实现：调用硅基流动 OpenAI Completion 接口
|
|
||||||
- 添加请求超时与错误处理
|
|
||||||
|
|
||||||
- [ ] 请求与响应模型定义
|
|
||||||
- `models/ai.go`：定义 `Message`、`ChatRequest`、`ChatResponse`
|
|
||||||
- 统一错误类型与包装
|
|
||||||
|
|
||||||
### 3.2 对话 API
|
|
||||||
|
|
||||||
- [ ] 对话会话管理
|
|
||||||
- 创建 `services/conversation_service.go`
|
|
||||||
- 维护会话上下文（最近 N 条消息）
|
|
||||||
- 方法：`CreateConversation()`、`AddMessage(sessionID, role, content)`、`GetHistory(sessionID)`
|
|
||||||
|
|
||||||
- [ ] 创建对话 API
|
|
||||||
- POST /api/chat
|
|
||||||
- 请求体：`{message, sessionId?}`
|
|
||||||
- 实现：
|
|
||||||
1. 创建或获取会话
|
|
||||||
2. 添加用户消息到历史
|
|
||||||
3. 调用 `AIService.ChatCompletion`
|
|
||||||
4. 保存 AI 回复到历史
|
|
||||||
5. 返回 AI 回复
|
|
||||||
- 支持流式返回（如平台支持）
|
|
||||||
|
|
||||||
### 3.3 图谱查询与对话集成
|
|
||||||
|
|
||||||
- [ ] 知识检索策略
|
|
||||||
- 在 `neo4j_service.go` 中添加：
|
|
||||||
- `SearchNodesByKeywords(keywords []string) ([]Node, error)`
|
|
||||||
- `GetRelevantContext(nodeID string, depth int) ([]Node, []Edge, error)`
|
|
||||||
- 支持根据消息关键词检索相关节点
|
|
||||||
|
|
||||||
- [ ] 上下文增强生成
|
|
||||||
- 在对话前步骤：
|
|
||||||
- 提取消息中的关键实体或关键词
|
|
||||||
- 检索图谱中的相关节点与关系
|
|
||||||
- 将检索结果作为系统提示或上下文注入到对话请求
|
|
||||||
- 输出格式：自然语言摘要或结构化 JSON（根据需求）
|
|
||||||
|
|
||||||
- [ ] 优化 AI 提示词
|
|
||||||
- 设计 System Prompt：介绍图谱助手角色与能力
|
|
||||||
- 提供示例对话
|
|
||||||
|
|
||||||
### 3.4 前端对话界面
|
|
||||||
|
|
||||||
- [ ] 创建 Chat 组件
|
|
||||||
- 消息列表（用户消息与 AI 消息）
|
|
||||||
- 输入框与发送按钮
|
|
||||||
- 显示加载状态
|
|
||||||
|
|
||||||
- [ ] 集成到图谱页面
|
|
||||||
- 在 `KnowledgeGraph.tsx` 中添加 Chat 组件
|
|
||||||
- 配置布局（侧边或底部面板）
|
|
||||||
|
|
||||||
- [ ] 增强交互
|
|
||||||
- 支持快捷键发送（Enter）
|
|
||||||
- 显示会话历史切换（可选）
|
|
||||||
- 消息支持 Markdown 渲染
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 后续增强阶段（非 MVP）
|
|
||||||
|
|
||||||
- 记忆与自省系统
|
|
||||||
- 邮件自动化
|
- 邮件自动化
|
||||||
- 定时任务
|
- 定时任务
|
||||||
- CoT 推理增强
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 二、整体架构
|
||||||
|
|
||||||
|
### 2.1 总体分层
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph UI[用户 / 前端]
|
||||||
|
User[用户]
|
||||||
|
Web[Web 前端]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph API[后端 API 层]
|
||||||
|
Router[Gin Router]
|
||||||
|
GH[GraphHandler]
|
||||||
|
NH[NodeHandler]
|
||||||
|
SH[SearchHandler]
|
||||||
|
CRUD[NodeCRUDHandler / EdgeCRUDHandler]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph APP[业务服务层]
|
||||||
|
GS[GraphService Interface]
|
||||||
|
GQ[graph_queries.go]
|
||||||
|
GC[graph_crud.go]
|
||||||
|
GSIMPLE[graph_simple.go]
|
||||||
|
UTL[neo4j_utils.go]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph INFRA[基础设施层]
|
||||||
|
Driver[Neo4j Driver]
|
||||||
|
Neo4j[(Neo4j 5.x)]
|
||||||
|
end
|
||||||
|
|
||||||
|
User --> Web
|
||||||
|
Web --> Router
|
||||||
|
Router --> GH
|
||||||
|
Router --> NH
|
||||||
|
Router --> SH
|
||||||
|
Router --> CRUD
|
||||||
|
|
||||||
|
GH --> GS
|
||||||
|
NH --> GS
|
||||||
|
SH --> GS
|
||||||
|
CRUD --> GS
|
||||||
|
|
||||||
|
GS --> GQ
|
||||||
|
GS --> GC
|
||||||
|
GS --> GSIMPLE
|
||||||
|
GQ --> UTL
|
||||||
|
GC --> UTL
|
||||||
|
GSIMPLE --> UTL
|
||||||
|
|
||||||
|
GQ --> Driver
|
||||||
|
GC --> Driver
|
||||||
|
GSIMPLE --> Driver
|
||||||
|
Driver --> Neo4j
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 请求流转方式
|
||||||
|
|
||||||
|
一次典型请求的流转如下：
|
||||||
|
|
||||||
|
1. 用户在前端发起请求
|
||||||
|
2. Gin Router 根据路径分发到对应 handler
|
||||||
|
3. Handler 解析参数并调用 service
|
||||||
|
4. Service 执行 Neo4j 查询或写入
|
||||||
|
5. Neo4j 返回记录后，Service 转换成 API 模型
|
||||||
|
6. Handler 将结果返回给前端
|
||||||
|
|
||||||
|
这个流程的重点是：
|
||||||
|
|
||||||
|
- HTTP 细节停留在 Handler
|
||||||
|
- 业务逻辑停留在 Service
|
||||||
|
- 数据访问细节停留在 Neo4j driver 和工具函数中
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、技术栈
|
||||||
|
|
||||||
|
### 3.1 后端
|
||||||
|
|
||||||
|
- Go 1.26.1
|
||||||
|
- Gin 1.12.0
|
||||||
|
- Neo4j 5.x
|
||||||
|
- Swagger / Swaggo
|
||||||
|
- CORS 中间件
|
||||||
|
|
||||||
|
### 3.2 前端
|
||||||
|
|
||||||
|
- React 19.2.4
|
||||||
|
- TypeScript 5.9.3
|
||||||
|
- AntV G6 5.1.0
|
||||||
|
- Zustand 5.0.12
|
||||||
|
- Tailwind CSS 4.2.2
|
||||||
|
- Axios 1.14.0
|
||||||
|
|
||||||
|
### 3.3 外部能力
|
||||||
|
|
||||||
|
- Neo4j 数据库：存储图谱节点和关系
|
||||||
|
- 硅基流动 OpenAI Completion：后续用于对话和推理增强
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、仓库结构
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
Repo[knowledge-graph-agent/] --> RootReadme[README.md]
|
||||||
|
Repo --> Backend[backend/]
|
||||||
|
|
||||||
|
Backend --> BackendReadme[README.md]
|
||||||
|
Backend --> Cmd[cmd/server/]
|
||||||
|
Backend --> Docs[docs/]
|
||||||
|
Backend --> Internal[internal/]
|
||||||
|
|
||||||
|
Cmd --> Main[main.go]
|
||||||
|
|
||||||
|
Internal --> Config[config/]
|
||||||
|
Internal --> Handler[handler/]
|
||||||
|
Internal --> Model[model/]
|
||||||
|
Internal --> Repository[repository/neo4j/]
|
||||||
|
Internal --> Service[service/]
|
||||||
|
|
||||||
|
Handler --> GH[graph_handler.go]
|
||||||
|
Handler --> NH[node_handler.go]
|
||||||
|
Handler --> SH[search_handler.go]
|
||||||
|
Handler --> CRUD[crud_handler.go]
|
||||||
|
|
||||||
|
Service --> IF[interface.go]
|
||||||
|
Service --> Q[graph_queries.go]
|
||||||
|
Service --> C[graph_crud.go]
|
||||||
|
Service --> S[graph_simple.go]
|
||||||
|
Service --> U[neo4j_utils.go]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、后端模块说明
|
||||||
|
|
||||||
|
如果你只看后端，建议优先阅读 `backend/README.md`。
|
||||||
|
|
||||||
|
这里先给一个简化理解：
|
||||||
|
|
||||||
|
### 5.1 Handler 层做什么
|
||||||
|
|
||||||
|
- 接收 HTTP 请求
|
||||||
|
- 解析参数
|
||||||
|
- 调用 service
|
||||||
|
- 返回 JSON
|
||||||
|
|
||||||
|
### 5.2 Service 层做什么
|
||||||
|
|
||||||
|
- 执行业务逻辑
|
||||||
|
- 组织 Cypher 查询
|
||||||
|
- 将 Neo4j 结果转换为 API 模型
|
||||||
|
- 处理图数据、图编辑、搜索、统计等能力
|
||||||
|
|
||||||
|
### 5.3 Repository / Driver 层做什么
|
||||||
|
|
||||||
|
- 初始化 Neo4j 连接
|
||||||
|
- 提供驱动实例
|
||||||
|
- 负责和数据库建立底层通信
|
||||||
|
|
||||||
|
### 5.4 Model 层做什么
|
||||||
|
|
||||||
|
- 定义节点、边、图数据、请求、响应模型
|
||||||
|
- 统一前后端传输格式
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、后端当前能力
|
||||||
|
|
||||||
|
### 6.1 图查询
|
||||||
|
|
||||||
|
- 获取整图
|
||||||
|
- 获取节点详情
|
||||||
|
- 获取节点邻居
|
||||||
|
- 获取图统计
|
||||||
|
- 获取简化图数据
|
||||||
|
- 搜索节点
|
||||||
|
|
||||||
|
### 6.2 图编辑
|
||||||
|
|
||||||
|
- 创建节点
|
||||||
|
- 更新节点
|
||||||
|
- 删除节点
|
||||||
|
- 创建边
|
||||||
|
- 删除边
|
||||||
|
|
||||||
|
### 6.3 对话准备能力
|
||||||
|
|
||||||
|
- 简化图数据适合输入给 LLM
|
||||||
|
- 图谱检索可作为上下文增强来源
|
||||||
|
- 后续可扩展会话与记忆能力
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、主要 API 设计
|
||||||
|
|
||||||
|
### 7.1 基础接口
|
||||||
|
|
||||||
|
- `GET /health`
|
||||||
|
- 健康检查
|
||||||
|
- `GET /api/graph`
|
||||||
|
- 获取完整图数据
|
||||||
|
- `GET /api/graph/stats`
|
||||||
|
- 获取图统计
|
||||||
|
- `GET /api/graph/simpleJson`
|
||||||
|
- 获取简化图数据
|
||||||
|
- `GET /api/search?q=xxx`
|
||||||
|
- 搜索节点
|
||||||
|
- `GET /api/nodes/:id`
|
||||||
|
- 获取节点详情
|
||||||
|
- `GET /api/nodes/:id/neighbors`
|
||||||
|
- 获取邻居
|
||||||
|
|
||||||
|
### 7.2 CRUD 接口
|
||||||
|
|
||||||
|
- `POST /api/nodes`
|
||||||
|
- `PUT /api/nodes/:id`
|
||||||
|
- `DELETE /api/nodes/:id`
|
||||||
|
- `POST /api/edges`
|
||||||
|
- `DELETE /api/edges/:id`
|
||||||
|
|
||||||
|
### 7.3 API 响应风格
|
||||||
|
|
||||||
|
当前后端倾向于：
|
||||||
|
|
||||||
|
- 成功时返回模型对象或结果对象
|
||||||
|
- 失败时返回统一错误结构
|
||||||
|
- 使用 JSON 作为默认响应格式
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 八、数据模型设计
|
||||||
|
|
||||||
|
### 8.1 节点
|
||||||
|
|
||||||
|
节点对象通常包含：
|
||||||
|
|
||||||
|
- `id`
|
||||||
|
- `label`
|
||||||
|
- `type`
|
||||||
|
- `x`
|
||||||
|
- `y`
|
||||||
|
- `style`
|
||||||
|
- `properties`
|
||||||
|
|
||||||
|
### 8.2 边
|
||||||
|
|
||||||
|
边对象通常包含：
|
||||||
|
|
||||||
|
- `id`
|
||||||
|
- `source`
|
||||||
|
- `target`
|
||||||
|
- `label`
|
||||||
|
- `type`
|
||||||
|
- `style`
|
||||||
|
- `properties`
|
||||||
|
|
||||||
|
### 8.3 简化图数据
|
||||||
|
|
||||||
|
为了服务 LLM 和摘要场景，后端还提供简化图结构：
|
||||||
|
|
||||||
|
- `SimpleNode`
|
||||||
|
- 仅保留最核心字段
|
||||||
|
- `SimpleEdge`
|
||||||
|
- 仅保留最核心字段
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 九、当前开发状态
|
||||||
|
|
||||||
|
> 这里保留的是产品与实现层面的任务视图，不是严格的发布计划。
|
||||||
|
|
||||||
|
### 9.1 已落地的方向
|
||||||
|
|
||||||
|
- Neo4j 接入
|
||||||
|
- 图查询 API
|
||||||
|
- 节点 / 边 CRUD API
|
||||||
|
- 简化图数据输出
|
||||||
|
- Swagger 文档
|
||||||
|
- 服务层拆分与工具抽取
|
||||||
|
|
||||||
|
### 9.2 后续计划中的能力
|
||||||
|
|
||||||
|
- 批量创建节点 / 边
|
||||||
|
- 更细粒度的错误码
|
||||||
|
- 服务测试与 handler 测试
|
||||||
|
- 对话 API
|
||||||
|
- 图谱上下文检索
|
||||||
|
- 记忆与自省系统
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十、文档关系图
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
RootDoc[README.md] --> BackendDoc[backend/README.md]
|
||||||
|
RootDoc --> ProjectGoals[项目目标与全局结构]
|
||||||
|
BackendDoc --> BackendArch[后端架构与 API 细节]
|
||||||
|
BackendDoc --> BackendModels[数据模型与模块拆分]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十一、如何开始理解这个项目
|
||||||
|
|
||||||
|
推荐阅读顺序：
|
||||||
|
|
||||||
|
1. `README.md`：先看整体目标和仓库结构
|
||||||
|
2. `backend/README.md`：再看后端架构和 API
|
||||||
|
3. `backend/cmd/server/main.go`：理解启动入口
|
||||||
|
4. `backend/internal/handler/`：理解 HTTP 层
|
||||||
|
5. `backend/internal/service/`：理解业务层
|
||||||
|
|
||||||
|
如果你的关注点是前端图谱交互，那么可以先看：
|
||||||
|
|
||||||
|
- 图数据 API
|
||||||
|
- 简化图数据结构
|
||||||
|
- 节点 / 边 CRUD 接口
|
||||||
|
|
||||||
|
如果你的关注点是后续 LLM 增强，那么可以先看：
|
||||||
|
|
||||||
|
- `GetSimpleGraphData()`
|
||||||
|
- 图谱搜索接口
|
||||||
|
- 未来的对话上下文注入逻辑
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十二、未来扩展方向
|
||||||
|
|
||||||
|
### 12.1 记忆与自省
|
||||||
|
|
||||||
|
- 会话记忆
|
||||||
|
- 长短期记忆分层
|
||||||
|
- 反馈驱动的自我修正
|
||||||
|
|
||||||
|
### 12.2 自动化能力
|
||||||
|
|
||||||
|
- 邮件自动化
|
||||||
|
- 定时任务
|
||||||
|
- 触发式工作流
|
||||||
|
|
||||||
|
### 12.3 推理增强
|
||||||
|
|
||||||
|
- CoT 提示增强
|
||||||
|
- 图谱检索增强生成
|
||||||
|
- 多轮上下文压缩
|
||||||
|
|
||||||
|
### 12.4 工程化增强
|
||||||
|
|
||||||
|
- 批量操作 API
|
||||||
|
- 权限控制
|
||||||
|
- 审计日志
|
||||||
|
- 测试覆盖率提升
|
||||||
|
- 统一错误码与响应规范
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十三、补充说明
|
||||||
|
|
||||||
|
如果你后面希望我继续整理，我可以直接帮你做下面任一项：
|
||||||
|
|
||||||
|
- 把根目录 README 再改成“项目介绍版”或“开发指南版”
|
||||||
|
- 给后端 README 增加更细的接口表格和请求/响应样例
|
||||||
|
- 继续补一张“前后端交互时序图”
|
||||||
|
- 把整个项目的文档风格统一成一套模板
|
||||||
|
|||||||
+485
-226
@@ -1,279 +1,538 @@
|
|||||||
# knowledge-graph-agent
|
# knowledge-graph-backend
|
||||||
|
|
||||||
🤖 以知识图谱为核心的学习辅助对话智能体，集成 层级记忆、自省反馈、CoT、邮件自动化等技术
|
知识图谱后端服务，基于 Go + Gin + Neo4j 构建，面向图谱查询、图谱编辑、搜索、统计与对话增强能力提供统一 API。
|
||||||
|
|
||||||
[Swagger 文档](http://localhost:3001/swagger/index.html)
|
这份文档聚焦于后端当前已经实现的结构与运行方式，帮助你快速理解：
|
||||||
|
|
||||||
|
- 请求是如何进入系统的
|
||||||
|
- Handler / Service / Neo4j Driver 之间如何协作
|
||||||
|
- 图数据是如何从 Neo4j 读写出来的
|
||||||
|
- 后续扩展功能应该从哪里接入
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## MVP 开发任务清单
|
## 一、系统定位
|
||||||
|
|
||||||
### 技术栈
|
当前后端主要承担以下职责：
|
||||||
|
|
||||||
**后端**
|
1. 对外暴露图谱相关 HTTP API
|
||||||
|
2. 将前端请求转换为对 Neo4j 的查询或写入
|
||||||
- 语言: Go 1.26.1
|
3. 统一节点、边、图数据、错误响应的格式
|
||||||
- 框架: Gin 1.12.0
|
4. 为后续 LLM / 对话增强能力预留简化图数据与上下文检索接口
|
||||||
- 数据库: Neo4j 5.x
|
|
||||||
- AI 服务: 硅基流动 OpenAI Completion
|
|
||||||
|
|
||||||
**前端**
|
|
||||||
|
|
||||||
- 框架: React 19.2.4 + TypeScript 5.9.3
|
|
||||||
- 图谱可视化: AntV G6 5.1.0
|
|
||||||
- 状态管理: Zustand 5.0.12
|
|
||||||
- 样式: Tailwind CSS 4.2.2
|
|
||||||
- HTTP 客户端: Axios 1.14.0
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 阶段一： Neo4j 数据库集成
|
## 二、运行时架构
|
||||||
|
|
||||||
### 1.1 环境搭建
|
### 2.1 整体调用链
|
||||||
|
|
||||||
- [x] 连接 Neo4j 5.x 服务器（http://47.121.181.112/）
|
```mermaid
|
||||||
- 使用服务器提供的数据库实例
|
flowchart LR
|
||||||
- 验证服务运行状态
|
Client[前端 / Postman / curl] --> Router[gin.Engine]
|
||||||
- 配置基础认证（用户名/密码）
|
Router --> Health[/GET /health/]
|
||||||
- 记录连接信息（bolt://47.121.181.112:7687）
|
Router --> Swagger[/GET /swagger/*any/]
|
||||||
- [x] 选择并安装 Go Neo4j 客户端库
|
Router --> API[/GET /api/*\nPOST /api/*\nPUT /api/*\nDELETE /api/*/]
|
||||||
- 评估候选库（如 github.com/neo4j/neo4j-go-driver）
|
|
||||||
- 添加到 go.mod
|
|
||||||
- 运行 `go mod tidy`
|
|
||||||
|
|
||||||
- [x] 配置数据库连接字符串
|
API --> GH[GraphHandler]
|
||||||
- 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
|
API --> NH[NodeHandler]
|
||||||
- 在 `main.go` 中读取并验证连接
|
API --> SH[SearchHandler]
|
||||||
- 实现简单的健康检查接口（GET /db/health）
|
API --> CRUD[NodeCRUDHandler / EdgeCRUDHandler]
|
||||||
|
|
||||||
### 1.2 数据模型设计与迁移
|
GH --> SVC[GraphService]
|
||||||
|
NH --> SVC
|
||||||
|
SH --> SVC
|
||||||
|
CRUD --> SVC
|
||||||
|
|
||||||
- [x] 设计 Neo4j 节点与边的属性模型
|
SVC --> Q[graph_queries.go]
|
||||||
- 节点标签（例如：Concept、Tool、Application）
|
SVC --> C[graph_crud.go]
|
||||||
- 节点属性：id、label、type、properties（JSON）、x、y、style（JSON）
|
SVC --> X[graph_simple.go]
|
||||||
- 关系类型：RELATIONSHIP、DEPENDENCY等
|
SVC --> U[neo4j_utils.go]
|
||||||
- 关系属性：id、label、type、properties、style（JSON）
|
|
||||||
|
|
||||||
- [ ] 编写数据迁移脚本 `scripts/migrate_to_neo4j.go`
|
Q --> D[Neo4j Driver]
|
||||||
- 读取现有 `data.json`
|
C --> D
|
||||||
- 创建 Neo4j 节点（批量 CREATE）
|
X --> D
|
||||||
- 创建 Neo4j 关系（批量 CREATE）
|
D --> DB[(Neo4j 5.x)]
|
||||||
- 添加唯一约束：`CREATE CONSTRAINT FOR (n:Node) REQUIRE n.id IS UNIQUE`
|
```
|
||||||
- 输出迁移统计（节点数、边数）
|
|
||||||
|
|
||||||
- [ ] 执行迁移并验证数据完整性
|
### 2.2 分层职责
|
||||||
- 运行迁移脚本
|
|
||||||
- 在 Neo4j Browser 中执行 Cypher 验证：
|
|
||||||
- `MATCH (n) RETURN count(n) AS totalNodes`
|
|
||||||
- `MATCH ()-[r]->() RETURN count(r) AS totalEdges`
|
|
||||||
- 对比原始 JSON 的统计
|
|
||||||
|
|
||||||
### 1.3 Neo4j 数据服务层
|
#### 路由层
|
||||||
|
|
||||||
- [ ] 创建 `services/neo4j_service.go`
|
入口位于 `cmd/server/main.go`。
|
||||||
- 实现 `NewNeo4jService(uri, username, password)`
|
|
||||||
- 实现基础 CRUD 接口：
|
这一层负责：
|
||||||
- `GetAllNodes() ([]Node, error)`
|
|
||||||
- `GetAllEdges() ([]Edge, error)`
|
- 加载配置
|
||||||
- `GetNodeByID(id string) (Node, error)`
|
- 初始化 Neo4j 驱动
|
||||||
- `GetNeighbors(nodeID string) (nodes []Node, edges []Edge, error)`
|
- 创建 service 实例
|
||||||
- `SearchNodes(query string) ([]Node, error)`
|
- 创建 handler 实例
|
||||||
|
- 注册路由与 Swagger
|
||||||
|
- 启动 HTTP 服务
|
||||||
|
|
||||||
|
#### Handler 层
|
||||||
|
|
||||||
|
目录：`internal/handler/`
|
||||||
|
|
||||||
|
Handler 的职责只包括：
|
||||||
|
|
||||||
|
- 读取 path / query / body 参数
|
||||||
|
- 调用 service
|
||||||
|
- 按统一格式返回 JSON
|
||||||
|
- 在必要时返回错误状态码
|
||||||
|
|
||||||
|
当前 handler 组成：
|
||||||
|
|
||||||
|
- `graph_handler.go`
|
||||||
|
- `GET /api/graph`
|
||||||
|
- `GET /api/graph/stats`
|
||||||
|
- `GET /api/graph/simpleJson`
|
||||||
|
- `node_handler.go`
|
||||||
|
- `GET /api/nodes/:id`
|
||||||
|
- `GET /api/nodes/:id/neighbors`
|
||||||
|
- `search_handler.go`
|
||||||
|
- `GET /api/search?q=...`
|
||||||
|
- `crud_handler.go`
|
||||||
|
- `POST /api/nodes`
|
||||||
|
- `PUT /api/nodes/:id`
|
||||||
|
- `DELETE /api/nodes/:id`
|
||||||
|
- `POST /api/edges`
|
||||||
|
- `DELETE /api/edges/:id`
|
||||||
|
|
||||||
|
#### Service 层
|
||||||
|
|
||||||
|
目录：`internal/service/`
|
||||||
|
|
||||||
|
Service 是核心业务层，负责：
|
||||||
|
|
||||||
|
- 查询图数据
|
||||||
|
- 搜索节点
|
||||||
|
- 获取邻居
|
||||||
|
- 增删改节点与边
|
||||||
|
- 对 Neo4j 结果做模型转换
|
||||||
|
- 封装公共工具函数
|
||||||
|
|
||||||
|
当前文件拆分如下：
|
||||||
|
|
||||||
|
- `interface.go`
|
||||||
|
- 定义 `GraphService` 接口
|
||||||
|
- `graph_queries.go`
|
||||||
|
- 图查询、搜索、统计、邻居、简化图数据
|
||||||
|
- `graph_crud.go`
|
||||||
|
- 节点 / 边创建、更新、删除
|
||||||
|
- `graph_simple.go`
|
||||||
|
- 简化图数据输出
|
||||||
|
- `neo4j_utils.go`
|
||||||
|
- Neo4j 记录转换、属性提取、字段清洗、辅助函数
|
||||||
|
|
||||||
|
#### Repository / Driver 层
|
||||||
|
|
||||||
|
目录：`internal/repository/neo4j/`
|
||||||
|
|
||||||
|
这里负责 Neo4j 驱动初始化与连接配置。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 三、模块关系图
|
||||||
|
|
||||||
|
### 3.1 控制流关系
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
subgraph HTTP[HTTP API]
|
||||||
|
GH[GraphHandler]
|
||||||
|
NH[NodeHandler]
|
||||||
|
SH[SearchHandler]
|
||||||
|
CH[NodeCRUDHandler]
|
||||||
|
EH[EdgeCRUDHandler]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Domain[Service Layer]
|
||||||
|
GS[GraphService Interface]
|
||||||
|
GQ[graph_queries.go]
|
||||||
|
GC[graph_crud.go]
|
||||||
|
GSIMPLE[graph_simple.go]
|
||||||
|
UTIL[neo4j_utils.go]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Infra[Infrastructure]
|
||||||
|
DRIVER[Neo4j Driver]
|
||||||
|
DB[(Neo4j Database)]
|
||||||
|
end
|
||||||
|
|
||||||
|
GH --> GS
|
||||||
|
NH --> GS
|
||||||
|
SH --> GS
|
||||||
|
CH --> GS
|
||||||
|
EH --> GS
|
||||||
|
|
||||||
|
GS --> GQ
|
||||||
|
GS --> GC
|
||||||
|
GS --> GSIMPLE
|
||||||
|
GQ --> UTIL
|
||||||
|
GC --> UTIL
|
||||||
|
GSIMPLE --> UTIL
|
||||||
|
|
||||||
|
GQ --> DRIVER
|
||||||
|
GC --> DRIVER
|
||||||
|
GSIMPLE --> DRIVER
|
||||||
|
DRIVER --> DB
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 数据结构关系
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
classDiagram
|
||||||
|
class GraphData {
|
||||||
|
+[]Node nodes
|
||||||
|
+[]Edge edges
|
||||||
|
}
|
||||||
|
|
||||||
|
class SimpleGraphData {
|
||||||
|
+[]SimpleNode nodes
|
||||||
|
+[]SimpleEdge edges
|
||||||
|
}
|
||||||
|
|
||||||
|
class Node {
|
||||||
|
+string id
|
||||||
|
+string label
|
||||||
|
+string type
|
||||||
|
+float64 x
|
||||||
|
+float64 y
|
||||||
|
+map style
|
||||||
|
+map properties
|
||||||
|
}
|
||||||
|
|
||||||
|
class Edge {
|
||||||
|
+string id
|
||||||
|
+string source
|
||||||
|
+string target
|
||||||
|
+string label
|
||||||
|
+string type
|
||||||
|
+map style
|
||||||
|
+map properties
|
||||||
|
}
|
||||||
|
|
||||||
|
class GraphService {
|
||||||
|
+GetGraphData() GraphData
|
||||||
|
+GetSimpleGraphData() SimpleGraphData
|
||||||
|
+GetNodeByID(id) Node
|
||||||
|
+SearchNodes(query) []Node
|
||||||
|
+GetNeighbors(nodeID) NeighborResponse
|
||||||
|
+GetStats() map
|
||||||
|
+CreateNode(req) Node
|
||||||
|
+UpdateNode(id, req) Node
|
||||||
|
+DeleteNode(id) error
|
||||||
|
+CreateEdge(req) Edge
|
||||||
|
+DeleteEdge(id) error
|
||||||
|
}
|
||||||
|
|
||||||
|
GraphData --> Node
|
||||||
|
GraphData --> Edge
|
||||||
|
SimpleGraphData --> Node
|
||||||
|
SimpleGraphData --> Edge
|
||||||
|
GraphService ..> GraphData
|
||||||
|
GraphService ..> SimpleGraphData
|
||||||
|
GraphService ..> Node
|
||||||
|
GraphService ..> Edge
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 四、API 能力
|
||||||
|
|
||||||
|
### 4.1 健康检查
|
||||||
|
|
||||||
|
- `GET /health`
|
||||||
|
|
||||||
|
用途：确认服务是否运行。
|
||||||
|
|
||||||
|
返回示例：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"message": "Knowledge Graph API is running",
|
||||||
|
"version": "1.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 图数据查询
|
||||||
|
|
||||||
|
- `GET /api/graph`
|
||||||
|
- 返回完整节点与边
|
||||||
|
- `GET /api/graph/stats`
|
||||||
|
- 返回节点数、边数和分类统计
|
||||||
|
- `GET /api/graph/simpleJson`
|
||||||
|
- 返回简化图数据，适合 LLM 或轻量消费端
|
||||||
|
|
||||||
|
### 4.3 节点查询
|
||||||
|
|
||||||
|
- `GET /api/nodes/:id`
|
||||||
|
- 获取单个节点
|
||||||
|
- `GET /api/nodes/:id/neighbors`
|
||||||
|
- 获取该节点的邻居节点和相关边
|
||||||
|
|
||||||
|
### 4.4 搜索
|
||||||
|
|
||||||
|
- `GET /api/search?q=xxx`
|
||||||
|
- 根据 `id`、`label`、`type` 模糊搜索节点
|
||||||
|
|
||||||
|
### 4.5 图谱编辑
|
||||||
|
|
||||||
|
- `POST /api/nodes`
|
||||||
|
- `PUT /api/nodes/:id`
|
||||||
|
- `DELETE /api/nodes/:id`
|
||||||
|
- `POST /api/edges`
|
||||||
|
- `DELETE /api/edges/:id`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 五、请求与响应模型
|
||||||
|
|
||||||
|
### 5.1 节点模型
|
||||||
|
|
||||||
|
节点保留以下标准字段：
|
||||||
|
|
||||||
|
- `id`
|
||||||
|
- `label`
|
||||||
|
- `type`
|
||||||
|
- `x`
|
||||||
|
- `y`
|
||||||
|
- `style`
|
||||||
|
- `properties`
|
||||||
|
|
||||||
|
其中：
|
||||||
|
|
||||||
|
- `style` 适合前端可视化使用
|
||||||
|
- `properties` 用于存放扩展字段
|
||||||
|
|
||||||
|
### 5.2 边模型
|
||||||
|
|
||||||
|
边保留以下标准字段：
|
||||||
|
|
||||||
|
- `id`
|
||||||
|
- `source`
|
||||||
|
- `target`
|
||||||
|
- `label`
|
||||||
|
- `type`
|
||||||
|
- `style`
|
||||||
|
- `properties`
|
||||||
|
|
||||||
|
### 5.3 统一错误响应
|
||||||
|
|
||||||
|
后端使用统一的错误结构：
|
||||||
|
|
||||||
|
- `error`
|
||||||
|
- `message`
|
||||||
|
|
||||||
|
这样前端可以基于同一格式做提示与状态分支处理。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 六、Neo4j 数据映射
|
||||||
|
|
||||||
|
### 6.1 节点映射原则
|
||||||
|
|
||||||
|
Neo4j 节点到 API 节点模型的映射规则：
|
||||||
|
|
||||||
|
- `id` → 节点唯一标识
|
||||||
|
- `label` → 显示名称
|
||||||
|
- `type` → 节点类型
|
||||||
|
- `x/y/style` → 可视化信息
|
||||||
|
- 其余字段 → 放入 `properties`
|
||||||
|
|
||||||
|
### 6.2 边映射原则
|
||||||
|
|
||||||
|
Neo4j 关系到 API 边模型的映射规则：
|
||||||
|
|
||||||
|
- `id` → 边唯一标识
|
||||||
|
- `label` → 边显示名称
|
||||||
|
- `type` → 关系类型
|
||||||
|
- `source/target` → 由起点和终点节点 ID 推导
|
||||||
|
- 其余字段 → 放入 `properties`
|
||||||
|
|
||||||
|
### 6.3 工具函数职责
|
||||||
|
|
||||||
|
`neo4j_utils.go` 集中处理：
|
||||||
|
|
||||||
|
- Neo4j Node / Relationship 转换
|
||||||
|
- 通用取值函数
|
||||||
|
- 保留字段判断
|
||||||
|
- 字段名和关系类型清洗
|
||||||
|
|
||||||
|
这样可以减少 CRUD 和查询代码里的重复逻辑。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 七、服务拆分说明
|
||||||
|
|
||||||
|
### 7.1 `graph_queries.go`
|
||||||
|
|
||||||
|
负责读取类功能：
|
||||||
|
|
||||||
- [ ] 在 `services/data_service.go` 中切换数据源
|
|
||||||
- 移除 JSON 文件加载逻辑
|
|
||||||
- 注入 `Neo4jService` 依赖
|
|
||||||
- 更新现有方法委托给 Neo4j 查询：
|
|
||||||
- `GetGraphData()`
|
- `GetGraphData()`
|
||||||
- `GetNodeByID()`
|
- `GetNodeByID()`
|
||||||
- `GetNeighbors()`
|
|
||||||
- `SearchNodes()`
|
- `SearchNodes()`
|
||||||
|
- `GetNeighbors()`
|
||||||
- `GetStats()`
|
- `GetStats()`
|
||||||
|
|
||||||
- [ ] 添加并发安全与连接池管理
|
这些方法面向“查询场景”，不修改数据库内容。
|
||||||
- 使用 Neo4j 驱动会话管理
|
|
||||||
- 确保连接池合理设置
|
|
||||||
- 添加重试机制（简单指数退避）
|
|
||||||
|
|
||||||
### 1.4 API 验证与测试
|
### 7.2 `graph_crud.go`
|
||||||
|
|
||||||
- [ ] 后端单元测试
|
负责写入类功能：
|
||||||
- 为 `neo4j_service.go` 编写测试
|
|
||||||
- Mock Neo4j 驱动（如有工具支持）或使用集成测试
|
|
||||||
- 测试搜索与邻居查询
|
|
||||||
|
|
||||||
- [ ] API 契约测试
|
- `CreateNode()`
|
||||||
- 使用 Postman 或 curl 验证：
|
- `UpdateNode()`
|
||||||
- GET /api/graph
|
- `DeleteNode()`
|
||||||
- GET /api/nodes/:id
|
- `CreateEdge()`
|
||||||
- GET /api/nodes/:id/neighbors
|
- `DeleteEdge()`
|
||||||
- GET /api/search?q=query
|
|
||||||
|
|
||||||
- [ ] 前端兼容性验证
|
这些方法面向“编辑场景”，负责校验、写入、返回更新后的模型。
|
||||||
- 服务端无需修改即可兼容现有前端
|
|
||||||
- 验证图谱渲染、搜索、节点详情、邻居加载
|
### 7.3 `graph_simple.go`
|
||||||
|
|
||||||
|
负责提供一个轻量版本的图数据：
|
||||||
|
|
||||||
|
- `GetSimpleGraphData()`
|
||||||
|
|
||||||
|
适合：
|
||||||
|
|
||||||
|
- LLM 上下文注入
|
||||||
|
- 快速摘要
|
||||||
|
- 轻量前端消费
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 阶段二：图谱构建功能增强
|
## 八、目录结构
|
||||||
|
|
||||||
### 2.1 后端 CRUD API
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
Root[backend/] --> Cmd[cmd/server/]
|
||||||
|
Root --> Docs[docs/]
|
||||||
|
Root --> Internal[internal/]
|
||||||
|
Root --> README[README.md]
|
||||||
|
|
||||||
- [ ] 创建节点 API
|
Cmd --> Main[main.go]
|
||||||
- POST /api/nodes
|
|
||||||
- 请求体：`{label, type, properties, x, y, style}`
|
|
||||||
- 实现：调用 Neo4j CREATE 节点
|
|
||||||
- 返回：新建节点的完整信息
|
|
||||||
|
|
||||||
- [ ] 更新节点 API
|
Internal --> Config[config/]
|
||||||
- PUT /api/nodes/:id
|
Internal --> Handler[handler/]
|
||||||
- 请求体：`{label, type, properties, x, y, style}`
|
Internal --> Model[model/]
|
||||||
- 实现：调用 Neo4j SET 更新指定节点属性
|
Internal --> Repository[repository/neo4j/]
|
||||||
- 返回：更新后节点
|
Internal --> Service[service/]
|
||||||
- 错误处理：节点不存在返回 404
|
|
||||||
|
|
||||||
- [ ] 删除节点 API
|
Handler --> GH[graph_handler.go]
|
||||||
- DELETE /api/nodes/:id
|
Handler --> NH[node_handler.go]
|
||||||
- 实现：先删除相关关系，再删除节点（或使用 DETACH DELETE）
|
Handler --> SH[search_handler.go]
|
||||||
- 返回：204 No Content 或 404
|
Handler --> CRUD[crud_handler.go]
|
||||||
|
|
||||||
- [ ] 创建边（关系）API
|
Service --> Interface[interface.go]
|
||||||
- POST /api/edges
|
Service --> Q[graph_queries.go]
|
||||||
- 请求体：`{source, target, label, type, properties, style}`
|
Service --> C[graph_crud.go]
|
||||||
- 实现：使用 Cypher MATCH + CREATE 创建关系
|
Service --> Simple[graph_simple.go]
|
||||||
- 返回：新建边的完整信息
|
Service --> Utils[neo4j_utils.go]
|
||||||
- 验证 source 和 target 节点是否存在
|
```
|
||||||
|
|
||||||
- [ ] 更新边 API
|
|
||||||
- PUT /api/edges/:id
|
|
||||||
- 请求体：`{label, type, properties, style}`
|
|
||||||
- 实现：使用 Cypher 找到边并 SET 属性
|
|
||||||
- 返回：更新后边
|
|
||||||
|
|
||||||
- [ ] 删除边 API
|
|
||||||
- DELETE /api/edges/:id
|
|
||||||
- 实现：Cypher DELETE 关系
|
|
||||||
- 返回：204 No Content 或 404
|
|
||||||
|
|
||||||
### 2.2 批量操作 API
|
|
||||||
|
|
||||||
- [ ] 批量创建节点 API
|
|
||||||
- POST /api/nodes/batch
|
|
||||||
- 请求体：`{nodes: [...]}`
|
|
||||||
- 实现：事务批量创建，任一失败则全部回滚
|
|
||||||
- 返回：成功与失败清单
|
|
||||||
|
|
||||||
- [ ] 批量创建边 API
|
|
||||||
- POST /api/edges/batch
|
|
||||||
- 请求体：`{edges: [...]}`
|
|
||||||
- 实现：事务批量创建边
|
|
||||||
- 返回：创建成功数量与失败清单
|
|
||||||
|
|
||||||
### 2.3 前端编辑界面
|
|
||||||
|
|
||||||
- [ ] 新增编辑状态与管理
|
|
||||||
- 在 `graphStore.ts` 中添加 `editingNode` 与 `editingEdge`
|
|
||||||
- 添加方法：`startEditingNode(node)`、`startEditingEdge(edge)`、`cancelEditing()`、`saveNode/Edge()`
|
|
||||||
|
|
||||||
- [ ] 节点编辑 Dialog 组件
|
|
||||||
- 表单字段：label、type、properties（JSON 编辑器）、x、y、style（JSON 编辑器）
|
|
||||||
- 用于新建与更新节点
|
|
||||||
- 集成到节点详情面板或右键菜单
|
|
||||||
|
|
||||||
- [ ] 边编辑 Dialog 组件
|
|
||||||
- 表单字段：label、type、properties、style
|
|
||||||
- 用于新建与更新边
|
|
||||||
- 集成到边点击交互或右键菜单
|
|
||||||
|
|
||||||
- [ ] 增强图谱视图交互
|
|
||||||
- 支持从工具栏拖拽创建节点
|
|
||||||
- 支持通过连线工具创建边（点击两个节点）
|
|
||||||
- 实时回显编辑结果
|
|
||||||
|
|
||||||
### 2.4 数据持久化与刷新
|
|
||||||
|
|
||||||
- [ ] 前端自动刷新机制
|
|
||||||
- CRUD 操作后自动调用 `loadGraphData()` 刷新图谱
|
|
||||||
- 优化：对于增量更新，避免全量重绘
|
|
||||||
|
|
||||||
- [ ] 添加撤销与重做
|
|
||||||
- 维护操作历史栈
|
|
||||||
- 提供 Undo/Redo 方法与按钮
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 阶段三：智能对话基础功能
|
## 九、配置与启动
|
||||||
|
|
||||||
### 3.1 AI 客户端封装
|
### 9.1 常见配置项
|
||||||
|
|
||||||
- [ ] 安装 Go HTTP 客户端库（如 resty 或使用标准库）
|
后端通常会从配置文件或环境变量中读取以下信息：
|
||||||
- [ ] 创建 `services/ai_service.go`
|
|
||||||
- 方法：`NewAIService(apiKey, baseURL)`
|
|
||||||
- 核心方法：`ChatCompletion(messages []Message) (string, error)`
|
|
||||||
- 实现：调用硅基流动 OpenAI Completion 接口
|
|
||||||
- 添加请求超时与错误处理
|
|
||||||
|
|
||||||
- [ ] 请求与响应模型定义
|
- 服务端口
|
||||||
- `models/ai.go`：定义 `Message`、`ChatRequest`、`ChatResponse`
|
- Neo4j URI
|
||||||
- 统一错误类型与包装
|
- Neo4j 用户名
|
||||||
|
- Neo4j 密码
|
||||||
|
- CORS 允许源
|
||||||
|
- 数据文件或迁移相关配置（若启用）
|
||||||
|
|
||||||
### 3.2 对话 API
|
### 9.2 启动方式
|
||||||
|
|
||||||
- [ ] 对话会话管理
|
在 `backend/` 目录下运行：
|
||||||
- 创建 `services/conversation_service.go`
|
|
||||||
- 维护会话上下文（最近 N 条消息）
|
|
||||||
- 方法：`CreateConversation()`、`AddMessage(sessionID, role, content)`、`GetHistory(sessionID)`
|
|
||||||
|
|
||||||
- [ ] 创建对话 API
|
```bash
|
||||||
- POST /api/chat
|
go run ./cmd/server
|
||||||
- 请求体：`{message, sessionId?}`
|
```
|
||||||
- 实现：
|
|
||||||
1. 创建或获取会话
|
|
||||||
2. 添加用户消息到历史
|
|
||||||
3. 调用 `AIService.ChatCompletion`
|
|
||||||
4. 保存 AI 回复到历史
|
|
||||||
5. 返回 AI 回复
|
|
||||||
- 支持流式返回（如平台支持）
|
|
||||||
|
|
||||||
### 3.3 图谱查询与对话集成
|
### 9.3 Swagger 地址
|
||||||
|
|
||||||
- [ ] 知识检索策略
|
启动后访问：
|
||||||
- 在 `neo4j_service.go` 中添加：
|
|
||||||
- `SearchNodesByKeywords(keywords []string) ([]Node, error)`
|
|
||||||
- `GetRelevantContext(nodeID string, depth int) ([]Node, []Edge, error)`
|
|
||||||
- 支持根据消息关键词检索相关节点
|
|
||||||
|
|
||||||
- [ ] 上下文增强生成
|
```text
|
||||||
- 在对话前步骤：
|
http://localhost:3001/swagger/index.html
|
||||||
- 提取消息中的关键实体或关键词
|
```
|
||||||
- 检索图谱中的相关节点与关系
|
|
||||||
- 将检索结果作为系统提示或上下文注入到对话请求
|
|
||||||
- 输出格式：自然语言摘要或结构化 JSON（根据需求）
|
|
||||||
|
|
||||||
- [ ] 优化 AI 提示词
|
|
||||||
- 设计 System Prompt：介绍图谱助手角色与能力
|
|
||||||
- 提供示例对话
|
|
||||||
|
|
||||||
### 3.4 前端对话界面
|
|
||||||
|
|
||||||
- [ ] 创建 Chat 组件
|
|
||||||
- 消息列表（用户消息与 AI 消息）
|
|
||||||
- 输入框与发送按钮
|
|
||||||
- 显示加载状态
|
|
||||||
|
|
||||||
- [ ] 集成到图谱页面
|
|
||||||
- 在 `KnowledgeGraph.tsx` 中添加 Chat 组件
|
|
||||||
- 配置布局（侧边或底部面板）
|
|
||||||
|
|
||||||
- [ ] 增强交互
|
|
||||||
- 支持快捷键发送（Enter）
|
|
||||||
- 显示会话历史切换（可选）
|
|
||||||
- 消息支持 Markdown 渲染
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 后续增强阶段（非 MVP）
|
## 十、当前实现特点
|
||||||
|
|
||||||
- 记忆与自省系统
|
### 10.1 已完成的结构优化
|
||||||
- 邮件自动化
|
|
||||||
- 定时任务
|
- Handler 与 Service 解耦
|
||||||
- CoT 推理增强
|
- 图查询与 CRUD 拆分
|
||||||
|
- 通用 Neo4j 工具统一收口
|
||||||
|
- 使用统一错误结构
|
||||||
|
- 使用 `GraphService` 接口约束业务能力
|
||||||
|
|
||||||
|
### 10.2 当前行为特征
|
||||||
|
|
||||||
|
- 图数据完全由 Neo4j 提供
|
||||||
|
- 节点与边都支持扩展属性
|
||||||
|
- 搜索同时覆盖 `id`、`label`、`type`
|
||||||
|
- 邻居查询会返回邻居节点和边
|
||||||
|
- 简化图数据适合 LLM 或摘要场景
|
||||||
|
|
||||||
|
### 10.3 已知设计取向
|
||||||
|
|
||||||
|
- 以可维护性优先，而不是一开始就追求极致抽象
|
||||||
|
- 保留较直观的 Cypher 语句，方便调试与演进
|
||||||
|
- 优先让 API 形状稳定，方便前端对接
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十一、建议的下一步演进
|
||||||
|
|
||||||
|
1. 补齐测试
|
||||||
|
- service 单元测试
|
||||||
|
- handler 测试
|
||||||
|
- Neo4j 交互测试
|
||||||
|
|
||||||
|
2. 增加批量写入能力
|
||||||
|
- 批量创建节点
|
||||||
|
- 批量创建边
|
||||||
|
|
||||||
|
3. 进一步规范错误语义
|
||||||
|
- `400 Bad Request`
|
||||||
|
- `404 Not Found`
|
||||||
|
- `409 Conflict`
|
||||||
|
- `500 Internal Server Error`
|
||||||
|
|
||||||
|
4. 为对话增强做准备
|
||||||
|
- 上下文检索
|
||||||
|
- 相关节点提取
|
||||||
|
- 简化图摘要注入
|
||||||
|
|
||||||
|
5. 进一步细分 service
|
||||||
|
- 如果后续功能继续增长，可以把查询、编辑、统计、上下文检索拆成更细粒度模块
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 十二、快速理解这套后端
|
||||||
|
|
||||||
|
如果你第一次接触这个项目，可以按这个顺序看：
|
||||||
|
|
||||||
|
1. `cmd/server/main.go`
|
||||||
|
2. `internal/handler/`
|
||||||
|
3. `internal/service/interface.go`
|
||||||
|
4. `internal/service/graph_queries.go`
|
||||||
|
5. `internal/service/graph_crud.go`
|
||||||
|
6. `internal/service/neo4j_utils.go`
|
||||||
|
|
||||||
|
这样能最快理解：
|
||||||
|
|
||||||
|
- 请求如何流动
|
||||||
|
- 图数据如何被读取和修改
|
||||||
|
- 模型如何映射到 Neo4j
|
||||||
|
- 后续扩展点在哪里
|
||||||
|
|||||||
Reference in New Issue
Block a user