ce-demo-reel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Demo Reel

演示素材合集

Detect project type, recommend a capture tier, record visual evidence, upload to a public URL, and return markdown for PR inclusion.

Evidence means USING THE PRODUCT, not running tests. "I ran npm test" is test evidence. Evidence capture is running the actual CLI command, opening the web app, making the API call, or triggering the feature. The distinction is absolute -- test output is never labeled "Demo" or "Screenshots."

If real product usage is impractical (requires API keys, cloud deploy, paid services, bot tokens), say so explicitly: "Real evidence would require [X]. Recommending [fallback approach] instead." Do not silently skip to "no evidence needed" or substitute test output.

Never generate fake or placeholder image/GIF URLs. If upload fails, report the failure.

检测项目类型，推荐捕获等级，录制可视化证据，上传到公开URL，然后返回可嵌入PR的markdown内容。

证据指的是实际使用产品的结果，而非运行测试的输出。 "I ran npm test"属于测试证据。证据捕获指的是运行实际CLI命令、打开Web应用、调用API，或是触发对应功能。这条界限是绝对的——测试输出绝对不能标注为"Demo"或"Screenshots"。

如果实际使用产品不现实（需要API密钥、云端部署、付费服务、机器人令牌），请明确说明："真实证据需要 [X]。建议采用 [fallback approach] 作为替代。" 不要默默跳过直接判定"无需证据"，或是用测试输出替代。

绝对不要生成伪造或占位的图片/GIF URL。如果上传失败，请直接报告失败。

Arguments

参数

Parse

$ARGUMENTS

What to capture: A description of the feature or behavior to demonstrate. If provided, use it to guide which pages to visit, commands to run, or states to capture.
If blank, infer what to capture from recoverable branch or PR context. If the target remains ambiguous after that, ask the user what they want to demonstrate before proceeding.

解析

$ARGUMENTS

：

捕获内容：需要演示的功能或行为的描述。如果提供了该参数，用它来指导需要访问哪些页面、运行哪些命令，或是捕获哪些状态。
如果为空，从可恢复的分支或PR上下文推断需要捕获的内容。如果推断后目标仍不明确，在继续操作前先询问用户想要演示的内容。

Step 0: Discover Capture Target

步骤0：确定捕获目标

Treat target discovery as stateless and branch-aware. The agent may be invoked in a fresh session after the work was already done, so do not rely on conversation history or assume the caller knows the right artifact.

If invoked by another skill, treat the caller-provided target as a hint, not proof. Rerun target discovery and validation before capturing anything.

Use the lightest available context to identify the best evidence target:

Current branch name
Open PR title and description, if one exists
Changed files and diff against the base branch
Recent commits
A plan file only when it is obviously referenced by the branch, PR, arguments, or caller context

Form a capture hypothesis: "The best evidence appears to be [behavior]."

Proceed without asking only when there is exactly one high-confidence observable behavior and a plausible way to exercise it from the workspace. Ask the user what to demonstrate when multiple behaviors are plausible, the diff does not reveal how to exercise the behavior, or the requested target cannot be mapped to a product surface.

Skip evidence with a clear reason when the diff is docs-only, markdown-only, config-only, CI-only, test-only, or a pure internal refactor with no observable output change.

将目标识别视为无状态且感知分支的流程。Agent可能是在工作完成后在新会话中被调用的，所以不要依赖对话历史，也不要假设调用者知道正确的产物。

如果是被其他Skill调用，将调用者提供的目标视为提示而非最终结论。在捕获任何内容前重新运行目标识别和校验流程。

使用最轻量的可用上下文来识别最佳证据目标：

当前分支名
已开启的PR标题和描述（如果存在）
改动的文件以及与基础分支的diff
最近的提交
仅当计划文件被分支、PR、参数或调用者上下文明确引用时才参考计划文件

形成捕获假设："最佳证据似乎是 [behavior]。"

仅当存在且仅存在一个高置信度的可观测行为，并且可以在工作区中合理触发它时，才无需询问直接继续。如果存在多个可能的行为、diff没有说明如何触发该行为，或是请求的目标无法对应到产品表面层，请询问用户需要演示的内容。

如果diff仅涉及文档、markdown、配置、CI、测试，或是没有可观测输出变更的纯内部重构，可跳过证据捕获并给出明确理由。

Step 1: Exercise the Feature

步骤1：运行验证功能

Before capturing anything, verify the feature works by actually using it:

