asciinema-player

asciinema-player

在专用 iTerm2 窗口中播放终端会话录制文件（.cast），并提供完整的播放控制。打开一个干净的窗口（绕过默认布局），以便专心观看。

平台：仅限 macOS（需要 iTerm2）

自我完善技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

何时使用此技能

在以下情形使用此技能：

• 在 iTerm2 中回放 .cast 录制文件
• 不受浏览器限制地查看会话录制
• 处理会导致浏览器播放器崩溃的大型录制文件（>100MB）
• 演示或查看终端会话

---

为什么选择 iTerm2，而不是浏览器？

方面	浏览器播放器	iTerm2 CLI
大型文件（>100MB）	崩溃（内存限制）	从磁盘流式读取
内存占用	700MB 文件占用 2-4GB	极少
启动时间	慢（下载 + 解析）	即时
原生体验	基于 Web	真正的终端

结论：对于大型录制文件，iTerm2 CLI 是唯一可靠的方法。

---

要求

组件	必需	安装方式
iTerm2	是	brew install --cask iterm2
asciinema CLI	是	brew install asciinema

注意：此技能仅适用于 macOS。Linux 用户应直接在终端中运行 asciinema play。

---

工作流阶段（全部必需）

重要：所有阶段均为必需。请勿跳过任何阶段。在每个决策点都必须使用 AskUserQuestion。

阶段 0：预检

目的：确认已安装 iTerm2 和 asciinema。

步骤 0.1：检查依赖项

# Check iTerm2 is installed
ls -d /Applications/iTerm.app 2>/dev/null && echo "iTerm2: OK" || echo "iTerm2: MISSING"

# Check asciinema CLI
which asciinema && asciinema --version

步骤 0.2：报告状态并询问是否安装

如果缺少任何依赖项，必须使用 AskUserQuestion：

Question: "Required dependencies are missing. Install them?"
Header: "Setup"
Options:
  - Label: "Install all (Recommended)"
    Description: "Will install: {list of missing: iTerm2, asciinema}"
  - Label: "Cancel"
    Description: "Abort - cannot proceed without dependencies"

步骤 0.3：安装缺失的依赖项（经确认后）

# Install iTerm2
brew install --cask iterm2

# Install asciinema CLI
brew install asciinema

---

阶段 1：选择文件（必需）

目的：查找并选择要播放的录制文件。

步骤 1.1：查找录制文件

# Search for .cast files in common locations
fd -e cast . --max-depth 5 2>/dev/null | head -20

