# 直播回放文字稿故事提取工具 — 方案设计文档

## 一、项目概述

### 1.1 背景

手头有大量直播回放导出的文字稿（DOCX 格式），其中散落着一些个人生活故事（家长里短类），需要用 AI 自动提取整理，并与讲述者个人信息匹配，最终输出为独立的 DOCX 文档。

### 1.2 目标

构建一个 **Web 端可复用工具**，支持：
- 批量上传和管理文字稿文件
- AI 自动提取故事（过滤讲课/知识点内容）
- 人工确认故事与讲述者的匹配关系
- 为每个讲述者生成独立 DOCX（个人信息 + 照片 + 故事正文）

### 1.3 使用场景

- **部署环境：** 局域网
- **用户规模：** 多人使用
- **数据规模：** 20+ 份文字稿，每份上万行

---

## 二、需求分析

### 2.1 输入

| 输入类型 | 格式 | 说明 |
|----------|------|------|
| 直播回放文字稿 | DOCX | 每份上万行，口语化，混合讲课/知识点内容，无明确说话人标记 |
| 讲述者个人信息 | DOCX（一人一个） | 包含姓名、照片等个人信息 |

### 2.2 处理要求

1. **故事提取：** 从文字稿中识别并提取个人生活故事（如家庭、情感、生活等），过滤掉纯讲课/知识点内容
2. **长文本切分：** 上万行文字稿需智能切分，确保不截断完整故事（每个故事可能跨半小时到一小时，稀疏分布）
3. **匹配确认：** AI 提取故事后，由人工在界面上确认每个故事对应的讲述者
4. **文档生成：** 按简洁模板生成最终 DOCX

### 2.3 输出

每个讲述者一份 DOCX 文档，结构为：
```
┌─────────────────────────┐
│     个人信息（含照片）     │
├─────────────────────────┤
│                         │
│       故事正文           │
│                         │
└─────────────────────────┘
```

### 2.4 扩展性要求

- LLM 可替换（支持升级/切换不同模型）
- 后续可扩展文章搜索引擎等功能

---

## 三、系统架构

```
┌─────────────────────────────────────────────────┐
│                  浏览器前端                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ 文件管理  │ │ 故事提取  │ │ 匹配确认 & 导出  │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
└────────────────────┬────────────────────────────┘
                     │ HTTP API
┌────────────────────┴────────────────────────────┐
│              Python 后端 (FastAPI)                │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ 文件处理  │ │ LLM 服务  │ │ DOCX 生成       │ │
│  └──────────┘ └──────────┘ └──────────────────┘ │
│  ┌──────────┐ ┌──────────┐                      │
│  │ 任务队列  │ │ 数据存储  │                      │
│  └──────────┘ └──────────┘                      │
└─────────────────────────────────────────────────┘
```

---

## 四、用户交互流程

### Step 1：上传文件
- 上传文字稿 DOCX（支持批量，显示上传列表）
- 上传讲述者信息 DOCX（支持批量，显示上传列表 + 预览）

### Step 2：提取故事
- 选择要处理的文字稿（可多选）
- 点击"开始提取"，显示进度
- LLM 实时返回提取结果
- 展示故事列表（摘要 + 原文定位）

### Step 3：匹配讲述者
- 左侧：故事列表
- 右侧：讲述者列表
- 拖拽/下拉匹配（或 AI 推荐候选）
- 确认匹配关系

### Step 4：预览 & 导出
- 预览最终 DOCX 效果
- 单个导出 / 批量导出
- 下载 ZIP 包

---

## 五、技术栈

| 层级 | 技术 | 理由 |
|------|------|------|
| **前端** | Vue 3 + Element Plus | 组件丰富、中文生态好、拖拽匹配等交互容易实现 |
| **后端** | FastAPI | 异步支持好、自带 API 文档、适合 AI 任务 |
| **LLM** | 抽象接口层，先支持 OpenAI 兼容 API | 后续可无缝切换国产模型/本地模型 |
| **DOCX 处理** | python-docx | 读写 DOCX 的标准库 |
| **任务队列** | Celery + Redis（或内置 asyncio） | 20+ 文件处理需要异步，避免前端卡死 |
| **数据存储** | SQLite | 轻量、无需额外安装、局域网够用 |
| **部署** | Docker Compose | 一键启动，局域网分发方便 |

---

## 六、核心技术难点与解决方案

| 难点 | 解决方案 |
|------|----------|
| **长文本切分不截断故事** | 两阶段策略：先用 LLM 做"话题分段"（识别话题边界），再对每个话题段判断是否包含故事 |
| **故事 vs 知识点区分** | Prompt 工程 + Few-shot 示例，明确"个人生活故事"的定义和排除规则 |
| **无说话人标记** | 提取故事后展示摘要，由人工在 GUI 上匹配讲述者；后续可加入 AI 推荐候选 |
| **上万行文本的 LLM 上下文** | 话题分段后，每个段落在上下文窗口内处理；超长段落再按语义子段切分 |

---

## 七、项目结构

```
story-extractor/
├── frontend/                    # Vue 3 前端
│   ├── src/
│   │   ├── views/               # 页面：文件管理、故事提取、匹配确认、导出
│   │   ├── components/          # 通用组件
│   │   └── api/                 # 后端 API 调用
│   └── ...
├── backend/                     # FastAPI 后端
│   ├── app/
│   │   ├── api/                 # API 路由
│   │   ├── services/            # 业务逻辑
│   │   │   ├── extractor.py     # 故事提取核心
│   │   │   ├── llm.py           # LLM 抽象层
│   │   │   ├── docx_parser.py   # DOCX 解析
│   │   │   └── docx_generator.py # DOCX 生成
│   │   ├── models/              # 数据模型
│   │   └── main.py
│   └── ...
├── docker-compose.yml
└── README.md
```

---

## 八、待确认事项

- [ ] LLM API 选型（OpenAI / 国产模型 / 本地模型）
- [ ] 技术栈最终确认
- [ ] 开发节奏（先跑通核心流程 vs 逐步完善）
- [ ] 讲述者信息 DOCX 的具体字段结构（需看样例）
- [ ] 文字稿样例（需看实际内容以优化切分和提取策略）