⚡

PR演示创建Skill pr-demo

这个技能涉及使用asciinema工具录制终端操作，并将其转换为GIF或SVG格式，用于GitHub拉取请求或文档中的动画演示。工作流程包括脚本编写、录制、转换、嵌入和验证，旨在创建短小精悍、高质量的终端演示。关键词：终端录制、asciinema、GIF转换、演示制作、开发工具、GitHub PR、自我验证、DevOps工具链。

DevOps 0 次安装 2 次浏览 更新于 3/14/2026

name: pr-demo description: 当为拉取请求或文档创建动画演示(GIFs)时使用。覆盖使用asciinema的终端录制以及转换为GIF/SVG用于GitHub嵌入。

PR演示创建

概述

使用转换为GIF的asciinema录制为PRs创建精美的终端演示。工作流程：脚本 → 录制 → 转换 → 嵌入。

工具选择

目标 工具链 输出
GitHub PR的CLI演示 asciinema → agg GIF (< 5MB)
需要较小文件 asciinema → svg-term-cli SVG (< 500KB)
TUI截图 tmux → freeze SVG/PNG

默认选择: asciinema + agg (最佳兼容性，GitHub原生渲染GIFs)

先决条件

# 安装工具 (macOS)
brew install asciinema
cargo install --git https://github.com/asciinema/agg
npm install -g svg-term-cli  # 可选: 用于SVG输出

工作流程

1. 脚本化您的演示 (必需)

在录制前，编写一个简短脚本：

## 演示: [功能名称]
时长: ~20-30秒

1. [0-3秒] 显示命令被输入
2. [3-10秒] 命令执行，显示关键输出
3. [10-25秒] 突出“灵光一现”时刻 - 展示其价值
4. [25-30秒] 干净退出或最终状态

保持简短。 最多20-30秒。展示一个内容充分。

2. 准备环境

# 清理终端状态
clear
export PS1='$ '                    # 简单提示符
export TERM=xterm-256color         # 一致的颜色
# 隐藏敏感信息 (API密钥、带用户名的路径)

终端大小：100x24 (缩放时仍可读)

3. 录制

# 录制到.cast文件
asciinema rec demo.cast --cols 100 --rows 24

# 执行您的脚本化演示
# 完成后按Ctrl+D或输入'exit'

提示:

  • 以可读速度输入 (不要太快)
  • 在关键时刻后稍作停顿
  • 如果出错，重新开始 (编辑比重新录制更难)

4. 转换为GIF

# 基本转换 (推荐)
agg demo.cast demo.gif

# 带速度调整 (1.5倍更快)
agg --speed 1.5 demo.cast demo.gif

# 带自定义字体大小以提高可读性
agg --font-size 14 demo.cast demo.gif

替代方案 - SVG (文件更小):

svg-term --in demo.cast --out demo.svg --window

5. 验证 (自我验证)

Claude可以使用三种方法自我验证演示：

A. 自动检查 (先运行这些)

# 检查文件大小 (必须 < 5MB用于GitHub)
ls -lh demo.gif

# 从.cast元数据检查录制时长
head -1 demo.cast | jq '.duration // "手动检查"'

B. 视觉验证 (LLM作为评判者)

提取静态帧供Claude分析：

# 选项1: 使用svg-term渲染特定时间戳 (例如，15秒处)
svg-term --in demo.cast --out demo-preview.svg --at 15000

# 选项2: 使用asciinema cat + freeze获取快照
asciinema cat demo.cast | head -500 | freeze -o demo-preview.png

# 选项3: 直接转换为GIF并使用文件
# Claude可以使用Read工具读取GIF文件

然后使用Read工具在图像上问Claude分析：

验证提示:

分析这个终端演示截图。检查：
1. 文本是否可读 (不太小/模糊)？
2. 演示的命令是否可见？
3. 是否有敏感信息 (API密钥、/Users/用户名路径)？
4. 终端是否看起来干净 (简单提示符，无杂乱)？
5. “灵光一现”时刻是否可见 - 这个演示展示了什么价值？

评分：通过或失败，并指出具体问题。

C. 内容验证 (解析.cast文件)

.cast文件是JSON行 - 以编程方式验证内容：

# 检查输入的命令 (输入事件)
grep '"i"' demo.cast | head -20

# 检查录制时长
head -1 demo.cast | jq -r '.duration | floor'
# 应为20-30秒

# 查找敏感模式
grep -iE '(api.?key|password|secret|/Users/[a-z])' demo.cast && echo "警告：发现敏感数据！"

D. 完整验证清单

运行以上后，验证：

  • [ ] 文件大小 < 5MB (自动)
  • [ ] 时长20-30秒 (自动)
  • [ ] .cast中无敏感信息 (自动)
  • [ ] 预览帧中文本可读 (视觉/LLM)
  • [ ] 演示清晰展示功能 (视觉/LLM)
  • [ ] 终端外观干净 (视觉/LLM)

6. 嵌入到PR中

## 演示

![功能演示](./docs/demos/feature-demo.gif)

*展示: [一句话描述演示内容]*

将演示存储在docs/demos/或assets/目录中。

快速参考

设置 推荐值
时长 20-30秒
终端大小 100x24
速度倍数 1.0-1.5x
目标文件大小 < 2MB理想，< 5MB最大
字体大小 (agg) 14-16

常见错误

错误 修复
演示太长 先编写脚本，展示一个内容
文本不可读 使用–font-size 14+，终端100x24
文件太大 使用svg-term-cli替代，或增加速度
终端杂乱 清理PS1，清除历史，隐藏路径
PR中无上下文 在GIF下方添加一行描述

文件组织

docs/demos/
├── feature-name.gif      # 演示
├── feature-name.cast     # 源录制文件 (可选，用于重新渲染)
└── README.md             # 录制说明供未来维护者使用