tps-dashboard/cca/CLAUDE.md

项目协作主控文件 (cca/CLAUDE.md)

---

🔖 状态栏 (STATUS — 每次结束 session 前必须更新这三行)

• 最后更新：Claude Code（动手开发）｜ 2026-07-05
• 当前状态一句话：CCA 唱词助手已部署至腾讯云（http://101.42.29.217/cca.html）。完整流程可用：上传音频+A稿 → ASR+AI校对 → 审稿台（含查找替换）→ 生成SRT下载。WAV自动转MP3。进入内测阶段。
• 下一个动手的人从这里开始：读完本文件。线上地址 http://101.42.29.217/cca.html（从配音首页"唱词助手"按钮进入）。服务器凭证见 /workspace/military_tech_voice/backend/.env。本地调试：python -X utf8 cca_pipeline.py --asr-cache output/asr_raw.json --script "data/重走战争老路的日本军备（A稿）.docx" --output-dir output_v6。

---

🤖 给 AI 的工作约定 (READ FIRST)

• 开始任何工作前，先读完本文件，特别是「状态栏」「交接备注」「关键决策」三节。
• 完成一段工作后增量更新：「已完成」追加一条、「待办」勾掉或新增、必要时更新「关键决策」，最后改「状态栏」三行。不要重写整份文件，不要删历史，只追加/勾选。
• 涉及发送、发布、删除、改权限、付款等不可逆操作前，先在对话里跟制片人确认。
• 本项目着急用——优先出可用版本，不追求完美架构。先跑通再优化。
• 沟通：全程简体中文；制片人不懂代码，解释说人话；给明确推荐不反复抛选项。

---

1. 项目概览

• 项目名：CCA 唱词助手（ChangCi Assist）— 《军事科技》栏目编导/责编用的唱词字幕生成工具
• 目标：把编导 A 稿 + 粗编人声音频 → 经过 ASR + AI 校对 + 编导审稿 → 最终输出符合大洋系统的 SRT 字幕文件
• 使用角色：编导（提供 A 稿+音频、审稿确认）、责编（拿 SRT 拉到大洋上线）
• 部署计划：先独立部署在 lanhao 配音 2.0 网站测试，成熟后吸收进 TPS 主项目作为子功能

核心工作流

编导A稿 ──→ AI提取专有名词词典
                ↓
粗编人声音频 + 词典 ──→ 讯飞ASR(录音文件转写标准版) ──→ 带时间戳ASR稿
                                                              ↓
                                                   ASR稿 ⊕ A稿 比对
                                                              ↓
                                              ┌─ AI自动修正(明显错别字)
                                              └─ 编导审稿台(拿不准的差异)
                                                              ↓
                                                        B稿(定稿)
                                                              ↓
                                                   按拍词规则折行 + 时间戳
                                                              ↓
                                                        SRT文件(大洋格式)

---

2. 技术栈与运行方式

• 语言：Python（与主项目 backend 对齐）
• 前端：纯 HTML/CSS/JS 单页（cca.html），暗色主题匹配 lanhao 配音系统，无框架依赖
• ASR：讯飞开放平台 录音文件转写标准版（已有 API Key，与 doco 共用同一套讯飞凭证）
• AI：LLM 用于两处——① 从 A 稿提取专有名词词典；② ASR 稿校对（的地得、引号、错别字）
• 输出格式：SRT（大洋系统兼容格式，有样本参照）
• 美术风格：参考 ai-labeling/example/（功能区划.jpg、幅面参考.jpg、页面风格.webp），与 TPS 主项目 UI 风格对齐
• 凭证：子项目自己 .env，不动主项目 backend/.env

---

3. 当前进度

• 已完成至：腾讯云部署完成 + 审稿台（含查找替换）上线。流水线 v6 + Web 审稿台 + WAV 自动转码。进入内测。
• 正在做：无（等待内测反馈）。
• 卡点/待解：无硬卡点。已知残留：ASR 切句边界跨越固定搭配（如"第二次/世界大战"）暂无法修复——需要跨句拆词检测（可做但需更大短语词典）。

---

4. 已完成（只追加，最新在上）

