ce-demo-reel

捕获视觉演示卷 — GIF、终端录制、屏幕截图 — 用于 PR 描述。真实的产品使用情况，而不是测试输出。

ce-demo-reel 是证据捕获技能。它检测项目类型，推荐正确的捕获层（浏览器卷轴/终端记录/屏幕截图卷轴/静态屏幕截图），记录实际运行的功能，上传到公共 URL，并返回准备好 PR 描述的 Markdown。 证据意味着使用产品，而不是运行测试——“我运行了 npm test”是测试证据。 Capture 正在运行实际的 CLI 命令、打开 Web 应用程序、进行 API 调用或触发功能。

当更改具有可观察到的行为时，它最常由 /ce-commit-push-pr 调用，但当您想事后将演示添加到 PR 描述时，也会直接调用它。

TL;DR

＃＃ 问题

由于可预见的原因，没有证据的公关描述较弱：

• 审阅者看不到发生了什么变化 — 他们必须克隆、构建、运行和重现，只是为了验证 UI 渲染
• 视觉回归是无声的 - 没有记录基线意味着未来的回归可能会在几周内被忽视
• 证据在压力下被伪造 - 当捕获真实流程很困难时，代理会替换测试输出并将其标记为“演示”
• 捕获焦点 - 弄清楚要使用哪个工具，获得正确的窗口大小，找到公共主机，生成降价 - 所有这些都会分散运输的注意力
• 秘密泄漏到录音中 - CLI 输出、URL 栏、DevTools、env 导出中的凭据 - 演示随泄漏一起提供
• 仅本地工件 — 磁盘上的录音从未达到 PR 描述，或者在本地文件移动时中断

解决方案

ce-demo-reel 作为具有显式回退的结构化捕获流运行：

• 项目检测自动选择正确的层（Web 应用程序的浏览器卷轴，CLI 的终端记录）
• 真实产品使用 — 该技能首先练习该功能以验证其是否有效，然后捕获
• 层后备链 — 如果所选层失败，技能将下降到下一个可用层，而不是运行失败
• 设计保密 — 录音仅保留在可见的记录中；秘密保留在环境变量中或框架外；预上传扫描发现泄漏
• 测试输出永远不会标记为“演示” - 这种区别是绝对的
• 上传到公共主机 — 返回准备用于 ## Demo 嵌入的真实公共 URL
• 在不相关时干净地跳过 - 仅文档，仅降价，内部重构得到明确的“不需要证据”而不是虚假替代品

是什么让它如此新颖

1. 证据意味着使用产品——与测试输出严格分离

该技能强制执行绝对区别：**证据是运行实际的 CLI 命令、打开 Web 应用程序、进行 API 调用或触发功能。**测试输出（npm test、pytest 等）永远不会标记为“演示”或“屏幕截图”。如果实际的产品使用不切实际（需要 API 密钥、云部署、付费服务、机器人令牌），该技能会明确说明并建议回退，而不是默默地替换测试输出。

2. 四层——按项目类型和变化形状选择

建议考虑项目类型（Web 应用程序与 CLI）、更改分类（动作与状态）和工具可用性（预检检查确认已安装的内容）。用户在可用的层中进行选择。

3.无状态目标发现——分支感知，不受会话限制

该技能假设可以在工作完成后在新会话中调用它。它不依赖于对话历史记录，也不假设呼叫者知道正确的工件。目标发现使用：当前分支名称、打开的 PR 标题和描述、更改的文件和差异、最近的提交以及仅在明显引用时的计划文件。当被另一个技能调用时，调用者提供的目标被视为提示，而不是证据 - 该技能在捕获之前重新运行目标发现和验证。

4. 设计上的秘密安全——记录卫生，而不是事后模糊

该技能从不记录凭据。秘密影响环境，而不是可见的文字记录：

• 计划框架外的秘密 — 记录前设置的环境变量、通过环境变量而不是标志值调用的 CLI、经过身份验证的状态演示（不是身份验证步骤）
• 录音中没有占位符替换 - 输入假的 sk-xxxxx 会产生误导性的工件，并可能破坏演示（401 Unauthorized 因为假的环境变量会覆盖真实的环境变量）
• 预上传扫描 — 查找 sk-、ghp_、Bearer、Authorization:、?token=、api_key=、靠近凭据探测标签的长十六进制/base64。如果出现任何情况，丢弃并重新捕获。切勿模糊或裁剪。

5.运行时后备链

如果所选层在执行期间失败（工具崩溃、服务器无法访问、记录产生空输出），则技能将回退到下一个可用层，而不是运行失败：

• 浏览器卷轴 → 静态屏幕截图
• 终端录音→截图卷轴→静态截图
• 屏幕截图卷轴 → 静态屏幕截图
• 静态截图→向用户报告失败

6. 飞行前工具检测

在捕获之前，预检脚本会检查工具可用性（agent_browser、vhs、silicon、ffmpeg、ffprobe）并输出哪些层可用。该技能会打印缺少工具的安装命令（brew install charmbracelet/tap/vhs、brew install silicon），以便用户可以根据需要启用更丰富的层。

7. 操作系统临时文件中每次运行的暂存目录

每次捕获都会在操作系统临时 (mktemp -d -t demo-reel-XXXXXX) 中创建一个用于临时工件的每次运行目录。录音被上传到公共主机然后被丢弃——它们不会污染存储库树。用户只能看到最终的 URL。

