CLI 树¶

以下只列出当前已实现的命令。规划能力不放进 CLI 树，避免把文档蓝图误当成可执行接口。

顶层命令¶

termcap
├── record [OUTPUT_PATH]       # 录制 PTY 会话为 asciicast v2
├── exec [OPTIONS] -- COMMAND  # 执行命令并同步保存录制/媒体产物
├── replay INPUT_FILE          # 在当前终端重放 CAST
├── render INPUT [OUTPUT]      # CAST→SVG/GIF，或 SVG→GIF
├── svg2gif INPUT [OUTPUT]     # 独立 SVG→GIF 入口
├── config ...                 # 查看和修改持久配置
├── template ...               # 管理自定义 SVG 模板
├── --version
└── --help

直接运行 termcap 会输出主帮助信息。

录制与重放¶

termcap record [OUTPUT_PATH]
├── -c, --command TEXT         # 默认 $SHELL
└── -g, --geometry WIDTHxHEIGHT

termcap exec [OPTIONS] -- COMMAND [ARGS...]
├── -o, --output PATH          # CAST 输出路径
├── -g, --geometry WIDTHxHEIGHT
├── --render [svg|gif]         # 命令退出后同步渲染
├── --media-output PATH        # SVG/GIF 输出路径；可通过后缀推断格式
├── --env-script PATH          # 执行前 source 的脚本；可重复
├── --no-env-script            # 禁用 ChatEnv/config/ChatArch 默认入口
└── -t, --template TEXT        # 渲染时使用的 SVG 模板

termcap replay INPUT_FILE
├── -s, --speed FLOAT
└── -i, --idle-time-limit FLOAT

record 默认读取当前终端尺寸；短演示建议显式设置 geometry。
record -c 会在 stdin EOF 后继续 drain PTY，避免短命令生成只有 header 的空 CAST。
exec 会透传子命令 exit code；脚本/多步操作应通过 bash scripts/flow.sh 这类入口录制。
exec 默认按 ChatEnv 读取 TERMCAP_EXEC_ENV_SCRIPTS，否则自动 source $CHATARCH_HOME/config/termcap/exec-env.sh 和 exec-env.d/*.sh。
exec --env-script script.sh 可指定一次性入口；--no-env-script 可禁用默认入口。
exec --media-output demo.svg 会按后缀自动推断 --render svg。
replay --idle-time-limit 可以压缩长时间无输出的等待。

渲染与 GIF¶

termcap render INPUT [OUTPUT]
├── --format [svg|gif]
├── -D, --loop-delay INTEGER
├── -m, --min-duration INTEGER
├── -M, --max-duration INTEGER
├── -s, --still-frames
├── -t, --template TEXT
├── --speed FLOAT
├── --fps INTEGER
└── --loop INTEGER

termcap svg2gif INPUT.svg [OUTPUT.gif]
├── --speed FLOAT
├── --fps INTEGER
└── --loop INTEGER

输入/输出矩阵：

输入	输出	命令
`.cast`	`.svg`	`termcap render demo.cast demo.svg`
`.cast`	`.gif`	`termcap render demo.cast demo.gif --format gif`
`.svg`	`.gif`	`termcap render demo.svg demo.gif --format gif`
`.svg`	`.gif`	`termcap svg2gif demo.svg demo.gif`

--format cast 未实现，因此不会出现在帮助里。

配置¶

termcap config
├── show
├── get SECTION KEY
├── set SECTION KEY VALUE
├── reset
└── templates

模板¶

termcap template
├── list
├── install NAME TEMPLATE_FILE
└── remove NAME

内置模板随 wheel 一起安装；自定义模板写入用户配置目录，不修改包源码。