快速开始¶

交互式录制

进入子 shell，自由执行多条命令，使用 exit 或 ++ctrl+d++ 结束。
单命令录制

使用 -c 录制脚本、测试或一次性命令，命令退出后自动结束。
命令包装录制

使用 termcap exec -- <command> 像 sandbox wrapper 一样运行原命令，并自动保存 CAST/SVG/GIF。
媒体导出

同一个 .cast 可以输出 SVG、GIF 或静态 SVG 帧。

安装¶

TermCap 支持 Linux、macOS 和 BSD，需要 Python 3.10 或更高版本。GIF 导出还需要本机可用的 Google Chrome；ChromeDriver 由工具首次运行时准备并缓存。

python -m pip install termcap
termcap --version

先看完整结果¶

下面两张图来自同一份终端录制：先生成可缩放的动画 SVG，再从同一时间轴确定性导出 GIF。

SVG 动画¶

GIF 导出¶

查看生成脚本和完整命令

录制终端¶

交互式 shell¶

termcap record demo.cast -g 80x20

进入子 shell 后正常执行命令；完成时运行：

exit

单条命令¶

termcap record tests.cast -g 100x24 -c "python -m pytest -q"

-c 模式会继续读取 PTY 直到子进程退出并把剩余输出 drain 完成，适合短命令和自动化验收。

命令包装录制¶

如果希望像 codex exec 或 sandbox wrapper 一样把 TermCap 放在原命令前面，用 exec：

termcap exec -g 96x16 \
  -o hello.cast \
  --media-output hello.svg \
  -- python3 -c 'print("hello from termcap exec")'

exec 会运行 -- 后面的原命令，保存 .cast，并在指定 --media-output 或 --render 时同步渲染 SVG/GIF。子命令的 exit code 会原样作为 termcap exec 的 exit code，方便 CI 或 agent 流水线判断成败。

默认执行环境入口¶

TermCap 是 Chat 系列项目，默认执行环境按 ChatEnv 管理。安装 TermCap 后会注册 termcap 配置类型，可以把需要提前 source 的脚本写进 ChatEnv active profile：

chatenv init -t termcap
chatenv set TERMCAP_EXEC_ENV_SCRIPTS='~/.nvm/nvm.sh:~/.local/bin/team-env.sh'

TERMCAP_EXEC_ENV_SCRIPTS 使用系统 path separator；Linux/macOS 下是 :。如果只需要一个兼容旧入口，也可以设置 TERMCAP_EXEC_ENV_SCRIPT。

同时保留一个 ChatArch 约定入口，不需要写 ChatEnv 也能生效：

$CHATARCH_HOME/config/termcap/exec-env.sh
$CHATARCH_HOME/config/termcap/exec-env.d/*.sh

termcap exec 会按顺序 source exec-env.sh，再按文件名排序 source exec-env.d/*.sh。如果某次执行不想加载默认入口：

termcap exec --no-env-script -- pwd

临时指定脚本可以重复使用 --env-script：

termcap exec --env-script ~/.nvm/nvm.sh --env-script ./project-env.sh -- node -v

多步操作可以先写成脚本，再录制脚本入口：

termcap exec -g 100x20 \
  --media-output workflow.svg \
  -- bash scripts/demo-workflow.sh

脚本内部可自由安排 sleep 间隔、检查点和多条命令；TermCap 当前只记录真实 PTY 行为，不声明额外隔离或权限沙箱。

重放 CAST¶

termcap replay demo.cast
termcap replay demo.cast --speed 2
termcap replay demo.cast --idle-time-limit 2

渲染 SVG¶

termcap render demo.cast demo.svg

指定模板：

termcap render demo.cast demo.svg -t window_frame

输出独立静态帧：

termcap render demo.cast demo_frames --still-frames

导出 GIF¶

CAST 直接转 GIF：

termcap render demo.cast demo.gif --format gif

已有 SVG 转 GIF：

termcap svg2gif demo.svg demo.gif

速度和循环：

termcap svg2gif demo.svg demo-fast.gif --speed 2 --loop 0

TermCap SVG 含离散终端关键帧时，--fps 不会制造重复帧；只有普通 SVG 缺少可识别关键帧时，才使用 --fps 进行回退采样。