Back to Details

pr-demo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PR Demo Creation

PR演示创建指南

Overview

概述

Create polished terminal demos for PRs using asciinema recordings converted to GIF. The workflow: script → record → convert → embed.
使用asciinema录制并转换为GIF，为PR制作精美的终端演示。工作流程：编写脚本 → 录制 → 转换 → 嵌入。

Tool Selection

工具选择

GoalTool ChainOutput
CLI demo for GitHub PRasciinema → aggGIF (< 5MB)
Smaller file neededasciinema → svg-term-cliSVG (< 500KB)
TUI screenshottmux → freezeSVG/PNG
Default choice: asciinema + agg (best compatibility, GitHub renders GIFs natively)
目标工具链输出格式
GitHub PR的CLI演示asciinema → aggGIF（小于5MB）
需要更小文件体积asciinema → svg-term-cliSVG（小于500KB）
TUI截图tmux → freezeSVG/PNG
默认选择： asciinema + agg（兼容性最佳，GitHub原生支持GIF渲染）

Prerequisites

前置条件

bash
undefined
bash
undefined

Install tools (macOS)

安装工具（macOS系统）

brew install asciinema cargo install --git https://github.com/asciinema/agg npm install -g svg-term-cli # Optional: for SVG output
undefined
brew install asciinema cargo install --git https://github.com/asciinema/agg npm install -g svg-term-cli # 可选：用于生成SVG格式输出
undefined

Workflow

工作流程

1. Script Your Demo (REQUIRED)

1. 编写演示脚本（必填）

Before recording, write a brief script:
markdown
undefined
录制前，先编写一份简短的脚本：
markdown
undefined

Demo: [feature name]

演示：[功能名称]

Duration: ~20-30 seconds
  1. [0-3s] Show command being typed
  2. [3-10s] Command executes, show key output
  3. [10-25s] Highlight the "aha moment" - what makes this valuable
  4. [25-30s] Clean exit or final state

**Keep it short.** 20-30 seconds max. Show ONE thing well.
时长：约20-30秒
  1. [0-3秒] 展示输入命令的过程
  2. [3-10秒] 执行命令，展示关键输出
  3. [10-25秒] 突出“惊喜时刻”——该功能的核心价值
  4. [25-30秒] 干净退出或展示最终状态

**保持简短**。最长20-30秒。把一件事展示清楚。

2. Prepare Environment

2. 准备环境

bash
undefined
bash
undefined

Clean terminal state

清理终端状态

clear export PS1='$ ' # Simple prompt export TERM=xterm-256color # Consistent colors
clear export PS1='$ ' # 简化命令提示符 export TERM=xterm-256color # 保持颜色一致性

Hide sensitive info (API keys, paths with usernames)

隐藏敏感信息（API密钥、包含用户名的路径等）


Terminal size: **100x24** (readable when scaled down)

终端尺寸：**100x24**（缩小时仍清晰可读）

3. Record

3. 录制

bash
undefined
bash
undefined

Record to .cast file

录制到.cast文件

asciinema rec demo.cast --cols 100 --rows 24
asciinema rec demo.cast --cols 100 --rows 24

Execute your scripted demo

执行你编写好的演示脚本

Press Ctrl+D or type 'exit' when done

完成后按Ctrl+D或输入'exit'结束录制


**Tips:**
- Type at readable speed (not too fast)
- Pause briefly after key moments
- If you make a mistake, start over (editing is harder than re-recording)

**小贴士：**
- 以可读的速度输入命令（不要太快）
- 在关键操作后稍作停顿
- 如果出错，重新录制（编辑比重录更麻烦）

4. Convert to GIF

4. 转换为GIF

bash
undefined
bash
undefined

Basic conversion (recommended)

基础转换（推荐）

agg demo.cast demo.gif
agg demo.cast demo.gif

With speed adjustment (1.5x faster)

调整播放速度（1.5倍速）

agg --speed 1.5 demo.cast demo.gif
agg --speed 1.5 demo.cast demo.gif

With custom font size for readability

自定义字体大小以提升可读性

agg --font-size 14 demo.cast demo.gif

**Alternative - SVG (smaller files):**
```bash
svg-term --in demo.cast --out demo.svg --window
agg --font-size 14 demo.cast demo.gif

**替代方案 - SVG（更小的文件体积）：**
```bash
svg-term --in demo.cast --out demo.svg --window

5. Validate (Self-Validation)

5. 验证（自我校验）

Claude can self-validate demos using three approaches:
Claude可以通过三种方式自我验证演示效果：

A. Automated Checks (run these first)

A. 自动化检查（优先执行）

bash
undefined
bash
undefined

Check file size (must be < 5MB for GitHub)

检查文件大小（GitHub要求小于5MB）

ls -lh demo.gif
ls -lh demo.gif

Check recording duration from .cast metadata

从.cast元数据中检查录制时长

head -1 demo.cast | jq '.duration // "check manually"'
undefined
head -1 demo.cast | jq '.duration // "手动检查"'
undefined

B. Visual Validation (LLM-as-judge)

B. 视觉验证（LLM作为评审）

Extract a static frame for Claude to analyze:
bash
undefined
提取静态帧供Claude分析：
bash
undefined

