wonder/knowledge-graph-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 优化 README

Browse Source
This commit is contained in:
wonder
2026-04-28 13:00:07 +08:00
parent f998f78c80
commit 10d5578a43
2 changed files with 850 additions and 442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/README.md
+476 -217
View File
@@ -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 开发任务清单
## 一、系统定位
### 技术栈
当前后端主要承担以下职责：
**后端**
- 语言: Go 1.26.1
- 框架: Gin 1.12.0
- 数据库: 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
1. 对外暴露图谱相关 HTTP API
2. 将前端请求转换为对 Neo4j 的查询或写入
3. 统一节点、边、图数据、错误响应的格式
4. 为后续 LLM / 对话增强能力预留简化图数据与上下文检索接口
---
## 阶段一： Neo4j 数据库集成
## 二、运行时架构
### 1.1 环境搭建
### 2.1 整体调用链
- [x] 连接 Neo4j 5.x 服务器（http://47.121.181.112/）
- 使用服务器提供的数据库实例
- 验证服务运行状态
- 配置基础认证（用户名/密码）
- 记录连接信息（bolt://47.121.181.112:7687）
- [x] 选择并安装 Go Neo4j 客户端库
- 评估候选库（如 github.com/neo4j/neo4j-go-driver）
- 添加到 go.mod
- 运行 `go mod tidy`
```mermaid
flowchart LR
Client[前端 / Postman / curl] --> Router[gin.Engine]
Router --> Health[/GET /health/]
Router --> Swagger[/GET /swagger/*any/]
Router --> API[/GET /api/*\nPOST /api/*\nPUT /api/*\nDELETE /api/*/]
- [x] 配置数据库连接字符串
- 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
- 在 `main.go` 中读取并验证连接
- 实现简单的健康检查接口（GET /db/health）
API --> GH[GraphHandler]
API --> NH[NodeHandler]
API --> SH[SearchHandler]
API --> CRUD[NodeCRUDHandler / EdgeCRUDHandler]
### 1.2 数据模型设计与迁移
GH --> SVC[GraphService]
NH --> SVC
SH --> SVC
CRUD --> SVC
- [x] 设计 Neo4j 节点与边的属性模型
- 节点标签（例如：Concept、Tool、Application）
- 节点属性：id、label、type、properties（JSON）、x、y、style（JSON）
- 关系类型：RELATIONSHIP、DEPENDENCY等
- 关系属性：id、label、type、properties、style（JSON）
SVC --> Q[graph_queries.go]
SVC --> C[graph_crud.go]
SVC --> X[graph_simple.go]
SVC --> U[neo4j_utils.go]
- [ ] 编写数据迁移脚本 `scripts/migrate_to_neo4j.go`
- 读取现有 `data.json`
- 创建 Neo4j 节点（批量 CREATE）
- 创建 Neo4j 关系（批量 CREATE）
- 添加唯一约束：`CREATE CONSTRAINT FOR (n:Node) REQUIRE n.id IS UNIQUE`
- 输出迁移统计（节点数、边数）
Q --> D[Neo4j Driver]
C --> D
X --> D
D --> DB[(Neo4j 5.x)]
```
- [ ] 执行迁移并验证数据完整性
- 运行迁移脚本
- 在 Neo4j Browser 中执行 Cypher 验证：
- `MATCH (n) RETURN count(n) AS totalNodes`
- `MATCH ()-[r]->() RETURN count(r) AS totalEdges`
- 对比原始 JSON 的统计
### 2.2 分层职责
### 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)`
入口位于 `cmd/server/main.go`。
- [ ] 在 `services/data_service.go` 中切换数据源
- 移除 JSON 文件加载逻辑
- 注入 `Neo4jService` 依赖
- 更新现有方法委托给 Neo4j 查询：
- `GetGraphData()`
- `GetNodeByID()`
- `GetNeighbors()`
- `SearchNodes()`
- `GetStats()`
这一层负责：
- [ ] 添加并发安全与连接池管理
- 使用 Neo4j 驱动会话管理
- 确保连接池合理设置
- 添加重试机制（简单指数退避）
- 加载配置
- 初始化 Neo4j 驱动
- 创建 service 实例
- 创建 handler 实例
- 注册路由与 Swagger
- 启动 HTTP 服务
### 1.4 API 验证与测试
#### Handler 层
- [ ] 后端单元测试
- 为 `neo4j_service.go` 编写测试
- Mock Neo4j 驱动（如有工具支持）或使用集成测试
- 测试搜索与邻居查询
目录：`internal/handler/`
- [ ] API 契约测试
- 使用 Postman 或 curl 验证：
- GET /api/graph
- GET /api/nodes/:id
- GET /api/nodes/:id/neighbors
- GET /api/search?q=query
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 驱动初始化与连接配置。
---
## 阶段二：图谱构建功能增强
## 三、模块关系图
### 2.1 后端 CRUD API
### 3.1 控制流关系
- [ ] 创建节点 API
- POST /api/nodes
- 请求体：`{label, type, properties, x, y, style}`
- 实现：调用 Neo4j CREATE 节点
- 返回：新建节点的完整信息
```mermaid
flowchart TD
subgraph HTTP[HTTP API]
GH[GraphHandler]
NH[NodeHandler]
SH[SearchHandler]
CH[NodeCRUDHandler]
EH[EdgeCRUDHandler]
end
- [ ] 更新节点 API
- PUT /api/nodes/:id
- 请求体：`{label, type, properties, x, y, style}`
- 实现：调用 Neo4j SET 更新指定节点属性
- 返回：更新后节点
- 错误处理：节点不存在返回 404
subgraph Domain[Service Layer]
GS[GraphService Interface]
GQ[graph_queries.go]
GC[graph_crud.go]
GSIMPLE[graph_simple.go]
UTIL[neo4j_utils.go]
end
- [ ] 删除节点 API
- DELETE /api/nodes/:id
- 实现：先删除相关关系，再删除节点（或使用 DETACH DELETE）
- 返回：204 No Content 或 404
subgraph Infra[Infrastructure]
DRIVER[Neo4j Driver]
DB[(Neo4j Database)]
end
- [ ] 创建边（关系）API
- POST /api/edges
- 请求体：`{source, target, label, type, properties, style}`
- 实现：使用 Cypher MATCH + CREATE 创建关系
- 返回：新建边的完整信息
- 验证 source 和 target 节点是否存在
GH --> GS
NH --> GS
SH --> GS
CH --> GS
EH --> GS
- [ ] 更新边 API
- PUT /api/edges/:id
- 请求体：`{label, type, properties, style}`
- 实现：使用 Cypher 找到边并 SET 属性
- 返回：更新后边
GS --> GQ
GS --> GC
GS --> GSIMPLE
GQ --> UTIL
GC --> UTIL
GSIMPLE --> UTIL
- [ ] 删除边 API
- DELETE /api/edges/:id
- 实现：Cypher DELETE 关系
- 返回：204 No Content 或 404
GQ --> DRIVER
GC --> DRIVER
GSIMPLE --> DRIVER
DRIVER --> DB
```
### 2.2 批量操作 API
### 3.2 数据结构关系
- [ ] 批量创建节点 API
- POST /api/nodes/batch
- 请求体：`{nodes: [...]}`
- 实现：事务批量创建，任一失败则全部回滚
- 返回：成功与失败清单
```mermaid
classDiagram
class GraphData {
+[]Node nodes
+[]Edge edges
}
- [ ] 批量创建边 API
- POST /api/edges/batch
- 请求体：`{edges: [...]}`
- 实现：事务批量创建边
- 返回：创建成功数量与失败清单
class SimpleGraphData {
+[]SimpleNode nodes
+[]SimpleEdge edges
}
### 2.3 前端编辑界面
class Node {
+string id
+string label
+string type
+float64 x
+float64 y
+map style
+map properties
}
- [ ] 新增编辑状态与管理
- 在 `graphStore.ts` 中添加 `editingNode` 与 `editingEdge`
- 添加方法：`startEditingNode(node)`、`startEditingEdge(edge)`、`cancelEditing()`、`saveNode/Edge()`
class Edge {
+string id
+string source
+string target
+string label
+string type
+map style
+map properties
}
- [ ] 节点编辑 Dialog 组件
- 表单字段：label、type、properties（JSON 编辑器）、x、y、style（JSON 编辑器）
- 用于新建与更新节点
- 集成到节点详情面板或右键菜单
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
}
- [ ] 边编辑 Dialog 组件
- 表单字段：label、type、properties、style
- 用于新建与更新边
- 集成到边点击交互或右键菜单
- [ ] 增强图谱视图交互
- 支持从工具栏拖拽创建节点
- 支持通过连线工具创建边（点击两个节点）
- 实时回显编辑结果
### 2.4 数据持久化与刷新
- [ ] 前端自动刷新机制
- CRUD 操作后自动调用 `loadGraphData()` 刷新图谱
- 优化：对于增量更新，避免全量重绘
- [ ] 添加撤销与重做
- 维护操作历史栈
- 提供 Undo/Redo 方法与按钮
GraphData --> Node
GraphData --> Edge
SimpleGraphData --> Node
SimpleGraphData --> Edge
GraphService ..> GraphData
GraphService ..> SimpleGraphData
GraphService ..> Node
GraphService ..> Edge
```
---
## 阶段三：智能对话基础功能
## 四、API 能力
### 3.1 AI 客户端封装
### 4.1 健康检查
- [ ] 安装 Go HTTP 客户端库（如 resty 或使用标准库）
- [ ] 创建 `services/ai_service.go`
- 方法：`NewAIService(apiKey, baseURL)`
- 核心方法：`ChatCompletion(messages []Message) (string, error)`
- 实现：调用硅基流动 OpenAI Completion 接口
- 添加请求超时与错误处理
- `GET /health`
- [ ] 请求与响应模型定义
- `models/ai.go`：定义 `Message`、`ChatRequest`、`ChatResponse`
- 统一错误类型与包装
用途：确认服务是否运行。
### 3.2 对话 API
返回示例：
- [ ] 对话会话管理
- 创建 `services/conversation_service.go`
- 维护会话上下文（最近 N 条消息）
- 方法：`CreateConversation()`、`AddMessage(sessionID, role, content)`、`GetHistory(sessionID)`
```json
{
"status": "ok",
"message": "Knowledge Graph API is running",
"version": "1.0.0"
}
```
- [ ] 创建对话 API
- POST /api/chat
- 请求体：`{message, sessionId?}`
- 实现：
1. 创建或获取会话
2. 添加用户消息到历史
3. 调用 `AIService.ChatCompletion`
4. 保存 AI 回复到历史
5. 返回 AI 回复
- 支持流式返回（如平台支持）
### 4.2 图数据查询
### 3.3 图谱查询与对话集成
- `GET /api/graph`
- 返回完整节点与边
- `GET /api/graph/stats`
- 返回节点数、边数和分类统计
- `GET /api/graph/simpleJson`
- 返回简化图数据，适合 LLM 或轻量消费端
- [ ] 知识检索策略
- 在 `neo4j_service.go` 中添加：
- `SearchNodesByKeywords(keywords []string) ([]Node, error)`
- `GetRelevantContext(nodeID string, depth int) ([]Node, []Edge, error)`
- 支持根据消息关键词检索相关节点
### 4.3 节点查询
- [ ] 上下文增强生成
- 在对话前步骤：
- 提取消息中的关键实体或关键词
- 检索图谱中的相关节点与关系
- 将检索结果作为系统提示或上下文注入到对话请求
- 输出格式：自然语言摘要或结构化 JSON（根据需求）
- `GET /api/nodes/:id`
- 获取单个节点
- `GET /api/nodes/:id/neighbors`
- 获取该节点的邻居节点和相关边
- [ ] 优化 AI 提示词
- 设计 System Prompt：介绍图谱助手角色与能力
- 提供示例对话
### 4.4 搜索
### 3.4 前端对话界面
- `GET /api/search?q=xxx`
- 根据 `id`、`label`、`type` 模糊搜索节点
- [ ] 创建 Chat 组件
- 消息列表（用户消息与 AI 消息）
- 输入框与发送按钮
- 显示加载状态
### 4.5 图谱编辑
- [ ] 集成到图谱页面
- 在 `KnowledgeGraph.tsx` 中添加 Chat 组件
- 配置布局（侧边或底部面板）
- [ ] 增强交互
- 支持快捷键发送（Enter）
- 显示会话历史切换（可选）
- 消息支持 Markdown 渲染
- `POST /api/nodes`
- `PUT /api/nodes/:id`
- `DELETE /api/nodes/:id`
- `POST /api/edges`
- `DELETE /api/edges/:id`
---
## 后续增强阶段（非 MVP）
## 五、请求与响应模型
- 记忆与自省系统
- 邮件自动化
- 定时任务
- CoT 推理增强
### 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`
负责读取类功能：
- `GetGraphData()`
- `GetNodeByID()`
- `SearchNodes()`
- `GetNeighbors()`
- `GetStats()`
这些方法面向“查询场景”，不修改数据库内容。
### 7.2 `graph_crud.go`
负责写入类功能：
- `CreateNode()`
- `UpdateNode()`
- `DeleteNode()`
- `CreateEdge()`
- `DeleteEdge()`
这些方法面向“编辑场景”，负责校验、写入、返回更新后的模型。
### 7.3 `graph_simple.go`
负责提供一个轻量版本的图数据：
- `GetSimpleGraphData()`
适合：
- LLM 上下文注入
- 快速摘要
- 轻量前端消费
---
## 八、目录结构
```mermaid
flowchart TD
Root[backend/] --> Cmd[cmd/server/]
Root --> Docs[docs/]
Root --> Internal[internal/]
Root --> README[README.md]
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 --> Interface[interface.go]
Service --> Q[graph_queries.go]
Service --> C[graph_crud.go]
Service --> Simple[graph_simple.go]
Service --> Utils[neo4j_utils.go]
```
---
## 九、配置与启动
### 9.1 常见配置项
后端通常会从配置文件或环境变量中读取以下信息：
- 服务端口
- Neo4j URI
- Neo4j 用户名
- Neo4j 密码
- CORS 允许源
- 数据文件或迁移相关配置（若启用）
### 9.2 启动方式
在 `backend/` 目录下运行：
```bash
go run ./cmd/server
```
### 9.3 Swagger 地址
启动后访问：
```text
http://localhost:3001/swagger/index.html
```
---
## 十、当前实现特点
### 10.1 已完成的结构优化
- Handler 与 Service 解耦
- 图查询与 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
- 后续扩展点在哪里