# PRD · Doco 文稿整理模块 · 视频源改造方案

> 版本：v2
> 日期：2026-06-12
> 作者：子 project Claude（Opus 4.7）
> 状态：草稿 / 待主项目审
> 上一版：v1（2026-06-12 同日，更早一稿）
> 主要变化：
>   1. **子模块正式定名为「Doco 文稿整理模块」**（v1 沿用旧称"TPS 三方融合子模块"，本版起全部改用 Doco；Q6 已由制片人拍板，不再列为待决问题）
>   2. **Q1（OCR 选型）方向更新**：制片人确认"软件离线刚需"已不成立，云端方案可接受。补充查清的关键事实：**讯飞 OCR 与 STT 共享鉴权凭证但套餐/余额各自独立**——按制片人原判据"如果能通用 token 订阅和余额就选讯飞"不成立。**新推荐方案：DeepSeek API**（制片人手上已有），并向主项目确认是否已有 OCR 能力或 LLM 视觉调用基础设施
>   3. 其他 Q（Q2/Q3/Q4/Q5）保持不变

---

## 〇、一段话摘要（给主 project 顾问的最短摘要）

Doco 文稿整理模块（前称"TPS 三方融合子模块"）此前的物理输入是 A 稿 docx + B 稿 OCR txt + ASR txt（mp3→讯飞）。栏目组现在改了素材输出方式：责编一次性输出 23 期"特殊视频"——画面是黑底白字唱词字幕、声音是无 BGM/音效的干净人声（极少同期声杂音）。**B 稿与 ASR 现在同源派生于一个视频文件**，物理输入从 3 个收敛到 2 个（A 稿 + 视频）。

**核心判断**：下游"三方融合引擎"（规则层 + AI 层）算法**零侵入**——只要新增的"视频双路拆分"模块输出与旧版 B 稿/ASR txt 格式完全一致（`[Nm Ns] 句子`），下游所有逻辑不动。**逻辑上仍然是三方融合**——A 稿术语权威 + B 路视频字幕 OCR + 音轨 ASR，三路独立验证的关系没破。

子项目这边需要主 project 在开工前对 5 件影响接口/数据形态的事拍板。详见 §4。

---

## 一、变更前后对照

### 旧设计（demo 已验证）

```
[A 稿 docx] ──────────────────────┐
                                  │
[上游既有 OCR 流程] ── B 稿 txt ──┤
                                  ├─► [三方融合引擎] ─► 终版.docx + 差异报告.docx
[节目纯净人声 mp3]                │
       │                          │
       └─► [讯飞 ASR] ── ASR txt ─┘
```

### 新设计（本 PRD 提出）

```
[A 稿 docx] ─────────────────────────────────────┐
                                                 │
[节目特殊视频文件]                               │
  画面：黑底白字字幕                             │
  声音：干净人声                                 │
        │                                        │
        ├─► [视频双路拆分子模块 · NEW]           │
        │     │                                  │
        │     ├─► ffmpeg 抽帧+字幕变化检测       │
        │     │     │                            │
        │     │     └─► [OCR] ── B 稿 txt ──────┤
        │     │       (待 Q1 拍板用 DeepSeek)    ├─► [三方融合引擎] ─► 终版 + 差异
        │     └─► ffmpeg 抽音轨 → 16k/mono WAV   │       (复用)
        │           │                            │
        │           └─► [讯飞 ASR · 复用]        │
        │                 └────── ASR txt ──────┘
        │
        └─ (后续接 23 期批量调度)
```

### 关键变化清单

| 项 | 旧 | 新 |
|---|---|---|
| 子模块名称 | TPS 三方融合子模块 | **Doco 文稿整理模块** |
| 物理输入 | A 稿 + B 稿 + ASR | A 稿 + 视频 |
| 逻辑融合方 | 三方 | **仍然三方**（A / B 路 / ASR 路） |
| B 稿来源 | 上游既有 OCR 流程 | 视频抽帧 → OCR |
| ASR 来源 | 节目 mp3 | 视频音轨 |
| 算法层 | 规则层 + AI 层 | **不变** |
| 新增模块 | — | 视频双路拆分（ffmpeg + OCR） |
| 处理粒度 | 单期 | 单期接口 + 23 期批量调度 |

