# SmartMindGraph

**Repository Path**: snowwolf_lj/smart-mind-graph

## Basic Information

- **Project Name**: SmartMindGraph
- **Description**: SmartMindGraph 是企业级智能知识图谱，是面向企业全域 AI Agent 的知识资产基础设施。它的使命是把分散在个人、项目、会话、代码、文档、方案、招投标、客户服务和交付中的隐性经验，持续沉淀为可追溯、可复用、可运营的组织资产，让知识主动找人、经验自动复用、体系自主进化。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SmartMindGraph

#### 介绍
SmartMindGraph 是企业级智能知识图谱，是面向企业全域 AI Agent 的知识资产基础设施。它的使命是把分散在个人、项目、会话、代码、文档、方案、招投标、客户服务和交付中的隐性经验，持续沉淀为可追溯、可复用、可运营的组织资产，让知识主动找人、经验自动复用、体系自主进化。

# SmartMindGraph 软件架构说明

## 1. 架构概述

SmartMindGraph 是一个面向企业 AI Agent 的**本地优先的知识图谱记忆系统**。它为 Claude Code 等 AI 编程工具及企业业务智能体提供持久化的长期记忆与可信上下文服务，使 Agent 能够在跨会话、跨项目中自动积累和复用知识。

系统以**单体 Spring Boot 应用**为核心运行时，内嵌图数据库（Neo4j）、全文检索引擎（Lucene）和向量嵌入引擎（ONNX Runtime），通过 MCP 协议（Streamable HTTP / stdio）对外暴露标准工具接口。前端可视化查看器为可选的 Vue 3 应用，与后端同机部署。

架构遵循**本地优先、契约优先、分层清晰**原则。内核提供通用记忆管理，领域知识包以可插拔方式扩展业务语义，不污染内核协议。

---

## 2. 系统组件视图

### 2.1 核心运行时组件

```
┌─────────────────────────────────────────────────┐
│                开发者本地机器                      │
│                                                   │
│  ┌───────────┐    ┌──────────────────────────┐   │
│  │ Claude Code│◄──►│ SmartMindGraph Server    │   │
│  │ (MCP Client)│   │ (Spring Boot 4.0,        │   │
│  └───────────┘    │  Java 21+, 单 JVM 进程)   │   │
│                   │                            │   │
│                   │  ┌──────────────────────┐ │   │
│                   │  │   MCP 传输层          │ │   │
│                   │  │ Streamable HTTP /     │ │   │
│                   │  │ stdio / legacy SSE    │ │   │
│                   │  └──────────┬───────────┘ │   │
│                   │             │              │   │
│                   │  ┌──────────▼───────────┐ │   │
│                   │  │   工具调度与契约层     │ │   │
│                   │  │ (P0 工具返回格式稳定) │ │   │
│                   │  └──────────┬───────────┘ │   │
│                   │             │              │   │
│                   │  ┌──────────▼───────────┐ │   │
│                   │  │     核心业务模块      │ │   │
│                   │  │ ┌──────────────────┐ │ │   │
│                   │  │ │ 知识摄入         │ │ │   │
│                   │  │ │ AST/Git/文档/URL │ │ │   │
│                   │  │ └──────────────────┘ │ │   │
│                   │  │ ┌──────────────────┐ │ │   │
│                   │  │ │ 知识检索         │ │ │   │
│                   │  │ │ BM25/向量/图/时序│ │ │   │
│                   │  │ └──────────────────┘ │ │   │
│                   │  │ ┌──────────────────┐ │ │   │
│                   │  │ │ 会话记忆管理     │ │ │   │
│                   │  │ │ 注入/压缩/生命周期│ │ │   │
│                   │  │ └──────────────────┘ │ │   │
│                   │  │ ┌──────────────────┐ │ │   │
│                   │  │ │ 可信治理         │ │ │   │
│                   │  │ │ 来源/置信度/审计 │ │ │   │
│                   │  │ └──────────────────┘ │ │   │
│                   │  │ ┌──────────────────┐ │ │   │
│                   │  │ │ 领域知识包运行时  │ │ │   │
│                   │  │ └──────────────────┘ │ │   │
│                   │  └──────────┬───────────┘ │   │
│                   │             │              │   │
│  ┌─────────┐      │  ┌──────────▼───────────┐ │   │
│  │Neo4j    │◄─────┼──│   数据访问层          │ │   │
│  │Docker   │      │  │ Neo4j/ContentStore/   │ │   │
│  │容器     │      │  │ Lucene/向量索引       │ │   │
│  └─────────┘      │  └──────────────────────┘ │   │
│                   └──────────────────────────┘   │
│                                                   │
│  ┌──────────────────────────────────────────┐    │
│  │ Vue 3 可视化查看器 (静态资源托管)        │    │
│  │ - 图谱总览 (WebGL)                       │    │
│  │ - 路径探索 / 时间线 / 查询调试           │    │
│  └──────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘
```

