Agency Docs Updater
すべてのステップを自動で順番に実行してください。ステップが失敗し、復旧不可能な場合のみ停止します。既知の問題については、事前に references/learnings.md を読んでください。
設定: パスはスキルルートの .env から読み取られます(.env.example を参照)。デフォルトは標準設定で動作します。主な環境変数: VAULT_DIR、DOCS_SITE_DIR、YOUTUBE_UPLOADER_DIR、PRESENTATIONS_DIR、SKILLS_REPO_DIR、SKILLS_LOCAL_DIR、ZOOM_CREDENTIALS_DIR、GITHUB_REPO、SITE_DOMAIN。
依存関係(実行前にこれらが存在することを確認してください):
- zoom — Zoom 録画のダウンロード (
scripts/zoom_meetings.py) - fathom — Fathom ビデオのフォールバック (
scripts/download_video.py) - nano-banana — サムネイルオーバーレイの生成 (
scripts/generate_image.sh) - calendar-sync — ローカルのみ、カレンダーイベントの同期 (
sync.sh) - youtube-uploader — 動画処理、アップロード、YouTube API 認証
ステップ 0: 引数の解析と設定の読み込み
スキルルートから .env を読み込みます。次に args を空白で分割します:
- 8桁のトークン (
YYYYMMDD) →DATE - "yesterday" →
DATE = $(date -v-1d +%Y%m%d) - "today" または省略 →
DATE = $(date +%Y%m%d) - 2桁のトークン (
NN) またはlab-NN→LAB_FILTER
後続のステップで使用されるパスの環境変数を展開します:
VAULT_DIR="${VAULT_DIR:-$HOME/Brains/brain}"
DOCS_SITE_DIR="${DOCS_SITE_DIR:-$HOME/Sites/agency-docs}"
YOUTUBE_UPLOADER_DIR="${YOUTUBE_UPLOADER_DIR:-$HOME/ai_projects/youtube-uploader}"
SKILLS_REPO_DIR="${SKILLS_REPO_DIR:-$HOME/ai_projects/claude-skills}"
SKILLS_LOCAL_DIR="${SKILLS_LOCAL_DIR:-$HOME/.claude/skills}"
ZOOM_CREDENTIALS_DIR="${ZOOM_CREDENTIALS_DIR:-$HOME/.zoom_credentials}"
PRESENTATIONS_DIR="${PRESENTATIONS_DIR:-$HOME/ai_projects/claude-code-lab}"
GITHUB_REPO="${GITHUB_REPO:-glebis/agency-docs}"
SITE_DOMAIN="${SITE_DOMAIN:-agency-lab.glebkalinin.com}"
ステップ 1: Fathom トランスクリプトの検索
LAB_FILTER が設定されている場合: ${VAULT_DIR}/${DATE}-claude-code-lab-${LAB_FILTER}.md
空の場合: glob ${VAULT_DIR}/${DATE}-claude-code-lab-*.md(mtime で最新を選択)
見つからない場合: ${SKILLS_LOCAL_DIR}/calendar-sync/sync.sh を実行し、再確認、それでも見つからなければ停止。
YAML フロントマターから抽出して保存:
FATHOM_FILE、SHARE_URL、MEETING_TITLE、DATE、LAB_NUMBERVIDEO_NAME=${DATE}-claude-code-lab-${LAB_NUMBER}TRANSCRIPT_LANG= 最初の約50行から自動検出(キリル文字の比率 > 0.3 ならru、それ以外はen)
MEETING_NUMBER の決定: ${DOCS_SITE_DIR}/content/docs/claude-code-internal-${LAB_NUMBER}/meetings/ に本日の日付のプレースホルダーが存在するか確認します。存在する場合はその番号を使用します。それ以外の場合は、ファイルの内容サイズから次に空いているスロットを探します。ゼロ埋め2桁の文字列として保存します(例: 04)。この変数はステップ 3b、4b、5、6、8 で使用されます。
ステップ 2: 動画のダウンロード
${VAULT_DIR}/${VIDEO_NAME}.mp4 が存在し、1MB 以上ある場合はスキップします。
注意: Zoom の録画は、ミーティング終了後、処理に約15分かかる場合があります。Zoom API が録画を返さない場合は、待機してから再試行し、その後 Fathom にフォールバックします。
プライマリ — Zoom:
python3 ${SKILLS_REPO_DIR}/zoom/scripts/zoom_meetings.py recordings \
--start ${DATE:0:4}-${DATE:4:2}-${DATE:6:2} \
--end $(date -j -v+1d -f %Y%m%d ${DATE} +%Y-%m-%d) \
--show-downloads 2>&1
MP4 URL を見つけて、次を実行:
TOK=$(python3 -c "import json,pathlib; print(json.load(open(pathlib.Path('${ZOOM_CREDENTIALS_DIR}')/'oauth_token.json'))['access_token'])")
curl -L -H "Authorization: Bearer ${TOK}" -o ${VAULT_DIR}/${VIDEO_NAME}.mp4 "${MP4_DOWNLOAD_URL}"
フォールバック — Fathom(Zoom 録画がない場合):
cd ${VAULT_DIR} && python3 ${SKILLS_LOCAL_DIR}/fathom/scripts/download_video.py \
"${SHARE_URL}" --output-name "${VIDEO_NAME}"
ステップ 3: YouTube にアップロード
cd ${YOUTUBE_UPLOADER_DIR} && \
python3 process_video.py \
--video ${VAULT_DIR}/${VIDEO_NAME}.mp4 \
--fathom-transcript ${FATHOM_FILE} \
--title "${MEETING_TITLE}" \
--upload
run_in_background: true で実行(10〜30分)。失敗した場合: --resume-from upload。
標準出力(✓ YouTube video: ...)または processed/metadata/${VIDEO_NAME}.json から YOUTUBE_URL を抽出します。
VIDEO_ID を URL(?v= の後ろ、または最後のパスセグメント)から抽出します。
ステップ 3a: アップロードの確認(必須)
VIDEO_ID を抽出した後、先に進む前に動画が実際に YouTube に存在することを確認してください。動画は処理中にサイレントで失敗したり、YouTube のコンテンツレビューによって自動削除されたりする可能性があります。
cd ${YOUTUBE_UPLOADER_DIR} && PYTHONPATH=. python3 -c "
from auth import get_authenticated_service
import sys, time
youtube = get_authenticated_service()
video_id = '${VIDEO_ID}'
# Poll up to 5 minutes for video to become available
for attempt in range(10):
resp = youtube.videos().list(part='status,processingDetails', id=video_id).execute()
if not resp['items']:
if attempt < 9:
print(f'Video not yet available (attempt {attempt+1}/10), waiting 30s...')
time.sleep(30)
continue
print(f'FATAL: Video {video_id} not found after 5 minutes. Upload may have failed.')
sys.exit(1)
status = resp['items'][0]['status']
processing = resp['items'][0].get('processingDetails', {})
upload_status = status.get('uploadStatus', 'unknown')
privacy = status.get('privacyStatus', 'unknown')
rejection = status.get('rejectionReason', None)
print(f'Upload status: {upload_status}, Privacy: {privacy}')
if rejection:
print(f'REJECTED: {rejection}')
sys.exit(1)
if upload_status in ('processed', 'uploaded'):
print(f'✓ Video {video_id} verified OK')
sys.exit(0)
if upload_status == 'failed':
print(f'FATAL: Upload failed — {status.get(\"failureReason\", \"unknown\")}')
sys.exit(1)
print(f'Status: {upload_status}, waiting 30s...')
time.sleep(30)
print('FATAL: Video not ready after 5 minutes')
sys.exit(1)
"
確認に失敗した場合: 失敗した動画のメタデータを削除し (rm processed/metadata/${VIDEO_NAME}.json)、--resume-from upload で再アップロードし、再確認します。未確認の VIDEO_ID で MDX またはサムネイルのステップに進まないでください。
ステップ 4 を並行して開始 — サマリーは YouTube URL に依存しません。
ステップ 3b: ラボスタイルのサムネイル(必須)
このステップは常に実行 — process_video.py の汎用サムネイルをブランド化されたラボテンプレートに置き換えます。汎用サムネイルは公開には適していません。
前提条件: VIDEO_ID が既知である必要があります(必要に応じてステップ 3 の完了を待ちます)。
完全なワークフローについては references/thumbnail-guide.md に従ってください:
- Nano Banana オーバーレイ画像を生成する(ガイドのプロンプトパターンからトピック固有のプロンプト)
- 生の画像を読み取り/検査して背景色を確認し、線の色をオレンジ (#e85d04) に変更する
${YOUTUBE_UPLOADER_DIR}/templates/images/lab-meeting.htmlに基づいて 一時的な HTML ファイル(例:/tmp/lab-meeting-${MEETING_NUMBER}.html)を書き込む — ミーティング番号、トピックのヒーローテキスト、箇条書きの説明、日付を更新します。元のテンプレートを直接編集しないでください。- Playwright で 1280×720 でレンダリング →
${YOUTUBE_UPLOADER_DIR}/processed/thumbnails/${VIDEO_NAME}.jpg - レンダリングされたサムネイルを読み取り/検査して、アップロード前にレイアウトを確認する
- YouTube にアップロード: ステップ 3 で抽出した
VIDEO_IDを使用します
このステップをスキップしたり、process_video.py のサムネイルに依存したりしないでください。
ステップ 4: ファクトチェック済みサマリーの生成
${FATHOM_FILE} を読み取ります。${TRANSCRIPT_LANG} で構造化されたサマリーを生成します:
##セクションヘッダー、箇条書き、関連するコード例- 技術用語は英語のまま(MCP、Skills、Claude Code など)
- 個人的なスケジュール詳細は除外
- MDX 用にサニタイズ:
<、>、および MDX コンパイルを壊す生の{文字をエスケープします
claude-code-guide サブエージェントを使用して Claude Code の機能の主張をファクトチェックします(利用可能な場合。エージェントにアクセスできない場合はファクトチェックをスキップします)。修正されたサマリーをスクラッチパッドに summary.md として保存します。
ステップ 4b: YouTube メタデータの更新
ステップ 3 とステップ 4 の両方が完了した後。 このステップの前に VIDEO_ID、MEETING_NUMBER、LAB_NUMBER がすべて決定されている必要があります。説明の形式と API スニペットについては references/youtube-api.md を参照してください。
サマリーから YouTube の説明を生成します。言語に適したテンプレートを使用します:
TRANSCRIPT_LANG=enの場合: 英語のラベル("In this video:"、"Course materials and session notes:")TRANSCRIPT_LANG=ruの場合: ロシア語のラベル("В этом видео:"、"Материалы и конспект занятия:")
1 つの説明内で言語を混在させないでください。
ミーティングページの URL: https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER}
YouTube API を介してタイトル、説明、タグを更新し、動画をプレイリスト「Claude Code Lab ${LAB_NUMBER}」に追加します(存在しない場合は自動的に作成されます)。
ステップ 5: MDX の生成
python3 ${SKILLS_LOCAL_DIR}/agency-docs-updater/scripts/update_meeting_doc.py \
${FATHOM_FILE} "${YOUTUBE_URL}" ${SCRATCHPAD}/summary.md
実行前: meetings/ 内に本日の日付のプレースホルダー MDX がすでに存在するか確認します(grep -l)。存在する場合、それをターゲットにするために -n ${MEETING_NUMBER} --update を使用します。
実行後:
- 追加された Marp コンテンツ(サマリーの最後の
---から<!-- _class: lead -->までの部分)を削除します — MDX は HTML コメント (<!-- -->)、エスケープされていない<、および生の{文字で壊れます - プレゼンテーションファイルを確認します:
${PRESENTATIONS_DIR}/presentations/lab-${LAB_NUMBER}/と${PRESENTATIONS_DIR}/lesson-generator/で${DATE}に一致するファイルを探します。見つかった場合、${DOCS_SITE_DIR}/public/${DATE}-claude-code-lab-${LAB_NUMBER}.htmlにコピーし、MDX にリンクを追加します - フロントマターのプレースホルダー(
[Название встречи]、[Краткое описание встречи]、[Дата встречи])を置き換えます TRANSCRIPT_LANG=enの場合、MDX 全体を英語のラベルで書き換えます — スクリプトはデフォルトでロシア語になり、翻訳フォールバックは壊れた混合言語出力を生成します- 確認:
cd ${DOCS_SITE_DIR} && npm run build 2>&1 | tail -5
ステップ 6: コミットとプッシュ
パイプラインファイルのみをステージング — 決して git add . しないでください:
cd ${DOCS_SITE_DIR}
git fetch origin main
BEHIND=$(git rev-list --count HEAD..origin/main)
if [ "$BEHIND" -gt 0 ]; then
git stash push -m "agency-docs-updater: temp stash"
git pull --rebase origin main
git stash pop || true
fi
git add content/docs/claude-code-internal-${LAB_NUMBER}/meetings/${MEETING_NUMBER}.mdx
# プレゼンテーション HTML がコピーされた場合のみステージング
[ -f public/${DATE}-claude-code-lab-${LAB_NUMBER}.html ] && git add public/${DATE}-claude-code-lab-${LAB_NUMBER}.html
git commit -m "Add Lab ${LAB_NUMBER} Meeting ${MEETING_NUMBER}"
git push
COMMIT_HASH=$(git rev-parse HEAD) をステップ 7 のために保存します。
ステップ 7: Vercel デプロイの待機
TIMEOUT=300; ELAPSED=0
until [ "$(gh api repos/${GITHUB_REPO}/commits/${COMMIT_HASH}/status --jq '.state' 2>/dev/null || echo 'pending')" != "pending" ]; do
sleep 15; ELAPSED=$((ELAPSED+15))
[ "$ELAPSED" -ge "$TIMEOUT" ] && echo "Deploy timeout after ${TIMEOUT}s" && break
done
DEPLOY_STATE=$(gh api repos/${GITHUB_REPO}/commits/${COMMIT_HASH}/status --jq '.state')
echo "Deploy state: ${DEPLOY_STATE}"
run_in_background: true で実行します。状態が failure または error の場合: Vercel ログを確認し (vercel logs)、ローカルで修正し、再プッシュし、このステップを再開します。
ステップ 8: ブラウザでの確認
ブラウザで https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER} を開きます(Chrome 自動化ツールまたは手動で)。YouTube 埋め込みが表示されることを確認します。表示されない場合: VIDEO_ID を確認し、YouTube の処理を待つか、再アップロードします。
パイプラインレポート
完了後、報告: Fathom パス、ビデオパス、YouTube URL、MDX パス、コミットハッシュ、デプロイステータス、埋め込み確認。