# ChronoQuill

**Repository Path**: limcod/chrono-quill

## Basic Information

- **Project Name**: ChronoQuill
- **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-05-25
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChronoQuill — 小说知识图谱引擎

基于 **Graphiti + Neo4j** 的时序知识图谱构建工具，将小说文本自动转化为结构化知识图谱，支持一致性检测和可视化浏览。

## 技术栈

| 层 | 技术 |
|---|------|
| 后端 | Python 3.12 / FastAPI / LangChain / Graphiti |
| 图谱 | Neo4j Community 2026.04 |
| 前端 | Next.js 14 / TypeScript / TailwindCSS / React Flow |
| 数据库 | SQLite (小说元数据) |
| LLM | DeepSeek V4 Flash |
| Embedding | 火山引擎 Doubao Embedding Vision |

## 快速开始

### 1. 环境准备

- [Conda](https://docs.conda.io/) (Python 3.12 环境)
- [Neo4j](https://neo4j.com/) (已配置在 `Z:\ChronoQuillData`)
- [Node.js](https://nodejs.org/) 18+

### 2. 启动 Neo4j

双击 `Z:\ChronoQuillData\start-neo4j.bat`，或命令行：

```bash
Z:\ChronoQuillData\start-neo4j.bat
```

### 3. 启动后端

```bash
conda activate ChronoQuill
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

或双击项目根目录的 `start-backend.bat`。

后端 API 文档：http://localhost:8000/docs

### 4. 启动前端

```bash
cd frontend
npm install
npm run dev
```

访问 http://localhost:3000

## 功能概览

### 上传与摄入

1. 在"上传"页面新建或选择已有小说
2. 拖入 `.txt` 章节文件
3. 点击"检测一致性"检查与已有设定的冲突
4. 点击"开始摄入"将章节转为知识图谱

### 任务管理

- 左栏：按小说筛选章节列表，标注完成进度
- 右栏：查看选中章节的任务详情和错误信息

### 图谱浏览

- 力导向布局展示实体和关系
- 按节点类型着色（角色/地点/事件/势力/物品）
- 点击节点查看详情，点击章节节点展开原始内容
- 边标签切换和边类型过滤

## API 端点

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/health` | 健康检查 |
| `GET` | `/api/novels` | 小说列表 |
| `POST` | `/api/novels` | 新建小说 |
| `POST` | `/api/ingest/upload` | 上传章节开始摄入 |
| `POST` | `/api/ingest/check` | 一致性检测 |
| `GET` | `/api/ingest/status/{id}` | 查询任务进度 |
| `GET` | `/api/ingest/chapters` | 章节上传记录 |
| `GET` | `/api/graph` | 图谱数据（支持 `?novel=` 筛选） |

## 项目结构

```
ChronoQuill/
├── backend/
│   ├── app/
│   │   ├── api/           # FastAPI 路由
│   │   ├── core/          # 配置、数据库
│   │   ├── graph/         # Graphiti 客户端
│   │   ├── ingestion/     # 文本分块、时间对齐、摄入管道
│   │   └── models/        # 数据模型
│   └── requirements.txt
├── frontend/
│   └── src/
│       ├── app/           # Next.js 页面
│       ├── components/    # React 组件
│       └── lib/           # API 客户端、类型
├── data/                  # SQLite、小说配置
└── docker-compose.yml     # Redis
```

## 环境变量

复制 `backend/.env.example` 为 `backend/.env`，配置：

```env
LLM_API_KEY=          # DeepSeek API Key
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_MODEL_NAME=deepseek-v4-flash

EMBEDDING_API_KEY=    # 火山引擎 API Key
EMBEDDING_BASE_URL=https://ark.cn-beijing.volces.com/api/v3/embeddings/multimodal
EMBEDDING_MODEL_NAME=doubao-embedding-vision-251215

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=neo4j
```