Skip to content
BranchesTags

Repository files navigation

🧠 Knowledge Graph App

一个高颜值、可交互、支持多画板的知识图谱编辑器

用辐射状布局把知识组织成「主题 → 能力域 → 概念」三层结构，拖拽、连线、展开折叠、自动保存、导出分享，一气呵成。

React 19 · TypeScript · Vite · Zustand · Express · SQLite

✨ 特性一览

能力 说明
🎯 辐射状三层布局 主题居中 → 能力域成环 → 概念递归子树展开，自动消除重叠
🖱️ 自由拖拽 + 智能布线 节点任意拖动定位，连线自适应曲率 + 同源扇形展开，不交叉不穿透
🔗 六种语义关系 先修 / 依赖 / 调用 / 实现 / 应用 / 相关，选中节点自动派生关联视图
💾 改即保存 500ms 防抖自动落库 SQLite，拖拽、折叠、增删改全程持久化，零手动操作
🎨 三套主题 Panda 深色暖调 · JetBrains 深色冷调 · Claude 浅色米调，一键切换
✨ 流光动效 SVG 虚线流光 + 节点脉冲发光 + hover 浮起，视觉层次清晰
📤 双格式导出 PNG 2× 高清截图 · 单文件离线 HTML（双击即可打开，保留全部动效）
🗂️ 多画板管理 独立知识空间随意切换，内置 LangChain / LangGraph 两套示例图谱

🚀 快速开始

环境要求

  • Node.js ≥ 18（推荐 20+）
  • npm 或 pnpm

安装 & 运行

# 1. 克隆仓库
git clone https://github.com/DevYangJC/knowledge-graph-app.git
cd knowledge-graph-app

# 2. 安装依赖
npm install

# 3. 一键启动前后端（推荐 ⭐）
npm run start:all

启动后：

服务 地址
前端页面 http://localhost:3000
后端 API http://localhost:3001/api/boards

首次启动会自动 seed 两块内置画板：LangChain 核心知识图谱（23 概念 · 6 域）和 LangGraph 知识图谱（26 概念 · 6 域）。

分别启动（调试用）

# 终端 1：后端
npm run server

# 终端 2：前端
npm run dev

其他命令

npm run build    # 生产构建（tsc 类型检查 + vite 打包）
npm run test     # 运行单元测试（vitest）
npm run lint     # 代码检查（oxlint）

📖 使用指南

节点操作

操作 方式
展开/折叠能力域 点击能力域 Hub 节点
自由拖拽 按住任意节点拖动，松手即保存位置
快捷派生子节点 悬浮节点 → 点击右侧 + 按钮
精准添加节点 工具栏 + 添加概念节点，可选图标、能力域、描述
编辑节点 选中节点 → 右侧卡片 编辑，改标题/描述/图标/外链
删除节点 右侧卡片 删除，同步清除所有关联连线

连线与关系

  1. 点击工具栏 连线模式
  2. 依次点击【起始节点】→【目标节点】
  3. 在弹窗中选择关系类型：
关系 含义 视觉
先修 Prerequisite 目标依赖此节点 实线 · 琥珀色
依赖 Depends On 同先修，反向语义 实线 · 琥珀色
调用 Calls 数据/接口调用 虚线 · 天蓝色
实现 Implements 架构落地实现 虚线 · 紫色
应用 Application 场景应用落地 实线 · 翡翠色
相关 Related 泛化关联 虚线 · 灰色 · 无箭头

选中任意节点后，右侧卡片自动归类展示其先修概念、被依赖概念、调用关系与应用实例。

画布交互

操作 方式
平移画布 拖拽空白区域
缩放 滚轮 / 右下角 + - 按钮
适应居中 右下角 适应居中 按钮

导出分享

  • 导出 PNG：工具栏 → 导出 PNG，2× 高清像素比，适合截图分享
  • 导出 HTML：工具栏 → 导出 HTML，生成单文件离线网页，file:/// 双击即可打开，保留流光动效、缩放、详情侧边栏

🏗️ 技术架构

技术栈

层 技术
前端框架 React 19 + TypeScript 6
构建工具 Vite 8 + vite-plugin-singlefile
状态管理 Zustand 5（三 store 分离 + facade 合并）
样式 Tailwind CSS 4 + CSS 变量主题系统
校验 Zod 4（Schema 驱动的运行时类型校验）
后端 Node.js + Express 5
数据库 better-sqlite3（WAL 模式）
测试 Vitest 4（14 个单元测试）
Lint oxlint

项目结构

