cast-record 用于把真实的终端会话——包括真实输出、颜色和时序——录制为 asciicast .cast 文件（换行分隔的 JSON），底层使用 asciinema 3.x。cast 是文本原生的可信来源：可在终端中回放、可做 diff，也可在之后渲染。录制以本地为先，除非你显式运行 asciinema upload，否则不会上传任何内容。
不适用场景
需要带模拟打字的、打磨过的脚本化 README 演示 → 使用 tape-demo（无需捕获真实内容）。
把已有的 .cast 转成 GIF/MP4 → 使用 cast-render。
从录制中移除敏感数据 → 使用 cast-redact。
托管、串流或嵌入 asciinema 网页播放器 → 不在范围内。
工作流程
- 准备一个抗泄漏的会话（预防可降低风险；脱敏仍是发布前的关卡）：
在全新的临时目录中工作；对于会打印路径的演示，可考虑 HOME=$(mktemp -d)，或使用精简环境（env -i HOME=$TMP PATH=/usr/bin:/bin TERM=xterm-256color bash）——否则 SSH_AUTH_SOCK 或云凭证等继承变量仍可能被你录制的内容访问到。
只使用假凭证；如果提示符会显示 user@host，设置通用提示符（PS1='$ '）。
-c 命令字符串和捕获的环境会存入 cast 头部——绝不要把密钥放在命令行里。
- 录制。
脚本化/智能体驱动（可复现，无需 TTY）：
asciinema rec --headless --window-size 100x30 -i 2
-c ./demo.sh --overwrite demo.cast
交互式（由你操作）：asciinema rec demo.cast —— 以 ctrl+d 或 exit 结束；ctrl+\ 可在会话中途暂停/恢复捕获。
重要参数：--window-size COLSxROWS 固定尺寸（3.x 取代了旧的 --cols/--rows）；-i/--idle-time-limit 2 限制空白等待；-t "Title" 为录制加标题。
把被录制的命令当作可执行代码对待：录制前先审查脚本，不要在环境中带生产凭证进行录制。
-
验证。head -1 demo.cast 必须是 JSON 头部（{"version":3,"term":{"cols":100,"rows":30,...}}）。用 asciinema play demo.cast 回放以检查内容和节奏。
-
选择格式。3.x 默认写出 asciicast v3（相对时间戳，最易编辑）。对于只读 v2 的工具：asciinema rec -f asciicast-v2 … 或之后用 asciinema convert -f asciicast-v2 demo.cast demo-v2.cast。asciinema convert demo.cast demo.txt 可导出纯文本用于文档。
-
隔离，然后交接。在完成密钥扫描前，让原始 cast 远离 git（例如命名为 *.raw.cast 并把该模式加入 gitignore）——发布前运行 cast-redact，然后用 cast-render 生成 GIF/MP4。
输出规格
一个 .cast 文件，含有效的 JSON 头部行和 NDJSON 事件，尺寸符合约定，空闲时间受限，可用 asciinema play 回放。
没有发生上传；在扫描/脱敏前，原始 cast 不会被提交。
注意事项
-I/--capture-input 会记录每一次按键，包括在关闭回显时输入的密码。它默认关闭；仅当按键本身就是重点时才启用，并明确说明。
-i/--idle-time-limit 会在元数据中存储一个限制供播放器遵守——捕获的时序不变（agg 在渲染时应用自己的空闲上限）。
头部泄漏：命令、标题和捕获的环境（默认 SHELL，可通过 --capture-env 捕获更多）都会进入头部——注意它们包含什么。
覆盖/追加：asciinema 在没有 --overwrite 时拒绝覆盖已有文件；-a/--append 则继续之前的录制。
不支持 Windows（GNU/Linux、macOS、FreeBSD）。已针对 asciinema 3.1.0 验证；3.x 系列在 2026 年中期为当前版本（3.2.1）。
打印到终端的一切都在 cast 中——包括之后被清除或退格删掉的文本。假定文件包含的内容比最终屏幕显示的更多。