fix: 完成 doco src layout 重构,文件移至 src/doco/ 子目录
This commit is contained in:
simonkoson
@@ -0,0 +1,295 @@
|
||||
# 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》§三的规范。*
|
||||
Reference in New Issue
Block a user