课代表立正 · 视频后期生产

lizheng-video-production 把视频或已有字幕整理成可靠的字幕交付和按需发布资产：高光、文章、标题与 YouTube description。仓库同时包含可执行工具、视频编排 skill 与可独立使用的 video-title-and-cover skill；自动化边界、外部能力和草稿发布被明确分开。

它真正完成什么

目录：

skill/       视频任务路由、交付契约和条件制作说明
skills/video-title-and-cover/  独立封标 skill 与 canonical 规范
tools/       可执行脚本
tests/       确定性行为和失败语义测试
data/        规范兼容链接、频道样本、术语、writing-skill fallback
DESIGN.md    长期技术决策

Fresh clone

前提

• Apple Silicon Mac；主 ASR 基于 MLX。
• Python 3.10 或更高。说话人标注建议使用单独的 Python 3.11+ 环境。
• ffmpeg 与 ffprobe。
• 已安装并登录 Codex CLI。Claude Code CLI 是内容生成的可选 fallback，需要降级能力时再安装并登录。

AI 文本步骤使用已登录 CLI，不直接读取云 API key。可选的 pyannote 模型需要 Hugging Face 账号授权。

安装代码

git clone https://github.com/sunyuzheng/lizheng-video-production.git
cd lizheng-video-production

python3 --version
python3 -m venv venv
venv/bin/pip install -r requirements.txt

ffmpeg -version
codex --version
claude --version  # 可选 fallback

如果系统 python3 低于 3.10，用已安装的具体版本创建 venv，例如 /opt/homebrew/bin/python3.12 -m venv venv。首次转写会下载 Qwen3-ASR 模型；下载大小与模型 revision、缓存状态有关，请预留充足磁盘空间。

安装 skill

视频编排入口是 lizheng-video-editing；只做标题与封面时可以仅安装独立入口。在仓库根目录执行：

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skills/video-title-and-cover" ~/.codex/skills/video-title-and-cover
test -f ~/.codex/skills/video-title-and-cover/SKILL.md

需要完整视频编排时，再安装：

mkdir -p ~/.codex/skills
ln -s "$(pwd)/skill" ~/.codex/skills/lizheng-video-editing
test -f ~/.codex/skills/lizheng-video-editing/SKILL.md

如果同时使用 Claude skill：

mkdir -p ~/.claude/skills
ln -s "$(pwd)/skill" ~/.claude/skills/lizheng-video-editing
test -f ~/.claude/skills/lizheng-video-editing/SKILL.md

命令故意不带强制覆盖参数；目标已存在时先检查它指向哪里，再决定是否迁移。旧名 kdb-video-post-production 已弃用，不再是 frontmatter 或安装文档的当前名称。

三个常用 recipe

1. 全链路

caffeinate -i venv/bin/python tools/process_video.py /path/to/video.mp4 \
  --seeds 嘉宾名 公司名 产品名

访谈若要独立社区帖，而不是随视频伴读：

caffeinate -i venv/bin/python tools/process_video.py /path/to/video.mp4 \
  --article-type interview \
  --article-surface community \
  --seeds 嘉宾名 公司名

没有当期专有名词时用 --no-seeds。单期实体只走 seeds；只有跨期复用且确认过的术语才进入 data/channel_vocab.json。 不传 --skip-transcribe 时，即使工作区已有 .qwen.srt 也会在隔离目录重跑 ASR；只有当前运行产出唯一且结构有效的 SRT 才刷新 raw，失败时保留上一版。

2. 只做字幕、VTT 和 QC

caffeinate -i venv/bin/python tools/process_video.py /path/to/video.mp4 \
  --seeds 嘉宾名 公司名 产品名 \
  --skip-highlights --skip-article --skip-titles --skip-youtube-description

字幕 QC 是依赖门。除结构、时长、字数和阅读速度外，自动 candidate 还会检查重断句前后正文字符流，并筛查连续的机械等长边界；触发时保存诊断用 SRT 和报告、退出非零，不会晋升 SRT/VTT 或继续生成下游。风险筛查不代替人工语义通读，处理方法见 skill/references/subtitle-delivery.md。

3. 已有 SRT，只补内容

venv/bin/python tools/generate_highlights.py /path/to/video.final.srt \
  -o /path/to/delivery