CLI tool: Run the new/changed command and confirm the output is correct
Web app: Navigate to the new/changed page and confirm it renders correctly
Library: Run example code using the new/changed API
Bug fix: Reproduce the original bug scenario and confirm it's fixed

Use the workspace where the feature was built. Do not reinstall from scratch. If setup requires credentials or services, use the platform's blocking question tool (

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini) to ask the user.

在捕获任何内容前，通过实际使用来验证功能是否正常运行：

CLI工具：运行新增/改动的命令，确认输出正确
Web应用：导航到新增/改动的页面，确认渲染正常
库：使用新增/改动的API运行示例代码
Bug修复：复现原始Bug场景，确认已修复

使用构建该功能的工作区。不要从头重新安装。如果设置需要凭证或服务，使用平台的阻塞提问工具（Claude Code中用

AskUserQuestion

，Codex中用

request_user_input

，Gemini中用

ask_user

）询问用户。

Step 2: Detect Project Type

步骤2：检测项目类型

Use the capture target from Step 0 to decide which directory to classify. If the diff touches a specific subdirectory with its own package manifest (e.g.,

packages/cli/

apps/web/

), pass that as the root. Otherwise use the repo root.

bash

python3 scripts/capture-demo.py detect --repo-root [TARGET_DIR]

This outputs JSON with

type

and

reason

. The result is a signal, not a gate. If the agent's understanding from Step 0 contradicts the script's classification (e.g., the diff clearly changes CLI behavior but the repo root classifies as

web-app

because of a sibling Next.js app), the agent's judgment wins.

使用步骤0得到的捕获目标确定需要分类的目录。如果diff修改了某个包含独立包清单的子目录（例如

packages/cli/

、

apps/web/

），将该目录作为根目录传入。否则使用仓库根目录。

bash

python3 scripts/capture-demo.py detect --repo-root [TARGET_DIR]

该命令会输出包含

type

和

reason

的JSON。结果仅作为参考，而非判定依据。如果步骤0中Agent的理解与脚本的分类矛盾（例如diff明显改动了CLI行为，但仓库根目录因为存在同级Next.js应用被分类为

web-app

），以Agent的判断为准。

Step 3: Assess Change Type

步骤3：评估改动类型

Step 0 already handled the "no observable behavior" early exit. This step classifies changes that DO have observable behavior into

motion

states

to guide tier selection.

If arguments describe what to capture, classify based on the description. Otherwise, use the diff context from Step 0.

Change classification:

Involves motion or interaction? (animations, typing flows, drag-and-drop, real-time updates, continuous CLI output) -> classify as
```
motion
```
.
Involves discrete states? (before/after UI, new page, command with output, API response) -> classify as
```
states
```
.

Change characteristic	Classification
Animations, typing, drag-and-drop, streaming output	`motion`
New UI, before/after, command output, API responses	`states`

Feature vs bug fix -- what to demonstrate:

New feature (
feat
): Demonstrate the feature working. Show the hero moment -- the feature doing its thing.
Bug fix (
fix
): Show before AND after. Reproduce the original broken state (if possible) then show the fix. If the broken state can't be reproduced (already fixed in the workspace), capture the fixed state and describe what was broken.

Infer feat vs fix from commit messages, branch name, or plan file frontmatter (

type: feat

type: fix

). If unclear, ask.

步骤0已经处理了"无可观测行为"的提前退出场景。本步骤将确实存在可观测行为的改动分类为

motion

（动态）或

states

（静态），用于指导等级选择。

如果参数中说明了需要捕获的内容，根据描述分类。否则使用步骤0得到的diff上下文。

改动分类规则：

涉及动态效果或交互？（动画、输入流程、拖拽、实时更新、连续CLI输出）-> 分类为
```
motion
```
。
涉及离散状态？（UI前后对比、新页面、带输出的命令、API响应）-> 分类为
```
states
```
。

改动特征	分类
动画、输入、拖拽、流式输出	`motion`
新UI、前后对比、命令输出、API响应	`states`

新功能vsBug修复——演示内容：

新功能(
feat
)：演示功能正常运行。展示核心亮点——功能正常工作的瞬间。
Bug修复(
fix
)：展示修复前后的效果。如果可能复现原始的损坏状态，然后展示修复效果。如果无法复现损坏状态（工作区中已经修复），捕获修复后的状态并说明之前的问题。

从提交信息、分支名、或计划文件的前置元数据（

