视频成片流水线

一个技能覆盖短视频成片的全部加工环节。不要新建同类技能——
历史上因为每条流水线单独建技能，导致 8 个技能职责重叠、参数互相矛盾。

硬规则（先读，比技术细节更容易出错）

1. 先跑 --probe 看清素材的真实分辨率、时长、方向、有无音轨，再决定参数。
2. 用户对素材的标注必须实测复核。曾出现用户明确说「11~15 无需去水印」，
   逐条复核发现 15 确实有水印。直接采信就会露水印。
3. 不要重写脚本、不要临时手搓 ffmpeg。脚本里已固化踩过的坑，
   直接改参数调用即可。重写 = 浪费 token + 重踩旧坑。
4. 自带旁白的素材只用硬切 concat，不要 xfade（会削掉段首段尾旁白）。
5. 成片必须核验后再交付：时长、分辨率、帧率、体积、交界处抽帧顺序。
6. 破坏性操作前先确认；清理只清自己建的临时目录。
7. 用对解释器。报「缺少依赖」时先怀疑解释器，而不是急着重装——
   本机依赖装在 venv 里（见文末「环境依赖自检」）。

按用户意图路由

去水印策略怎么选（实测数据）

结论：整条长片一律不要用 inpaint，时间上不可接受。详见 references/watermark.md。

脚本清单

全部位于 scripts/，都支持 --help。

参数怎么填：先问再猜

不确定去水印框、字幕位置、字高这些数值时，用脚本自带的测量模式先量：

python remove_watermark.py measure --src a.mp4          # 出 watermark_measure.png
python subtitle_char_replace.py --analyze --src a.mp4 --at 9.6 --band 900,1080
python merge_clips.py --segments a.mp4 b.mp4 --probe

测量结果都要肉眼复核脚本输出的对照图再定参数。

参考文档（经验细节都在这里）

快速示例

最常见的任务：图片片头 + 视频合并 + 去水印

cd <技能目录>/scripts

# 1) 先看清素材，并确认哪几条真有水印
python merge_clips.py --segments 封面.png:3 1.mp4 2.mp4 结尾.png:3 --probe
python remove_watermark.py measure --src 1.mp4     # 看 watermark_measure.png

# 2) 合并（含去水印 + 关键帧核验）
python merge_clips.py --delogo auto \
    --segments 封面.png:3 1.mp4 2.mp4 结尾.png:3 \
    --out 成片.mp4 --check-frames 8

加旁白和逐句字幕

# 写 task.json（结构见 references/narration-tts.md）
python tts_narration.py segments --task task.json

改一个字幕错字

python subtitle_char_replace.py --analyze --src a.mp4 --at 9.6 --band 900,1080
# 按实测的 bbox / 白芯中心 / 字高 填参数
python subtitle_char_replace.py --src a.mp4 --out a_fixed.mp4 \
    --char 他 --t1 9.33 --t2 10.41 \
    --box 249 945 49 59 --center 274 975 --core-h 43

环境依赖自检

先确认用哪个 Python 跑。 最常见的事故是「明明装过却报缺依赖」——
装依赖的解释器和跑脚本的解释器不是同一个。本机装了依赖的是虚拟环境：

# 本机已验证可用的解释器
C:/Users/michael/.workbuddy/binaries/python/envs/default/Scripts/python.exe

先用它跑一遍自检：

<上面的 python> scripts/selfcheck.py

期望输出（本机已验证）：ffmpeg 7.1 + 三种中文字体 + PIL/numpy/cv2/edge_tts/imageio_ffmpeg 全 OK。

need() 报「缺少依赖」时会一并打印当前解释器路径，照着对比就能定位。

缺依赖时的安装（装进同一个解释器）：

<上面的 python> -m pip install imageio-ffmpeg Pillow numpy opencv-python edge-tts

找不到 ffmpeg 或字体时，可显式指定：

export VIDEO_PIPELINE_FFMPEG=/path/to/ffmpeg
export VIDEO_PIPELINE_FONT=/path/to/font.ttc

> 脚本内部自调用（如 merge_clips.py 调 remove_watermark.py）统一用
> _common.python_exe()（即 sys.executable），所以只要启动时用对了解释器，
> 后续就不会串味。

关于发布到技能市场

本技能已按平台要求做了可移植化（无硬编码路径、依赖运行时探测），
frontmatter 也已补齐平台强制字段。上架前只需改两处：

author: TODO          # ← 改成你的名称
category: TODO        # ← 改成平台的合法分类之一（如 writing），
                      #    取错值会解析失败

打包注意（已自检通过）：

流程：open.workbuddy.cn 提交 ZIP → 解析 → 审核 → 审核通过后还要点一次「发布」。
平台目前没有付费/分成通道（腾讯不参与合作方收益分成）。

> ⚠️ 去水印能力有合规敏感性。AI 生成内容标识在国内有明确要求，
> 「去除 AI 生成标识」类技能公开上架很可能过不了平台合规审核。
> 建议只做团队内「专用发布」，不要公开发布。