venv/bin/python tools/generate_article.py /path/to/video.final.srt \
  -o /path/to/delivery \
  --workspace-dir /path/to/video_process \
  --highlights /path/to/delivery/video.highlights.md \
  --article-type interview --surface companion

venv/bin/python tools/generate_titles.py /path/to/delivery/video.article.md \
  -o /path/to/delivery \
  --workspace-dir /path/to/video_process \
  --source-srt /path/to/video.final.srt

venv/bin/python tools/generate_youtube_description.py /path/to/video.final.srt \
  -o /path/to/delivery

文章按类型只加载一个主责 writing skill：访谈使用 expert-interview-article，单口使用 substance-writing-review。本机没有当前 skill 时使用 data/writing-skills/ fallback；其中 substance-writing-review.md 同步自公开仓库 https://github.com/sunyuzheng/substance-writing-review 的自包含主文件。实际注入的文件、来源和 hash 会保存到本期工作区。自动流水线不会自行读取其中按需引用的外部 reference，因此 fallback 主文件必须能独立承担写作契约。

标题流程会先读取完整文章或带时间线的完整 SRT，保存一份 packaging_brief.md。它不概括整期，也不从最稀奇的事实倒推 relevance；它先找核心观众在这个题材上原本就有的观看动机，再扫描能改变理解的强事实、数字、冲突、人物关系和机制，保住可能被摘要磨平的现场问题。候选从一开始就是标题 × 封面组合，先比较不同观看承诺，再磨措辞。独立 challenger 在看见 brief 和首轮候选之前先重读源材料、另做一套候选，下一轮才把两套方案放在一起冷读，以减少首轮锚定；这种模型判断不是观众实测。输入文章并传入 --source-srt 时，brief 与 challenger 都优先读取完整逐字稿，文章作为辅助；同一 SRT 另为终审提供 cue-level 开头定位。主流程会自动传入本次 final SRT，终审也直接读取当前频道 guideline。编辑规范的 owner 是 skills/video-title-and-cover/references/editorial-judgment.md，旧 data/guideline_kedaibiao.md 为仓内相对链接，标题与高光脚本均直接读到新正文；完整 clone 不依赖本机另一份 skill。

终稿还会把开头当作同一包装的下一拍：访谈里若有干净原话能确认标题承诺并抬高问题，就给出 cue-level in/out 与可回查原话的 package-specific cold open；若最强 premise 需要跨片段综合，则给出可补录的主持人 narrative intro 和进入正片的位置。可用的 .speaker_labeled.srt 会自动校验并采用，也可以显式加 --speaker-srt /path/to/video.speaker_labeled.srt；没有可靠 sidecar 时不替原片声音强行标注“主持人／嘉宾”。一般高光用于发现 substance，不默认按顺序拼成开场。最终稿仍需要编辑判断，多轮输出不等于自动选中了可发布标题。

surface 含义：

主入口参数

以 python3 tools/process_video.py --help 为最终真值。常用参数：

维护频道词汇

data/channel_vocab.json 是运行时文件，只保留 schema_version、verified_candidates 和 hotwords_context。人工确认的源分别是 data/verified_corrections.json 与 data/verified_hotwords.txt：

python3 tools/extract_channel_vocab.py \
  --channel-root /path/to/kedaibiao-channel \
  --candidates data/verified_corrections.json \
  --hotwords-file data/verified_hotwords.txt \
  --output data/channel_vocab.json

历史字幕里自动推断出的专有词和混淆对只在显式 --audit-output 时另存审计文件，不直接进入 runtime。这样不会把“出现频率高”误当成“可以自动改”。

产物与失败语义

交付区是源媒体目录，只放可使用的最终资产：

工作区默认是 _process/，包含 raw ASR、corrected 字幕、字幕 QC、article brief/context、writing-skill 快照、editorial notes、diarization 数据和标题轮次草稿。

主流程失败会退出非零。诊断文件可能仍然存在，目录里也可能有此前运行的旧产物；以本次退出码、终端摘要和 QC 报告为准，不用“看见文件”代替成功判断。

可选：说话人归因

安装独立环境：

/opt/homebrew/bin/python3.11 -m venv venv-diarization
venv-diarization/bin/pip install -r requirements-diarization.txt
venv-diarization/bin/hf auth login

按 Hugging Face 页面提示接受 pyannote 模型条款。最轻量的 diarization：