# Also check common locations
ls -lh ~/scripts/tmp/*.cast 2>/dev/null
ls -lh ~/.local/share/asciinema/*.cast 2>/dev/null
ls -lh ./tmp/*.cast 2>/dev/null

步骤 1.2：获取文件信息

# Get file size and line count for selected file
ls -lh {file_path}
wc -l {file_path}

步骤 1.3：展示文件选择（必须使用 AskUserQuestion）

如果用户直接提供了路径，请确认：

Question: "Play this recording?"
Header: "Confirm"
Options:
  - Label: "Yes, play {filename}"
    Description: "{size}, {line_count} events"
  - Label: "Choose different file"
    Description: "Browse for other recordings"

如果用户未提供路径，请查找并展示选项：

Question: "Which recording would you like to play?"
Header: "Recording"
Options:
  - Label: "{filename} ({size})"
    Description: "{line_count} events"
  - ... (up to 4 most recent)

---

阶段 2：播放设置（必需）

目的：启动 iTerm2 前配置播放选项。

步骤 2.1：询问播放速度（必须使用 AskUserQuestion）

Question: "Select playback speed:"
Header: "Speed"
Options:
  - Label: "2x (fast)"
    Description: "Good for review, see everything"
  - Label: "6x (very fast)"
    Description: "Quick scan of long sessions"
  - Label: "16x (ultra fast)"
    Description: "Rapid skim for 700MB+ files"
  - Label: "Custom"
    Description: "Enter your own speed multiplier"

如果选择了“自定义”，请询问速度值（使用 Other 选项输入数字）。

步骤 2.2：询问其他选项（必须使用 AskUserQuestion）

Question: "Select additional playback options:"
Header: "Options"
multiSelect: true
Options:
  - Label: "Limit idle time (2s)"
    Description: "Cap pauses to 2 seconds max (recommended)"
  - Label: "Loop playback"
    Description: "Restart automatically when finished"
  - Label: "Resize terminal"
    Description: "Match terminal size to recording dimensions"
  - Label: "Pause on markers"
    Description: "Auto-pause at marked points (for demos)"

---

阶段 3：在 iTerm2 中启动

目的：打开干净的 iTerm2 窗口并开始播放。

步骤 3.1：构建命令

根据用户的选择构建 asciinema play 命令：

# Example with all options
asciinema play -s 6 -i 2 -l -r /path/to/recording.cast

选项标记：

• -s {speed} - 播放速度
• -i 2 - 空闲时间限制（如果已选择）
• -l - 循环播放（如果已选择）
• -r - 调整终端大小（如果已选择）
• -m - 在标记处暂停（如果已选择）

步骤 3.2：启动 iTerm2 窗口

使用 AppleScript 打开一个干净的窗口（绕过默认布局）：

osascript -e 'tell application "iTerm2"
    create window with default profile
    tell current window
        tell current session
            write text "asciinema play -s {speed} {options} {file_path}"
        end tell
    end tell
end tell'

步骤 3.3：显示控制说明

## Playback Started

**Recording:** `{filename}`
**Speed:** {speed}x
**Options:** {options_summary}

### Keyboard Controls

| Key      | Action                            |
| -------- | --------------------------------- |
| `Space`  | Pause / Resume                    |
| `Ctrl+C` | Stop playback                     |
| `.`      | Step forward (when paused)        |
| `]`      | Skip to next marker (when paused) |

### Tips

- Press `Space` to pause anytime
- Use `.` to step through frame by frame
- `Ctrl+C` to exit when done

---

TodoWrite 任务模板（必需）

开始前将此模板载入 TodoWrite：

1. [Preflight] Check iTerm2 installed
2. [Preflight] Check asciinema CLI installed
3. [Preflight] AskUserQuestion: install missing deps (if needed)
4. [Preflight] Install dependencies (if confirmed)
5. [Selection] Get file info (size, events)
6. [Selection] AskUserQuestion: confirm file selection
7. [Settings] AskUserQuestion: playback speed
8. [Settings] AskUserQuestion: additional options (multi-select)
9. [Launch] Build asciinema play command
10. [Launch] Execute AppleScript to open iTerm2
11. [Launch] Display controls reference

---

CLI 选项参考

选项	标志	值	描述
速度	-s	0.5, 1, 2, 6, 16...	播放速度倍数
空闲限制	-i	秒（例如，2）	限制空闲／暂停时间
循环	-l	（标志）	连续循环
调整大小	-r	（标志）	使终端尺寸与录制内容匹配
标记	-m	（标志）	在标记处自动暂停
静默	-q	（标志）	不显示信息消息

---

AppleScript 参考

打开干净的 iTerm2 窗口（不使用默认布局）

tell application "iTerm2"
    create window with default profile
    tell current window
        tell current session
            write text "your command here"
        end tell
    end tell
end tell

原理：create window with default profile 会创建一个新窗口，绕过已保存的窗口布局。

Bash 单行命令

osascript -e 'tell application "iTerm2"
    create window with default profile
    tell current window
        tell current session
            write text "asciinema play -s 6 -i 2 /path/to/file.cast"
        end tell
    end tell
end tell'

---

故障排除

“Device not configured” 错误

原因：在非 TTY 上下文中运行 asciinema play（例如 Claude Code 的 Bash 工具）

修复方法：使用 AppleScript 打开一个真正的 iTerm2 窗口（此技能会自动执行此操作）

录制内容播放过快／过慢

修复方法：使用速度 AskUserQuestion 选择合适的速度：

• 2x：仔细查看
• 6x：快速浏览
• 16x：超快浏览很长的录制内容

iTerm2 无法打开

原因：未安装 iTerm2，或未授予 AppleScript 权限

修复方法：

1. 安装 iTerm2：brew install --cask iterm2
2. 授予权限：系统设置 → 隐私与安全性 → 自动化 → 允许 Terminal/Claude 控制 iTerm2

大文件（>500MB）注意事项

CLI 播放器会从磁盘流式读取，因此文件大小不会导致内存问题。不过：

• 很长的录制内容可能适合使用更高速度（6x、16x）
• 使用 -i 2 跳过空闲时间
• 考虑拆分很长的录制内容

---

变更后检查清单

修改此技能后：

1. 预检会验证 iTerm2 和 asciinema
2. AskUserQuestion 阶段会在适用时使用正确的 multiSelect
3. AppleScript 使用 heredoc 包装器以兼容 bash
4. 速度选项与 CLI 功能（-s 标志）一致
5. TodoWrite 模板与实际工作流阶段一致

---

参考文档

• asciinema play 用法
• asciinema CLI 选项
• iTerm2 AppleScript 文档
• asciinema 标记

执行后复盘

此技能完成后，在结束任务前进行复盘：

0. 定位自身。 — 在编辑前找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修复导致问题的指令。
2. 哪些地方比预期更有效？ — 将其提升为推荐做法。
3. 哪里出现了偏差？ — 修复任何与实际情况不再一致的脚本、参考资料或依赖项。
4. 记录下来。 — 添加演进日志条目，说明触发因素、修复方法和证据。

不要拖延。下一次调用会继承你留下的一切。