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
README.md
+374 -225
View File
@@ -1,277 +1,426 @@
# 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
- 图谱可视化: AntV G6 5.1.0
- 状态管理: Zustand 5.0.12
- 样式: Tailwind CSS 4.2.2
- HTTP 客户端: Axios 1.14.0
### 1.2 核心能力
当前设计中的核心能力包括：
1. 图谱查询
- 查询整图
- 查询节点详情
- 查询邻居关系
- 搜索节点
- 获取统计信息
2. 图谱编辑
- 创建节点
- 更新节点
- 删除节点
- 创建边
- 删除边
3. 对话增强
- 基于图谱检索上下文
- 为 LLM 提供简化图数据
- 为后续 Chat API 预留能力
4. 后续扩展
- 层级记忆
- 自省反馈
- CoT 推理增强
- 邮件自动化
- 定时任务
---
## 阶段一： Neo4j 数据库集成
## 二、整体架构
### 1.1 环境搭建
### 2.1 总体分层
- [x] 连接 Neo4j 5.x 服务器（http://47.121.181.112/）
- 使用服务器提供的数据库实例
- 验证服务运行状态
- 配置基础认证（用户名/密码）
- 记录连接信息（bolt://47.121.181.112:7687）
- [ ] 选择并安装 Go Neo4j 客户端库
- 评估候选库（如 github.com/neo4j/neo4j-go-driver）
- 添加到 go.mod
- 运行 `go mod tidy`
```mermaid
flowchart TB
subgraph UI[用户 / 前端]
User[用户]
Web[Web 前端]
end
- [ ] 配置数据库连接字符串
- 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
- 在 `main.go` 中读取并验证连接
- 实现简单的健康检查接口（GET /db/health）
subgraph API[后端 API 层]
Router[Gin Router]
GH[GraphHandler]
NH[NodeHandler]
SH[SearchHandler]
CRUD[NodeCRUDHandler / EdgeCRUDHandler]
end
### 1.2 数据模型设计与迁移
subgraph APP[业务服务层]
GS[GraphService Interface]
GQ[graph_queries.go]
GC[graph_crud.go]
GSIMPLE[graph_simple.go]
UTL[neo4j_utils.go]
end
- [ ] 设计 Neo4j 节点与边的属性模型
- 节点标签（例如：Concept、Tool、Application）
- 节点属性：id、label、type、properties（JSON）、x、y、style（JSON）
- 关系类型：RELATIONSHIP、DEPENDENCY等
- 关系属性：id、label、type、properties、style（JSON）
subgraph INFRA[基础设施层]
Driver[Neo4j Driver]
Neo4j[(Neo4j 5.x)]
end
- [ ] 编写数据迁移脚本 `scripts/migrate_to_neo4j.go`
- 读取现有 `data.json`
- 创建 Neo4j 节点（批量 CREATE）
- 创建 Neo4j 关系（批量 CREATE）
- 添加唯一约束：`CREATE CONSTRAINT FOR (n:Node) REQUIRE n.id IS UNIQUE`
- 输出迁移统计（节点数、边数）
User --> Web
Web --> Router
Router --> GH
Router --> NH
Router --> SH
Router --> CRUD
- [ ] 执行迁移并验证数据完整性
- 运行迁移脚本
- 在 Neo4j Browser 中执行 Cypher 验证：
- `MATCH (n) RETURN count(n) AS totalNodes`
- `MATCH ()-[r]->() RETURN count(r) AS totalEdges`
- 对比原始 JSON 的统计
GH --> GS
NH --> GS
SH --> GS
CRUD --> GS
### 1.3 Neo4j 数据服务层
GS --> GQ
GS --> GC
GS --> GSIMPLE
GQ --> UTL
GC --> UTL
GSIMPLE --> UTL
- [ ] 创建 `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)`
GQ --> Driver
GC --> Driver
GSIMPLE --> Driver
Driver --> Neo4j
```
- [ ] 在 `services/data_service.go` 中切换数据源
- 移除 JSON 文件加载逻辑
- 注入 `Neo4jService` 依赖
- 更新现有方法委托给 Neo4j 查询：
- `GetGraphData()`
- `GetNodeByID()`
- `GetNeighbors()`
- `SearchNodes()`
- `GetStats()`
### 2.2 请求流转方式
- [ ] 添加并发安全与连接池管理
- 使用 Neo4j 驱动会话管理
- 确保连接池合理设置
- 添加重试机制（简单指数退避）
一次典型请求的流转如下：
### 1.4 API 验证与测试
1. 用户在前端发起请求
2. Gin Router 根据路径分发到对应 handler
3. Handler 解析参数并调用 service
4. Service 执行 Neo4j 查询或写入
5. Neo4j 返回记录后，Service 转换成 API 模型
6. Handler 将结果返回给前端
- [ ] 后端单元测试
- 为 `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
- [ ] 前端兼容性验证
- 服务端无需修改即可兼容现有前端
- 验证图谱渲染、搜索、节点详情、邻居加载
- HTTP 细节停留在 Handler
- 业务逻辑停留在 Service
- 数据访问细节停留在 Neo4j driver 和工具函数中
---
## 阶段二：图谱构建功能增强
## 三、技术栈
### 2.1 后端 CRUD API
### 3.1 后端
- [ ] 创建节点 API
- POST /api/nodes
- 请求体：`{label, type, properties, x, y, style}`
- 实现：调用 Neo4j CREATE 节点
- 返回：新建节点的完整信息
- Go 1.26.1
- Gin 1.12.0
- Neo4j 5.x
- Swagger / Swaggo
- CORS 中间件
- [ ] 更新节点 API
- PUT /api/nodes/:id
- 请求体：`{label, type, properties, x, y, style}`
- 实现：调用 Neo4j SET 更新指定节点属性
- 返回：更新后节点
- 错误处理：节点不存在返回 404
### 3.2 前端
- [ ] 删除节点 API
- DELETE /api/nodes/:id
- 实现：先删除相关关系，再删除节点（或使用 DETACH DELETE）
- 返回：204 No Content 或 404
- 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
- [ ] 创建边（关系）API
- POST /api/edges
- 请求体：`{source, target, label, type, properties, style}`
- 实现：使用 Cypher MATCH + CREATE 创建关系
- 返回：新建边的完整信息
- 验证 source 和 target 节点是否存在
### 3.3 外部能力
- [ ] 更新边 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 方法与按钮
- Neo4j 数据库：存储图谱节点和关系
- 硅基流动 OpenAI Completion：后续用于对话和推理增强
---
## 阶段三：智能对话基础功能
## 四、仓库结构
### 3.1 AI 客户端封装
```mermaid
flowchart TD
Repo[knowledge-graph-agent/] --> RootReadme[README.md]
Repo --> Backend[backend/]
- [ ] 安装 Go HTTP 客户端库（如 resty 或使用标准库）
- [ ] 创建 `services/ai_service.go`
- 方法：`NewAIService(apiKey, baseURL)`
- 核心方法：`ChatCompletion(messages []Message) (string, error)`
- 实现：调用硅基流动 OpenAI Completion 接口
- 添加请求超时与错误处理
Backend --> BackendReadme[README.md]
Backend --> Cmd[cmd/server/]
Backend --> Docs[docs/]
Backend --> Internal[internal/]
- [ ] 请求与响应模型定义
- `models/ai.go`：定义 `Message`、`ChatRequest`、`ChatResponse`
- 统一错误类型与包装
Cmd --> Main[main.go]
### 3.2 对话 API
Internal --> Config[config/]
Internal --> Handler[handler/]
Internal --> Model[model/]
Internal --> Repository[repository/neo4j/]
Internal --> Service[service/]
- [ ] 对话会话管理
- 创建 `services/conversation_service.go`
- 维护会话上下文（最近 N 条消息）
- 方法：`CreateConversation()`、`AddMessage(sessionID, role, content)`、`GetHistory(sessionID)`
Handler --> GH[graph_handler.go]
Handler --> NH[node_handler.go]
Handler --> SH[search_handler.go]
Handler --> CRUD[crud_handler.go]
- [ ] 创建对话 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 渲染
Service --> IF[interface.go]
Service --> Q[graph_queries.go]
Service --> C[graph_crud.go]
Service --> S[graph_simple.go]
Service --> U[neo4j_utils.go]
```
---
## 后续增强阶段（非 MVP）
## 五、后端模块说明
如果你只看后端，建议优先阅读 `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 自动化能力
- 邮件自动化
- 定时任务
- CoT 推理增强
- 触发式工作流
### 12.3 推理增强
- CoT 提示增强
- 图谱检索增强生成
- 多轮上下文压缩
### 12.4 工程化增强
- 批量操作 API
- 权限控制
- 审计日志
- 测试覆盖率提升
- 统一错误码与响应规范
---
## 十三、补充说明
如果你后面希望我继续整理，我可以直接帮你做下面任一项：
- 把根目录 README 再改成“项目介绍版”或“开发指南版”
- 给后端 README 增加更细的接口表格和请求/响应样例
- 继续补一张“前后端交互时序图”
- 把整个项目的文档风格统一成一套模板