• [2026-07-05] 腾讯云部署 + 审稿台上线：① deploy/cca_route.py（Flask 蓝图，6 个 API 端点：upload/status/review/save/generate/download）；② deploy/cca.html（4 步单页流程：上传→处理→审稿→下载，暗色主题匹配配音系统）；③ 审稿台功能：左栏 ASR 原文 vs 右栏 AI 校对稿对比、逐句编辑确认、仅看修改过滤、全部确认、查找替换（Ctrl+H，支持逐个/全部替换+高亮定位）；④ WAV 大文件自动 ffmpeg 转 MP3（解决讯飞上传超时）；⑤ 服务器架构：Nginx→静态 HTML + Flask:5000，CCA 源码在 /workspace/military_tech_voice/backend/cca_src/，蓝图注册在 app/routes/cca.py。首页已加"唱词助手"入口按钮。
• [2026-07-05] 脚本版流水线 v6（14项审片修复+专家段识别）：① term_normalizer 新增：波浪号→"到"、顿号→空格、小数点保留（0.9马赫）、同音字映射表（建制→舰只/沉默→沉没/继承→击沉）、引号上下文感知（日向号加引号但日向级不加）、书名号补全（《军事科技》）；② ai_proofreader 新增：speaker 角色自动识别（解说/主持/专家）、专家采访增强 Prompt（严格删除嗯/呃/啊/这个/那么/就是说等口头语）、的地得规则大幅加强（+大量示例）、数字照抄 ASR 规则；③ ai_line_breaker 新增：引号不跨屏后处理（≤6字引号内容不拆两行）、极短行合并（≤3字+时长<1秒→并入相邻行）、极短句合并间隔放宽（≤4字句间隔阈值1200ms）；④ line_breaker 修改：clean_punctuation 保留小数点、顿号→空格；⑤ pipeline 新增 Step 2.5 校对后二次正则修复（兜住 AI 校对引入的新问题）。
• [2026-07-04] 脚本版流水线 v5（四层纠错体系+折行优化）：基于制片人逐帧审片反馈，解决 10+ 问题。新增四层纠错：① term_normalizer.py 正则层（型号短横线 F-15J/武器昵称引号"鱼鹰"/中文数字修复，零token）；② 校对 Prompt 升级（+代词他→它、+的地得纠错、+A稿权重规则）；③ 折行 Prompt 升级（+禁忌字规则"的了着过"不开头、+主谓宾拆分规则、+不可拆词示例）；④ 折行后处理三层（超长切分→禁忌字修复→拆词检测 _fix_split_words）。新增短句合并预处理（解决专家气口碎片句问题）。
• [2026-07-04] 脚本版流水线 v3（绝对时间戳+严格校对）：① 恢复绝对时间戳（方便在大洋时间线对位）；② 重写校对 Prompt——铁律：只改错别字/同音字、术语格式、口语填充词，绝不润色/调序/替换实词；③ 校对效果：60 处修正（vs v2 的 100 处，去掉了过度修改）。输出目录 output_v3/。
• [2026-07-04] 脚本版流水线 v2 真实测试通过：① 热词提取（规则+AI，127个术语）→ ② 讯飞ASR（94秒完成25MB音频，357句）→ ③ AI校对（DeepSeek，修正同音字/术语格式/口语填充，"建制"→"舰只"等）→ ④ AI折行（语义断句，98%行≤14字）→ ⑤ 5段SRT输出（段内相对时间戳，从00:00:00开始）。新增：hotword_extractor.py（热词提取）、ai_proofreader.py（AI校对）、ai_line_breaker.py（AI折行）。
• [2026-07-04] 脚本版流水线骨架完成：① asr_client.py（讯飞ASR适配，从doco复用）；② line_breaker.py（折行引擎，≤14字/语义断句/空白行检测）；③ srt_writer.py（大洋格式SRT输出）；④ segment_splitter.py（节目结构切分：导视/正片×3/预告）；⑤ cca_pipeline.py（主入口串联全流程）。本地测试全部通过。
• [2026-07-04] 子项目立项：目录结构、CLAUDE.md、Brief、主项目寄存条建立。

---

5. 待办（按优先级）

