knowledge-graph-agent/README.md

# knowledge-graph-agent

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

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

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

---

## 一、项目目标

### 1.1 解决什么问题

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

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

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

### 1.2 核心能力

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

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

2. 图谱编辑
   - 创建节点
   - 更新节点
   - 删除节点
   - 创建边
   - 删除边

3. 对话增强
   - 基于图谱检索上下文
   - 为 LLM 提供简化图数据
   - 为后续 Chat API 预留能力

4. 后续扩展
   - 层级记忆
   - 自省反馈
   - CoT 推理增强
   - 邮件自动化
   - 定时任务

---

## 二、整体架构

### 2.1 总体分层

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

---

## 四、仓库结构

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

---

## 十、文档关系图

```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 自动化能力

- 邮件自动化
- 定时任务
- 触发式工作流

### 12.3 推理增强

- CoT 提示增强
- 图谱检索增强生成
- 多轮上下文压缩

### 12.4 工程化增强

- 批量操作 API
- 权限控制
- 审计日志
- 测试覆盖率提升
- 统一错误码与响应规范

---

## 十三、补充说明

如果你后面希望我继续整理，我可以直接帮你做下面任一项：

- 把根目录 README 再改成“项目介绍版”或“开发指南版”
- 给后端 README 增加更细的接口表格和请求/响应样例
- 继续补一张“前后端交互时序图”
- 把整个项目的文档风格统一成一套模板