### 2.2 外部依赖

| 组件 | 类型 | 用途 | 部署方式 |
|------|------|------|----------|
| Neo4j Community Edition | 图数据库 | 存储知识图谱（实体、关系、向量索引） | Docker 容器，本地 bolt://localhost:7687 |
| Apache Lucene | 内嵌库 | 全文检索（BM25） | 集成在 Server 进程内 |
| ONNX Runtime | 内嵌推理引擎 | 运行本地向量嵌入模型 (all-MiniLM-L6-v2) | 集成在 Server 进程内 |
| tree-sitter + language-pack | JNI 本地库 | 多语言代码 AST 解析 | 通过 Java JNI 绑定加载 |
| JGraphT | Java 库 | 图算法（社区聚类 Louvain/Leiden） | 集成在 Server 进程内 |
| LLM API (可选) | 远程服务 | 用于 Episode 压缩、实体关系提取等推断任务 | 通过配置的 API 端点调用（默认本地模型优先，可降级） |

---

## 3. 数据架构

### 3.1 存储分层

系统采用**混合内容存储**策略，避免图谱膨胀：

- **小内容（< 2KB）**：直接作为 Neo4j 节点/关系属性存储。适合元数据、摘要、短文本。
- **大内容（≥ 2KB）**：存储为本地文件引用（`filePath + line range` 或 `contentStoreId`），图谱节点仅保留元数据指针。适合代码片段、文档全文、长文本。

### 3.2 数据模型核心实体

数据模型围绕**溯源、代码结构、知识经验、业务域、治理**五大主题展开：

| 主题 | 主要实体 | 关系 |
|------|---------|------|
| **溯源** | EpisodicNode (一次会话记忆单元), SagaNode (长事务记忆) | `MENTIONS`, `HAS_EPISODE`, `NEXT_EPISODE` |
| **代码结构** | Project, File, Function, Class, Interface 等 | `CONTAINS`, `DEFINES`, `CALLS`, `EXTENDS` 等 |
| **知识经验** | Concept, Decision, Pitfall, Pattern, Workflow | 核心 `RELATES_TO` (带时序窗口) |
| **业务域** | Client, Product, Feature, Requirement, Solution, Tender, Ticket, FAQ 等 | `REQUIRES`, `SATISFIES`, `RESPONDS_TO` 等 |
| **治理** | User, Role, PermissionGrant, AuditEvent, OutputArtifact, Claim, Citation | `OWNS`, `GRANTS`, `REVIEWED_BY`, `HAS_CLAIM` 等 |
| **来源** | SourceSystem, Connector, SourceRecord | `SYNCED_FROM`, `FEDERATED_FROM` |

**关键数据机制：**

- **时序窗口**：知识关系 `RELATES_TO` 携带 `tvalid` 和 `tvalidEnd`，旧事实标记失效但不删除，支持时间旅行查询。
- **多标签**：Neo4j 节点使用复合标签如 `Entity:Function:CodeElement` 支持灵活类型。
- **关系来源标记**：每条关系标注来源类型和置信度，如 `source=ast(1.0)`, `source=inference(0.7-0.9)`。
- **声明级引用**：业务输出物通过 `Claim → Citation → SourceRecord/EpisodicNode` 实现逐声明溯源。
- **向量索引**：Neo4j Vector Index 存储 384 维嵌入，模型为 all-MiniLM-L6-v2，用于语义检索。

### 3.3 Schema 版本管理

- `SchemaVersion` 节点记录当前图谱 schema 版本。
- 启动时自动执行迁移脚本，支持幂等执行与回滚。
- 迁移失败时系统进入只读模式，防止数据损坏。

---

## 4. 关键架构决策与原则

| 决策 | 解释 |
|------|------|
| **本地优先** | 所有存储、推理、检索默认在本地完成，首发不依赖云端服务。向量嵌入和 BM25 均在本地运行。 |
| **契约优先** | 对外 MCP 工具接口和返回格式视为公有契约，版本化演进；内部实现可替换。 |
| **确定性优先** | AST、Git diff、图谱结构等确定性信号优先使用；LLM 仅用于补充推断和压缩，且标记置信度。 |
| **可逆优先** | 重扫、回滚、撤回等操作必须支持，避免不可逆破坏。 |
| **失败显性化** | 降级、错误和补偿必须明确返回给 Agent，禁止静默失效。 |
| **分层清晰** | 内核（通用记忆层）、领域知识包、相邻模块（检索、可视化）、独立产品线（团队协作）严格分层。 |
| **领域可插拔** | 业务部门通过领域知识包定义自己的实体、流程和输出，不硬编码在内核。 |
| **声明级输出治理** | 所有由 Agent 生成的业务输出（方案、标书、答复）必须逐声明绑定来源、置信度和审批状态。 |

