# kgraph

**Repository Path**: 741852963/kgraph

## Basic Information

- **Project Name**: kgraph
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KnowledgeGraph — 全领域知识图谱 MCP Server

> AI 原生的第二大脑：基于 Go + SQLite + MCP 协议的全领域知识库，支持哲学、历史、文学、经济等任意领域的知识存储与跨域联想。

---

## 目录

- [项目概述](#项目概述)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [使用说明](#使用说明)
  - [MCP 模式（Claude Desktop）](#1-mcp-模式claude-desktop)
  - [Web UI 模式](#2-web-ui-模式)
  - [REST API](#3-rest-api)
  - [MCP 工具](#4-mcp-工具)
- [数据模型](#数据模型)
- [知识分类体系](#知识分类体系)
- [知识抽取技能](#知识抽取技能)
- [项目结构](#项目结构)
- [开发指南](#开发指南)
- [配置说明](#配置说明)

---

## 项目概述

### 核心理念

打造一个 **"AI 原生（AI-Native）"** 的第二大脑。它不仅是笔记工具，更是 AI 模型进行深度推理、跨领域联想（从《资本论》联想到明朝税制）的**语义燃料库**。

### 设计原则

| 原则 | 说明 |
|------|------|
| **全领域兼容** | 历史学、文学、经济学、哲学、社会学等任意领域，统一 Node 模型存储 |
| **Schema-less 灵活性** | JSON metadata 存储领域专有属性，无需改表结构 |
| **本地优先（Local First）** | 数据 100% 归属用户，SQLite 本地存储 |
| **双通道交互** | AI 通过 MCP 协议读写；人类通过 Web UI 漫游图谱 |
| **双链知识图谱** | 节点间多类型关系（引用/因果/对立/包含），支持 `[[双链]]` 语法 |

---

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                      客户端层                            │
│  ┌──────────────┐  ┌──────────────────────────────────┐ │
│  │ Claude Desktop│  │  Web UI (Vue 3 + Element Plus)  │ │
│  │  MCP Stdio   │  │  图谱漫游 / 编辑器 / 命令面板    │ │
│  └──────┬───────┘  └────────────┬─────────────────────┘ │
└─────────┼───────────────────────┼───────────────────────┘
          │ MCP/Stdio             │ HTTP
          ▼                       ▼
┌─────────────────────────────────────────────────────────┐
│                    服务端 (Go)                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  MCP Server  │  │  REST API    │  │  静态资源     │ │
│  │  /mcp        │  │  /api/*      │  │  / (前端)     │ │
│  └──────┬───────┘  └──────┬───────┘  └──────────────┘ │
│         │                 │                             │
│  ┌──────┴─────────────────┴──────────────────────────┐ │
│  │              Service 层 (业务逻辑)                  │ │
│  │  NodeService / GraphService / SearchService / Tag  │ │
│  └──────────────────────┬────────────────────────────┘ │
│  ┌──────────────────────┴────────────────────────────┐ │
│  │            Repository 层 (数据访问)                 │ │
│  └──────────────────────┬────────────────────────────┘ │
└─────────────────────────┼──────────────────────────────┘
                          ▼
              ┌───────────────────────┐
              │  SQLite (FTS5 + JSON) │
              │  nodes / relations /  │
              │  tags / metadata_flat │
              └───────────────────────┘
```

### 技术栈

| 分类 | 技术 | 说明 |
|------|------|------|
| **后端** | Go 1.26+ | 高并发，单一二进制 |
| **MCP SDK** | `mark3labs/mcp-go` v0.56 | MCP 协议实现 |
| **数据库** | SQLite (`modernc.org/sqlite`) | 无 CGO，纯 Go，支持 JSON1 + FTS5 |
| **中文分词** | gse (`github.com/go-ego/gse`) | 词典分词 + 搜索模式，支持自定义词典 |
| **ORM** | GORM + `datatypes.JSON` | 动态 metadata 支持 |
| **前端** | Vue 3 + TypeScript + Vite | 组合式 API |
| **UI** | Element Plus + UnoCSS | 组件库 + 原子化样式 |
| **状态管理** | Pinia | 模块化 Store |
| **图谱可视化** | vis-network | 知识图谱力导向布局 |
| **图表** | ECharts (vue-echarts) | 仪表盘统计 |

---

## 快速开始

### 前置条件

- Go 1.26+ （服务端编译）
- Node.js 18+ （前端开发，仅 Web UI 模式需要）

### 1. 编译服务端

```bash
cd server
go build -o knowledgegraph.exe .
```

### 2. 启动服务

**MCP Stdio 模式**（供 Claude Desktop 等 AI 客户端使用）：

```bash
./knowledgegraph.exe -db ./data/knowledge.db
```

**Web UI 模式**（REST API + 前端界面）：

```bash
./knowledgegraph.exe -ui -port 8080 -db ./data/knowledge.db
```

启动后访问 http://localhost:8080 即可使用 Web 界面。

### 3. 前端开发（可选）

如需修改前端，在 `web/` 目录下开发：

```bash
cd web
npm install
npm run dev        # 开发模式，http://localhost:5173
npm run build      # 构建到 web/dist/
```

---

## 使用说明

### 1. MCP 模式（Claude Desktop）

在 Claude Desktop 的 `claude_desktop_config.json` 中配置：

```json
{
  "mcpServers": {
    "knowledgegraph": {
      "command": "D:/code/knowledgeGraph/knowledgegraph.exe",
      "args": ["-db", "D:/code/knowledgeGraph/data/knowledge.db"]
    }
  }
}
```

配置后，Claude 即可通过 MCP 工具直接读写知识图谱。

### 2. Web UI 模式

```bash
./knowledgegraph.exe -ui -port 8080
```

启动后访问 http://localhost:8080 即可使用 Web 界面。

#### 功能页面一览

**📊 仪表盘** — 知识库全局概览，统计节点数、关系数、标签分布等

![仪表盘](./docs/screenshots/dashboard.png)

**📋 节点列表** — 浏览和管理所有知识节点，支持按类型/状态筛选、搜索

![节点列表](./docs/screenshots/node-list.png)

**📝 节点详情** — 查看节点完整信息，包括内容、元数据、关联节点、标签等

![节点详情](./docs/screenshots/node-detail.png)

**🕸️ 知识图谱** — 力导向布局可视化，支持节点悬停查看信息、图例过滤、搜索联想高亮

![知识图谱](./docs/screenshots/graph-viewer.png)

图谱交互功能：
- **悬停节点** → 弹出信息卡，显示标题、类型、浏览次数等基本信息

![图谱悬停提示](./docs/screenshots/graph-hover-tooltip.png)

- **搜索联想** → 输入关键词自动联想匹配节点，选中后定位高亮
- **图例过滤** → 点击右侧图例中的类型项，切换对应节点的显示/隐藏
- **连线标签** → 关系类型以中文显示（引用、因果、对立、包含等）

**🌳 知识树** — 树形层级浏览，快速定位父子关系

![知识树](./docs/screenshots/tree-browser.png)

**🔍 搜索** — 全文搜索，结果以可视化卡片展示

![搜索结果](./docs/screenshots/search-result.png)

#### 路由总览

| 功能 | 路径 | 说明 |
|------|------|------|
| 仪表盘 | `/dashboard` | 知识库统计概览 |
| 节点列表 | `/nodes` | 浏览/筛选/管理节点 |
| 节点详情 | `/nodes/:id` | 节点完整信息 |
| 知识图谱 | `/graph` | 力导向可视化 + 搜索 + 过滤 |
| 知识树 | `/tree` | 树形层级浏览 |
| 搜索 | `/search` | 全文搜索结果 |
| MCP 端点 | `/mcp` | MCP over HTTP 协议 |
| REST API | `/api/*` | 节点/关系/标签/图谱/搜索 |
| 健康检查 | `/health` | `{"status":"ok","version":"1.0.0"}` |

### 3. REST API

#### 节点操作

```bash
# 创建节点
curl -X POST http://localhost:8080/api/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "明朝一条鞭法",
    "content": "张居正推行的赋役改革，将田赋和力役合并，按亩征银...",
    "node_type": "event",
    "metadata": {"dynasty":"明朝","start_year":1581,"era":"万历"},
    "tags": ["历史学","断代史","明朝"]
  }'

# 搜索节点
curl "http://localhost:8080/api/search?q=一条鞭法&limit=10"

# 获取节点详情
curl http://localhost:8080/api/nodes/1

# 获取节点树
curl http://localhost:8080/api/nodes/tree

# 获取反向链接
curl http://localhost:8080/api/nodes/1/backlinks

# 更新节点
curl -X PUT http://localhost:8080/api/nodes/1 \
  -H "Content-Type: application/json" \
  -d '{"content": "更新后的内容..."}'

# 删除节点（软删除）
curl -X DELETE http://localhost:8080/api/nodes/1
```

#### 关系操作

```bash
# 创建关系
curl -X POST http://localhost:8080/api/relations \
  -H "Content-Type: application/json" \
  -d '{"source_id":1,"target_id":2,"relation_type":"references"}'

# 获取节点关系
curl http://localhost:8080/api/nodes/1/relations
```

#### 图谱与搜索

```bash
# 获取知识图谱（BFS 遍历）
curl "http://localhost:8080/api/graph/1?depth=2"

# 获取全图
curl http://localhost:8080/api/graph/full

# 全文搜索
curl "http://localhost:8080/api/search?q=明朝&node_type=event&limit=10"
```

#### 仪表盘

```bash
# 统计概览
curl http://localhost:8080/api/dashboard/stats

# 类型分布
curl http://localhost:8080/api/dashboard/type-distribution
```

### 4. MCP 工具

AI 客户端通过统一工具 `knowledge_graph` 操作知识图谱，通过 `action` 参数路由到不同功能：

#### 工具名称：`knowledge_graph`

**必填参数**：`action`（操作类型）

| action | 功能 | 其他参数 |
|--------|------|---------|
| `create_node` | 创建知识节点 | title, content, node_type, metadata, tags |
| `get_node` | 获取节点详情 | id 或 uuid |
| `update_node` | 更新节点 | id, title, content, node_type, metadata, tags, status |
| `delete_node` | 删除节点（软删除） | id |
| `search_nodes` | 全文搜索（支持中文分词） + 类型/metadata 过滤 | query, node_type, metadata_filters, limit |
| `search_by_metadata` | 按元数据精确查询 | filters, limit |
| `create_relation` | 创建节点关系 | source_id, target_id, relation_type |
| `delete_relation` | 删除关系 | id |
| `get_graph` | 获取知识图谱（BFS） | node_id, depth |
| `list_tags` | 列出所有标签 | — |

#### 中文搜索分词策略

搜索采用 **gse (Go 中文分词引擎)** + unigram 双重索引，确保中文搜索既精确又全面：
- **gse 词典分词**：搜索"孔子"精确匹配"孔子"节点，不会误命中"孔明"
- **unigram 兜底**：搜索单字"知"也能命中包含该字的所有节点
- **AND 连接**：多词搜索时要求全部匹配，提高结果相关性
- **小写归一化**：英文自动转小写，与 FTS5 unicode61 行为一致

#### MCP 工具使用示例（在 Claude 中）

```
请创建一个历史事件节点：
- 标题：靺难之役
- 类型：event
- 元数据：{"dynasty":"明朝","start_year":1399,"end_year":1402,"era":"建文"}
- 标签：["历史学","断代史","明朝"]
```

---

## 数据模型

### 核心表结构

```sql
-- 节点主表（全领域通用）
CREATE TABLE nodes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    uuid VARCHAR(36) UNIQUE NOT NULL,
    title VARCHAR(500) NOT NULL,
    content TEXT,                              -- Markdown，支持 [[双链]]
    node_type VARCHAR(50) DEFAULT 'note',      -- note/concept/event/person/book/theory/data/code
    status VARCHAR(20) DEFAULT 'active',       -- active/archived/deleted
    parent_id INTEGER,
    sort_order INTEGER DEFAULT 0,
    view_count INTEGER DEFAULT 0,
    metadata_json TEXT DEFAULT '{}',           -- 领域专有属性 JSON
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 节点关系表（双链/图谱）
CREATE TABLE node_relations (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id INTEGER NOT NULL,
    target_id INTEGER NOT NULL,
    relation_type VARCHAR(50) DEFAULT 'references',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(source_id, target_id, relation_type)
);

-- 标签表
CREATE TABLE tags (id INTEGER PRIMARY KEY, name VARCHAR(100) UNIQUE, color VARCHAR(7));
CREATE TABLE node_tags (node_id INTEGER, tag_id INTEGER, PRIMARY KEY(node_id, tag_id));

-- 元数据扁平索引（加速 JSON 内字段查询）
CREATE TABLE node_metadata_flat (
    node_id INTEGER NOT NULL, key VARCHAR(100) NOT NULL, value TEXT NOT NULL,
    PRIMARY KEY(node_id, key)
);

-- FTS5 全文索引（CJK 文本使用 gse 词典分词+unigram 存储索引，搜索时 AND 连接）
CREATE VIRTUAL TABLE nodes_fts USING fts5(uuid UNINDEXED, title, content, metadata_json, tokenize='unicode61');
```

### 各领域数据存储示例

| 领域 | node_type | 标题 | metadata_json |
|------|-----------|------|--------------|
| 历史 | `event` | 靺难之役 | `{"dynasty":"明朝","start_year":1399,"end_year":1402,"era":"建文"}` |
| 文学 | `book` | 百年孤独 | `{"author":"马尔克斯","genre":"魔幻现实主义","country":"哥伦比亚"}` |
| 经济 | `data` | 2024年CPI指数 | `{"indicator":"CPI","country":"中国","value":100.5,"unit":"同比"}` |
| 哲学 | `concept` | 存在先于本质 | `{"philosopher":"萨特","school":"存在主义","opposite":"本质主义"}` |

---

## 知识分类体系

本项目支持 **11 大学科 + 6 种文本形式** 的完整知识分类，详见 [docs/知识分类.md](./docs/知识分类.md)。

### 11 大学科

| 学科 | node_type | metadata 核心属性 |
|------|-----------|------------------|
| 历史学 | event | dynasty, start_year, end_year, era, region |
| 文学 | book | author, genre, country, language, school |
| 经济学 | data | indicator, country, value, unit, source |
| 哲学 | theory | philosopher, school, era, opposes |
| 社会学 | concept | theorist, theory_type, research_method |
| 政治学 | theory | school, political_system, era |
| 法学 | concept | law_type, jurisdiction, legal_system |
| 语言学 | concept | language, sub_field, era |
| 艺术学 | book | art_form, artist, style, period |
| 教育学与心理学 | theory | researcher, method, application_area |
| 新闻传播学 | concept | media_type, theory_type, platform |

### 节点类型（node_type）

| 类型 | 含义 | 示例 |
|------|------|------|
| `note` | 通用笔记 | 读书笔记、灵感碎片 |
| `concept` | 概念/术语 | 社会分层、训诂学、民法典 |
| `event` | 事件 | 靺难之役、工业革命 |
| `person` | 人物 | 张居正、萨特、韦伯 |
| `book` | 书籍/作品 | 百年孤独、红楼梦 |
| `theory` | 理论/学说 | 凯恩斯主义、存在主义 |
| `data` | 数据/指标 | CPI指数、GDP数据 |
| `code` | 代码/算法 | 快速排序、Transformer |

---

## 知识抽取技能

本项目配套 **knowledge-extractor** 技能，可从互联网或本地文档中自动提取结构化知识并写入知识图谱。

### 功能

- 🌐 从 URL / 本地文件 / 纯文本提取知识
- 🏷️ 自动识别 11 大学科分类 + 6 种文本形式
- 🔗 自动建立节点间关系（引用/因果/对立等）
- 🔄 写入前自动去重检查
- ✅ 四维质量自检（分类/属性/保真/关系）

### 使用方式

在 Trae 对话中直接触发：

| 操作 | 触发语 |
|------|--------|
| URL 抽取 | "从 https://xxx 抽取知识" |
| 文件抽取 | "把 ./docs/xxx.md 的知识整理到图谱" |
| 纯文本抽取 | "提炼以下内容的知识点：..." |
| 批量处理 | "批量处理 ./docs/ 目录" |
| 指定学科 | "按历史学分类整理" |

---

## 项目结构

```
knowledgeGraph/
├── server/                          # Go 后端
│   ├── main.go                      # 入口：MCP Stdio / HTTP 模式
│   ├── go.mod                       # Go 依赖
│   ├── internal/
│   │   ├── config/                  # 配置（端口/DB/UI开关/CORS）
│   │   ├── database/                # SQLite 初始化 + 迁移
│   │   ├── model/                   # 数据模型（Node/Relation/Tag）
│   │   ├── repository/              # 数据访问层（CRUD + FTS + Metadata）
│   │   ├── service/                 # 业务逻辑层
│   │   ├── api/                     # REST API（路由/Handler/中间件）
│   │   │   ├── handler/             # 各资源 Handler
│   │   │   ├── dto/                 # 请求/响应 DTO
│   │   │   └── router.go            # 路由注册
│   │   └── mcp/                     # MCP Server
│   │       ├── server.go            # MCP 服务初始化
│   │       └── tools/               # MCP 工具注册
│   └── web_dist/                    # 前端构建产物（embed）
│
├── web/                             # Vue 3 前端
│   ├── package.json                 # 前端依赖
│   ├── vite.config.ts               # Vite 配置
│   ├── unocss.config.ts             # UnoCSS 原子化样式
│   └── src/
│       └── types/                   # TypeScript 类型定义
│           ├── node.ts              # Node 类型（含 node_type 枚举/颜色/标签）
│           ├── tag.ts               # Tag 类型
│           └── common.ts            # 通用类型
│
└── docs/                            # 项目文档
    ├── 需求文档.md                   # 完整需求文档
    └── 知识分类.md                   # 11大学科+6种文本形式分类体系
```

---

## 开发指南

### 后端开发

```bash
cd server

# 运行测试
go test ./internal/...

# 运行服务（MCP 模式）
go run . -db ./data/knowledge.db

# 运行服务（Web UI 模式）
go run . -ui -port 8080

# 编译
go build -o knowledgegraph.exe .
```

### 前端开发

```bash
cd web

# 安装依赖
npm install

# 开发模式（热更新，需后端 -ui 模式运行）
npm run dev

# 构建生产版本
npm run build
```

构建后，将 `web/dist/` 内容复制到 `server/web_dist/`，重新编译后端即可嵌入前端。

### 添加新的 MCP action

在 `server/internal/mcp/tools/tools.go` 中扩展统一工具 `knowledge_graph`：

1. 在 `action` 的 `mcp.Enum()` 中添加新操作名
2. 添加新操作所需的参数定义
3. 实现 `handleXxx` Handler 函数
4. 在 `switch action` 中添加新 case 路由

---

## 配置说明

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-port` | `8080` | HTTP 监听端口 |
| `-db` | `./data/knowledge.db` | SQLite 数据库文件路径 |
| `-ui` | `false` | 启用 Web UI 模式（REST API + 前端） |
| `-cors` | `http://localhost:5173` | CORS 允许的前端来源 |

### 运行模式

| 模式 | 命令 | 用途 |
|------|------|------|
| MCP Stdio | `./knowledgegraph.exe` | Claude Desktop 等 AI 客户端 |
| Web UI | `./knowledgegraph.exe -ui -port 8080` | 人类浏览 + AI 同时使用 |