From 7e192a9f0acbcabb23f8fc2ef11131c4acb1cd0c Mon Sep 17 00:00:00 2001
From: OpenClaw Bot <openclaw@local>
Date: Wed, 18 Feb 2026 12:13:51 +0800
Subject: [PATCH] Add Phase 3 feature documentation

---
 docs/PHASE3_FEATURES.md | 198 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)
 create mode 100644 docs/PHASE3_FEATURES.md

diff --git a/docs/PHASE3_FEATURES.md b/docs/PHASE3_FEATURES.md
new file mode 100644
index 0000000..4c390b8
--- /dev/null
+++ b/docs/PHASE3_FEATURES.md
@@ -0,0 +1,198 @@
+# 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 文档
+- [ ] 切换不同转录文件
+- [ ] 查看知识库面板统计
+- [ ] 添加术语到术语表
+- [ ] 删除术语
+- [ ] 实体合并功能
+- [ ] 关系创建/删除