• PRD / 业务规则确认 → 已在对话中完成（2026-07-04）
• 脚本版流水线 → v5 完成（四层纠错+折行优化+短句合并）
• AI 校对层 → 已实现（四层防线：热词→正则→AI校对→折行后处理）
• 制片人审片第一轮 → 10+ 问题全部解决
• 编导审稿台 → 已完成（查找替换+逐句对比+编辑确认，2026-07-05）
• 部署至腾讯云 → 已完成（http://101.42.29.217/cca.html，2026-07-05）
• 内测反馈收集：同事试用中，等待反馈
• 大洋系统验证：导入 SRT 测试兼容性
• 热词注入真实 ASR 测试：用 --audio 跑完整流水线（非缓存），验证热词在转写层的效果
• 首页入口按钮可能被遮挡：index.html 已添加代码但可能需要样式调整（Ctrl+F5 刷新后可见）

---

6. 关键决策（跨 session 最易丢）

• [2026-07-04] ASR 稿是权威底稿：最终 SRT 必须和音频对应，ASR 稿（时间戳+内容）是基准。A 稿只提供专有名词写法和上下文参考，不能用 A 稿覆盖 ASR 的内容结构。
• [2026-07-04] 讯飞用录音文件转写标准版（与 doco 一样，不要大模型版）。热词偏置注入专有名词词典。
• [2026-07-04] 编导审稿台是必要环节：AI 拿不准的差异必须过编导确认，不能全自动。尊重编导创作主权（继承主项目设计哲学）。
• [2026-07-04] 先独立部署再吸收：先在 lanhao 配音 2.0 上跑通测试，成熟后并入 TPS 主项目。不等主项目进度。
• [2026-07-04] SRT 格式有样本：data/ 下 3 个 SRT 是人工拍词导出的真实样本，作为格式参照。
• [2026-07-04] 折行（拍词）规则：
  • A. 每行 ≤ 14 字
  • B. ASR 中 >2 秒空白 → 插入空白行（屏幕清字幕）
  • C. 按语义断句（不机械凑满 14 字），符合阅读习惯
  • D. 去掉逗号/句号/感叹号等标点，只保留引号
• [2026-07-04] 输出结构（5 个 SRT）：
  • 导视 1 个 + 正片 3 个 + 下期预告 1 个
  • 正片 3 个拆分依据：按时长大致均分，优先在角色转换处（解说词→专家采访）切分
  • 5 个 SRT 时间戳连续拼接 = 音频总长
• [2026-07-04] 节目结构标志词：
  • 导视结束标志：听到"本期《军事科技》……"
  • 正片开始标志：听到"各位观众你们好，我是主持人蓝皓"
  • 正片结束标志：听到"好了观众朋友们，感谢您关注国防军事频道军事科技……"
  • 正片之后是下期预告（无固定话术）
• [2026-07-04] 正片拆 3 个 SRT 的原因：大洋字幕系统不稳定容易出错，责编提的需求。
• [2026-07-04] 音频是纯人声：已分离好的干净音频（无 BGM/音效），无需人声分离。
• [2026-07-04] 先出脚本版：命令行跑通流水线，审稿台第二步做。
• [2026-07-04] 讯飞代码从 doco 复用：doco/src/doco/asr_adapter.py 有完整签名/上传/轮询/解析逻辑，直接适配。
• [2026-07-04] SRT 用绝对时间戳：每段 SRT 的时间戳是音频中的真实位置（不从 00:00:00 开始），方便在大洋时间线直接对位。制片人实测确认比相对时间戳好用。
• [2026-07-04] AI 校对严格纪律：只允许改三类——① 错别字/同音字 ② 术语格式（F-15J）③ 口语填充词删除。绝不润色、绝不调序、绝不替换实词。ASR 是已录音频的转写，改不了内容。
• [2026-07-04] 两层 ASR 纠错防线：第一层=热词注入（预防，让讯飞在转写时就认对专有名词）；第二层=AI 校对（修正，用 A 稿上下文判断同音字）。两层互补。
• [2026-07-04] LLM 选型已定：校对+折行+热词提取统一用 DeepSeek（deepseek-chat），性价比最优。
• [2026-07-04] 四层纠错体系（v5 确立）：① 热词注入（讯飞ASR层，预防中文同音字）→ ② term_normalizer 正则后处理（型号短横线/引号/中文数字，零token确定性替换）→ ③ AI 校对（DeepSeek，同音字/代词/的地得/术语/填充词）→ ④ 折行后处理（超长切分+禁忌字修复+拆词检测）。
• [2026-07-04] 折行三条铁律：① 词语不可拆分到两屏 ② "的了着过地得和与及或"不能作为新行第一个字 ③ 主谓宾优先折为"主语(折行)谓语+宾语"。
• [2026-07-04] 短句合并策略：ASR 按音频静音切句，专家气口会产生碎片短句（2-5字）。折行前先合并：≤8字+间隔<800ms→合并为一个语义单元再送AI折行。>2s静音仍插空白行。
• [2026-07-04] A稿与ASR权重规则：内容冲突时ASR优先（配音员可能改过措辞），但专有名词格式/写法按A稿（如F-35A、"鱼鹰"引号）。
• [2026-07-04] 国家代词不改：指代国家时口语用"他"是可接受的，不纠正；只纠正指代武器/舰艇/飞机/导弹时的"他→它"。

