tutorial-updates
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTable of Contents
目录
- Overview
- Command Options
- Required TodoWrite Items
- Phase 1: Discovery ()
tutorial-updates:discovery - Step 1.1: Locate Tutorial Assets
- Step 1.2: Parse Manifests
- Step 1.3: Handle Options
- Phase 1.5: Validation ()
tutorial-updates:validation - Step 1.5.1: VHS Syntax Validation
- Step 1.5.2: Extract and Validate CLI Commands
- Step 1.5.3: Verify Demo Data Exists
- Step 1.5.4: Test Commands Locally
- Validation Flags
- Validation Exit Criteria
- Phase 1.6: Binary Rebuild ()
tutorial-updates:rebuild - Step 1.6.1: Detect Build System
- Step 1.6.2: Check Binary Freshness
- Step 1.6.3: Rebuild Binary
- Step 1.6.4: Verify Binary Accessibility
- Rebuild Flags
- Rebuild Exit Criteria
- Phase 2: Recording ()
tutorial-updates:recording - Step 2.1: Process Tape Components
- Step 2.2: Process Browser Components
- Step 2.3: Handle Multi-Component Tutorials
- Phase 3: Generation ()
tutorial-updates:generation - Step 3.1: Parse Tape Annotations
- Step 3.2: Generate Dual-Tone Markdown
- Step 3.3: Generate README Demo Section
- Demos
- Quickstart
- Phase 4: Integration ()
tutorial-updates:integration - Step 4.1: Verify All Outputs
- Step 4.2: Update SUMMARY.md (Book)
- Step 4.3: Report Results
- Exit Criteria
- Error Handling
- Scaffold Mode
- 概述
- 命令选项
- 必填TodoWrite项
- 阶段1：发现（）
tutorial-updates:discovery - 步骤1.1：定位教程资源
- 步骤1.2：解析清单文件
- 步骤1.3：处理参数
- 阶段1.5：校验（）
tutorial-updates:validation - 步骤1.5.1：VHS语法校验
- 步骤1.5.2：提取并校验CLI命令
- 步骤1.5.3：验证演示数据存在
- 步骤1.5.4：本地测试命令
- 校验参数
- 校验退出标准
- 阶段1.6：二进制文件重建（）
tutorial-updates:rebuild - 步骤1.6.1：检测构建系统
- 步骤1.6.2：检查二进制文件新鲜度
- 步骤1.6.3：重建二进制文件
- 步骤1.6.4：验证二进制文件可访问性
- 重建参数
- 重建退出标准
- 阶段2：录制（）
tutorial-updates:recording - 步骤2.1：处理Tape组件
- 步骤2.2：处理浏览器组件
- 步骤2.3：处理多组件教程
- 阶段3：生成（）
tutorial-updates:generation - 步骤3.1：解析Tape注解
- 步骤3.2：生成双模式Markdown
- 步骤3.3：生成README演示部分
- 演示
- 快速开始
- 阶段4：集成（）
tutorial-updates:integration - 步骤4.1：验证所有输出
- 步骤4.2：更新SUMMARY.md（书籍）
- 步骤4.3：上报结果
- 退出标准
- 错误处理
- 脚手架模式
Tutorial Updates Skill
教程更新Skill
Orchestrate tutorial generation with GIF recordings from VHS tape files and Playwright browser specs.
编排教程生成全流程，可基于VHS tape文件和Playwright浏览器规范生成附带GIF录制内容的教程。
When To Use
适用场景
- Generating or updating user-facing tutorials
- Creating VHS and Playwright tutorial recordings
- 生成或更新面向用户的教程
- 创建VHS和Playwright教程录制内容
When NOT To Use
不适用场景
- Internal documentation without user-facing tutorials
- API reference docs - use scribe:doc-generator instead
- 无面向用户教程的内部文档
- API参考文档，请使用scribe:doc-generator工具
Overview
概述
This skill coordinates the complete tutorial generation pipeline:
- Discover tape files and manifests in the project
- Validate tape commands and check binary freshness
- Rebuild binaries if stale so demos reflect latest code
- Record terminal sessions using VHS (scry:vhs-recording)
- Record browser sessions using Playwright (scry:browser-recording)
- Generate optimized GIFs (scry:gif-generation)
- Compose multi-component tutorials (scry:media-composition)
- Generate dual-tone markdown for docs/ and book/
本Skill协调完整的教程生成流水线：
- 发现项目中的tape文件和清单文件
- 校验tape命令并检查二进制文件新鲜度
- 若二进制文件过时则重建，确保演示内容匹配最新代码
- 使用VHS录制终端会话（scry:vhs-recording）
- 使用Playwright录制浏览器会话（scry:browser-recording）
- 生成优化后的GIF（scry:gif-generation）
- 组合多组件教程（scry:media-composition）
- 为docs/和book/目录生成双模式markdown
Command Options
命令选项
bash
/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 recordingVerification: Run the command with flag to verify availability.
--helpbash
/update-tutorial quickstart # 按名称生成单个教程
/update-tutorial sync mcp # 生成多个教程
/update-tutorial --all # 生成所有带清单文件的教程
/update-tutorial --list # 展示可用教程
/update-tutorial --scaffold # 创建结构但不执行录制验证： 执行带参数的命令确认可用。
--helpRequired TodoWrite Items
必填TodoWrite项
Create todos with these prefixes for progress tracking:
**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:integrationVerification: Run the command with flag to verify availability.
--help创建带以下前缀的待办项用于进度跟踪：
**验证：** 执行带`--help`参数的命令确认可用。
- tutorial-updates:discovery
- tutorial-updates:validation
- tutorial-updates:rebuild
- tutorial-updates:recording
- tutorial-updates:generation
- tutorial-updates:integration验证： 执行带参数的命令确认可用。
--helpPhase 1: Discovery (tutorial-updates:discovery
)
tutorial-updates:discovery阶段1：发现（tutorial-updates:discovery
）
tutorial-updates:discoveryStep 1.1: Locate Tutorial Assets
步骤1.1：定位教程资源
Find tape files and manifests in the project:
bash
undefined查找项目中的tape文件和清单文件：
bash
undefinedFind manifest files
查找清单文件
find . -name "*.manifest.yaml" -type f 2>/dev/null | head -20
find . -name "*.manifest.yaml" -type f 2>/dev/null | head -20
Find tape files
查找tape文件
find . -name "*.tape" -type f 2>/dev/null | head -20
find . -name "*.tape" -type f 2>/dev/null | head -20
Find browser specs
查找浏览器规范文件
find . -name ".spec.ts" -path "/browser/*" -type f 2>/dev/null | head -20
**Verification:** Run the command with `--help` flag to verify availability.find . -name ".spec.ts" -path "/browser/*" -type f 2>/dev/null | head -20
**验证：** 执行带`--help`参数的命令确认可用。Step 1.2: Parse Manifests
步骤1.2：解析清单文件
For each manifest file, extract:
- Tutorial name and title
- Component list (tape files, playwright specs)
- Output paths for GIFs
- Composition rules (layout, combine options)
See for manifest schema details.
modules/manifest-parsing.md为每个清单文件提取以下内容：
- 教程名称和标题
- 组件列表（tape文件、playwright规范）
- GIF输出路径
- 组合规则（布局、合并选项）
参考查看清单文件schema详情。
modules/manifest-parsing.mdStep 1.3: Handle Options
步骤1.3：处理参数
| Option | Behavior |
|---|---|
| Display discovered tutorials and exit |
| Process all discovered manifests |
| Create directory structure and empty files without recording |
| Process only specified tutorials |
When is specified:
--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.tapeVerification: Run the command with flag to verify availability.
--help| 参数 | 行为 |
|---|---|
| 展示已发现的教程后退出 |
| 处理所有已发现的清单文件 |
| 创建目录结构和空文件但不执行录制 |
| 仅处理指定名称的教程 |
指定参数时输出：
--list**验证：** 执行带`--help`参数的命令确认可用。
可用教程：
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验证： 执行带参数的命令确认可用。
--helpPhase 1.5: Validation (tutorial-updates:validation
)
tutorial-updates:validation阶段1.5：校验（tutorial-updates:validation
）
tutorial-updates:validationCRITICAL: Validate tape commands BEFORE running VHS to avoid expensive regeneration cycles.
See for detailed validation logic.
modules/tape-validation.md重要提示：运行VHS前先校验tape命令，避免耗费大量时间重新生成。
参考查看详细校验逻辑。
modules/tape-validation.mdStep 1.5.1: VHS Syntax Validation
步骤1.5.1：VHS语法校验
Check each tape file for valid VHS syntax:
bash
undefined检查每个tape文件的VHS语法是否合法：
bash
undefinedRequired: Output directive exists
必备：存在Output指令
grep -q '^Output ' "$tape_file" || echo "ERROR: Missing Output directive"
grep -q '^Output ' "$tape_file" || echo "ERROR: 缺失Output指令"
Check for balanced quotes in Type directives
检查Type指令中的引号是否配对
grep '^Type ' "$tape_file" | while read -r line; do
quote_count=$(echo "$line" | tr -cd '"' | wc -c)
if [ $((quote_count % 2)) -ne 0 ]; then
echo "ERROR: Unbalanced quotes: $line"
fi
done
**Verification:** Run the command with `--help` flag to verify availability.grep '^Type ' "$tape_file" | while read -r line; do
quote_count=$(echo "$line" | tr -cd '"' | wc -c)
if [ $((quote_count % 2)) -ne 0 ]; then
echo "ERROR: 引号未配对: $line"
fi
done
**验证：** 执行带`--help`参数的命令确认可用。Step 1.5.2: Extract and Validate CLI Commands
步骤1.5.2：提取并校验CLI命令
For each directive, extract the command and validate flags:
Typebash
undefined为每个指令提取命令并校验参数：
Typebash
undefinedExtract commands from Type directives
从Type指令中提取命令
grep '^Type ' "$tape_file" | sed 's/^Type "//' | sed 's/"$//' | while read -r cmd; do
Skip comments, clear, and echo commands
[[ "$cmd" =~ ^# ]] && continue
[[ "$cmd" == "clear" ]] && continue
For skrills commands, validate flags exist
if [[ "$cmd" =~ ^skrills ]]; then
base_cmd=$(echo "$cmd" | awk '{print $1, $2}')
flags=$(echo "$cmd" | grep -oE '--[a-zA-Z0-9-]+' || true)
for flag in $flags; do
if ! $base_cmd --help 2>&1 | grep -q -- "$flag"; then
echo "ERROR: Invalid flag '$flag' in command: $cmd"
fi
donefi
done
**Verification:** Run the command with `--help` flag to verify availability.grep '^Type ' "$tape_file" | sed 's/^Type "//' | sed 's/"$//' | while read -r cmd; do
跳过注释、clear和echo命令
[[ "$cmd" =~ ^# ]] && continue
[[ "$cmd" == "clear" ]] && continue
针对skrills命令，校验参数是否存在
if [[ "$cmd" =~ ^skrills ]]; then
base_cmd=$(echo "$cmd" | awk '{print $1, $2}')
flags=$(echo "$cmd" | grep -oE '--[a-zA-Z0-9-]+' || true)
for flag in $flags; do
if ! $base_cmd --help 2>&1 | grep -q -- "$flag"; then
echo "ERROR: 命令中存在非法参数'$flag': $cmd"
fi
donefi
done
**验证：** 执行带`--help`参数的命令确认可用。Step 1.5.3: Verify Demo Data Exists
步骤1.5.3：验证演示数据存在
If the tape uses demo data, verify it exists and is populated:
bash
undefined若tape使用了演示数据，验证数据存在且已填充：
bash
undefinedCheck SKRILLS_SKILL_DIR if set
若设置了SKRILLS_SKILL_DIR则检查该目录
skill_dir=$(grep '^Env SKRILLS_SKILL_DIR' "$tape_file" | sed 's/."(.)"/\1/')
if [ -n "$skill_dir" ]; then
if [ ! -d "$skill_dir" ]; then
echo "ERROR: Demo skill directory missing: $skill_dir"
else
skill_count=$(find "$skill_dir" -name "SKILL.md" 2>/dev/null | wc -l)
if [ "$skill_count" -eq 0 ]; then
echo "ERROR: No skills in demo directory: $skill_dir"
else
echo "OK: Found $skill_count demo skills in $skill_dir"
fi
fi
fi
**Verification:** Run the command with `--help` flag to verify availability.skill_dir=$(grep '^Env SKRILLS_SKILL_DIR' "$tape_file" | sed 's/."(.)"/\1/')
if [ -n "$skill_dir" ]; then
if [ ! -d "$skill_dir" ]; then
echo "ERROR: 演示Skill目录不存在: $skill_dir"
else
skill_count=$(find "$skill_dir" -name "SKILL.md" 2>/dev/null | wc -l)
if [ "$skill_count" -eq 0 ]; then
echo "ERROR: 演示目录中没有Skill: $skill_dir"
else
echo "OK: 在$skill_dir中找到$skill_count个演示Skill"
fi
fi
fi
**验证：** 执行带`--help`参数的命令确认可用。Step 1.5.4: Test Commands Locally
步骤1.5.4：本地测试命令
CRITICAL: Run each extracted command locally to verify it produces expected output:
bash
undefined重要提示：本地运行每个提取的命令，确认可生成预期输出：
bash
undefinedFor each command in the tape, do a quick sanity check
对tape中的每个命令做快速合理性检查
This catches issues like:
可捕获以下问题：
- Commands that exit with non-zero status
- 命令执行返回非零状态码
- Commands that produce no output (won't show anything in GIF)
- 命令无输出（GIF中不会显示任何内容）
- Commands that require user input (will hang VHS)
- 命令需要用户输入（会导致VHS挂起）
for cmd in $(extract_commands "$tape_file"); do
Run with timeout to catch hanging commands
if ! timeout 5s bash -c "$cmd" &>/dev/null; then
echo "WARNING: Command may fail or hang: $cmd"
fi
done
**Verification:** Run the command with `--help` flag to verify availability.for cmd in $(extract_commands "$tape_file"); do
添加超时逻辑捕获挂起的命令
if ! timeout 5s bash -c "$cmd" &>/dev/null; then
echo "WARNING: 命令可能执行失败或挂起: $cmd"
fi
done
**验证：** 执行带`--help`参数的命令确认可用。Validation Flags
校验参数
| Flag | Behavior |
|---|---|
| Run validation without generating GIF |
| Bypass validation for rapid regeneration |
| 参数 | 行为 |
|---|---|
| 仅执行校验，不生成GIF |
| 跳过校验，快速重新生成 |
Validation Exit Criteria
校验退出标准
- VHS tape syntax is valid (Output directive, balanced quotes)
- All CLI flags in commands are valid (verified against --help)
- Demo data directories exist and are populated
- Commands execute successfully with expected output
If validation fails: Stop immediately, report errors, and do NOT proceed to VHS recording.
- VHS tape语法合法（存在Output指令、引号配对）
- 命令中所有CLI参数合法（通过--help验证）
- 演示数据目录存在且已填充
- 命令执行成功，输出符合预期
若校验失败：立即停止、上报错误，不要继续执行VHS录制。
Phase 1.6: Binary Rebuild (tutorial-updates:rebuild
)
tutorial-updates:rebuild阶段1.6：二进制文件重建（tutorial-updates:rebuild
）
tutorial-updates:rebuildCRITICAL: Ensure the binary being tested in tapes matches the latest source code. Stale binaries produce misleading demos.
重要提示：确保tape中测试的二进制文件匹配最新源代码，过时的二进制文件会生成具有误导性的演示内容。
Step 1.6.1: Detect Build System
步骤1.6.1：检测构建系统
Identify the project's build system:
bash
undefined识别项目的构建系统：
bash
undefinedCheck for Cargo (Rust)
检测Cargo（Rust）
if [ -f "Cargo.toml" ]; then
BUILD_SYSTEM="cargo"
BINARY_NAME=$(grep '^name = ' Cargo.toml | head -1 | sed 's/."(.)"/\1/')
echo "Detected Cargo project: $BINARY_NAME"
if [ -f "Cargo.toml" ]; then
BUILD_SYSTEM="cargo"
BINARY_NAME=$(grep '^name = ' Cargo.toml | head -1 | sed 's/."(.)"/\1/')
echo "检测到Cargo项目: $BINARY_NAME"
Check for Makefile
检测Makefile
elif [ -f "Makefile" ]; then
BUILD_SYSTEM="make"
echo "Detected Make project"
elif [ -f "Makefile" ]; then
BUILD_SYSTEM="make"
echo "检测到Make项目"
Unknown
未知构建系统
else
echo "WARNING: Unknown build system, skipping binary check"
BUILD_SYSTEM="unknown"
fi
**Verification:** Run `make --dry-run` to verify build configuration.else
echo "WARNING: 未知构建系统，跳过二进制检查"
BUILD_SYSTEM="unknown"
fi
**验证：** 执行`make --dry-run`确认构建配置。Step 1.6.2: Check Binary Freshness
步骤1.6.2：检查二进制文件新鲜度
Compare binary modification time against Git HEAD:
bash
check_binary_freshness() {
local binary_name="$1"
# Locate binary (check cargo install location first, then PATH)
local binary_path=$(which "$binary_name" 2>/dev/null)
if [ -z "$binary_path" ]; then
echo "WARNING: Binary '$binary_name' not found in PATH"
return 1
fi
# Get binary modification time (Linux/macOS compatible)
local binary_mtime
if command -v stat >/dev/null 2>&1; then
# Linux
binary_mtime=$(stat -c %Y "$binary_path" 2>/dev/null || \
# macOS
stat -f %m "$binary_path" 2>/dev/null)
else
echo "WARNING: stat command not available, skipping freshness check"
return 2
fi
# Get Git HEAD commit time
local git_head_time=$(git log -1 --format=%ct 2>/dev/null)
if [ -z "$git_head_time" ]; then
echo "WARNING: Not a git repository, skipping freshness check"
return 2
fi
# Compare timestamps
if [ "$binary_mtime" -lt "$git_head_time" ]; then
echo "STALE: Binary is older than Git HEAD"
echo " Binary: $(date -d @$binary_mtime 2>/dev/null || date -r $binary_mtime)"
echo " HEAD: $(date -d @$git_head_time 2>/dev/null || date -r $git_head_time)"
return 1
else
echo "OK: Binary is up-to-date"
return 0
fi
}Verification: Run to confirm working tree state.
git status对比二进制文件修改时间和Git HEAD提交时间：
bash
check_binary_freshness() {
local binary_name="$1"
# 定位二进制文件（优先检查cargo安装位置，再检查PATH）
local binary_path=$(which "$binary_name" 2>/dev/null)
if [ -z "$binary_path" ]; then
echo "WARNING: 路径中未找到二进制文件'$binary_name'"
return 1
fi
# 获取二进制文件修改时间（兼容Linux/macOS）
local binary_mtime
if command -v stat >/dev/null 2>&1; then
# Linux
binary_mtime=$(stat -c %Y "$binary_path" 2>/dev/null || \
# macOS
stat -f %m "$binary_path" 2>/dev/null)
else
echo "WARNING: 无stat命令，跳过新鲜度检查"
return 2
fi
# 获取Git HEAD提交时间
local git_head_time=$(git log -1 --format=%ct 2>/dev/null)
if [ -z "$git_head_time" ]; then
echo "WARNING: 非Git仓库，跳过新鲜度检查"
return 2
fi
# 对比时间戳
if [ "$binary_mtime" -lt "$git_head_time" ]; then
echo "STALE: 二进制文件早于Git HEAD提交"
echo " 二进制文件修改时间: $(date -d @$binary_mtime 2>/dev/null || date -r $binary_mtime)"
echo " HEAD提交时间: $(date -d @$git_head_time 2>/dev/null || date -r $git_head_time)"
return 1
else
echo "OK: 二进制文件为最新版本"
return 0
fi
}验证： 执行确认工作树状态。
git statusStep 1.6.3: Rebuild Binary
步骤1.6.3：重建二进制文件
Rebuild using the detected build system:
bash
rebuild_binary() {
local build_system="$1"
local binary_name="$2"
case "$build_system" in
cargo)
echo "Rebuilding with Cargo..."
# Use cargo install for CLI binaries
if [ -d "crates/cli" ]; then
cargo install --path crates/cli --locked --quiet
else
cargo install --path . --locked --quiet
fi
;;
make)
echo "Rebuilding with Make..."
make build --quiet
;;
*)
echo "ERROR: Cannot rebuild, unknown build system"
return 1
;;
esac
echo "Build complete: $binary_name"
}Verification: Run to verify build configuration.
make --dry-run使用检测到的构建系统重建：
bash
rebuild_binary() {
local build_system="$1"
local binary_name="$2"
case "$build_system" in
cargo)
echo "使用Cargo重建..."
# CLI二进制文件使用cargo install
if [ -d "crates/cli" ]; then
cargo install --path crates/cli --locked --quiet
else
cargo install --path . --locked --quiet
fi
;;
make)
echo "使用Make重建..."
make build --quiet
;;
*)
echo "ERROR: 未知构建系统，无法重建"
return 1
;;
esac
echo "构建完成: $binary_name"
}验证： 执行确认构建配置。
make --dry-runStep 1.6.4: Verify Binary Accessibility
步骤1.6.4：验证二进制文件可访问性
Ensure the rebuilt binary is accessible:
bash
verify_binary() {
local binary_name="$1"
if ! command -v "$binary_name" >/dev/null 2>&1; then
echo "ERROR: Binary '$binary_name' not found after rebuild"
echo " Check PATH includes: $HOME/.cargo/bin"
return 1
fi
# Test binary can execute
if ! "$binary_name" --version >/dev/null 2>&1; then
echo "WARNING: Binary exists but --version failed"
else
echo "OK: Binary is accessible and functional"
"$binary_name" --version
fi
}Verification: Run to verify tests pass.
pytest -v确保重建后的二进制文件可访问：
bash
verify_binary() {
local binary_name="$1"
if ! command -v "$binary_name" >/dev/null 2>&1; then
echo "ERROR: 重建后未找到二进制文件'$binary_name'"
echo " 检查路径是否包含: $HOME/.cargo/bin"
return 1
fi
# 测试二进制文件可执行
if ! "$binary_name" --version >/dev/null 2>&1; then
echo "WARNING: 二进制文件存在但--version执行失败"
else
echo "OK: 二进制文件可访问且功能正常"
"$binary_name" --version
fi
}验证： 执行确认测试通过。
pytest -vRebuild Flags
重建参数
| Flag | Behavior |
|---|---|
| Skip binary freshness check and rebuild |
| Force rebuild even if binary is fresh |
| 参数 | 行为 |
|---|---|
| 跳过二进制文件新鲜度检查和重建 |
| 即使二进制文件为最新版本也强制重建 |
Rebuild Exit Criteria
重建退出标准
- Build system detected (Cargo, Make, or explicitly skipped)
- Binary freshness checked against Git HEAD
- Binary rebuilt if stale (or forced)
- Rebuilt binary is accessible in PATH
- Binary executes successfully (--version test)
If rebuild fails: Stop immediately, report build errors, and do NOT proceed to tape validation or VHS recording.
- 已检测到构建系统（Cargo、Make或明确跳过）
- 已对照Git HEAD检查二进制文件新鲜度
- 若二进制文件过时（或强制重建）已完成重建
- 重建后的二进制文件在路径中可访问
- 二进制文件执行成功（通过--version测试）
若重建失败：立即停止、上报构建错误，不要继续执行tape校验或VHS录制。
Phase 2: Recording (tutorial-updates:recording
)
tutorial-updates:recording阶段2：录制（tutorial-updates:recording
）
tutorial-updates:recordingStep 2.1: Process Tape Components
步骤2.1：处理Tape组件
For each tape file component:
- Parse tape file for metadata annotations (@step, @docs-brief, @book-detail)
- Validate Output directive exists
- Invoke with tape file path
Skill(scry:vhs-recording) - Verify GIF output was created
针对每个tape文件组件：
- 解析tape文件的元数据注解（@step、@docs-brief、@book-detail）
- 校验存在Output指令
- 传入tape文件路径调用
Skill(scry:vhs-recording) - 确认已生成GIF输出
Step 2.2: Process Browser Components
步骤2.2：处理浏览器组件
For each playwright spec component:
- Check field for prerequisite commands (e.g., start server)
requires - Launch any required background processes
- Invoke with spec path
Skill(scry:browser-recording) - Stop background processes
- Invoke to convert WebM to GIF
Skill(scry:gif-generation)
针对每个playwright规范组件：
- 检查字段获取前置命令（例如启动服务）
requires - 启动所有必需的后台进程
- 传入规范路径调用
Skill(scry:browser-recording) - 停止后台进程
- 调用将WebM转换为GIF
Skill(scry:gif-generation)
Step 2.3: Handle Multi-Component Tutorials
步骤2.3：处理多组件教程
For manifests with section:
combine- Verify all component GIFs exist
- Invoke with manifest
Skill(scry:media-composition) - Verify combined output was created
针对包含部分的清单文件：
combine- 验证所有组件GIF都存在
- 传入清单文件调用
Skill(scry:media-composition) - 确认已生成合并后的输出
Phase 3: Generation (tutorial-updates:generation
)
tutorial-updates:generation阶段3：生成（tutorial-updates:generation
）
tutorial-updates:generationStep 3.1: Parse Tape Annotations
步骤3.1：解析Tape注解
Extract documentation content from tape files:
tape
undefined从tape文件中提取文档内容：
tape
undefined@step Install skrills
@step 安装skrills
@docs-brief Install via cargo
@docs-brief 通过cargo安装
@book-detail The recommended installation method uses cargo...
@book-detail 推荐使用cargo安装...
Type "cargo install skrills"
**Verification:** Run the command with `--help` flag to verify availability.
Annotations:
- `@step` - Step title/heading
- `@docs-brief` - Concise text for project docs (docs/ directory)
- `@book-detail` - Extended text for technical book (book/ directory)Type "cargo install skrills"
**验证：** 执行带`--help`参数的命令确认可用。
注解说明：
- `@step` - 步骤标题/小标题
- `@docs-brief` - 项目文档（docs/目录）使用的简洁内容
- `@book-detail` - 技术书籍（book/目录）使用的扩展内容Step 3.2: Generate Dual-Tone Markdown
步骤3.2：生成双模式Markdown
Generate two versions of each tutorial:
-
Project docs ()
docs/tutorials/<name>.md- Brief, action-oriented
- Uses @docs-brief content
- Focuses on commands and quick results
-
Technical book ()
book/src/tutorials/<name>.md- Detailed, educational
- Uses @book-detail content
- Explains concepts and rationale
See for formatting details.
modules/markdown-generation.md为每个教程生成两个版本：
-
项目文档（）
docs/tutorials/<name>.md- 简洁、面向操作
- 使用@docs-brief内容
- 聚焦命令和快速结果
-
技术书籍（）
book/src/tutorials/<name>.md- 详细、面向教学
- 使用@book-detail内容
- 解释概念和设计逻辑
参考查看格式详情。
modules/markdown-generation.mdStep 3.3: Generate README Demo Section
步骤3.3：生成README演示部分
Create or update demo section in README.md:
markdown
undefined创建或更新README.md中的演示部分：
markdown
undefinedDemos
演示
Quickstart
快速开始
Install, validate, analyze, and serve in under a minute. Full tutorial**Verification:** Run the command with `--help` flag to verify availability.**验证：** 执行带`--help`参数的命令确认可用。Phase 4: Integration (tutorial-updates:integration
)
tutorial-updates:integration阶段4：集成（tutorial-updates:integration
）
tutorial-updates:integrationStep 4.1: Verify All Outputs
步骤4.1：验证所有输出
Confirm all expected files exist:
bash
undefined确认所有预期文件都存在：
bash
undefinedCheck GIF files
检查GIF文件
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
for gif in assets/gifs/*.gif; do
if [[ -f "$gif" ]]; then
echo "OK: $gif ($(du -h "$gif" | cut -f1))"
else
echo "缺失: $gif"
fi
done
Check markdown files
检查markdown文件
ls -la docs/tutorials/.md 2>/dev/null
ls -la book/src/tutorials/.md 2>/dev/null
**Verification:** Run the command with `--help` flag to verify availability.ls -la docs/tutorials/.md 2>/dev/null
ls -la book/src/tutorials/.md 2>/dev/null
**验证：** 执行带`--help`参数的命令确认可用。Step 4.2: Update SUMMARY.md (Book)
步骤4.2：更新SUMMARY.md（书籍）
If the project has an mdBook structure, update :
book/src/SUMMARY.mdmarkdown
- [Tutorials](./tutorials/README.md)
- [Quickstart](./tutorials/quickstart.md)
- [Sync Workflow](./tutorials/sync.md)
- [MCP Integration](./tutorials/mcp.md)
- [Skill Debugging](./tutorials/skill-debug.md)Verification: Run the command with flag to verify availability.
--help若项目使用mdBook结构，更新：
book/src/SUMMARY.mdmarkdown
- [教程](./tutorials/README.md)
- [快速开始](./tutorials/quickstart.md)
- [同步工作流](./tutorials/sync.md)
- [MCP集成](./tutorials/mcp.md)
- [Skill调试](./tutorials/skill-debug.md)验证： 执行带参数的命令确认可用。
--helpStep 4.3: Report Results
步骤4.3：上报结果
Summarize the update:
**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 updatedVerification: Run the command with flag to verify availability.
--help汇总更新结果：
**验证：** 执行带`--help`参数的命令确认可用。
教程更新完成
========================
已处理教程数: 4
已生成GIF数: 5
- quickstart.gif (1.2MB)
- sync.gif (980KB)
- mcp-terminal.gif (1.5MB)
- mcp-browser.gif (2.1MB)
- skill-debug.gif (890KB)
已生成Markdown文件:
- docs/tutorials/ (4个文件)
- book/src/tutorials/ (4个文件)
README演示部分已更新验证： 执行带参数的命令确认可用。
--helpExit Criteria
退出标准
- All specified tutorials processed (or all if --all)
- GIF files created at manifest-specified paths
- Dual-tone markdown generated for each tutorial
- README demo section updated with GIF embeds
- Book SUMMARY.md updated (if applicable)
- All TodoWrite items completed
- 所有指定教程已处理（若指定--all则处理所有教程）
- GIF文件已生成在清单指定的路径
- 每个教程已生成双模式markdown
- README演示部分已更新GIF嵌入内容
- 书籍SUMMARY.md已更新（若适用）
- 所有TodoWrite项已完成
Error Handling
错误处理
| Error | Resolution |
|---|---|
| VHS not installed | |
| Playwright not installed | |
| Tape file missing Output | Add |
| Browser spec requires server | Start server before running spec |
| GIF too large | Adjust fps/scale in gif-generation |
| 错误 | 解决方案 |
|---|---|
| 未安装VHS | |
| 未安装Playwright | |
| Tape文件缺失Output指令 | 添加 |
| 浏览器规范需要启动服务 | 运行规范前先启动服务 |
| GIF体积过大 | 调整gif-generation的帧率/缩放比例 |
Scaffold Mode
脚手架模式
When is specified, create structure without recording:
--scaffold- Create directory
assets/tapes/ - Create directory
assets/gifs/ - Create directory (if browser tutorials planned)
assets/browser/ - Create template tape file with metadata annotations
- Create template manifest file
- Create empty markdown files in docs/tutorials/ and book/src/tutorials/
Template tape file:
tape
undefined指定参数时，创建结构但不执行录制：
--scaffold- 创建目录
assets/tapes/ - 创建目录
assets/gifs/ - 创建目录（若计划制作浏览器教程）
assets/browser/ - 创建带元数据注解的模板tape文件
- 创建模板清单文件
- 在docs/tutorials/和book/src/tutorials/目录中创建空markdown文件
模板tape文件：
tape
undefined@title: Tutorial Name
@title: 教程名称
@description: Brief description of the tutorial
@description: 教程的简要描述
Output assets/gifs/tutorial-name.gif
Set FontSize 14
Set Width 1200
Set Height 600
Set Theme "Catppuccin Mocha"
Output assets/gifs/tutorial-name.gif
Set FontSize 14
Set Width 1200
Set Height 600
Set Theme "Catppuccin Mocha"
@step Step 1 Title
@step 步骤1标题
@docs-brief Brief docs text
@docs-brief 简洁的文档内容
@book-detail Extended book text with more context and explanation
@book-detail 包含更多上下文和解释的扩展书籍内容
Type "command here"
Enter
Sleep 2s
**Verification:** Run the command with `--help` flag to verify availability.Type "command here"
Enter
Sleep 2s
**验证：** 执行带`--help`参数的命令确认可用。Troubleshooting
故障排查
Common Issues
常见问题
Command not found
Ensure all dependencies are installed and in PATH
Permission errors
Check file permissions and run with appropriate privileges
Unexpected behavior
Enable verbose logging with flag
--verbose命令未找到
确保所有依赖已安装且在PATH中
权限错误
检查文件权限，使用合适的权限运行
非预期行为
使用参数开启详细日志
--verbose