SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cli-demo-generator

cli-demo-generator

编程与开发

查看项目

更新于 10-13 20:08

技能介绍

用途

CLI Demo Generator 用于创建专业的动画式命令行（CLI）演示，最终以 GIF 形式输出，底层通过 VHS 终端录制实现。它适合需要把终端操作流程录制为动图、用于 README、文档或演示文稿的场景。

主要能力

该工具提供四种方式，覆盖从全自动到像素级手动控制：

  1. 自动化生成（推荐）：给出命令即可生成 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

自动化生成支持的参数：-c（要包含的命令，必填、可重复）、-o（输出 GIF 路径，必填）、--title（开头显示的标题，默认无）、--theme（VHS 主题名，默认 Dracula）、--font-size（字号，单位 pt，默认 16）、--width（终端宽度 px，默认 1400）、--height（终端高度 px，默认 700）、--bootstrap（隐藏的初始化命令，可重复）、--filter（从输出中过滤的正则）、--speed（播放速度倍数，使用 gifsicle，默认 1）、--no-execute（仅生成 .tape）。

智能时序：install/build/test/deploy → 3 秒，ls/pwd/echo → 1 秒，其他 → 2 秒。

  1. 批量生成：从一个配置生成多个演示。配置示例：
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
  1. 交互式录制：录制实时终端会话。
bash ${CLAUDE_SKILL_DIR}/scripts/record_interactive.sh output.gif --theme "Catppuccin Latte"
# Type commands naturally, Ctrl+D when done

需要 asciinema（brew install asciinema）。

  1. 手写 tape 文件：需要最大控制力时直接编写 tape。模板位于 assets/templates/：basic.tape（简单命令序列）、interactive.tape（打字模拟）、self-bootstrap.tape（带隐藏初始化的自清理演示，推荐用于可重复演示）。

使用方式与关键要点

VHS 解析器限制（关键）：VHS 的 Type 字符串不能包含 $、\" 或反引号，否则会解析报错。例如以下写法会失败：

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 特殊字符的命令都至关重要。

高级模式（详见 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 中。

  • 输出噪声过滤：隐藏一个包装函数来过滤噪声。
Hide
Type "echo <base64-encoded-wrapper> | base64 -d > /tmp/w.sh && source /tmp/w.sh"
Enter
Sleep 500ms
Type "clear"
Enter
Sleep 500ms
Show

Type "my-noisy-command"
Enter
Sleep 3s
  • 帧验证：录制后提取关键帧验证 GIF 内容。
ffmpeg -i demo.gif -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame.png -y 2>/dev/null
  • 后处理加速：用 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/docs 用 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 过大：减小尺寸、缩短 sleep 时间或使用 --speed 2
  • 文本换行/断开：增大 --width 或减小 --font-size
  • VHS 遇到 $ 或 \" 解析错误：使用 base64 编码
  • 隐藏命令泄漏到 GIF：在 Show 前加 clear + Sleep 500ms
  • 命令在上一条完成前执行：增加 Sleep 时长

Tape 文件语法

references/vhs_syntax.md 是完整的 VHS tape 文件参考，涵盖每条命令、设置和按键名及其接受的参数形式。手写 tape、tape 能解析但行为异常、或需要 SKILL.md 未给出示例的命令时可查阅。

依赖

必需：VHS（brew install charmbracelet/tap/vhs）。 可选：gifsicle（加速）、asciinema（交互式录制）、ffmpeg（帧验证）、PyYAML（批量 YAML 配置）。

限制

以上内容为资料提供的全部信息，其他功能、收费、价格、平台或效果暂未提供。