---

7. ⏩ 交接备注

• 立项背景：编导剪完节目后需要给责编一份 SRT 唱词字幕文件。传统流程是责编拿折行稿到大洋系统里 1:1 实时"拍词"（播放视频、听到对应句子拍空格记录时间戳），效率极低。CCA 用 ASR 自动化这个过程。
• "拍词"术语解释：折行稿（去标点、按规则断行的文稿）+ 时间戳对位 = 拍词。传统靠人工实时听拍，CCA 用 ASR 时间戳代替。
• 与 doco 的区别：doco 是"播出后"整理终版文稿（三方融合）；CCA 是"剪辑后、播出前"生成唱词字幕（ASR→校对→SRT）。两者共用讯飞 ASR 能力，但流程目的完全不同。
• 数据样本：data/ 下有 A 稿 docx + mp3 音频 + 3 个人工拍词 SRT（对应正片三段）。
• 代码文件：src/ 下是核心流水线代码（asr_client / line_breaker / ai_line_breaker / ai_proofreader / srt_writer / segment_splitter / hotword_extractor / term_normalizer），入口 cca_pipeline.py。deploy/ 下是部署文件（cca_route.py Flask 蓝图 + cca.html 前端页面 + deploy_to_server.py 部署脚本）。
• 凭证：本地需在 cca/.env 中填写；服务器凭证在 /workspace/military_tech_voice/backend/.env（讯飞大号 + DeepSeek）。
• 服务器架构：腾讯云 101.42.29.217，Nginx:80 → 静态文件(/var/www/voice/) + Flask:5000 代理(/api/)。CCA 源码部署在 /workspace/military_tech_voice/backend/cca_src/，任务数据在 cca_data/。Flask 无 systemd 服务，重启方式：fuser -k 5000/tcp && cd backend && source venv/bin/activate && nohup python3 -m app.main > /tmp/flask_cca.log 2>&1 &。
• 输出目录：output/（ASR 缓存 + v1 输出）、output_v2/~output_v6/（各版本输出）。
• 运行命令示例：
  • 从缓存跑（调试校对/折行）：python -X utf8 cca_pipeline.py --asr-cache output/asr_raw.json --script "data/重走战争老路的日本军备（A稿）.docx" --output-dir output_v6
  • 完整流水线（含真实 ASR）：python -X utf8 cca_pipeline.py --audio "data/重走战争老路的日本军备A0.mp3" --script "data/重走战争老路的日本军备（A稿）.docx" --output-dir output_v7

---

8. 待确认 / 开放问题

• 拍词规则 → 已确认（见关键决策）
• 大洋 SRT 样本文件 → data/ 下已有 3 个真实样本
• 音频格式 → 纯人声 MP3，无需预处理
• LLM 选型 → DeepSeek（deepseek-chat），已验证效果好、价格低
• 的地得纠错 → 已加入校对 Prompt（v5）
• 前端审稿台技术选型 → 纯 HTML/JS 单页，无框架（2026-07-05）
• 大洋系统 SRT 导入兼容性（待验证）
• 跨句固定搭配拆词（"第二次/世界大战"类问题，需大短语词典，优先级低）