wonder/knowledge-graph-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
knowledge-graph-agent/README.md
T
wonder 10d5578a43 docs: 优化 README
2026-04-28 13:00:07 +08:00

8.1 KiB
Raw Permalink Blame History

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