# file-index

**Repository Path**: forai/file-index

## Basic Information

- **Project Name**: file-index
- **Description**: 树形结构做为索引
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# file-index 文档索引工具

基于多模态大模型的文档索引生成工具，支持 Markdown、PDF、Word 等格式文档，生成树形结构层次索引用于 RAG 检索。

## 功能特性

- 📄 **多格式支持** - Markdown、PDF、Word 文档解析
- 🤖 **LLM 智能分析** - 支持 OpenAI、Anthropic 等云端 API
- 🌳 **树形索引** - 自动生成层次结构索引
- 📍 **精确定位** - 支持行号和页码定位
- 🔗 **联动交互** - 点击节点自动定位到文档内容
- 📤 **多格式导出** - JSON、Markdown 格式导出
- ⚡ **批量处理** - 多文档队列处理

## 项目结构

```
pageindex1/
├── backend/                    # 后端服务 (Python/FastAPI)
│   ├── app/
│   │   ├── api/               # API 路由
│   │   ├── parsers/           # 文档解析器
│   │   ├── generators/        # 索引生成器
│   │   ├── services/          # 业务服务
│   │   ├── models/            # 数据模型
│   │   ├── core/              # 核心配置
│   │   └── utils/             # 工具函数
│   ├── tests/                 # 单元测试
│   ├── requirements.txt       # Python 依赖
│   └── .env.example           # 环境变量示例
│
├── frontend/                   # 前端应用 (React/TypeScript)
│   ├── src/
│   │   ├── components/        # UI 组件
│   │   ├── hooks/             # 自定义 Hooks
│   │   ├── api/               # API 调用
│   │   ├── stores/            # 状态管理
│   │   └── types/             # 类型定义
│   ├── package.json           # Node 依赖
│   └── vite.config.ts         # Vite 配置
│
├── plan.md                     # 项目架构与进度计划
└── plan-viewer.html           # 进度可视化界面
```

---

## 部署指南

### 环境要求

- Python 3.13+
- Node.js 18+
- Git

### 1. 克隆项目

```bash
git clone https://gitee.com/forai/file-index.git
cd file-index
```

### 2. 后端部署

```bash
# 进入后端目录
cd backend

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
```

编辑 `.env` 文件，配置 LLM API：

```env
# LLM 配置 (选择其一)
LLM_PROVIDER=openai
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-4

# 或使用 Anthropic
# LLM_PROVIDER=anthropic
# ANTHROPIC_API_KEY=your-anthropic-api-key

# 服务配置
HOST=0.0.0.0
PORT=8000
DEBUG=true
```

### 3. 前端部署

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 开发模式运行
npm run dev

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

### 4. 启动服务

**开发模式：**

```bash
# 终端 1 - 启动后端
cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 终端 2 - 启动前端
cd frontend
npm run dev
```

**生产模式：**

```bash
# 构建前端
cd frontend
npm run build

# 启动后端（前端静态文件由 FastAPI 托管或使用 Nginx）
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### 5. 访问应用

- 前端界面: http://localhost:5173 (开发模式) 或 http://localhost:8000 (生产模式)
- API 文档: http://localhost:8000/docs
- API 文档: http://localhost:8000/redoc

---

## 使用指南

### 单文档处理

1. **上传文档**
   - 点击「选择文件」按钮
   - 支持 .md、.pdf、.docx 格式
   - 或拖拽文件到上传区域

2. **自动解析**
   - 文件上传后自动解析
   - 提取文档结构和内容

3. **生成索引**
   - 解析完成后自动调用 LLM 生成索引
   - 或手动点击「生成索引」

4. **查看索引**
   - 左侧显示树形索引结构
   - 点击节点查看对应内容
   - 右侧自动定位到文档位置

5. **导出索引**
   - 点击「导出索引」按钮
   - 选择 JSON 或 Markdown 格式
   - 下载索引文件

### 批量处理

1. **选择多个文件**
   - 在批量上传区域选择多个文件
   - 支持混合格式

2. **开始处理**
   - 点击「开始处理」
   - 系统自动排队处理

3. **查看进度**
   - 实时显示处理进度
   - 查看每个任务状态

4. **获取结果**
   - 处理完成后自动显示结果
   - 支持批量导出

### API 使用

#### 上传并解析文档

```bash
# 上传文件
curl -X POST "http://localhost:8000/api/documents/upload" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@document.md"

