vhs

Charmbracelet VHS 最佳实践

由 Charmbracelet 维护的 VHS 终端录制综合最佳实践指南。包含 8 个类别中的 47 条规则，并按影响排序，帮助创建专业、可移植且经过优化的终端演示。

适用场景

在以下情况下参考这些指南：

• 编写新的 VHS 磁带文件
• 为文档创建终端演示
• 为自动生成 GIF 配置 CI/CD
• 优化录制文件的大小和质量
• 排查磁带文件问题
• 根据最佳实践审查磁带文件

按优先级划分的规则类别

优先级	类别	影响	前缀
1	配置结构	严重	config-
2	依赖管理	严重	deps-
3	命令语法	高	cmd-
4	计时与同步	高	timing-
5	输出优化	中高	output-
6	视觉质量	中	visual-
7	CI/自动化	中	ci-
8	高级模式	低	advanced-

快速参考

1. 配置结构（严重）

• config-settings-order - 将所有设置放在命令之前
• config-output-first - 在文件开头声明输出
• config-shell-explicit - 明确设置 Shell 类型
• config-typing-speed-global - 尽早设置全局 TypingSpeed
• config-dimensions-explicit - 明确设置终端尺寸
• config-comments-document - 使用注释说明磁带结构

2. 依赖管理（严重）

• deps-require-early - 使用 Require 验证依赖项
• deps-require-order - 将 Require 放在设置之前
• deps-require-all - 对所有外部命令使用 Require
• deps-system-requirements - 验证系统依赖项

3. 命令语法（高）

• cmd-type-syntax - 使用正确的 Type 命令语法
• cmd-enter-explicit - 始终在 Type 后使用 Enter
• cmd-key-repeat - 使用按键重复次数
• cmd-ctrl-combinations - 使用 Ctrl 组合键控制终端
• cmd-hide-show - 对敏感操作使用 Hide/Show
• cmd-env-variables - 使用 Env 设置环境变量
• cmd-screenshot - 使用 Screenshot 截取静态画面
• cmd-multiline-type - 正确处理多行命令

4. 计时与同步（高）

• timing-sleep-after-enter - 在命令后添加 Sleep，以等待输出
• timing-wait-pattern - 使用 Wait 等待动态命令完成
• timing-type-speed-override - 覆盖 TypingSpeed 以突出重点
• timing-sleep-units - 使用明确的时间单位
• timing-final-sleep - 在录制结束时添加最终的 Sleep
• timing-natural-pauses - 在操作之间加入自然停顿
• timing-wait-timeout - 设置合适的 Wait 超时时间
• timing-playback-speed - 使用 PlaybackSpeed 进行最终调整

5. 输出优化（中高优先级）

• output-format-selection - 根据使用场景选择输出格式
• output-framerate - 优化帧率以减小文件体积
• output-dimensions-optimize - 合理设置终端尺寸
• output-loop-offset - 使用 LoopOffset 实现无缝循环
• output-multiple-formats - 生成多种输出格式
• output-relative-paths - 使用相对路径以便于移植

6. 视觉质量（中优先级）

• visual-font-readable - 选择易读的字体设置
• visual-theme-selection - 选择合适的主题
• visual-window-decoration - 添加窗口装饰以提升观感
• visual-spacing - 调整字间距和行间距
• visual-padding-margin - 有效设置内边距和外边距
• visual-cursor-visibility - 确保光标清晰可见

7. CI/自动化（中优先级）

• ci-github-action - 使用官方 VHS GitHub Action
• ci-auto-commit - 自动提交生成的资源
• ci-golden-files - 使用黄金文件进行集成测试
• ci-matrix-builds - 生成特定于平台的演示
• ci-caching - 在 CI 中缓存 VHS 依赖项

8. 高级模式（低优先级）

• advanced-source-include - 使用 Source 创建可复用的磁带组件
• advanced-clipboard - 使用 Copy 和 Paste 输入复杂内容
• advanced-recording-live - 录制实时会话后再进行编辑
• advanced-server-mode - 使用服务器模式进行远程访问

使用方法

阅读各参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
AGENTS.md	包含所有规则的完整汇编指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息