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

工具选择

Goal	Tool Chain	Output
CLI demo for GitHub PR	asciinema → agg	GIF (< 5MB)
Smaller file needed	asciinema → svg-term-cli	SVG (< 500KB)
TUI screenshot	tmux → freeze	SVG/PNG

Default choice: asciinema + agg (best compatibility, GitHub renders GIFs natively)

目标	工具链	输出格式
GitHub PR的CLI演示	asciinema → agg	GIF（小于5MB）
需要更小文件体积	asciinema → svg-term-cli	SVG（小于500KB）
TUI截图	tmux → freeze	SVG/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

[0-3s] Show command being typed
[3-10s] Command executes, show key output
[10-25s] Highlight the "aha moment" - what makes this valuable
[25-30s] Clean exit or final state


**Keep it short.** 20-30 seconds max. Show ONE thing well.

时长：约20-30秒

[0-3秒] 展示输入命令的过程
[3-10秒] 执行命令，展示关键输出
[10-25秒] 突出“惊喜时刻”——该功能的核心价值
[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

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

With speed adjustment (1.5x faster)

调整播放速度（1.5倍速）

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

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

Option 2: Use asciinema cat + freeze for a snapshot

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

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:

Is the text readable (not too small/blurry)?
Is the command being demonstrated visible?
Is there any sensitive info (API keys, /Users/username paths)?
Does the terminal look clean (simple prompt, no clutter)?
Is the "aha moment" visible - what value does this demo show?

Rate: PASS or FAIL with specific issues.

undefined


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

**验证提示词：**

分析这张终端演示截图。检查以下内容：

文本是否清晰可读（不要太小或模糊）？
演示的命令是否可见？
是否包含敏感信息（API密钥、/Users/用户名路径等）？
终端界面是否整洁（简洁的提示符，无杂乱内容）？
是否展示了“惊喜时刻”——该演示体现了什么价值？

评分：通过（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

Check recording duration

检查录制时长

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

演示

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


Store demos in `docs/demos/` or `assets/` directory.

说明：[一句话描述该演示展示的内容]


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

Quick Reference

快速参考

Setting	Recommended Value
Duration	20-30 seconds
Terminal size	100x24
Speed multiplier	1.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

常见错误

Mistake	Fix
Demo too long	Script it first, show ONE thing
Text unreadable	Use --font-size 14+, terminal 100x24
File too large	Use svg-term-cli instead, or increase speed
Cluttered terminal	Clean PS1, clear history, hide paths
No context in PR	Add 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             # 供后续维护者参考的录制说明

pr-demo

Original

Translation

PR Demo Creation

PR演示创建指南

Overview

概述

Tool Selection

工具选择

Prerequisites

前置条件

Install tools (macOS)

安装工具（macOS系统）

Workflow

工作流程

1. Script Your Demo (REQUIRED)

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

Demo: [feature name]

演示：[功能名称]

2. Prepare Environment

2. 准备环境

Clean terminal state

清理终端状态

Hide sensitive info (API keys, paths with usernames)

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

3. Record

3. 录制

Record to .cast file

录制到.cast文件

Execute your scripted demo

执行你编写好的演示脚本

Press Ctrl+D or type 'exit' when done

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

4. Convert to GIF

4. 转换为GIF

Basic conversion (recommended)

基础转换（推荐）

With speed adjustment (1.5x faster)

调整播放速度（1.5倍速）

With custom font size for readability

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

5. Validate (Self-Validation)

5. 验证（自我校验）

A. Automated Checks (run these first)

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

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

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

Check recording duration from .cast metadata

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

B. Visual Validation (LLM-as-judge)

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

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

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

Option 2: Use asciinema cat + freeze for a snapshot

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

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文件

C. Content Validation (parse .cast file)

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

Check what commands were typed (input events)

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

Check recording duration

检查录制时长

Should be 20-30 seconds

时长应在20-30秒之间

Look for sensitive patterns

查找敏感信息模式

D. Full Validation Checklist

D. 完整验证清单

6. Embed in PR

6. 嵌入到PR中

Demo

演示

Quick Reference

快速参考

Common Mistakes

常见错误

File Organization