# InsightFlow Phase 3 功能说明

## 概述

Phase 3 实现了 InsightFlow 的"记忆与生长"能力，支持多文件知识融合、文档导入和项目级知识库管理。

## 功能清单

### 1. 多文件图谱融合 ✅

#### 功能描述
- 支持向同一项目上传多个音频文件
- 系统自动对齐新文件中的实体与已有实体
- 合并知识图谱，保持实体一致性
- 跨文件追踪实体提及

#### 使用方式
1. 在工作台点击"+ 上传文件"
2. 选择音频文件（MP3/WAV/M4A）
3. 系统自动转录并提取实体
4. 新实体与已有实体自动对齐
5. 使用"📁 选择文件"切换不同转录内容

#### API
```
POST /api/v1/projects/{project_id}/upload
Content-Type: multipart/form-data
file: <音频文件>
```

### 2. 实体对齐算法优化 ✅

#### 功能描述
- 使用 Kimi API 的 embedding 服务计算语义相似度
- 余弦相似度匹配算法
- 支持阈值调整（默认 0.85）
- 自动别名建议
- 失败时回退到字符串匹配

#### 实现模块
- `backend/entity_aligner.py`

#### 核心算法
```python
# 余弦相似度计算
def compute_similarity(embedding1, embedding2):
    vec1 = np.array(embedding1)
    vec2 = np.array(embedding2)
    dot_product = np.dot(vec1, vec2)
    norm1 = np.linalg.norm(vec1)
    norm2 = np.linalg.norm(vec2)
    return dot_product / (norm1 * norm2)
```

#### API
```
POST /api/v1/projects/{project_id}/align-entities?threshold=0.85
```

### 3. PDF/DOCX 文档导入 ✅

#### 功能描述
- 支持 PDF、DOCX、DOC、TXT、MD 格式
- 自动提取文档文本
- 文本参与实体提取和关系构建
- 文档类型标记和区分

#### 使用方式
1. 在工作台点击"+ 上传文件"
2. 切换到"📄 文档"标签
3. 选择文档文件
4. 系统自动解析并提取知识

#### 实现模块
- `backend/document_processor.py`

#### API
```
POST /api/v1/projects/{project_id}/upload-document
Content-Type: multipart/form-data
file: <文档文件>
```

### 4. 项目知识库面板 ✅

#### 功能描述
- 项目级全域知识库视图
- 统计面板（实体数、关系数、文件数、术语数）
- 实体网格展示（带提及统计）
- 关系列表展示
- 术语表管理
- 文件列表（区分音频/文档）

#### 使用方式
1. 在工作台点击左侧"📚"图标
2. 查看项目统计概览
3. 切换侧边栏标签浏览不同内容
4. 点击实体可跳转回工作台查看详情

#### API
```
GET /api/v1/projects/{project_id}/knowledge-base
```

### 5. 术语表管理 ✅

#### 功能描述
- 项目级术语表
- 支持添加术语和发音提示
- 频率统计
- 用于 ASR 热词优化

#### 使用方式
1. 在知识库面板切换到"📖 术语表"
2. 点击"+ 添加术语"
3. 输入术语和发音提示
4. 可删除不需要的术语

#### API
```
POST /api/v1/projects/{project_id}/glossary
GET /api/v1/projects/{project_id}/glossary
DELETE /api/v1/glossary/{term_id}
```

## 数据库 Schema 更新

### transcripts 表
```sql
ALTER TABLE transcripts ADD COLUMN type TEXT DEFAULT 'audio';
-- 'audio' 或 'document'
```

### entities 表
```sql
ALTER TABLE entities ADD COLUMN embedding TEXT;
-- JSON 数组存储 embedding 向量
```

### glossary 表（新增）
```sql
CREATE TABLE glossary (
    id TEXT PRIMARY KEY,
    project_id TEXT NOT NULL,
    term TEXT NOT NULL,
    pronunciation TEXT,
    frequency INTEGER DEFAULT 1
);
```

## 前端更新

### 新增组件
1. **侧边栏导航** - 切换工作台/知识库视图
2. **文件选择器** - 切换不同转录文件
3. **上传标签页** - 区分音频/文档上传
4. **知识库面板** - 统计卡片、实体网格、关系列表、术语表

### 更新文件
- `frontend/workbench.html` - 新增知识库 UI
- `frontend/app.js` - 新增知识库逻辑、多文件支持

## 部署说明

### 环境变量
```bash
KIMI_API_KEY=your_kimi_api_key
KIMI_BASE_URL=https://api.kimi.com/coding
ALIYUN_ACCESS_KEY_ID=your_aliyun_key
ALIYUN_ACCESS_KEY_SECRET=your_aliyun_secret
```

### 部署命令
```bash
# 使用部署脚本
./deploy.sh

# 或手动部署
docker build -t insightflow:phase3 .
docker run -d \
  -p 18000:8000 \
  -v /opt/data:/app/data \
  -e KIMI_API_KEY=$KIMI_API_KEY \
  insightflow:phase3
```

## 测试检查清单

- [ ] 上传多个音频文件到同一项目
- [ ] 检查实体是否正确对齐
- [ ] 上传 PDF 文档
- [ ] 上传 DOCX 文档
- [ ] 切换不同转录文件
- [ ] 查看知识库面板统计
- [ ] 添加术语到术语表
- [ ] 删除术语
- [ ] 实体合并功能
- [ ] 关系创建/删除