---

## 5. 接口架构

### 5.1 MCP 工具接口

系统通过 MCP 协议暴露一系列工具，Agent 通过标准 JSON-RPC 2.0 调用。首发以 **Streamable HTTP** 为主传输，stdio 用于本地进程集成，legacy SSE 仅兼容旧客户端。

所有 P0 工具返回格式稳定契约，核心字段如下：

| 工具 | 用途 | 返回核心字段 |
|------|------|-------------|
| `impact` | 影响分析 | `symbol`, `directCallers[]`, `riskAssessment`, `relatedPitfalls[]` |
| `context` | 符号 360° 上下文 | `definition`, `callers[]`, `callees[]`, `executionFlows[]`, `knowledge[]` |
| `query` | 混合搜索 | `results[]`, `total`, `degraded?` |
| `detect_changes` | Git 差异影响 | `affectedSymbols[]`, `affectedFlows[]`, `suggestedTests[]` |
| `memory_context` | 新会话自动注入 | `projectProfile`, `hotKnowledge[]`, `injectedTokens` |
| `memory_add_episode` | 添加记忆单元 | `episodeId`, `status`, `extractedEntities` |
| `memory_temporal_query` | 时间旅行快照 | `asOf`, `snapshot[]` |
| `claim_trace` | 声明溯源 | `claimId`, `sourceType`, `confidence`, `dependentArtifacts[]` |
| `artifact_review` | 审批输出物 | `artifactId`, `previousStatus`, `newStatus` |
| `memory_status` | 系统健康检查 | `neo4jConnected`, `schemaVersion`, `episodeQueueLength`, `connectorHealth{}` |

完整的 P0 工具清单及契约见 PRD 第 5 节。

### 5.2 内部 API 与外部 API 边界

- **公有 API**：MCP 工具接口，必须保持向后兼容。新字段可加，旧字段不可突然删除或改变语义。
- **内部 API**：图构建器、聚类算法、压缩流水线、实体去重等模块间的接口，允许重构，但不能破坏外部契约。
- **视图接口**：Vue 3 前端通过 HTTP/WebSocket 访问后端提供的 REST API（用于可视化查询），该 API 可能不稳定，不建议外部直接依赖。

---

## 6. 安全架构

### 6.1 权限模型

系统支持 **RBAC（基于角色）+ ABAC（基于属性）** 的混合访问控制，通过统一授权链路执行：

```
用户 / Agent
  │
  ▼
身份解析器 (Identity Resolver) ──► 委托上下文 (Delegation Context)
  │
  ▼
策略决策点 (Policy Decision Point) ──► 策略执行点 (Policy Enforcement Point)
  │
  ▼
过滤检索 / 声明过滤 / 审计事件
```

**关键规则：**
- Agent 不拥有超级权限，其访问范围受限于所代表的用户或任务的权限。
- 所有知识查询、注入、输出、导出都必须通过过滤。
- 联邦连接器查询时必须回源系统进行实时授权，不能仅依赖本地权限快照。
- 输出物的声明（Citation）在展示、导出、发布时按目标受众权限重新过滤。

### 6.2 数据分级与隔离

- 数据分级：Public / Internal / Confidential / Restricted。
- 项目隔离：每个 Project 独立子图，默认查询仅限项目内。
- 跨项目共享仅允许 Concept/Pattern/Preference 等高层知识，代码节点始终隔离。
- 租户隔离：为 L1/L2 形态预留，团队/部门间严格隔离。
- 所有跨范围访问必须可审计、可回放、可撤回。

### 6.3 审计

- `AuditEvent` 节点记录所有读、写、注入、导出、审批、撤回、权限拒绝事件。
- 可追踪到人、Agent、项目、客户和来源系统。

---

## 7. 部署架构与演进路径

### 7.1 当前部署模型（L0 个人本地版）

- 所有组件运行在单个开发者机器上。
- Neo4j 通过 Docker 提供，Server 为单一 JVM 进程。
- 数据存储于本地文件系统，ContentStore 使用本地目录。
- 无多用户协作，无中心化备份（用户自行备份）。

### 7.2 演进拓扑

