knowledge-graph-agent/backend

knowledge-graph-agent

🤖 以知识图谱为核心的学习辅助对话智能体，集成 层级记忆、自省反馈、CoT、邮件自动化等技术

Swagger 文档

---

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

---

阶段一： Neo4j 数据库集成

1.1 环境搭建

• 连接 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

• 配置数据库连接字符串

  • 新增配置文件或环境变量：NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD
  • 在 main.go 中读取并验证连接
  • 实现简单的健康检查接口（GET /db/health）

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 推理增强