# graph-copilot-framework

**Repository Path**: onekxlpt/graph-copilot-framework

## Basic Information

- **Project Name**: graph-copilot-framework
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-23
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Graph-Copilot Framework 🚀

一个通用的、配置驱动的知识图谱交互式分析与 AI 助手框架。

## 🌟 特性

- **配置驱动**：无需改动代码，通过 `settings.yaml` 即可自定义 UI、样式和右键菜单。
- **高性能渲染**：基于 AntV X6，内置 Dagre 布局、自动截断和深度控制，支持大规模图谱。
- **AI 增强**：集成 Dify / OpenAI 兼容 API，支持流式对话，右键即可触发针对特定节点的 AI 分析。
- **并发友好**：采用 URL 参数驱动的无状态架构，支持多用户同时探索。
- **安全可靠**：内置 Cypher 注入防护、API 限流、配置验证等安全机制。
- **高性能**：Neo4j 连接池、图谱缓存、请求超时控制。

## 🛠️ 快速开始

### 1. 安装依赖
```bash
pip install flask flask-cors neo4j requests python-dotenv pyyaml
```

### 2. 环境配置
将 `.env.example` 重命名为 `.env` 并填写你的配置：

```env
# Neo4j 数据库配置
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

# AI 服务配置 (二选一)
# 方式一：Dify
AI_PROVIDER=dify
DIFY_API_URL=http://your-dify-server/v1/chat-messages
DIFY_API_KEY=your_dify_api_key

# 方式二：OpenAI 兼容 API (OpenAI/Qwen/DeepSeek 等)
AI_PROVIDER=openai
AI_API_URL=https://api.openai.com/v1/chat/completions
AI_API_KEY=your_api_key
AI_MODEL=gpt-3.5-turbo

# Flask 配置
FLASK_PORT=5000
FLASK_DEBUG=True
```

### 3. 自定义配置
修改 `config/settings.yaml`：

```yaml
# UI 界面配置
ui:
  title: "Graph-Copilot 分析框架"
  subtitle: "基于知识图谱与 AI 的交互式探索平台"

# 图谱渲染配置
visualization:
  default_depth: 1
  max_depth: 5
  node_limit: 200
  styles:
    dw: { fill: "#eff6ff", stroke: "#3b82f6" }
    ods: { fill: "#f0fdf4", stroke: "#22c55e" }

# 右键菜单配置
context_menu:
  - label: "分析业务含义"
    type: "ai"
    prompt: "请解释节点【{nodeId}】的业务含义。"
```

### 4. 启动服务
```bash
python app.py
```

访问 http://localhost:5000 即可使用。

## 📂 目录结构

```
graph_copilot_framework/
├── app.py                 # Flask 主应用 (路由、限流、缓存)
├── config/
│   └── settings.yaml      # UI 与业务配置文件
├── core/
│   ├── ai_proxy.py        # AI 代理 (Dify/OpenAI)
│   ├── config_loader.py   # 配置加载与验证
│   └── graph_engine.py    # Neo4j 图谱查询引擎
├── static/
│   └── lib/               # 静态资源 (X6, Dagre)
├── templates/
│   ├── index.html         # 首页搜索页
│   └── visual.html        # 可视化分析页
├── .env                   # 环境变量配置
└── .env.example           # 环境变量模板
```

## 🔌 API 接口

| 接口 | 方法 | 说明 | 限流 |
|------|------|------|------|
| `/` | GET | 首页搜索页 | - |
| `/visual` | GET | 可视化分析页 | - |
| `/api/get_graph` | GET | 获取图谱数据 | 30次/分钟 |
| `/api/chat_with_ai` | POST | AI 对话 (流式) | 10次/分钟 |
| `/api/health` | GET | 健康检查 | - |

### 示例请求

**获取图谱数据：**
```bash
curl "http://localhost:5000/api/get_graph?node=table_name&depth=2"
```

**AI 对话：**
```bash
curl -X POST http://localhost:5000/api/chat_with_ai \
  -H "Content-Type: application/json" \
  -d '{"query": "解释这个表的业务含义"}'
```

## 🔒 安全特性

### Cypher 注入防护
- 节点标签白名单验证
- 关系类型白名单验证
- 节点 ID 长度限制 (256字符)

### API 限流
- 基于客户端 IP 的滑动窗口限流
- 超限返回 HTTP 429 状态码

### 配置安全
- 必需环境变量检查
- 敏感信息脱敏输出
- 配置文件结构验证

## ⚡ 性能优化

### Neo4j 连接池
```python
max_connection_pool_size = 50
max_connection_lifetime = 3600s
connection_timeout = 30s
```

### 图谱缓存
- 内存缓存 (LRU 策略)
- 最大缓存数: 100 条
- TTL: 5 分钟

### 请求控制
- AI API 超时: 60s
- 查询长度限制: 4000 字符
- 深度限制: 1-10 层

## 🔧 扩展开发

### 添加新的节点标签

在 `core/graph_engine.py` 中修改白名单：

```python
ALLOWED_NODE_LABELS: Set[str] = {
    'Table', 'Person', 'Company', 'Product', 
    'Event', 'Location', 'Organization', 'YourNewLabel'
}
```

### 添加新的 AI 提供商

在 `core/ai_proxy.py` 中继承 `AIProxy` 类：

```python
class YourAIProxy(AIProxy):
    def stream_chat(self, query: str) -> Generator[str, None, None]:
        # 实现你的 AI 调用逻辑
        pass
```

## 📄 开源协议

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！