Asciinema 终端演示录制

要解决的问题

日常排查问题或编写 CLI 工具的使用说明时，最头疼的往往不是命令本身，而是如何把一段终端操作准确、可复现地传达给别人。截图只能捕捉某一瞬间的输出，录屏文件是二进制产物，既不能 diff，也无法直接重跑；读者想照着做一遍，只能盯着画面逐字抄命令，稍有出入就得到完全不同的结果。对需要「照着做就能复现」的排查记录和操作指南来说，这种形式天然不合格。

技能如何工作

该技能基于 asciinema，把一次终端会话录制成可回放的 cast 文件。它的核心思路是放弃「像素级录屏」，转而记录终端会话的语义信息——你输入了什么、程序输出了什么、时间戳如何推进。这样产出的 cast 本质上是文本原生的，可以被检索、diff、纳入版本管理，也能被其他人精确重放。

关键步骤：

• 准备环境：需要 asciinema CLI 和一个待录制的终端会话。
• 录制：在 shell 中启动录制，依次执行目标 CLI 操作，结束后保存为 cast 文件。
• 回放与分享：cast 可在本地直接回放；也可通过内置 HTTP 服务或 asciinema server 中继（relay）进行实时直播式分享。
• 沉淀为文档：配合逐条命令注释，cast 就能直接充当可重现的 CLI 操作指南，供他人或 agent 照着执行。

适用边界与注意点

• 从源码构建 asciinema 需要 Rust 工具链；早期基于 Python 的 2.x 版本仍可找到，但属于上一代实现。
• 它不是通用屏幕录像机。如果要录制 GUI 应用或非终端画面，这个方案并不适用。
• 实时推流依赖 asciinema server（自建中继）；只想本地保存和回放则无需这一步。
• 更多构建细节和命令用法以仓库文档为准（见来源页的 GitHub 仓库）。