1实现原理 · 为什么它能做到

自动化生成的核心是把命令列表翻译成 VHS tape 文件（Output/Set Theme/Set FontSize/Type/Enter/Sleep…），再交给 vhs 渲染成 GIF。

cli-demo-generator/scripts/auto_generate_demo.py

tape_lines = [ f'Output {output_gif}', f'Set Theme "{theme}"', f'Set FontSize {font_size}', f'Set Width {width}', f'Set Height {height}', f'Set Padding {padding}', 'Set TypingSpeed 10ms', 'Set Shell zsh', '', ]

这里在做什么：VHS 的 tape 是逐键脚本——每步 Type 一条命令再 Enter，Sleep 控制节奏；Set Shell zsh 决定录制终端里跑什么 shell。生成器把『想演示什么命令』结构化成录制脚本，避免手写 tape。

录制是真实执行：main() 在无 --no-execute 时直接 subprocess 调 vhs，tape 中的命令会在 vhs 的模拟终端里真的敲下去并运行。

cli-demo-generator/scripts/auto_generate_demo.py

subprocess.run(['vhs', str(tape_file)], check=True)

这意味着录出来的不是『画出来的假终端』而是命令的真实运行过程（真实输出/真实退出码）——自举 demo 里 cleanup/install 等隐藏命令也会真执行，这正是 self-bootstrapping 能『自己清理状态』的原因。

VHS 解析器缺陷的规避：Type 串不能含 $、双引号、反引号，复杂命令先 base64 编码、运行时解码执行。

cli-demo-generator/SKILL.md

VHS `Type` strings cannot contain `$`, `"`, or backticks. These cause parse errors

SKILL.md 给出把整段 shell（如带 2>&1 | grep -v 的输出过滤器包装函数）base64 后写成 'echo <b64> | base64 -d > /tmp/wrapper.sh && source /tmp/wrapper.sh' 再进 Type 的标准套路；auto_generate_demo.py 的 --filter 分支内部就自动做这件事（wrapper = _wrap() {...grep -v -E "filter"...} → base64 → 写入 /tmp/cw.sh 并 source）。

自举/噪声过滤的『观众视角』编排：Hide 段跑 setup/cleanup → clear 清屏 → Show 后才开始录观众要看的命令。

cli-demo-generator/scripts/auto_generate_demo.py

tape_lines.append('Hide') … tape_lines.append('Show')

SKILL.md 强调 'The `Hide` → commands → `clear` → `Show` sequence is critical. `clear` wipes the terminal buffer so hidden commands don't leak into the GIF.'——隐藏段与展示段共用同一真实 shell，靠清屏保证成品只含想展示的内容。

智能节奏：按命令语义给不同 Sleep（install/build/test/deploy→3s，ls/pwd/echo 等→1s，其余→2s），录完可用 gifsicle 变速后处理。

cli-demo-generator/scripts/auto_generate_demo.py

if any(kw in cmd.lower() for kw in ['install', 'build', 'test', 'deploy', 'marketplace']): sleep_time = '3s' elif any(kw in cmd.lower() for kw in ['ls', 'pwd', 'echo', 'cat', 'grep']): sleep_time = '1s' else: sleep_time = '2s'

speed_up_gif 用 gifsicle 改帧延迟：'subprocess.run(['gifsicle', f'-d{delay}', tmp, '#0-'], stdout=out, check=True)'，delay = 10 // speed，先 cp 到 /tmp 再写回，避免污染原始录制。

三种附加模式：批量配置（batch_generate.py 读 YAML/JSON 逐个调用 auto 脚本）、交互录制（asciinema 录真会话→转 tape→vhs）、手写/模板 tape（assets/templates + placeholder 替换）。

cli-demo-generator/scripts/batch_generate.py

cmd = [sys.executable, str(script_path)] for command in commands: cmd.extend(['-c', command])

batch_generate 对每个 demo 条目重建 auto_generate_demo 的 argv（-c 命令可重复），YAML 解析依赖可选 PyYAML（缺时打印提示退出）；record_interactive.sh 则 'asciinema rec "$CAST_FILE"' 后把 cast 转成 tape 再 'vhs < "$TAPE_FILE"'。

2核心能力

01命令列表 → 成品 GIF 的全自动生成（auto_generate_demo.py -c/-o，含标题/主题/尺寸参数）

02自举型 demo：--bootstrap 隐藏清理/准备命令，成品自己恢复现场

03输出噪声过滤（--filter 正则；base64 包装 _wrap 函数运行时过滤）

04gifsicle 变速后处理（--speed N，改帧延迟，不重录）