type: feat

或

type: fix

）推断是新功能还是修复。如果不明确，询问用户。

Step 4: Tool Preflight

步骤4：工具预检查

Run the preflight check:

bash

python3 scripts/capture-demo.py preflight

This outputs JSON with boolean availability for each tool:

agent_browser

vhs

silicon

ffmpeg

ffprobe

. Print a human-readable summary for the user based on the result, noting install commands for missing tools (e.g.,

brew install charmbracelet/tap/vhs

for vhs,

brew install silicon

for silicon,

brew install ffmpeg

for ffmpeg).

运行预检查命令：

bash

python3 scripts/capture-demo.py preflight

该命令输出包含每个工具可用状态（布尔值）的JSON：

agent_browser

、

vhs

、

silicon

、

ffmpeg

、

ffprobe

。根据结果为用户打印易读的汇总信息，注明缺失工具的安装命令（例如vhs对应

brew install charmbracelet/tap/vhs

，silicon对应

brew install silicon

，ffmpeg对应

brew install ffmpeg

）。

Step 5: Create Run Directory

步骤5：创建运行目录

Create a per-run scratch directory in the OS temp location:

bash

mktemp -d -t demo-reel-XXXXXX

Use the output as

RUN_DIR

. Pass this concrete run directory to every tier reference. Evidence artifacts are ephemeral — they get uploaded to a public URL and then discarded. The OS temp directory is the right place for them, not the repo tree.

在操作系统临时目录下创建每次运行独立的临时目录：

bash

mktemp -d -t demo-reel-XXXXXX

将输出作为

RUN_DIR

。将这个具体的运行目录传入所有等级引用中。证据产物是临时的——它们会被上传到公开URL然后被丢弃。操作系统临时目录是合适的存储位置，不要放在仓库目录树中。

Step 6: Recommend Tier and Ask User

步骤6：推荐等级并询问用户

Run the recommendation script with the project type from Step 2, change classification from Step 3, and preflight JSON from Step 4:

bash

python3 scripts/capture-demo.py recommend --project-type [TYPE] --change-type [motion|states] --tools '[PREFLIGHT_JSON]'

This outputs JSON with

recommended

(the best tier),

available

(list of tiers whose tools are present), and

reasoning

Present the available tiers to the user via the platform's blocking question tool (

AskUserQuestion

in Claude Code,

request_user_input

in Codex,

ask_user

in Gemini). Mark the recommended tier. Always include "No evidence needed" as a final option.

Question: "How should evidence be captured for this change?"

Options (show only tiers from the

available

list, order by recommendation):

Browser reel -- Agent-browser screenshots stitched into animated GIF. Best for web apps.
Terminal recording -- VHS terminal recording to GIF. Best for CLI tools with interaction/motion.
Screenshot reel -- Styled terminal frames stitched into animated GIF. Best for discrete CLI steps.
Static screenshots -- Individual PNGs. Fallback when other tools are unavailable.
No evidence needed -- The diff speaks for itself. Best for text-only or config changes.

If the question tool is unavailable (background agent, batch mode), present the numbered options and wait for the user's reply before proceeding.

使用步骤2得到的项目类型、步骤3得到的改动分类、步骤4得到的预检查JSON运行推荐脚本：

bash

python3 scripts/capture-demo.py recommend --project-type [TYPE] --change-type [motion|states] --tools '[PREFLIGHT_JSON]'

该命令输出包含

recommended

（最佳等级）、

available

（工具已就绪的等级列表）和

reasoning

的JSON。

通过平台的阻塞提问工具（Claude Code中用

AskUserQuestion

，Codex中用

request_user_input

，Gemini中用

ask_user

）向用户展示可用等级。标记推荐的等级。始终将"无需证据"作为最后一个选项。

问题： "本次改动应该如何捕获证据？"

选项（仅展示

available

列表中的等级，按推荐顺序排序）：

浏览器演示合集 -- Agent-browser截图拼接成动画GIF。最适合Web应用。
终端录制 -- VHS终端录制导出为GIF。最适合带交互/动态效果的CLI工具。
截图合集 -- 样式化的终端帧拼接成动画GIF。最适合离散的CLI步骤。
静态截图 -- 单张PNG图片。其他工具不可用时的备选方案。
无需证据 -- diff本身已经足够说明问题。最适合纯文本或配置改动。

如果提问工具不可用（后台Agent、批量模式），展示编号选项并等待用户回复后再继续。