系统设计支持从个人版平滑演进到企业版：

```
L0 个人本地版
  本地 Neo4j + 本地 ContentStore + 本地 Agent
        │  导出/提升：脱敏、权限映射、冲突检测
        ▼
L1 团队共享版
  团队图谱实例 + 团队领域包 + 团队审计 (RBAC)
        │  同步/治理：SSO、备份、待审队列
        ▼
L2 企业私有化版
  企业知识平台 + 多租户/多部门 + 连接器 + 高可用 + 合规删除
```

三种形态共享同一知识语义和 MCP 契约，仅在存储、权限、同步和运维层分化。

---

## 8. 技术栈选型

| 类别 | 技术选型 | 说明 |
|------|---------|------|
| **运行环境** | Java 21+ (JDK 23+ 用于 tree-sitter 绑定) | 稳定、生态丰富 |
| **应用框架** | Spring Boot 4.0, Spring AI 2.0 | MCP Server 原生支持，简化集成 |
| **图数据库** | Neo4j Community Edition (Docker) | 原生图存储与向量索引，支持 Cypher |
| **AST 解析** | tree-sitter + java-tree-sitter (JNI) + language-pack | 支持 305+ 语言，本地高性能解析 |
| **向量嵌入** | all-MiniLM-L6-v2 (384维), ONNX Runtime Java API | 本地推理，无云依赖，低延迟 |
| **全文检索** | Apache Lucene | 成熟 BM25 实现，可嵌入式 |
| **图算法** | JGraphT (Louvain/Leiden 社区检测) | 纯 Java，无需额外服务 |
| **前端** | Vue 3 + Vite + sigma.js (WebGL) | 可视化查看器，由 Spring Boot 静态资源托管 |
| **MCP 传输** | Spring AI MCP Server (Streamable HTTP/stdio/SSE) | 符合 MCP 规范，优先 HTTP |

---

## 9. 可靠性设计

### 9.1 故障降级

| 故障场景 | 系统行为 |
|---------|---------|
| Neo4j 不可用 | 返回结构化错误，不静默失败；启动时未就绪则进入降级模式（只读缓存） |
| LLM API 不可用 | Episode 处理排队重试，AST 通道不受影响 |
| Embedding 引擎故障 | 向量搜索不可用，BM25 + 图检索继续工作 |
| MCP 连接中断 | 返回可恢复错误，Agent 可继续使用本地缓存上下文 |
| 文件系统不可读 | 返回可用元数据，跳过不可读文件 |

**核心降级原则**：宁可少给知识，也不静默给错知识。

### 9.2 数据持久化与恢复

- Episode 处理队列持久化到本地 SQLite/JSONL，崩溃恢复后自动重试。
- 大项目扫描支持断点续扫，进度持久化到 Neo4j。
- Schema 迁移幂等，失败时系统进入只读模式并支持回滚。

---

## 10. 扩展性设计

### 10.1 领域知识包

各部门通过**声明式 schema 文件**注册领域包，包含：
- 实体类型与关系定义
- 输入模板（文档类型、抽取字段）
- 检索意图（典型问题与召回策略）
- 输出 artifact 定义
- 审批流与权限策略
- 指标定义

运行时加载后无需修改内核代码。领域包之间通过共享的溯源、权限、声明引用机制实现跨部门桥接。

### 10.2 连接器架构

外部系统（CRM、工单、邮件等）通过连接器接入，支持两种模式：
- **同步索引模式**：定期同步元数据和向量索引到本地图谱。
- **联邦实时模式**：查询时回源系统实时取数，不缓存正文，适用于高敏数据。

每个连接器需实现标准的 `sourceSystem` 标识、增量同步、删除传播和权限快照协议。首发预留协议，后续分阶段实现具体连接器。

### 10.3 独立产品线

团队协作、云同步、多 Agent 市场、行业知识包商业化等作为独立产品线规划，不与内核耦合。

---

## 11. 术语表

| 术语 | 架构含义 |
|------|---------|
| **MCP** | Model Context Protocol，Agent 与工具间标准通信协议 |
| **Episode** | 一次会话或事件的结构化记忆单元，是所有知识的溯源起点 |
| **Provenance** | 来源信息，包括来源系统、时间、主体、模型版本 |
| **RRF** | Reciprocal Rank Fusion，多路检索结果融合算法 |
| **ContentStore** | 本地大文件引用存储层，避免图谱内存储大量文本 |
| **领域知识包** | 可插拔的业务语义扩展单元，定义部门级的实体、模板、流程 |
| **Claim/Citation** | 输出物中的“声明-引用”对，用于逐句溯源 |

---