jackyuyz/repo-demo-video-skill

Repo Demo Video

使用此技能将仓库转变为精美的产品演示计划，并在拥有足够运行时信息时，生成浏览器录制的演示视频。

核心原则

优先使用仓库中的证据，而不是用户配置：

1. 如果存在 demo.config.json 或 demo.config.yaml，则使用它们。
2. 如果存在 DEMO_GUIDE.md，则使用它。
3. 使用 README.md。
4. 使用 package.json、框架文件、路由文件夹、组件名称、页面标题和源代码结构。
5. 如果存在安全的 URL，则在浏览器中探索已部署或本地的应用。
6. 生成带有置信度分数的回退假设。

将 README.md 和源代码视为主要来源，DEMO_GUIDE.md 视为推荐的人工友好指南，demo.config.* 视为可选的机器友好覆盖。

工作流程

1. 解析目标仓库路径或 URL。对于 MVP CLI，使用本地仓库路径；如果提供的是 GitHub URL，请让用户提供本地克隆，除非将来明确提供克隆工作流程。

2. 运行分析器：

   npm run demo -- --repo ./path-to-repo
   

   可选输入：

   npm run demo -- --repo ./path-to-repo --config ./demo.config.json
   npm run demo -- --repo ./path-to-repo --url https://example.com
   npm run demo -- --repo ./path-to-repo --mode draft
   npm run demo -- --repo ./path-to-repo --mode full
   

3. 在时间戳命名的输出文件夹（例如 demoOutput-2026-05-10-143012/）中检查生成的工件：

   • project_summary.md
   • demo_plan.draft.json
   • demo_plan.json（置信度足够高时）
   • narration_script.draft.md
   • narration_script.md
   • script_quality_report.json
   • timing_plan.json
   • demo_storyboard.md
   • manual_recording_guide.md
   • recordings/（浏览器捕获成功时）
   • screenshots/（浏览器探索成功时）
   • voiceover.mp3（当设置了 TTS_PROVIDER=openai 和 OPENAI_API_KEY 时）
   • demo_video.html（当 MP4 合成不完整时，作为本地预览回退）
   • demo_video.mp4（仅当录制、真实音频和 ffmpeg 都可用时）

置信度规则

• 将明确的文档和配置声明标记为 high。
• 当项目名称、摘要和至少一个功能明确时，将 README 功能列表视为足以生成最终计划的证据。
• 将路由名称、组件名称、包元数据和清晰的代码结构标记为 medium。
• 将推测性的产品声明和猜测的操作标记为 low。
• 如果重要声明的置信度为低，则生成 demo_plan.draft.json，解释缺少的内容，并避免将最终视频计划呈现为确定的。

README 解析

• 在提取产品摘要时，忽略徽章、盾牌图片、装饰性图片行、原始 URL 和许可证/状态元数据。
• 优先使用 DEMO_GUIDE.md 的推介、README 的引用摘要、README 的概述/关于/描述部分，然后是包描述。
• 通过规范化标题再进行匹配，识别带有表情符号或符号的装饰性标题，例如 ## Features。
• 将功能/能力/亮点标题下的项目符号列表提取为高置信度功能。
• 将用法/如何操作/演示/快速启动标题下的编号工作流程提取为中等置信度的演示流程提示。
• 在编写脚本之前清理旁白输入；不要将 Markdown 徽章、图片语法或原始 URL 带入配音文本。

安全

• 保持仓库分析为只读。
• 仅将生成的工件写入目标仓库中新建的时间戳文件夹 demoOutput-YYYY-MM-DD-HHMMSS/。
• 不要递归删除文件或运行破坏性命令。
• 不要运行部署命令。
• 当用户请求旁白输出或配置了提供商环境变量时，允许调用外部 LLM/TTS。仅发送清理过的项目摘要、演示计划、浏览器观察结果和旁白脚本文本。
• 不要将原始的 .env 文件、API 密钥、私有令牌、私有用户数据、真实凭据或不必要的源文件发送给外部 LLM/TTS 提供商。
• 不要在旁白、截图、视频、日志或生成的工件中暴露秘密、API 密钥、私有令牌、.env 值、私有用户数据或真实凭据。
• 如果有测试账户记录，除非用户明确要求，否则仅提及使用了演示账户。