knowledge-graph-app/
├── server/                         # 后端
│   ├── index.ts                    #   Express API 入口（端口 3001）
│   ├── db.ts                       #   SQLite 操作层（CRUD + 迁移）
│   ├── migrate.ts                  #   JSON → SQLite 数据迁移
│   └── data/                       #   数据库文件（WAL 模式）
│
├── src/                            # 前端
│   ├── components/
│   │   ├── GraphCanvas/            #   画布核心（Canvas / 节点 / SVG 连线）
│   │   ├── Modals/                 #   弹窗（新建画板/节点/连线/图标选择）
│   │   ├── Header.tsx              #   顶栏（画板切换/保存/主题）
│   │   ├── Toolbar.tsx             #   工具栏（搜索/增删/连线/导出）
│   │   ├── DetailSidebar.tsx       #   右侧详情卡片
│   │   ├── Legend.tsx              #   关系图例
│   │   └── ZoomControls.tsx        #   缩放控件
│   ├── store/
│   │   ├── useGraphDataStore.ts    #   图数据（节点/边/域/位置）
│   │   ├── useBoardStore.ts        #   画板持久化（API 调用/自动保存）
│   │   ├── useUIStore.ts           #   UI 状态（主题/选中/编辑态）
│   │   └── useGraphStore.ts        #   三 store 合并 facade
│   ├── hooks/
│   │   └── useGraphLayout.ts       #   递归子树布局 + 碰撞松弛算法
│   ├── utils/
│   │   ├── geometry.ts             #   贝塞尔曲线 / 自适应曲率 / 边界裁剪
│   │   └── exportHtml.ts           #   单文件离线 HTML 生成器
│   ├── assets/theme.css            #   三套主题 + 流光动画
│   └── types/graph.ts              #   Zod Schema + TS 类型
│
├── tests/                          # 单元测试
│   ├── db.test.ts                  #   数据库 CRUD + Schema 校验
│   ├── geometry.test.ts            #   几何计算函数
│   ├── store.test.ts               #   图数据 store 操作
│   └── sidebar.test.ts             #   关系派生逻辑
│
└── package.json

核心设计

布局算法（useGraphLayout.ts）

采用递归子树布局 + 力导向微调两段式策略：

  1. 递归子树布局：以 Hub 为根，按 parentId 递归构建子树。预计算每个子树的包围盒，按子树高度排序后分配不重叠的垂直空间，X 坐标按层级深度递增。保证初始布局零重叠。
  2. 力导向微调：relaxPositions 做轻量 AABB 碰撞分离（40 次松弛 + 10 次强制分离），处理 pinned 节点占位与边界情况。

性能优化

  • 拖拽解耦：setPinnedPosition 只改 pinnedPositions，不克隆整个 nodes 数组，避免 O(n²) 布局重算
  • rAF 合并：拖拽时用 requestAnimationFrame 合并同帧多次 pointermove，60+ 次/秒 → 60 帧/秒
  • 细粒度订阅：节点组件用 React.memo + selector 订阅，只重渲染自身位置变化的节点
  • 自适应迭代：布局已不重叠后，松弛迭代从 230 次降到 50 次

自动保存

  • Zustand subscribe 监听 currentBoard / pinnedPositions / expandedDomains 三路变更
  • 500ms 防抖触发 PUT /api/boards/:id
  • isSavingInProgress 标志位防止保存回写 setBoardData 触发循环

连线渲染（geometry.ts + Canvas.tsx）

  • 自适应曲率：curveOffset = clamp(dist × 0.14, 8, 48)，近距弯小、远距弯大
  • 同源扇形展开：同一父节点的多条出边按索引分配曲率偏移，像树枝自然张开
  • AABB 边界裁剪：连线起终点精确裁剪到节点卡片边缘 + gap，不穿透不悬空

📡 API 文档

后端提供 5 个 RESTful 端点：

方法 路径 说明
GET /api/boards 获取所有画板摘要列表
GET /api/boards/:id 获取指定画板完整数据（含节点、边、位置）
POST /api/boards 新建画板（Zod 校验 CreateBoardDTO）
PUT /api/boards/:id 保存/更新画板（Zod 校验 Board）
DELETE /api/boards/:id 删除画板（default-gbrain 禁止删除）

🧪 测试

npm run test

覆盖数据库 CRUD、几何计算、图数据操作、关系派生逻辑，共 14 个测试用例。

📦 内置示例画板

画板 内容
LangChain 核心知识图谱 23 个概念 · 6 个能力域（LangChain 核心抽象、链与调用、记忆与上下文、Agent 与工具、检索增强、应用模式）
LangGraph 知识图谱 26 个概念 · 6 个能力域（核心抽象、状态管理、图的控制流、编译与执行、持久化与记忆、多 Agent 架构）

📄 License

本项目未声明开源许可证，package.json 标记为 "private": true。如需使用请联系作者。

如果这个项目对你有帮助，欢迎 ⭐ Star 支持！

About

基于 React 19 + Vite + Express + SQLite 的交互式知识图谱可视化应用，支持节点拖拽编辑、关系连线、自动布局、多画板管理与高清导出。

Topics

graph-visualizationinteractive-graphicsknowledge-graphmind-mapreactjs

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages