hhs
280 lines
8.2 KiB
Markdown
280 lines
8.2 KiB
Markdown
# knowledge-graph-agent
|
||
|
||
🤖 以知识图谱为核心的学习辅助对话智能体，集成 层级记忆、自省反馈、CoT、邮件自动化等技术
|
||
|
||
[Swagger 文档](http://localhost:3001/swagger/index.html)
|
||
|
||
---
|
||
|
||
## 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 环境搭建
|
||
|
||
- [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`
|
||
|
||
- [x] 配置数据库连接字符串
|
||
- 新增配置文件或环境变量：`NEO4J_URI`、`NEO4J_USERNAME`、`NEO4J_PASSWORD`
|
||
- 在 `main.go` 中读取并验证连接
|
||
- 实现简单的健康检查接口（GET /db/health）
|
||
|
||
### 1.2 数据模型设计与迁移
|
||
|
||
- [x] 设计 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 推理增强
|