---

## 二、子项目这边已经拍板的事（不需要主 project 决策，仅告知）

### 2.1 制片人已明确的决策

1. **子模块定名**：**Doco 文稿整理模块**（"Doco" 取意"Documentation Consolidation"——文稿整合）。本 PRD 起所有引用旧称（"TPS 三方融合子模块"、"三方融合"）的地方都用新名替换。
2. **离线不再是刚需**：原 v1 推荐 PaddleOCR 本地的核心理由（离线刚需）失效；OCR 选型转向云端。

### 2.2 demo 已验证或设计文档已定义的事

不变：

1. **三方融合优先级**（A 稿术语权威 / ASR 口吻 / B 稿验证）—— 见 project_design.md §5.1
2. **时间戳容忍度 ±5 秒** —— project_design.md §5.2
3. **口语清理三档**（keep_all / medium / clean）—— project_design.md §5.3
4. **改动确信度阈值**（0.85 自动 / 0.6–0.85 黄标 / <0.6 待确认）—— project_design.md §5.4
5. **AI 融合层模型**：Claude Sonnet 4.6 起步
6. **差异报告格式**：demo 黄金对照已落定
7. **A 稿术语表数据结构**：project_design.md §9.1
8. **OCR 错字映射表**：复用 demo 整理的字形混淆对

---

## 三、子项目这边的开发计划草案（待主 project 审）

| Phase | 内容 | 产物 | 主依赖 |
|---|---|---|---|
| P1 | 视频双路拆分预处理（单期）| `video_split.py`：视频 → 抽帧+字幕变化检测+OCR → B稿.txt；视频 → 音轨 → 16k WAV | ffmpeg、OCR（待 Q1 拍板，倾向 DeepSeek API） |
| P2 | 讯飞 ASR 适配层 | 复用 `xfyun_asr_standard.py`，替换新凭证、做成可被 P1 流水线调用的模块 | 讯飞开发端密钥（待 Q4 拍板） |
| P3 | Doco 融合引擎 | 规则层 Python + AI 层 Claude API；输入 A/B/ASR 三方 txt，输出终版 docx + 差异报告 + needs_review JSON | Claude API |
| P4 | 单期端到端 golden test | 用 demo 那期《现代防空反导大对决》的视频跑一遍，与 demo 产物比对，确认零回归 | 上面三 phase |
| P5 | 23 期批量 | 单期模块包成可被批量调度调用的接口（CLI / Python API 二选一，待 Q3 拍板） | — |

---

## 四、需要主项目决策的 5 个问题

> 每条都给了子项目这边的推荐答案 + 理由。主项目顾问可以照单批，也可以推翻。

### Q1. OCR 方案选型？

**问题**：B 路 OCR 用什么？这是新引入的依赖，绕不开。

#### Q1.A 关键事实（更新自 v1）

子项目这边查清了几件事，供主项目决策参考：

1. **讯飞 OCR 与 STT 的共享情况**：
   - 鉴权凭证（开发者账号、APPID、APIKey、APISecret）**可共享**，一组凭证可同时调用多个服务
   - 但**套餐/计费/余额各自独立**：STT 是"5 小时免费试用包"独立购买；OCR 是另一套计费体系（参考 SaaS 零售价 4.9 元/10 张、9.9 元/50 张）。**不存在用 STT 的余额跑 OCR 这种事**
   - **按制片人原判据（"如果能通用 token 订阅和余额就选讯飞"）此条件不成立**

2. **制片人手上已有的 API**：
   - **DeepSeek**：有专门的 `DeepSeek-OCR` 模型（OCR 2.0 方案，对中文文档识别准确率行业领先）+ DeepSeek Vision 识图模式（官方 API endpoint）。**推荐**
   - **MiniMax**：有 MiniMax-VL 视觉模型，理论上可 OCR，但 OCR 专项优化不如 DeepSeek-OCR
   - **小米 MiMo**：主推推理模型，未见明确的视觉/OCR 能力

3. **本场景的 OCR 难度评估**：
   - 输入图像是**黑底白字纯字幕画面**——OCR 最简单的子集（高对比度、印刷体、无图案干扰、无版面分析）
   - LLM 视觉模型在此场景几乎不会出错；用 LLM 做 OCR 在这里不是杀鸡用牛刀，因为成本极低且无新增依赖