# 返回
{
  "success": true,
  "data": {
    "document_id": "abc123",
    "file_path": "/path/to/document.md",
    "file_name": "document.md",
    "file_type": "markdown"
  }
}
```

#### 生成索引

```bash
curl -X POST "http://localhost:8000/api/index/generate/abc123?use_llm=true"
```

#### 获取索引

```bash
curl -X GET "http://localhost:8000/api/index/abc123"
```

#### 导出索引

```bash
curl -X GET "http://localhost:8000/api/index/abc123/export?format=json"
```

---

## 测试指南

### 运行所有测试

```bash
cd backend

# 激活虚拟环境
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# 运行所有测试
pytest

# 运行并显示详细信息
pytest -v

# 运行特定测试文件
pytest tests/test_markdown_parser.py -v

# 运行特定测试用例
pytest tests/test_markdown_parser.py::TestMarkdownParser::test_parse_simple_markdown -v
```

### 测试覆盖率

```bash
# 安装覆盖率工具
pip install pytest-cov

# 运行测试并生成覆盖率报告
pytest --cov=app --cov-report=html

# 查看报告
# 打开 htmlcov/index.html
```

### 测试文件说明

| 测试文件 | 测试内容 |
|----------|----------|
| `test_markdown_parser.py` | Markdown 解析器功能测试 |
| `test_index.py` | 索引生成和层次结构测试 |
| `test_utils.py` | 工具函数测试 |

### 手动测试

1. **健康检查**
   ```bash
   curl http://localhost:8000/health
   # 返回: {"status": "healthy"}
   ```

2. **API 文档测试**
   - 访问 http://localhost:8000/docs
   - 使用 Swagger UI 进行 API 测试

---

## 配置说明

### 后端配置 (.env)

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `LLM_PROVIDER` | LLM 提供商 | `openai` |
| `OPENAI_API_KEY` | OpenAI API 密钥 | - |
| `OPENAI_MODEL` | OpenAI 模型 | `gpt-4` |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | - |
| `ANTHROPIC_MODEL` | Anthropic 模型 | `claude-3-opus-20240229` |
| `HOST` | 服务主机 | `0.0.0.0` |
| `PORT` | 服务端口 | `8000` |
| `DEBUG` | 调试模式 | `true` |

### 前端配置

编辑 `frontend/vite.config.ts` 配置代理：

```typescript
server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8000',
      changeOrigin: true
    }
  }
}
```

---

## 常见问题

### Q: 上传 PDF 后解析失败？

确保已安装 PyMuPDF：
```bash
pip install PyMuPDF
```

### Q: LLM 调用失败？

1. 检查 API Key 是否正确配置
2. 检查网络连接
3. 检查 API 配额是否用尽

### Q: 前端无法连接后端？

1. 确认后端服务已启动
2. 检查端口是否被占用
3. 检查 CORS 配置

### Q: 测试失败？

1. 确认已安装测试依赖：`pip install pytest pytest-asyncio`
2. 确认虚拟环境已激活
3. 确认在 backend 目录下运行

---

## 技术栈

**后端：**
- Python 3.13+
- FastAPI - Web 框架
- PyMuPDF - PDF 解析
- python-docx - Word 解析
- OpenAI / Anthropic - LLM API

**前端：**
- React 18+
- TypeScript
- Vite - 构建工具
- Ant Design - UI 组件库
- Zustand - 状态管理

---

## 许可证

MIT License