---
slug: "aimine"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ichendev/aimine@main/README.md"
repo: "https://github.com/ichendev/aimine"
source_file: "README.md"
branch: "main"
---
# AI Mine

> AI Agent 探索平台，集成 RAG、Knowledge Graph、Memory、Skill、MCP 等核心能力。

![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)
![React](https://img.shields.io/badge/React-19-61dafb)
![Hono](https://img.shields.io/badge/Hono-4-orange)
![License](https://img.shields.io/badge/License-MIT-green)

## ✨ 特性

- 🤖 **双模式 Agent** - ReAct（推理+行动）和 Plan（规划+执行）两种模式
- 📚 **RAG 知识库** - 文档上传、向量检索、Reranking 重排序
- 🕸️ **知识图谱** - Neo4j 实体关系存储、可视化、图查询
- 🧠 **记忆系统** - 短期/长期记忆，对话上下文管理
- 🔧 **工具系统** - 三层架构（Primitives/Services/Specialists）
- 🔌 **MCP 集成** - Model Context Protocol 动态工具加载
- 🎯 **技能系统** - 预定义任务模板，可扩展
- 💬 **流式对话** - SSE 实时输出，Markdown 渲染
- 🌓 **主题切换** - 深色/浅色模式

## 🛠️ 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 19, Vite, TailwindCSS, Zustand, tRPC, react-markdown |
| 后端 | Hono, tRPC, Drizzle ORM, neo4j-driver, OpenAI SDK |
| 向量数据库 | PostgreSQL 16 + pgvector |
| 图数据库 | Neo4j 5 |
| 沙箱执行 | E2B Code Interpreter |
| Prompt | promptfoo + Handlebars |

## 📁 项目结构

```
aimine/
├── fe/                  # React 前端
│   └── src/
│       ├── components/  # UI 组件 (ChatPanel, RAGPanel, KGPanel...)
│       ├── stores/      # Zustand 状态管理
│       └── trpc/        # tRPC 客户端
├── be/                  # Hono 后端
│   └── src/
│       ├── db/          # Drizzle ORM + Schema
│       ├── lib/         # OpenAI, Neo4j 客户端
│       ├── services/    # 业务逻辑 (agent, rag, kg, memory, mcp...)
│       └── trpc/        # tRPC 路由
├── pkg/                 # 共享包
│   ├── types/           # TypeScript 类型
│   ├── schema/          # Zod Schema
│   └── utils/           # 工具函数
├── prompts/             # Handlebars Prompt 模板
│   ├── agent/           # Agent 系统提示 (react.hbs, planner.hbs)
│   ├── subagent/        # SubAgent 提示
│   └── extraction/      # 信息抽取提示
└── skills/              # 技能配置 (WHAT - 任务模板)
    ├── code-review/       # 代码审查流程
    ├── data-analysis/     # 数据分析流程
    ├── document-qa/       # 文档问答流程
    └── report-generation/ # 报告生成流程
```

## 🚀 快速开始

### 环境要求

- Node.js >= 20
- pnpm >= 9
- Docker & Docker Compose

### 安装

```bash
# 克隆项目
git clone https://github.com/yourname/aimine.git
cd aimine

# 安装依赖
pnpm install

# 复制环境变量
cp env.example .env
# 编辑 .env 填入你的 API Key
```

### 启动数据库

```bash
# 启动 PostgreSQL + Neo4j
pnpm db:up

# 推送数据库 schema
pnpm db:push
```

### 启动开发服务器

```bash
# 同时启动前后端
pnpm dev

# 或分别启动
pnpm dev:be  # 后端: http://localhost:3000
pnpm dev:fe  # 前端: http://localhost:5173
```

## 🤖 Agent 模式

### ReAct 模式

经典的 Reasoning + Acting 循环，适合简单直接的任务：

```
用户问题 → 思考 → 调用工具 → 观察结果 → 思考 → ... → 最终回答
```

### Plan 模式

先规划后执行，适合复杂多步骤任务：

```
用户问题 → 规划器 → 任务计划 → [用户确认] → 执行器 → SubAgents → 汇总结果
```

**SubAgents 角色专家（WHO - 通用能力）：**
- `planner` - 任务规划，分解复杂任务
- `researcher` - 信息检索，知识库和图谱查询
- `coder` - 代码实现，编写和执行代码
- `critic` - 质量审查，评估和改进建议
- `writer` - 内容创作，文档和报告撰写

## 🔧 工具系统

三层架构设计：

### Primitives（原子操作）
| 工具 | 描述 |
|------|------|
| `bash` | 在 E2B 沙箱中执行命令 |
| `file_read` | 读取文件内容 |
| `file_write` | 写入文件 |

### Services（服务连接器）
| 工具 | 描述 |
|------|------|
| `rag_search` | 知识库检索 |
| `rag_upload` | 上传文档 |
| `kg_query` | 查询知识图谱 |
| `kg_addEntity` | 添加实体 |
| `kg_addRelation` | 添加关系 |
| `memory_search` | 搜索记忆 |
| `memory_add` | 添加记忆 |
| `todo_*` | TODO 管理 |
| `mcp_*` | MCP 服务交互 |

### Specialists（专家代理）
| 工具 | 描述 |
|------|------|
| `specialist_list` | 列出可用专家 |
| `specialist_call` | 调用专家执行任务 |

## 📚 核心模块

### RAG 知识库
- 文档上传（支持文本分块）
- 向量化存储（pgvector）
- 相似度检索
- Reranking 重排序（BGE-Reranker）

### 知识图谱
- Neo4j 存储实体和关系
- 可视化展示（Canvas 力导向图）
- Cypher 查询
- LLM 驱动的信息抽取

### 记忆系统
- 短期记忆（对话上下文）
- 长期记忆（向量检索）
- 记忆提升机制
- 按对话维度管理

### MCP 集成
- 支持 stdio 和 HTTP 传输
- 动态发现工具/资源/提示
- 多服务器连接管理

## ⚙️ 环境变量

```bash
# OpenAI (必需)
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1  # 可选，支持兼容 API
OPENAI_MODEL=gpt-4o                        # 可选，默认模型

# PostgreSQL (必需)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/aimine

# Neo4j (必需)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# E2B (代码执行)
E2B_API_KEY=e2b_xxx

# Reranker (可选)
RERANKER_MODEL=BAAI/bge-reranker-v2-m3
```

## 📖 常用命令

```bash
pnpm dev          # 启动开发服务器
pnpm build        # 构建项目
pnpm lint         # 类型检查
pnpm db:up        # 启动数据库
pnpm db:down      # 停止数据库
pnpm db:push      # 推送 Schema
pnpm db:studio    # 打开 Drizzle Studio
pnpm promptfoo    # 运行 Prompt 测试
```

## 🖼️ 界面预览

- **对话面板** - 流式输出、Markdown 渲染、工具调用展示
- **知识库** - 文档管理、搜索测试
- **知识图谱** - 实体关系可视化
- **记忆管理** - 按对话查看和管理记忆
- **TODO 管理** - Agent 执行计划追踪
- **MCP 管理** - 服务器连接和工具查看
- **技能库** - 技能创建和编辑

## 📝 License

MIT