05批量生成（demos.yaml/json → 逐 demo 出图，可并行/可选参数）

06交互式真人录制（asciinema rec → cast 转 tape → vhs，Ctrl+D 结束）

07帧级验证：ffmpeg 抽关键帧为 PNG，让 Claude/用户 Read 核对 GIF 内容

08手写 tape + 模板（basic/interactive/self-bootstrap.tape）+ 占位符替换（sed 注入检测到的仓库名）

3外部依赖

Kind	Dependency / Endpoint
cli	vhs（charmbracelet，必需）
cli	gifsicle（可选，变速）
cli	asciinema（可选，交互录制）
cli	ffmpeg/ffprobe（可选，抽帧验证）
package	PyYAML（可选，batch YAML 配置）

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: cli-demo-generator/scripts/auto_generate_demo.py（内部再执行 vhs/gifsicle/cp）
本地工作目录: 文件读写与工件输出: 输出 GIF/tape 写到用户指定 -o 路径

审计说明： 。自带 stdlib 本地脚本 + 本地 CLI（vhs/gifsicle/asciinema/ffmpeg），零网络外发、零凭证读取；写本地 GIF/tape/临时文件，无破坏性内建操作。核心注意点：录制即真实执行用户给的命令——这是该 skill 的功能本质（demo 命令必须在真终端跑才有真实输出），执行面等于宿主自身的 bash 面，不属于隐藏风险；但 filter 正则与命令串的引号边界需要使用者自持，VHS 解析缺陷路径由 base64 规避。

5第二遍独立确认

[ok] 自带脚本零网络外发 — scripts/ 三文件 token 扫描（URL/curl/wget/requests/urllib/socket/API_KEY/token/secret/os.system）零命中；子进程仅 vhs/gifsicle/cp/asciinema/sed。
[ok] 执行面：tape 命令真实执行 — auto_generate_demo.py 主流程 subprocess.run(['vhs', str(tape_file)])；tape 中 Type+Enter 在 vhs 终端内被 shell 执行（VHS 工具行为）。
[ok] --filter 的 base64 包装实现 — wrapper f-string + base64.b64encode + 'echo <b64> | base64 -d > /tmp/cw.sh && source /tmp/cw.sh' 在 create_tape_file 中逐字存在。
[ok] 变速后处理（gifsicle delay = 10//speed） — speed_up_gif 内 gifsicle -d{delay} tmp '#0-' 且先 cp 到 /tmp 再写回，与 SKILL.md 手写 gifsicle 命令一致。
[ok] 自举/隐藏命令防泄漏（Hide→clear→Show） — create_tape_file 在有 bootstrap/filter 时依次 append Hide/Type/Enter/Sleep/Type "clear"/Show；SKILL.md 有同序说明。
[ok] 批处理与交互模式调用链成立 — batch_generate 重建 auto_generate_demo argv（-c 循环）；record_interactive.sh 走 asciinema rec → 写 tape → vhs < tape。
[ok] 功能声明 vs 夸大检查 — description 八项能力全部有代码/SKILL.md 支撑；无越界承诺。依赖标注（VHS 必需、gifsicle/asciinema/ffmpeg/PyYAML 可选）与脚本内降级提示一致。
[ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。

6结论

一条命令从『要演示的命令列表』到成品 GIF，且录制是真实执行——输出可信、可放进 README。

把 VHS 生态的坑（解析器特殊字符、时序、隐藏命令泄漏）系统性文档化并自动化规避（base64、语义计时、clear）。

自举 demo 与噪声过滤针对真实需求：重复录制可复现、长输出命令能出干净成品，适合插件/CLI 宣传素材。

可选依赖降级设计：缺 gifsicle/asciinema/PyYAML 时打印提示继续/明确失败，不隐藏缺失。

多档自由度 + 帧级质检，兼顾自动化效率与『像素级』要求。

适合： 适合：需要给 CLI 工具/插件/脚本做 README 动图或演示素材的开发者；想录『可复现、自清理』的安装/使用流程 demo（self-bootstrap）；需要从一批命令批量出图的文档自动化；以及要求成品帧级可控（抽帧核对、变速不重录）的出品场景。

不适合： 不适合：演示命令含敏感输出或不可信第三方命令串的场景（录制=真实执行）；对终端『逐键外观』要求高于真实运行的伪录需求（应改用纯脚本打字模拟类工具）；无 vhs 环境（Linux 需自行安装 charmbracelet tap）或不想引入第三方录制 CLI 的用户；希望 demo 不产生任何真实副作用（如真实 npm install）的场景。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload cli-demo-generator.tar.gz

sha256: 9991cfcecc32bad8…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.