tutorial-updates

教程更新技能

使用 VHS 磁带文件和 Playwright 浏览器规格编排教程生成。

适用场景

• 生成或更新面向用户的教程
• 创建 VHS 和 Playwright 教程录制

不适用场景

• 不包含面向用户教程的内部文档
• API 参考文档——请改用 scribe:doc-generator

概述

此技能协调完整的教程生成流程：

1. 在项目中发现磁带文件和清单
2. 验证磁带命令并检查二进制文件是否为最新版本
3. 如果二进制文件已过时，则重新构建，以确保演示反映最新代码
4. 使用 VHS 录制终端会话（scry:vhs-recording）
5. 使用 Playwright 录制浏览器会话（scry:browser-recording）
6. 生成经过优化的 GIF（scry:gif-generation）
7. 组合多组件教程（scry:media-composition）
8. 为 docs/ 和 book/ 生成双语气 Markdown

命令选项

/update-tutorial quickstart        # Single tutorial by name
/update-tutorial sync mcp          # Multiple tutorials
/update-tutorial --all             # All tutorials with manifests
/update-tutorial --list            # Show available tutorials
/update-tutorial --scaffold        # Create structure without recording

验证： 使用 --help 标志运行命令，以验证其是否可用。

必需的进度事项

创建带有以下前缀的待办事项，以跟踪进度：

**Verification:** Run the command with `--help` flag to verify availability.
- tutorial-updates:discovery
- tutorial-updates:validation
- tutorial-updates:rebuild
- tutorial-updates:recording
- tutorial-updates:generation
- tutorial-updates:integration

验证： 使用 --help 标志运行命令，以验证其是否可用。

阶段 1：发现（tutorial-updates:discovery）

步骤 1.1：定位教程资源

在项目中查找磁带文件和清单：

# Find manifest files
find . -name "*.manifest.yaml" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

# Find tape files
find . -name "*.tape" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

# Find browser specs
find . -name "*.spec.ts" -path "*/browser/*" -type f \
  -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  2>/dev/null | head -20

验证： 使用 --help 标志运行命令，以验证其是否可用。

步骤 1.2：解析清单

对于每个清单文件，提取：

• 教程名称和标题
• 组件列表（磁带文件、playwright 规格）
• GIF 的输出路径
• 组合规则（布局、合并选项）

清单架构的详细信息请参阅 modules/manifest-parsing.md。

步骤 1.3：处理选项

选项	行为
--list	显示发现的教程并退出
--all	处理所有已发现的清单
--scaffold	创建目录结构和空文件，但不进行录制
<names>	仅处理指定的教程

指定 --list 时：

**Verification:** Run the command with `--help` flag to verify availability.
Available tutorials:
  quickstart     assets/tapes/quickstart.tape
  sync           assets/tapes/sync.tape (manifest)
  mcp            assets/tapes/mcp.manifest.yaml (terminal + browser)
  skill-debug    assets/tapes/skill-debug.tape

验证： 使用 --help 标志运行命令，以验证其是否可用。

阶段 1.5：验证（tutorial-updates:validation）

关键： 在运行 VHS 之前验证磁带命令，以避免耗费大量资源的重复生成。

每个磁带都会执行四项检查：VHS 语法（包含 Output 指令且引号成对），根据 --help 检查每条 Type 命令中的 CLI 标志，确保演示数据存在且已填充，以及在超时限制内本地运行每条命令，以捕获失败、空输出和卡死情况。脚本和验证的退出条件详见 modules/tape-validation.md。

验证标志

标志	行为
--validate-only	运行验证，但不生成 GIF
--skip-validation	跳过验证，以便快速重新生成

如果验证失败：立即停止，报告错误，且不要继续进行 VHS 录制。

阶段 1.6：重新构建二进制文件（tutorial-updates:rebuild）

关键： 确保磁带中测试的二进制文件与最新源代码一致。过时的二进制文件会生成误导性演示。

检测构建系统（Cargo 或 Make），比较二进制文件的修改时间与 Git HEAD；如果已过时，则重新构建，随后确认二进制文件位于 PATH 中且能运行 --version。脚本、标志和重新构建的退出条件详见 modules/binary-rebuild.md。

如果重新构建失败：立即停止并报告构建错误，且不要继续进行磁带验证或 VHS 录制。

阶段 2：录制（tutorial-updates:recording）

步骤 2.1：处理磁带组件

对于每个磁带文件组件：

1. 解析磁带文件中的元数据注释（@step、@docs-brief、@book-detail）
2. 验证是否存在 Output 指令
3. 使用磁带文件路径调用 Skill(scry:vhs-recording)
4. 确认已创建 GIF 输出

步骤 2.2：处理浏览器组件

对于每个 Playwright 规格组件：

1. 检查 requires 字段中的前置命令（例如，启动服务）
2. 启动所需的任何后台进程
3. 使用规格文件路径调用 Skill(scry:browser-recording)
4. 停止后台进程
5. 调用 Skill(scry:gif-generation) 将 WebM 转换为 GIF

