用途:把一串裸命令变成可自定进度、带讲解的演示脚本,既适合现场演示,也适合用户自行跟练(入门、学习、复现结果)。不适用于非交互式 CI 脚本、一次性临时脚本或纯参考文档。
主要能力:提供 skeleton.sh 骨架,含 banner / note / pause / run 辅助函数,支持编号小节、暗色说明、每步按 Enter 暂停、原样流式输出命令结果;另有可选的 run_expect_fail 处理预期非零退出的步骤(用 || rc=$? 避免 set -euo pipefail 中断)。顶部集中一个环境变量配置块,必填项快速失败,其余有默认值。支持重跑:DEMO_NO_PAUSE=1 无人值守运行,跳过标志(如 SKIP_SETUP=1)复用预置状态。
四段式:Frame 说明为什么(一两句,无命令);Tell 先列出步骤,标出慢、需网络/VPN 及需注意处;Show 逐条运行真实命令,运行前暂停并流式输出完整结果,慢或易失败部分预置并留回退;Close 用一行总结并给出文档/ADR、相关演示等指引。
规则:展示真实输出,不用 >/dev/null,不伪造;不通过放宽门槛制造成功,诚实失败也是有效一节;多分钟步骤(部署、基准、登录)预置,现场步骤控制在秒级;默认可直接提交,不含家目录路径、kubeconfig 路径或私有引用。
示例:demos/evidence-demo.sh 按 Frame(可达性缺口)→ Tell(validate → publish → verify)→ Show(各段流式、预置并带回退)→ Close(ADR-007 及相关演示)组织。
常见错误:只堆命令缺 Frame/Close;慢的生产步骤现场运行;硬编码路径或标准;伪造/抑制输出或放宽门槛。