Step 7: Execute Selected Tier

步骤7：执行选中的等级

Carry the capture hypothesis from Step 0 and the feature exercise results from Step 1 into tier execution — these determine which specific pages to visit, commands to run, or states to screenshot. Substitute

[RUN_DIR]

in the tier reference with the concrete path from Step 5.

Load the appropriate reference file for the selected tier:

Browser reel -> Read
```
references/tier-browser-reel.md
```
Terminal recording -> Read
```
references/tier-terminal-recording.md
```
Screenshot reel -> Read
```
references/tier-screenshot-reel.md
```
Static screenshots -> Read
```
references/tier-static-screenshots.md
```
No evidence needed -> Skip to output. Set
```
evidence_url
```
to null,
```
evidence_label
```
to null.

Runtime failure fallback: If the selected tier fails during execution (tool crashes, server not accessible, recording produces empty output), fall back to the next available tier rather than failing entirely. The fallback order is: browser reel -> static screenshots, terminal recording -> screenshot reel -> static screenshots, screenshot reel -> static screenshots. Static screenshots is the terminal fallback -- if even that fails, report the failure and let the user decide.

将步骤0的捕获假设和步骤1的功能验证结果带入等级执行流程——这些信息决定了需要访问哪些具体页面、运行哪些命令，或是给哪些状态截图。将等级引用中的

[RUN_DIR]

替换为步骤5得到的具体路径。

加载选中等级对应的参考文件：

浏览器演示合集 -> 读取
```
references/tier-browser-reel.md
```
终端录制 -> 读取
```
references/tier-terminal-recording.md
```
截图合集 -> 读取
```
references/tier-screenshot-reel.md
```
静态截图 -> 读取
```
references/tier-static-screenshots.md
```
无需证据 -> 跳转到输出环节。设置
```
evidence_url
```
为null，
```
evidence_label
```
为null。

运行失败备选方案： 如果选中的等级在执行过程中失败（工具崩溃、服务器无法访问、录制输出为空），回退到下一个可用等级而非直接整体失败。回退顺序为：浏览器演示合集 -> 静态截图，终端录制 -> 截图合集 -> 静态截图，截图合集 -> 静态截图。静态截图是最终备选——如果连静态截图都失败，报告失败并让用户决定后续操作。

Step 8: Upload and Approval

步骤8：上传和审批

After the selected tier produces an artifact, read

references/upload-and-approval.md

for upload to a public host, user approval gate, and markdown embed generation.

选中的等级生成产物后，读取

references/upload-and-approval.md

了解如何上传到公开主机、用户审批流程，以及markdown嵌入代码生成方法。

Output

输出

Return these values to the caller (e.g., git-commit-push-pr):

=== Evidence Capture Complete ===
Tier: [browser-reel / terminal-recording / screenshot-reel / static / skipped]
Description: [1 sentence describing what the evidence shows]
URL: [public URL or "none" (multiple URLs comma-separated for static screenshots)]
=== End Evidence ===

The

Description

is a 1-line summary derived from the capture hypothesis in Step 0 (e.g., "CLI detect command classifying 3 project types and recommending capture tiers"). The caller decides how to format the URL(s) into the PR description.

```
Tier: skipped
```
or
```
URL: "none"
```
means no evidence was captured.

Label convention:

Browser reel, terminal recording, screenshot reel: label as "Demo"
Static screenshots: label as "Screenshots"
The caller applies the label when formatting. ce-demo-reel does not generate markdown.
Test output is never labeled "Demo" or "Screenshots"

向调用者（例如git-commit-push-pr）返回以下值：

=== Evidence Capture Complete ===
Tier: [browser-reel / terminal-recording / screenshot-reel / static / skipped]
Description: [1 sentence describing what the evidence shows]
URL: [public URL or "none" (多个URL用英文逗号分隔，适用于静态截图)]
=== End Evidence ===

Description

是从步骤0的捕获假设衍生的1行摘要（例如"CLI detect命令分类3种项目类型并推荐捕获等级"）。调用者决定如何将URL格式化到PR描述中。

```
Tier: skipped
```
或
```
URL: "none"
```
表示未捕获任何证据。

标签规则：

浏览器演示合集、终端录制、截图合集：标注为"Demo"
静态截图：标注为"Screenshots"
调用者在格式化时应用标签。ce-demo-reel不生成markdown。
测试输出绝对不能标注为"Demo"或"Screenshots"