8. 上游调用者的稳定输出合约

该技能返回一个结构化信封 (Tier、Description、URL、Path)，其中 URL 或 Path 中的一个恰好带有实际值（另一个是 "none"）。调用者（通常是 /ce-commit-push-pr）将其格式化为 PR 描述的 ## Demo 或 ## Screenshots 部分。静态屏幕截图获得“屏幕截图”标签；所有动作层都获得“演示”。测试输出也永远不会得到。

简单示例

您完成了通知设置页面。您调用 /ce-commit-push-pr，它会检测可观察的行为并询问是否捕获证据。你说是的。它加载 /ce-demo-reel。

该技能从分支 + PR 差异中发现目标：带有切换的设置页面路由。它练习该功能（导航到 /settings/notifications，切换一些选项，验证热重载工作）。检测项目类型为 web-app (Next.js)。将更改分类为 motion（切换状态更改、微动画）。

预检发现 agent_browser 和 ffmpeg 可用 — 建议 浏览器卷轴。你确认一下。该技能通过切换流程捕获一系列代理浏览器屏幕截图，通过 ffmpeg 将它们拼接成 GIF，扫描机密（未找到），上传到公共主机，返回 URL。

/ce-commit-push-pr 将 ## Demo 与嵌入到 PR 正文中的 GIF 拼接。总耗时：~30 秒。

何时去实现它

在以下情况下使用 ce-demo-reel：

• PR 具有值得展示的可观察行为（UI 渲染、CLI 输出、带有可运行示例的 API 调用）
• 错误修复前后值得展示
• 该功能需要散文无法捕捉到的交互或动作
• 您正在提供输出格式很重要的 CLI 功能

在以下情况下跳过 ce-demo-reel：

• 更改是仅文档、仅降价、仅 CI、仅测试或纯内部重构 - 选择“无需证据”
• 真正的产品使用需要您没有的资源（付费服务、云部署、机器人令牌）——明确地说出来，而不是伪造它
• 差异真正说明了一切

用作工作流程的一部分

当行为可观察时，其他技能会调用 ce-demo-reel：

• /ce-commit-push-pr 步骤 6 — 当更改具有 UI / CLI / API 行为时调用此技能并询问用户是否捕获
• /ce-work 阶段 4.1 — 证据上下文 — 标记证据是否可能，以便 ce-commit-push-pr 可以提出正确的问题

该技能返回 Tier、Description、URL、Path — 调用者决定如何将结果格式化为 PR 描述。

使用独立版

该技能也是直接调用的：

• PR 已打开后 — /ce-demo-reel "the new settings page" 将演示添加到现有 PR
• 对于特定行为 — /ce-demo-reel "CLI output of the migrate command"
• 没有描述 — /ce-demo-reel 从分支/PR/diff 上下文推断并询问是否不明确

当在 ce-commit-push-pr 外部调用时，用户通常将返回的 markdown 手动复制到 PR 描述中，或单独使用 gh pr edit --body-file 。

＃＃ 参考

一旦计算出推荐，就会将等级选择作为一个阻塞问题提供；用户在可用层中进行选择。

＃＃ 常问问题

为什么测试输出没有证据？ 测试证明孤立的逻辑；他们没有透露该功能是否适用于用户。审阅者需要知道“使用时它是什么样子”，而不是“单元测试是否通过”（CI 表明了这一点）。严格的分离可以防止代理用简单的测试运行来代替更困难的实际产品捕获。

如果真实证据需要我不想记录的凭据怎么办？ 在录制开始之前，在录制区域之外设置凭证。演示经过验证的结果，而不是验证步骤。切勿在录制内容中输入 export API_KEY=fake — 这会覆盖您的真实环境变量并破坏演示 (401 Unauthorized)。如果您无法在不透露秘密的情况下捕获，请说出来并选择“不需要证据”或建议后备。

如果所选层在捕获过程中失败怎么办？ 该技能会回退到下一个可用层，而不是完全失败。浏览器卷轴 → 静态屏幕截图。终端录音→截图卷轴→静态截图。即使静态屏幕截图也失败，该技能也会报告失败并让您做出决定。

GIF 或屏幕截图位于哪里？ 每次运行的工件会转到操作系统临时 (/tmp/...) 并上传到公共主机。本地文件是短暂的。 URL进入PR描述；本地副本将被丢弃。

--full 页面截图怎么样？ 静态屏幕截图层支持通过代理浏览器的 screenshot --full 对于高页面进行全页捕获。该技能根据所演示的内容选择正确的捕捉模式。

为什么它不会自动模糊掉的秘密？ 因为部分模糊是一种已知的不良缓解措施，即使是裁剪或模糊的秘密也可能通过元数据、帧边缘或可见模式泄漏。该技能的规则是：上传前扫描，如果有任何东西看起来像秘密，则重新捕获。夺回是唯一的补救办法。

另请参阅

• ce-commit-push-pr — 主要调用者；将捕获的证据拼接到 PR 描述中
• ce-work — 在阶段 4.1 标记证据上下文，以便 PR 流程可以提出正确的问题
• ce-test-browser — 用于端到端浏览器测试的同级技能（不同的目标：验证行为，而不是捕获）