浏览器与视频行为

• 优先使用配置、DEMO_GUIDE.md、README、或 --url 参数中的已部署 demoUrl。
• 当 Playwright 可用时，使用它来检查可见的标题、按钮、链接、表单，并捕获截图或录制。
• 使用保守的 DOM 启发式方法填充安全的示例输入、选择非空的选择选项，并点击常见的演示控件，例如 Add、Calculate、Method、Resources、New 或 Create。
• 每个计划的场景在屏幕上保持足够长的时间以适应旁白节奏，在启发式操作后短暂暂停，使录制不仅仅是快速的点击。
• 在 run_report.json 中注册规范的 .webm 录制路径。
• 当运行说明不确定时，不要强制启动本地项目。
• 如果 Playwright、TTS、ffmpeg 或应用程序运行时不可用，仍然生成书面工件、部分交付物、demo_video.html 和手动录制指南。
• 根据配音时长合成最终的 MP4。不要使用最短流截断。如果浏览器录制短于配音，则使用 ffmpeg 的 tpad 扩展最终视频帧，并报告扩展时长。

专业脚本编写

• 使用确定性草稿作为回退，但当设置了 SCRIPT_PROVIDER=openai 和 OPENAI_API_KEY 时，优先使用 OpenAI 脚本编写器。
• 在编写最终脚本之前生成 timing_plan.json。基于可用功能、浏览器场景、配置的视频时长和节奏警告来生成。
• 对脚本编写和 OpenAI TTS 使用相同的 OPENAI_API_KEY。
• 在 src/prompts/demoNarrationPrompt.ts 中控制产品演示编写提示。
• 使用 OPENAI_SCRIPT_MODEL 控制 OpenAI Responses API 模型；如果未设置，则回退到 OPENAI_MODEL，然后回退到 gpt-5.4-mini。
• 编写 narration_script.draft.md 作为模板草稿，编写 narration_script.md 作为最终的 LLM 或回退脚本。
• 编写 script_quality_report.json，包含提供商、模型、回退原因和质量门控警告。
• 提示应使脚本编写者首先理解产品，避免徽章和原始 README 元数据，专注于受众/问题/价值，对不确定的声明使用保守措辞，并尊重时间计划中的场景数量和字数预算。

演示视觉引导

对于精美的浏览器录制，通过 Playwright 注入临时的非持久性视觉引导覆盖层，而不是编辑应用源代码。

使用：

• 当前旁白节拍的微妙标注说明。
• 活动 UI 元素或结果区域周围的高亮环。
• 高 z-index、pointer-events: none 和固定定位。
• 不遮挡产品 UI 的中性样式。

不要使用覆盖层来伪造功能。仅用于引导观看者注意力转向真实的 UI 状态变化。覆盖层必须仅存在于录制浏览器会话中，并在会话关闭时消失。

配音

• 当设置了 OPENAI_API_KEY 时，在完整模式下默认为 OpenAI TTS。
• 要明确生成真实音频，请设置 TTS_PROVIDER=openai 和 OPENAI_API_KEY。
• 如果 TTS_PROVIDER 未设置但存在 OPENAI_API_KEY，则使用 OpenAI TTS。
• 要强制本地模拟模式，请设置 TTS_PROVIDER=mock。
• OPENAI_API_KEY 可以与专业脚本编写器使用的密钥相同。
• 可选变量：OPENAI_TTS_MODEL、OPENAI_TTS_VOICE、OPENAI_TTS_INSTRUCTIONS、TTS_VOICE。
• 将真实音频写入当前运行文件夹，例如 demoOutput-2026-05-10-143012/voiceover.mp3。
• 将清理后的 voiceover_script.txt 文本发送到配置的 TTS 提供商是创建配音音频所必需的。
• 切勿将 API 密钥写入生成的文件中。
• 在发布演示时，披露生成的配音是 AI 生成的。

扩展技能

保持架构模块化。通过扩展相应的 src/*.ts 模块，而不是将 CLI 变成一个大型脚本，来添加对 GitHub URL 克隆、更深层次的 UI 交互、真实 TTS 提供商、字幕、视频样式、本地启动和人工审核的未来支持。