4. **成本估算（23 期总量）**：
   - 单期约 300 条字幕（demo 数据），23 期 ≈ 6900 张图
   - DeepSeek Vision API 单张成本约几厘到一分，**总成本预估 50–150 元**
   - 对比讯飞 OCR SaaS 零售价：6900 张 × 0.198 元/张 ≈ 1370 元
   - 对比 PaddleOCR 本地：0 元但需要维护本地环境（已不是刚需）

#### Q1.B 选项与推荐

**选项**：
- A. **DeepSeek API（视觉模型）**——制片人已有 API，无新增订阅
- B. **讯飞 OCR**——与 STT 同账号但余额独立
- C. **PaddleOCR 本地**——零成本但需本地环境
- D. **主 project 已有的 OCR 服务**——如果存在

**子项目推荐**：A（DeepSeek API）

**理由**：
- 满足制片人"用现有 API 资源"的方向
- 黑底白字字幕是 LLM 视觉模型的舒适区，识别质量有保障
- 与讯飞 STT 解耦，单点故障范围小
- 成本最低（除 PaddleOCR）且无本地环境维护成本

**请主项目确认**：
- 主 project 是否已有 OCR 子模块/能力？（制片人初步判断"主 project 应该没有 OCR 配置"，请顾问最终确认）
- 主 project 的密钥管理体系是否已经接入 DeepSeek？还是需要 Doco 子模块自行管理 DeepSeek 凭证？
- 6900 张图调用 DeepSeek 是否会影响主 project 其他模块的 DeepSeek 配额/限流？

---

### Q2. 视频处理依赖（ffmpeg）的入口？

**问题**：抽帧与抽音轨都依赖 ffmpeg。

**选项**：
- A. Doco 子模块自带 ffmpeg 系统依赖 + Python 封装（`ffmpeg-python` 或 subprocess）
- B. 主 project 有统一的视频处理服务/适配层

**子项目推荐**：A，使用 subprocess 调用系统 ffmpeg

**理由**：ffmpeg 是标准工具，独立部署足够简单。

**请主项目确认**：是否已经有视频处理子模块/服务在规划中？如有，应改走中台接口。

---

### Q3. 23 期批量 vs 单期接口？

**问题**：本次实际场景是 23 期，Doco 子模块的接口应该长什么样？

**选项**：
- A. 子模块只负责单期，输入 = 1 视频 + 1 A 稿；批量调度交给主 project 编排层
- B. 子模块内部支持批量，输入 = 视频目录 + A 稿目录
- C. 两者都提供

**子项目推荐**：A（子模块只对单期负责）

**理由**：
- 单一职责原则。批量调度涉及失败重试、进度跟踪、并发控制——属于编排层职责
- 单期接口在出错时定位简单（哪期失败、失败在哪个 phase 一目了然）
- 主 project 未来可能有节目档案库流水线、报题单流水线等，统一在编排层做并发更合理

**请主项目确认**：
- 主 project 是否计划做"节目素材批量处理编排层"？如有，Doco 的单期接口应满足什么样的契约（CLI？Python API？返回值结构？）
- 23 期这次是先单期跑通再批量，还是要求一次性 batch？

---

### Q4. 讯飞密钥更新/续费策略？

**问题**：demo 凭证可能已过期（制片人提示"讯飞试用可能也过了"），且需要区分**消费端**（讯飞听见 App）与**开发端**（开放平台）。

**选项**：
- A. Doco 子模块各自申请新凭证、各自管理
- B. 接入中台统一密钥服务（如果有）
- C. 申请新凭证 + 写入"中台密钥资产文档"作为登记

**子项目推荐**：C

**理由**：现阶段中台密钥服务可能未完成，但密钥归属、过期日期、所属子模块应该有统一登记入口。

**请主项目确认**：
- 中台是否已有密钥管理子模块？
- 新申请的讯飞开发端密钥（包括 APP_ID、SECRET_KEY、5 小时免费试用包激活状态）应该登记在哪里？
- 如果 Q1 拍板用 DeepSeek，DeepSeek API key 是否也按同样规则登记？

