Validated Engineering Playbook · 2026-08-06

Engineering Demo Video Production

从真实 CLI 与产品 UX 素材构建可信、清晰、流畅的工程演示视频。该 Playbook 来自 FNTK 跨 GitHub Copilot CLI、Codex CLI、Claude Code CLI 和 Microsoft Fabric Notebook 的完整录制与多轮修订。

Plan → Capture → Edit → Verify → Publish OBS / RDP FFmpeg Fixed-rate narration Truthful agent story 1920×1080 / 30 FPS

Download SKILL.md Download validator Storyboard template Capture checklist Detailed lessons

核心原则

画面是事实来源

旁白、字幕和 agent 标签必须与最终画面一致。不能按原 storyboard 猜测，也不能叙述没有实际发生的操作。

状态必须按时间真实

baseline 阶段只能展示当时的 Notebook。后续 agent 添加的内容不能提前出现在前面的 Fabric UX。

不要为铺满而拉伸

保持宽高比。先裁剪真实空画布，再等比 scale，最后用 pad/letterbox 补足 1080p。

录制时保证可读

4K desktop Fit 到 1080p 会让 CLI 字体过小。录制前放大终端字体，后期锐化不能恢复已经丢失的像素。

失败也要真实

遇到 usage limit 或 auth failure，简短展示真实错误并透明说明，不伪造成功输出。

自动检查 + 人工审片

blackdetect 和 silencedetect 只能发现技术异常；错误 agent 标签、重复开页和状态泄漏仍需 contact sheet 人工确认。

五阶段工作流

1. Plan — 写 story state contract：每段使用哪个 agent、显示什么 prompt、发生哪些真实操作、结束后 artifact 处于什么状态、最终由哪个产品 UX 证明结果。

2. Capture — 每个 agent 独立录制。显示 prompt、命令、进度和结果；任何 monitor/RDP 变化后先录 10 秒测试。最后录一段干净稳定的产品 UX。

3. Edit — 删除等待、重复 polling、OBS 控件和误切窗口。只加速等待区间，保留 prompt、关键结果和最终 UX。优先连续素材，不用长时间 freeze 填空。

4. Narrate — 所有句子使用同一 voice/rate/volume，不用 atempo。旁白描述当前可见内容，普通停顿控制在 2–5 秒，超过 7 秒进入 review。

5. Verify — 检查 stream、duration、black、silence、每 5 秒 contact sheet、所有章节边界前后 ±1 秒和 SHA-256。最终 narration 后保留 2–3 秒稳定 UX。

真实项目验证结果

问题	初始表现	最终处理
OBS + RDP	自动录制出现长黑屏和 monitor 不稳定	切换为人工分段录制，并在每次屏幕变化后预检
分辨率	4K Fit-to-screen 后 CLI 文字过小	使用可读字体和按比例的 1080p 输出
画面比例	宽素材直接铺满造成高度拉伸	scale + pad + `setsar=1`
故事真实性	旁白曾误称切回 Copilot；baseline UX 曾含后续 Claude 内容	按最终时间线重写旁白，并使用正确阶段的 UX 素材
结尾 UX	Fabric 页面多次打开，形成循环	只播放一次打开过程，随后保持稳定页面
流畅度	最长旁白空白约 16.3 秒	保持固定语速、补充有信息量的旁白，降至约 6.5 秒

质量门槛

非预期黑屏

blackdetect 发现任何业务段黑屏都应阻止交付。

≤ 7s

最长业务静默

超过阈值应补充有价值的 narration 或压缩画面，不通过变速说话解决。

2–3s

最终稳定停留

音频结束后保留最终 UX，给观众确认结果的时间。

推荐验证命令

pwsh -NoLogo -NoProfile -NonInteractive `
  -File .\validate_video.ps1 `
  -VideoPath .\final.mp4 `
  -TransitionTimes 18,38,58,82,105,125,149,163,177

输出包含 probe metadata、black/silence log、五秒 contact sheets、transition frames 和 SHA-256 manifest。

快速决策

观察到的问题	正确处理	不要这样做
OBS 黑屏	更换 capture source/method，重新录 10 秒预检	继续完成整段长录制后再检查
文字不可读	放大终端字体后重录	只依赖后期 sharpen
素材不满 16:9	保持比例并 letterbox	独立拉伸高度
命令等待很长	保留开始和结果，加速或剪掉中间	长时间 freeze 或重复播放
agent 被限流	展示真实限制并透明说明	构造成功输出
音画不一致	以画面为准重写 narration 或替换素材	保留不真实的原稿