名称： pr-demo
描述： 为拉取请求（PR）或文档创建动画演示（GIF）时使用。涵盖使用 asciinema 进行终端录制，以及转换为可在 GitHub 中嵌入的 GIF/SVG。

PR 演示创建指南

概述

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

工具选择

默认选择： asciinema + agg（兼容性最佳，GitHub 原生支持渲染 GIF）

前置准备

# 安装工具 (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. 自动检查（首先运行）

# 检查文件大小（GitHub 要求 < 5MB）
ls -lh demo.gif

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

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.  “亮点时刻”是否可见——这个演示展示了什么价值？

评级：通过（PASS）或失败（FAIL），并说明具体问题。

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/ 目录中。

快速参考

常见错误

文件组织

docs/demos/
├── feature-name.gif      # 演示文件
├── feature-name.cast     # 源录制文件（可选，用于重新渲染）
└── README.md             # 为未来维护者准备的录制说明