步骤 2.3：处理多组件教程

对于包含 combine 部分的清单：

1. 确认所有组件 GIF 均已存在
2. 使用清单调用 Skill(scry:media-composition)
3. 确认已生成合并后的输出

阶段 3：生成（tutorial-updates:generation）

步骤 3.1：解析 Tape 注释

从 tape 文件中提取文档内容：

# @step Install skrills
# @docs-brief Install via cargo
# @book-detail The recommended installation method uses cargo...
Type "cargo install skrills"

验证： 使用 --help 标志运行命令，以确认其可用。

注释：

• @step - 步骤标题/标题
• @docs-brief - 项目文档（docs/ 目录）的简洁文本
• @book-detail - 技术书籍（book/ 目录）的扩展文本

步骤 3.2：生成双风格 Markdown

为每个教程生成两个版本：

1. 项目文档（docs/tutorials/<name>.md）

   • 简洁，以操作为导向
   • 使用 @docs-brief 内容
   • 侧重命令和快速结果

2. 技术书籍（book/src/tutorials/<name>.md）

   • 详尽，具有教学性
   • 使用 @book-detail 内容
   • 解释概念和理由

格式详情请参阅 modules/markdown-generation.md。

步骤 3.3：生成 README 演示部分

在 README.md 中创建或更新演示部分：

## Demos

### Quickstart
![Quickstart demo](assets/gifs/quickstart.gif)
*Install, validate, analyze, and serve in under a minute. [Full tutorial](docs/tutorials/quickstart.md)*

验证： 使用 --help 标志运行命令，以确认其可用。

阶段 4：集成（tutorial-updates:integration）

步骤 4.1：验证所有输出

确认所有预期文件均已存在：

# Check GIF files
for gif in assets/gifs/*.gif; do
  if [[ -f "$gif" ]]; then
    echo "OK: $gif ($(du -h "$gif" | cut -f1))"
  else
    echo "MISSING: $gif"
  fi
done

# Check markdown files
ls -la docs/tutorials/*.md 2>/dev/null
ls -la book/src/tutorials/*.md 2>/dev/null

验证： 使用 --help 标志运行命令，以确认其可用。

步骤 4.2：更新 SUMMARY.md（书籍）

如果项目采用 mdBook 结构，请更新 book/src/SUMMARY.md：

- [Tutorials](./tutorials/README.md)
  - [Quickstart](./tutorials/quickstart.md)
  - [Sync Workflow](./tutorials/sync.md)
  - [MCP Integration](./tutorials/mcp.md)
  - [Skill Debugging](./tutorials/skill-debug.md)

验证： 使用 --help 标志运行命令，以确认其可用。

步骤 4.3：报告结果

总结更新内容：

**Verification:** Run the command with `--help` flag to verify availability.
Tutorial Update Complete
========================
Tutorials processed: 4
GIFs generated: 5
  - quickstart.gif (1.2MB)
  - sync.gif (980KB)
  - mcp-terminal.gif (1.5MB)
  - mcp-browser.gif (2.1MB)
  - skill-debug.gif (890KB)

Markdown generated:
  - docs/tutorials/ (4 files)
  - book/src/tutorials/ (4 files)

README demo section updated

验证： 使用 --help 标志运行命令，以确认其可用。

退出条件

• 已处理所有指定的教程（或使用 --all 时处理全部教程）
• 已在清单指定的路径创建 GIF 文件
• 已为每个教程生成双风格 Markdown
• 已更新 README 演示部分并嵌入 GIF
• 已更新书籍的 SUMMARY.md（如适用）
• 已完成所有进度项

错误处理

错误	解决方法
未安装 VHS	go install github.com/charmbracelet/vhs@latest
未安装 Playwright	npm install -D @playwright/test && npx playwright install chromium
Tape 文件缺少 Output	添加 Output assets/gifs/<name>.gif 指令
浏览器规格需要服务	运行规格前启动服务
GIF 过大	在 gif-generation 中调整 fps/scale

脚手架模式

指定 --scaffold 时，创建结构但不进行录制：

1. 创建 assets/tapes/ 目录
2. 创建 assets/gifs/ 目录
3. 创建 assets/browser/ 目录（如果计划编写浏览器教程）
4. 创建包含元数据注释的 Tape 模板文件
5. 创建模板清单文件
6. 在 docs/tutorials/ 和 book/src/tutorials/ 中创建空 Markdown 文件

Tape 模板文件：

# @title: Tutorial Name
# @description: Brief description of the tutorial

Output assets/gifs/tutorial-name.gif
Set FontSize 14
Set Width 1200
Set Height 600
Set Theme "Catppuccin Mocha"

# @step Step 1 Title
# @docs-brief Brief docs text
# @book-detail Extended book text with more context and explanation
Type "command here"
Enter
Sleep 2s

验证： 使用 --help 标志运行命令，以确认其可用。