venv-diarization/bin/python tools/speaker_attribution.py /path/to/video.mp4 \
  --srt /path/to/video.final.srt --num-speakers 2

有单人参考音频时：

venv-diarization/bin/python tools/build_speaker_refs.py /path/to/solo.m4a \
  --speaker host --out-dir data/speakers/host/refs --count 3 --clip-seconds 10

venv-diarization/bin/python tools/speaker_attribution.py /path/to/video.mp4 \
  --srt /path/to/video.final.srt \
  --speaker-ref host=data/speakers/host/refs/host_ref_01_000120s.wav \
  --assign-remaining guest --num-speakers 2

参考音频文件名末尾的秒数由 build_speaker_refs.py 自动生成；上面的 000120s 只是示例，实际命令使用脚本刚输出的路径。

声纹是生物识别材料，不提交 GitHub。ASR 负责“说了什么”，diarization 只负责“谁在说”；低置信位置保留 UNKNOWN／MIXED。 高光和文章只会自动采用与当前 final SRT 的 cue 时间轴和去除 speaker 前缀后文字一致的 .speaker_labeled.srt；无法校验或已过期的 sidecar 不会替换本次逐字稿。

可选：口头禅与假启动剪辑

先建立并审核 _process/.filler-cuts.json，然后 dry-run：

venv/bin/python tools/render_filler_cuts.py /path/to/video.mp4 \
  /path/to/video_process/video.filler-cuts.json \
  --output /path/to/video.clean.mp4 \
  --srt-in /path/to/video.final.srt \
  --srt-out /path/to/video_process/video.clean.candidate.srt \
  --dry-run

确认区间和预计删减时长后去掉 --dry-run。脚本只执行 decision: "cut" 的区间，永不覆盖源视频。字幕会按同一计划重映射时间，但先命名为 .clean.candidate.srt；部分 cue 内的文字不会被猜测性改写，必须对照成片修字，再通过 subtitle_qc.py --promote-srt ... --write-vtt ... 晋升为 .clean.final.srt/.vtt。详细判断与命令见 skill/references/filler-cut-editing.md。

外部制作与发布

• 封标由 skills/video-title-and-cover/SKILL.md 主责；完整双平台任务做独立 16:9／3:4，用户只要一个比例就只做该比例。人物选帧、原图要求、排版与实际成图交付见该 skill 的 references/cover-production.md；原 skill/references/cover-style-guide.md 保留为兼容链接。
• 双 WAV、剪前导和社区版压制见 skill/references/longform-community-delivery.md。这些是 recipe，不是主脚本承诺。
• Google Doc、Canva 与平台草稿依赖已安装 connector／浏览器能力。仓库不会自动安装或检测这些外部服务。
• 本地稿与平台 draft 可以直接创建；公开发布、通知、群发或覆盖线上内容前必须展示最终 payload、目的地和受众并取得批准。

开发与验证

python3 -m unittest discover -s tests -p 'test_*.py'
python3 -m compileall -q tools tests
python3 tools/process_video.py --help

单元测试覆盖文件契约、失败语义、字幕重切/QC、模型 CLI 封装与文章 context。它们不替代真实的 ASR 下载、Codex／Claude 登录、pyannote、ffmpeg 全片解码或平台上传测试。

常见问题

ASR 看起来没动？ 应使用当前 venv 同目录或 PATH 中的 mlx-qwen3-asr CLI，并保留可见进度。第一次运行还可能在下载模型。

校对显示 0 个修改？ 这不是质量证明。结合画面、seeds 和语境抽查专有名词、数字与否定词。

为什么没有 VTT？ 查看 _process/.subtitle_qc.md；QC 未通过时不会晋升 VTT。

Codex 不可用？ 内容步骤会显式报告并尝试 Claude fallback；两者都不可用时失败，不把旧文件冒充本次结果。Codex 内容模型可用 LIZHENG_CODEX_CONTENT_MODEL（或通用的 LIZHENG_CODEX_MODEL）覆盖，Claude fallback 可用 LIZHENG_CLAUDE_FALLBACK_MODEL（或 LIZHENG_CLAUDE_MODEL）覆盖；不设置时使用各自 CLI 当前默认。

为什么 fresh clone 没有小红书专用 skill 或 Canva？ 它们是可选外部能力。核心脚本自包含；外部能力可用时由 lizheng-video-editing 编排，不把个人机器路径写成仓库依赖。