knowledge-graph-agent

知识图谱驱动的学习辅助对话智能体项目。

这个项目的目标不是单纯做一个聊天机器人，而是把“知识图谱”“对话”“记忆”“检索”“自动化”组合成一个可演进的智能体系统：

• 以知识图谱作为核心数据结构
• 以图谱查询作为对话上下文补充
• 以图谱编辑作为知识沉淀方式
• 以后续的记忆、自省、任务编排作为增强方向

---

一、项目目标

1.1 解决什么问题

传统问答系统通常只有“输入文本 -> 生成回答”的链路，缺少可追溯、可扩展、可持续积累的知识结构。

本项目希望补上这几个部分：

• 把知识拆成节点和边，形成图谱
• 让用户可以查询、编辑、扩展知识
• 让对话不仅依赖模型参数，还能依赖图谱上下文
• 为后续的记忆层、自省层、任务层预留架构

1.2 核心能力

当前设计中的核心能力包括：

1. 图谱查询

   • 查询整图
   • 查询节点详情
   • 查询邻居关系
   • 搜索节点
   • 获取统计信息

2. 图谱编辑

   • 创建节点
   • 更新节点
   • 删除节点
   • 创建边
   • 删除边

3. 对话增强

   • 基于图谱检索上下文
   • 为 LLM 提供简化图数据
   • 为后续 Chat API 预留能力

4. 后续扩展

   • 层级记忆
   • 自省反馈
   • CoT 推理增强
   • 邮件自动化
   • 定时任务

---

二、整体架构

2.1 总体分层

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：后续用于对话和推理增强

---

四、仓库结构

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
• 图谱上下文检索
• 记忆与自省系统

---

十、文档关系图

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 增加更细的接口表格和请求/响应样例
• 继续补一张“前后端交互时序图”
• 把整个项目的文档风格统一成一套模板