asciinema-streaming-backup

asciinema-streaming-backup

将 asciinema 录制内容流式备份到 GitHub，并自动归档为 brotli 的完整系统。使用空闲检测实现智能分块，使用 zstd 进行可拼接的流式压缩，并通过 GitHub Actions 进行最终的 brotli 重新压缩。

持续演进的技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移或需要变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 设置将 asciinema 录制内容实时备份到 GitHub
• 配置录制内容的空闲检测分块
• 为录制内容存储创建孤立分支基础设施
• 集成 GitHub Actions 以重新压缩为 brotli

平台：macOS、Linux 隔离：使用 Git 孤立分支（独立历史记录，不会污染主分支）

---

架构概览

┌─────────────────┐     zstd chunks      ┌─────────────────┐     Actions      ┌─────────────────┐
│  asciinema rec  │ ──────────────────▶  │  GitHub Orphan  │ ───────────────▶ │  brotli archive │
│  + idle-chunker │   (concatenatable)   │  gh-recordings  │                  │  (300x compress)│
└─────────────────┘                      └─────────────────┘                  └─────────────────┘
         │                                        │
         │ Idle ≥30s triggers chunk               │ Separate history
         ▼                                        │ Cannot PR to main
    ~/asciinema_recordings/                                 ▼
    └── repo-name/                          .github/workflows/
        └── chunks/*.zst                    └── recompress.yml

---

要求

组件	必需	安装	版本
asciinema CLI	是	brew install asciinema	3.0+（Rust）
zstd	是	brew install zstd	任意
brotli	是	brew install brotli	任意
git	是	预装	2.20+
gh CLI	是	brew install gh	任意
fswatch	可选	brew install fswatch	用于实时监控

---

工作流阶段

阶段 0：预检验证

验证是否已安装所有工具；如果缺少工具，则提供自动修复选项。运行预检脚本，然后通过 AskUserQuestion 提供安装缺失工具的选项。

完整的 preflight-check.sh 脚本请参阅设置脚本。

自动修复：如果缺少工具，则生成安装命令并提供运行选项。

---

阶段 1：GitHub 账户检测

从 4 个来源（SSH 配置、SSH 密钥、gh CLI、git 配置）检测可用的 GitHub 账户，并让用户选择要使用的账户。

检测脚本、评分逻辑和 AskUserQuestion 流程请参阅账户和仓库检测。

---

阶段 1.5：当前仓库检测

检测当前 git 仓库上下文（CURRENT_REPO_OWNER、CURRENT_REPO_NAME、DETECTED_FROM），为阶段 2 提供智能默认值。

检测脚本请参阅账户和仓库检测。

---

阶段 2：核心配置

收集基本配置：仓库 URL（根据阶段 1.5 自动检测）、录制目录和分支名称。

所有 AskUserQuestion 流程和 URL 规范化逻辑请参阅配置参考。

---

阶段 3：高级配置

允许自定义压缩和行为参数：

参数	默认值	范围
空闲阈值	30s	5-300s
zstd 级别	3	1-22
Brotli 级别	9	1-11
自动推送	是	是/否
轮询间隔	5s	2s、5s、10s

所有 AskUserQuestion 流程请参阅配置参考。

---

阶段 4：孤立分支设置

使用 GitHub Actions 工作流创建或配置孤立分支。首先检查分支是否已存在，并提供克隆、重置或验证选项。

关键操作：

1. 通过 git ls-remote 检查远程分支是否存在
2. 如果存在：使用 AskUserQuestion 询问克隆、重置或验证
3. 如果是新分支：创建孤立分支，添加工作流和目录结构，然后推送

完整的 setup-orphan-branch.sh 脚本请参阅设置脚本。 完整的 recompress.yml Actions 工作流请参阅 GitHub 工作流。

---

阶段 5：本地环境设置

配置本地目录，并根据阶段 3 中嵌入的用户参数生成定制的 idle-chunker.sh。

关键操作：

1. 将孤立分支克隆到 ~/asciinema_recordings/<repo>/
2. 生成嵌入配置的 idle-chunker.sh
3. 显示配置摘要和使用说明

本地设置脚本请参阅设置脚本。 完整的分块器实现请参阅 Idle Chunker。

---

阶段 6：自主验证

Claude 自主执行 8 项测试，并显示格式化结果。只有 2 项测试需要用户操作（录制测试、分块器实时测试）。

测试类别	数量	自主执行？
工具预检	5	是
压缩往返测试	3	是
仓库验证	4	是
GitHub Actions 触发	1	是
录制测试	1	否（用户）
分块器实时测试	1	否（用户）

完整的验证脚本、需要用户参与的测试流程和故障排除表请参阅自主验证。

---

快速开始

首次设置

/usr/bin/env bash << 'PREFLIGHT_EOF'
# 1. Check requirements
for tool in asciinema zstd brotli git gh; do
  command -v "$tool" &>/dev/null && echo "$tool: OK" || echo "$tool: MISSING"
done

# 2. Create orphan branch (replace with your repo)
REPO="[email protected]:YOUR/REPO.git"
./setup-orphan-branch.sh "$REPO"

# 3. Validate setup
./validate-setup.sh "$HOME/asciinema_recordings/REPO"
PREFLIGHT_EOF

录制会话

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
# Terminal 1: Start recording
WORKSPACE=$(basename "$PWD")
asciinema rec $PWD/tmp/${WORKSPACE}_$(date +%Y-%m-%d_%H-%M).cast

# Terminal 2: Start idle-chunker
~/asciinema_recordings/REPO/idle-chunker.sh $PWD/tmp/${WORKSPACE}_*.cast
SKILL_SCRIPT_EOF

---

关键设计决策

决策	原因
流式处理使用 zstd	支持帧拼接（brotli 不支持）
归档使用 brotli	压缩率最高（对 .cast 文件约为 300 倍）
孤立分支	完全隔离，不会污染主分支历史
基于空闲时间分块	在语义断点处分块，而非在输出中间拆分
浅克隆	磁盘占用最少，也不会意外访问主分支
30s 空闲阈值	平衡分块频率与语义完整性

---

故障排除

常见问题和解决方法请参阅故障排除指南。

---

更改后检查清单

修改此技能后：

1. 孤立分支创建脚本使用 heredoc 包装器
2. 所有 bash 代码块都兼容 zsh（不使用 declare -A 或 grep -P）
3. GitHub Actions 工作流会验证 brotli 重新压缩
4. 空闲分块器兼容 macOS 和 Linux 的 stat 语法
5. 检测流程输出可解析的 key=value 格式
6. 参考资料中的外部文档链接均通过验证

---

参考文档

• 账户与仓库检测 - GitHub 账户检测 + 仓库上下文
• 配置参考 - AskUserQuestion 序列 + 任务模板
• 空闲分块脚本 - 完整的分块器实现
• GitHub 工作流 - 完整的 Actions 工作流
• 设置脚本 - 所有设置和验证脚本
• 自主验证 - 验证脚本和用户必需的测试
• 故障排除指南 - 常见问题和解决方法
• asciinema 3.0 文档
• zstd 帧格式
• Git 孤立分支

执行后反思

此技能完成后，请在结束任务前进行反思：

0. 确认所在位置。 — 编辑前，找到此 SKILL.md 的规范路径。
1. 哪里失败了？ — 修正导致失败的指令。
2. 哪些做得比预期更好？ — 将其列为推荐实践。
3. 哪里出现了偏差？ — 修正任何与实际情况不再一致的脚本、参考文档或依赖项。
4. 记录下来。 — 在演进日志中记录触发原因、修复措施和证据。

不要拖延。下一次调用会继承你留下的一切。