repo-cinema 导演技能
从代码库直接创建 Screen Studio 级别的 60fps 产品演示视频。代替临时的屏幕录制或光标无目的游走，repo-cinema 执行一个五阶段的确定性流水线：分析 -> 编排 -> 分镜 -> 渲染 -> 验证。
核心架构原则
- 角色优先用例（分析）：绝不展示内部调试统计或原始配置屏幕。阅读入口点、CLI 命令、路由、组件和测试，以综合出具体的
角色 -> 痛点 -> 用户操作 -> 持久结果场景。 - 因果共帧（编排）：框定 联合包围盒
bbox(触发 ∪ 结果)，而不是追踪鼠标指针。当内容宽度占据舞台 >= 70% 时，将水平焦点锁定fx = viewport.width / 2，从而确保坐标轴、标题和右侧列不会裁剪到屏幕外。 - 静止阅读停顿：在操作前缓慢拉近相机，然后在交互和理解期间保持
(zoom, fx, fy)100% 冻结，以便观众能够看清图表和提示更新。 - 确定性虚拟时钟 60fps（渲染）：在页面加载前注入虚拟时钟垫片（
Date、performance.now、requestAnimationFrame），使得 CSS 过渡、ECharts 动画、C2 最小突变光标轨迹（sin^3(pi * u)弧线，速度波动 <=12%，+/-6 度倾斜，箭头与指向手形之间的变形）以及双点击涟漪，能够在 FFmpeg 中逐帧确定性地步进。 - 联系单自检（验证）：生成
3x3的contact-sheet.png和verify-report.json（包含ffprobe流验证以及零界外点击），并在交付前目视检查每一个面板。
实用 CLI 命令（repo-cinema）
当全局安装或从仓库执行时（npx repo-cinema ... 或 node dist/cli.js ...），每个阶段都输出结构化文件：
# 1. 读取任何仓库并提取用例场景（可选先运行 repomix）
repo-cinema analyze --repo ./my-project --output ./out/dossier.json [--repomix]
# 2. 构建因果相机/光标分镜板 JSON + 视觉 HTML 预览
repo-cinema plan --dossier ./out/dossier.json --output ./out/storyboard.json --html ./out/storyboard.html --theme aurora-indigo
# 3. 构建四合一舞台（web-url | plugin-or-component | cli-terminal | hybrid）
repo-cinema stage --dossier ./out/dossier.json --plan ./out/storyboard.json --output ./out/stage.html [--url http://localhost:3000]
# 4. 确定性 60fps CDP 捕获 + 48kHz 立体声 SFX（或可选 TTS）
repo-cinema render --plan ./out/storyboard.json --stage ./out/stage.html --output ./out/demo.mp4 --gif ./out/demo.gif --audio sfx
# 5. 验证流、遥测边界并构建 3x3 视觉联系单
repo-cinema verify --video ./out/demo.mp4 --telemetry ./out/demo.telemetry.json --contact-sheet ./out/contact-sheet.png --output ./out/verify.json
# 或在一个命令中运行完整的五阶段流水线：
repo-cinema run --repo ./my-project --out-dir ./out --theme aurora-indigo
导演工作流程
步骤 1：分析仓库与受众
运行 repo-cinema analyze --repo <path> --output <dossier.json>。阅读生成的 useCases：
- 验证检测到的
archetype（web-app、desktop-or-ide-plugin、cli-tool、ui-library、hybrid）。 - 如果仓库具有专门的工作流，则优化字幕或添加领域真实的示例夹具（记住：零个人数据，零仅限开发者的计数器）。
步骤 2：编排分镜板并批准取景
使用 --html 运行 repo-cinema plan 并检查 storyboard.html（或回顾 beats、captionWarnings 和 cameraKeyframes）：
- 修复来自反废话字幕检查器的任何警告（没有“前所未有”、“下一代”、“无缝地”或超过 96 个字符的字幕）。
- 确保开场帧（
t=0）和结束帧（t=durationMs）在zoom: 1.0处干净对齐，以实现 README 动图的流畅循环。
步骤 3：选择舞台适配器
web-url：应用已在本地运行（http://localhost:PORT）。录制器将虚拟时钟垫片以及非侵入式光标/相机/字幕叠加层直接注入到实时页面。plugin-or-component：桌面插件（Obsidian、VS Code、Raycast）或 UI 组件包在深色 macOS Studio 镀铬框架内渲染，并通过esbuild打包真实的核心模块。cli-terminal：终端工具在玻璃质感的 macOS 终端中展示，带有同步的命令输出、KPI 磁贴和结果影响卡片。hybrid：多标签 macOS Studio 将 CLI 执行与实时视觉输出和架构图配对。
步骤 4：渲染 60fps 母版 + GIF + 音频
运行 repo-cinema render：
- 默认
--audio sfx合成零依赖的 48kHz 立体声微音效（立体声平移的点击与光标x对齐，轻柔的缩放空气呼啸声，确认提示音）——无需外部 API 密钥。 - 可选
--audio tts --tts-provider <macos-say|edge-tts|openai|elevenlabs>干净地将旁白与微音效混合。
步骤 5：验证与目视检查
运行 repo-cinema verify 并使用你的文件/图像查看器直接检查 contact-sheet.png：
- 确认
passed: true、offscreenClicks: 0，并且所有 9 个关键帧缩略图上的文本清晰可读。 - 如果任何元素在视口边缘附近被裁剪，则在
computeCausalFraming中增加marginPx或将zoom减少0.06并重新渲染。
参考指南
应避免的常见错误
- 在打字/拖拽期间逐帧跟随指针：会导致晕动。务必在停顿期间在每个节拍锁定相机取景。
- 使用挂钟
setTimeout/ 实时屏幕捕获：每当 CPU 峰值时就会丢帧，产生断断续续的 24–40fps 录制。始终通过__rcStep(dtMs)驱动动画。 - 在宽图表或表格上过度缩放（
> 1.35x）：会裁剪 Y 轴标签或最右侧的汇总列。将wideLockRatio保持在0.70，以便fx = width / 2。 - 将大块原始
.mp4二进制文件提交到 GitHub 仓库：在docs/assets/中追踪轻量调色板优化的.gif和contact-sheet.png，并将.mp4附加到 GitHub Releases 或在本地忽略*.mp4。