cli-demo-generator

CLI 演示生成器

创建专业的动画 CLI 演示。提供四种方式，从全自动生成到像素级精准的手动控制。

快速开始

最简单的方式——提供命令，生成 GIF：

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif

自举演示——适用于可重复录制且能自行清理状态的演示：

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif \
  --bootstrap "npm uninstall my-package 2>/dev/null" \
  --speed 2

重要：VHS 解析器的限制

VHS Type 字符串不能包含 $、\" 或反引号，否则会导致解析错误：

# FAILS — VHS parser rejects special chars
Type "echo \"hello $USER\""
Type "claude() { command claude \"$@\"; }"

解决方法：对命令进行 base64 编码，并在运行时解码：

# 1. Encode your complex command
echo 'claude() { command claude "$@" 2>&1 | grep -v "noise"; }' | base64
# Output: Y2xhdWRlKCkgey4uLn0K

# 2. Use in tape
Type "echo Y2xhdWRlKCkgey4uLn0K | base64 -d > /tmp/wrapper.sh && source /tmp/wrapper.sh"

此模式对于输出过滤、函数定义以及任何包含 Shell 特殊字符的命令都至关重要。

方式

1. 自动生成（推荐）

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "command1" -c "command2" \
  -o output.gif \
  --title "My Demo" \
  --theme "Catppuccin Latte" \
  --font-size 24 \
  --width 1400 --height 600

标记	默认值	描述
-c	必填	要包含的命令（可重复指定）
-o	必填	输出 GIF 路径
--title	无	开始时显示的标题
--theme	Dracula	VHS 主题名称
--font-size	16	字体大小，单位为 pt
--width	1400	终端宽度，单位为 px
--height	700	终端高度，单位为 px
--bootstrap	无	隐藏的设置命令（可重复指定）
--filter	无	用于过滤输出内容的正则表达式
--speed	1	播放速度倍数（使用 gifsicle）
--no-execute	false	仅生成 .tape 文件

智能计时：install/build/test/deploy → 3s，ls/pwd/echo → 1s，其他命令 → 2s。

2. 批量生成

通过一个配置创建多个演示：

# demos.yaml
demos:
  - name: "Install"
    output: "install.gif"
    commands: ["npm install my-package"]
  - name: "Usage"
    output: "usage.gif"
    commands: ["my-package --help", "my-package run"]

python3 ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py demos.yaml --output-dir ./gifs

3. 交互式录制

录制实时终端会话：

bash ${CLAUDE_SKILL_DIR}/scripts/record_interactive.sh output.gif --theme "Catppuccin Latte"
# Type commands naturally, Ctrl+D when done

需要 asciinema（brew install asciinema）。

4. 手动编写 Tape 文件

如需最大程度的控制，可直接编写 tape 文件。模板位于 assets/templates/：

• basic.tape — 简单的命令序列
• interactive.tape — 打字模拟
• self-bootstrap.tape — 带隐藏设置步骤且可自行清理的演示（推荐用于可重复演示）

高级模式

这些模式源自实际生产应用。完整详情请参阅 references/advanced_patterns.md。

自举演示

清理之前的状态、设置环境，并向观看者隐藏所有这些操作的演示：

Hide
Type "cleanup-previous-state 2>/dev/null"
Enter
Sleep 2s
Type "clear"
Enter
Sleep 500ms
Show

Type "the-command-users-see"
Enter
Sleep 3s

Hide → 命令 → clear → Show 这一序列至关重要。clear 会清除终端缓冲区，避免隐藏命令泄露到 GIF 中。

过滤输出噪声

过滤输出冗长的命令产生的噪声进度行：

# Hidden: create a wrapper function that filters noise
Hide
Type "echo <base64-encoded-wrapper> | base64 -d > /tmp/w.sh && source /tmp/w.sh"
Enter
Sleep 500ms
Type "clear"
Enter
Sleep 500ms
Show

# Visible: clean command, filtered output
Type "my-noisy-command"
Enter
Sleep 3s

帧验证

录制完成后，提取关键帧以验证 GIF 内容：

# Extract frames at specific positions
ffmpeg -i demo.gif -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame.png -y 2>/dev/null

# View the frame (Claude can read images)
# Use Read tool on /tmp/frame.png to verify content

后期加速

使用 gifsicle 加速录制内容，无需重新录制：

# 2x speed (halve frame delay)
gifsicle -d2 original.gif "#0-" > fast.gif

# 1.5x speed
gifsicle -d4 original.gif "#0-" > faster.gif

模板占位符模式

使用占位符保持 tape 文件通用，并在构建时替换：

# In tape file
Type "claude plugin marketplace add MARKETPLACE_REPO"

# In build script
sed "s|MARKETPLACE_REPO|$DETECTED_REPO|g" template.tape > rendered.tape
vhs rendered.tape

计时与尺寸参考

场景	宽度	高度	字体	时长
README/文档	1400	600	16-20	10-20s
演示文稿	1800	900	24	15-30s
紧凑嵌入	1200	600	14-16	10-15s
宽幅输出	1600	800	16	15-30s

详细指南请参阅 references/best_practices.md。

故障排查

问题	解决方法
未安装 VHS	brew install charmbracelet/tap/vhs
未安装 gifsicle	brew install gifsicle
GIF 过大	减小尺寸、缩短休眠时间，或使用 --speed 2
文本换行或显示异常	增大 --width 或减小 --font-size
VHS 因 $ 或 \" 报解析错误	使用 base64 编码（参见上文“重要”部分）
隐藏命令泄露到 GIF 中	在 Show 之前添加 clear + Sleep 500ms
上一条命令尚未完成就执行下一条	延长 Sleep 时长

Tape 文件语法

references/vhs_syntax.md 是完整的 VHS tape 文件参考，涵盖每条命令、 每项设置和每个按键名称，以及它们支持的参数形式。手动编写 tape、 tape 解析成功但行为异常，或需要使用本 SKILL.md 未提供示例的命令时，请阅读此文档。

Dependencies

Required: VHS (brew install charmbracelet/tap/vhs)

Optional: gifsicle (speed-up), asciinema (interactive recording), ffmpeg (frame verification), PyYAML (batch YAML configs)