---

### Q5. 目录结构与命名规约？

**问题**：23 期素材、抽帧产物、wav、终版 docx 的存储路径需要规约，否则后期归档混乱。

**子项目草案**：

```
programs/
└── {episode_id}/                # 例：20260612_防空反导
    ├── source/
    │   ├── video.mp4            # 原始特殊视频（黑底白字+干净人声）
    │   └── a_draft.docx         # A 稿（编导定稿）
    ├── work/                    # 中间产物（可清理）
    │   ├── frames/              # 抽出的字幕关键帧
    │   ├── audio_16k.wav        # 抽音轨标准化产物
    │   ├── b_draft.txt          # OCR 产物（带 [Nm Ns] 时间戳）
    │   ├── asr_result.txt       # 讯飞 ASR 产物
    │   └── asr_result_raw.json  # 讯飞原始返回
    └── output/                  # 主产物（入档案库）
        ├── final.docx           # 终版文稿
        ├── diff_report.docx     # 差异报告
        └── needs_review.json    # 待编导确认队列
```

**请主项目确认**：
- TPS 中台是否对节目素材的目录有统一规约？
- `episode_id` 命名规则是什么？（日期+栏目+期号？UUID？编导给定？）
- `work/` 中间产物保留多久？是否要自动清理？

---

## 五、不向主项目提问、但需要告知的事

1. **demo 的 5 份 fixture 仍然有效**：A 稿 / B 稿 / ASR / 终版 / 差异报告 在新流程下都可作为单元测试与集成测试的黄金对照
2. **讯飞 ASR 脚本仍然有效**：`xfyun_asr_standard.py` 只需替换凭证、把"音频文件路径"参数从"独立 mp3"改为"视频抽音轨产物 wav"
3. **23 期之后的常态化问题**：栏目组以后是否每期都按"黑底白字+干净人声"特殊视频出素材？还是只这一批 23 期是特例？这影响 Doco 子模块要不要保留旧的 mp3+独立 OCR 流程作为回退路径。**建议主项目顾问直接跟栏目组确认**

---

## 六、给主项目顾问的"接手提示词"

如果主 project 顾问要审这份 PRD，最重要的三件事：

1. **算法层零侵入是 demo 验证过的硬保证**。任何改动如果会让 P3（Doco 融合引擎）必须改算法，需要警惕——大概率是输入数据形态没对齐。
2. **OCR 选型（Q1）和目录规约（Q5）是会广泛影响其他子模块的事**，主项目顾问视野更大，应该是这两条的最终拍板人。如果主 project 有 OCR 能力或 DeepSeek 集成基础设施，Q1 的子项目推荐随时可被覆盖。
3. **23 期是一次性还是常态化（§5 第 3 条）是个产品问题，不是技术问题**，建议主项目顾问直接跟栏目组确认后再批 PRD。

---

## 七、回复期望

子项目这边等以下确认才正式开干：
- Q1（OCR 选型）—— 必须先答，否则 P1 不能开始
- Q4（讯飞密钥）—— 必须先答，否则 P2 不能开始
- Q5（目录规约）—— 必须先答，否则 P1 输出无处可放
- Q3（接口契约）—— P5 之前必须答
- Q2 —— Doco 子模块可以先按推荐方案开干，主项目随后批

收到主项目 Claude 顾问的回复 md 后，Doco 子项目这边出 PRD v3（含元信息块标注"上一版：v2"），再启动 P1。

---

## 八、版本变更摘要

| 版本 | 日期 | 主要变化 |
|---|---|---|
| v1 | 2026-06-12 | 首版。6 个待决问题（含子模块命名 Q6）。OCR 选型推荐 PaddleOCR 本地 |
| **v2** | **2026-06-12** | 子模块定名"Doco 文稿整理模块"；Q1 改推荐 DeepSeek API（基于讯飞 OCR/STT 余额独立的事实查清 + 制片人手上已有 API 资源）；Q6 已拍板移出待决列表；剩余 5 个待决问题 |

---

*v2 由 Doco 子 project Claude（Opus 4.7）于 2026-06-12 拟稿，遵照《跨 project 协作提示单 v1》§三的规范。*
