asciinema-streaming-backup

asciinema-streaming-backup

asciinema の録画を GitHub にストリーミングし、brotli で自動アーカイブする完全なシステムです。アイドル検出によるインテリジェントなチャンク分割、連結可能なストリーミング圧縮に zstd を使用し、最終的な brotli への再圧縮に GitHub Actions を使用します。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターにずれがある場合、または回避策が必要になった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使用する場面

次のような場合にこのスキルを使用してください。

• asciinema の録画を GitHub にリアルタイムでバックアップする場合
• 録画のアイドル検出によるチャンク分割を設定する場合
• 録画保存用の孤立ブランチのインフラストラクチャを作成する場合
• brotli への再圧縮に GitHub Actions を統合する場合

プラットフォーム：macOS、Linux 分離：Git の孤立ブランチを使用します（履歴は別で、main を汚染できません）

---

アーキテクチャの概要

┌─────────────────┐     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 倍）
孤立ブランチ	完全に分離でき、main の履歴を汚染しない
アイドル時間ベースのチャンク分割	出力の途中ではなく、意味的な区切りで分割する
シャロークローン	ディスク使用量を最小限に抑え、誤って main にアクセスできない
30 秒のアイドルしきい値	チャンクの頻度と意味的な完全性のバランスを取る

---

トラブルシューティング

よくある問題と解決方法については、トラブルシューティングガイドを参照してください。

---

変更後のチェックリスト

このスキルを変更した後：

1. 孤立ブランチの作成スクリプトでヒアドキュメントのラッパーを使用している
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. 記録する。 — きっかけ、修正内容、根拠を含む進化ログのエントリーを追加します。

先送りしてはいけません。次回の実行には、あなたが残した状態が引き継がれます。