Option 1: Use svg-term to render a specific timestamp (e.g., 15 seconds in)

选项1：使用svg-term渲染特定时间点的帧（例如第15秒）

svg-term --in demo.cast --out demo-preview.svg --at 15000
svg-term --in demo.cast --out demo-preview.svg --at 15000

Option 2: Use asciinema cat + freeze for a snapshot

选项2：使用asciinema cat + freeze生成快照

asciinema cat demo.cast | head -500 | freeze -o demo-preview.png
asciinema cat demo.cast | head -500 | freeze -o demo-preview.png

Option 3: Just convert to GIF and use the file directly

选项3：直接转换为GIF并使用该文件

Claude can read GIF files with the Read tool

Claude可以通过Read工具读取GIF文件


Then ask Claude to analyze using the Read tool on the image:

**Validation prompt:**
Analyze this terminal demo screenshot. Check:
  1. Is the text readable (not too small/blurry)?
  2. Is the command being demonstrated visible?
  3. Is there any sensitive info (API keys, /Users/username paths)?
  4. Does the terminal look clean (simple prompt, no clutter)?
  5. Is the "aha moment" visible - what value does this demo show?
Rate: PASS or FAIL with specific issues.
undefined

然后使用Read工具让Claude分析图片：

**验证提示词：**
分析这张终端演示截图。检查以下内容：
  1. 文本是否清晰可读（不要太小或模糊）？
  2. 演示的命令是否可见？
  3. 是否包含敏感信息（API密钥、/Users/用户名路径等）？
  4. 终端界面是否整洁（简洁的提示符，无杂乱内容）？
  5. 是否展示了“惊喜时刻”——该演示体现了什么价值？
评分：通过（PASS）或失败（FAIL），并说明具体问题。
undefined

C. Content Validation (parse .cast file)

C. 内容验证（解析.cast文件）

The 
.cast
file is JSON lines - validate the content programmatically:
bash
undefined
.cast文件是JSON行格式——可以通过编程方式验证内容：
bash
undefined

Check what commands were typed (input events)

检查输入的命令（输入事件）

grep '"i"' demo.cast | head -20
grep '"i"' demo.cast | head -20

Check recording duration

检查录制时长

head -1 demo.cast | jq -r '.duration | floor'
head -1 demo.cast | jq -r '.duration | floor'

Should be 20-30 seconds

时长应在20-30秒之间

Look for sensitive patterns

查找敏感信息模式

grep -iE '(api.?key|password|secret|/Users/[a-z])' demo.cast && echo "WARNING: Sensitive data found!"
undefined
grep -iE '(api.?key|password|secret|/Users/[a-z])' demo.cast && echo "警告：发现敏感数据！"
undefined

D. Full Validation Checklist

D. 完整验证清单

After running the above, verify:
  • File size < 5MB (automated)
  • Duration 20-30 seconds (automated)
  • No sensitive info in .cast (automated)
  • Text readable in preview frame (visual/LLM)
  • Demo shows feature clearly (visual/LLM)
  • Clean terminal appearance (visual/LLM)
执行上述检查后，确认以下内容：
  • 文件大小小于5MB（自动化检查）
  • 时长在20-30秒之间（自动化检查）
  • .cast文件中无敏感信息（自动化检查）
  • 预览帧中的文本清晰可读（视觉/LLM检查）
  • 演示清晰展示了功能（视觉/LLM检查）
  • 终端界面整洁（视觉/LLM检查）

6. Embed in PR

6. 嵌入到PR中

markdown
undefined
markdown
undefined

Demo

演示

feature demo
Shows: [one-sentence description of what the demo shows]

Store demos in `docs/demos/` or `assets/` directory.
功能演示
说明：[一句话描述该演示展示的内容]

将演示文件存储在`docs/demos/`或`assets/`目录下。

Quick Reference

快速参考

SettingRecommended Value
Duration20-30 seconds
Terminal size100x24
Speed multiplier1.0-1.5x
Target file size< 2MB ideal, < 5MB max
Font size (agg)14-16
设置项推荐值
时长20-30秒
终端尺寸100x24
速度倍数1.0-1.5倍
目标文件大小理想小于2MB，最大不超过5MB
字体大小（agg）14-16

Common Mistakes

常见错误

MistakeFix
Demo too longScript it first, show ONE thing
Text unreadableUse --font-size 14+, terminal 100x24
File too largeUse svg-term-cli instead, or increase speed
Cluttered terminalClean PS1, clear history, hide paths
No context in PRAdd one-line description below GIF
错误修复方案
演示时长过长先编写脚本，只展示一个核心内容
文本不可读使用--font-size 14+参数，终端尺寸设为100x24
文件体积过大改用svg-term-cli，或提高播放速度
终端界面杂乱清理PS1，清空历史记录，隐藏路径信息
PR中无上下文说明在GIF下方添加一句话描述

File Organization

文件组织

docs/demos/
├── feature-name.gif      # The demo
├── feature-name.cast     # Source recording (optional, for re-rendering)
└── README.md             # Recording instructions for future maintainers
docs/demos/
├── feature-name.gif      # 演示文件
├── feature-name.cast     # 源录制文件（可选，用于重新渲染）
└── README.md             # 供后续维护者参考的录制说明