Agency Docs Updater – Actualizador de Documentación de Agencia
Ejecuta TODOS los pasos automáticamente en secuencia. Solo detente si un paso falla y no se puede recuperar. Lee references/learnings.md antes de comenzar para conocer los errores conocidos.
Configuración: las rutas se leen desde .env en la raíz de la habilidad (consulta .env.example). Los valores predeterminados funcionan para la configuración estándar. Variables de entorno clave: VAULT_DIR, DOCS_SITE_DIR, YOUTUBE_UPLOADER_DIR, PRESENTATIONS_DIR, SKILLS_REPO_DIR, SKILLS_LOCAL_DIR, ZOOM_CREDENTIALS_DIR, GITHUB_REPO, SITE_DOMAIN.
Dependencias (verifica que existan antes de ejecutar):
- zoom — Descarga de grabaciones de Zoom (
scripts/zoom_meetings.py) - fathom — Video de respaldo de Fathom (
scripts/download_video.py) - nano-banana — Generación de superposición de miniaturas (
scripts/generate_image.sh) - calendar-sync — Solo local, sincronización de eventos de calendario (
sync.sh) - youtube-uploader — Procesamiento de video, subida y autenticación de la API de YouTube
Paso 0: Analizar Argumentos y Cargar Configuración
Carga .env desde la raíz de la habilidad. Luego divide args por espacios en blanco:
- Token de 8 dígitos (
YYYYMMDD) →DATE - "yesterday" →
DATE = $(date -v-1d +%Y%m%d) - "today" o faltante →
DATE = $(date +%Y%m%d) - Token de 2 dígitos (
NN) olab-NN→LAB_FILTER
Expande las variables de entorno para las rutas utilizadas en pasos posteriores:
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}"
Paso 1: Encontrar Transcripción de Fathom
Si LAB_FILTER está definido: ${VAULT_DIR}/${DATE}-claude-code-lab-${LAB_FILTER}.md
Si está vacío: glob ${VAULT_DIR}/${DATE}-claude-code-lab-*.md (elige el más reciente por mtime).
Si falta: ejecuta ${SKILLS_LOCAL_DIR}/calendar-sync/sync.sh, vuelve a verificar, detente si todavía falta.
Extrae del frontmatter YAML y almacena:
FATHOM_FILE,SHARE_URL,MEETING_TITLE,DATE,LAB_NUMBERVIDEO_NAME=${DATE}-claude-code-lab-${LAB_NUMBER}TRANSCRIPT_LANG= detección automática de las primeras ~50 líneas (proporción de cirílico > 0.3 →ru, si noen)
Determinar MEETING_NUMBER: verifica archivos MDX existentes en ${DOCS_SITE_DIR}/content/docs/claude-code-internal-${LAB_NUMBER}/meetings/ en busca de un marcador de posición con la fecha de hoy. Si se encuentra, usa ese número. De lo contrario, verifica los tamaños de contenido de los archivos para encontrar el siguiente espacio vacío. Almacena como una cadena de dos dígitos con relleno de ceros (ej. 04). Esta variable se usa en los Pasos 3b, 4b, 5, 6 y 8.
Paso 2: Descargar Video
Omite si ${VAULT_DIR}/${VIDEO_NAME}.mp4 existe y tiene más de 1 MB.
Nota: Las grabaciones de Zoom pueden tardar ~15 minutos en procesarse después de que finaliza una reunión. Si la API de Zoom no devuelve grabaciones, espera y vuelve a intentar antes de recurrir a Fathom.
Principal — 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
Encuentra la URL del MP4, luego:
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}"
Respaldo — Fathom (si no hay grabación de Zoom):
cd ${VAULT_DIR} && python3 ${SKILLS_LOCAL_DIR}/fathom/scripts/download_video.py \
"${SHARE_URL}" --output-name "${VIDEO_NAME}"
Paso 3: Subir a YouTube
cd ${YOUTUBE_UPLOADER_DIR} && \
python3 process_video.py \
--video ${VAULT_DIR}/${VIDEO_NAME}.mp4 \
--fathom-transcript ${FATHOM_FILE} \
--title "${MEETING_TITLE}" \
--upload
Ejecuta con run_in_background: true (10-30 min). En caso de fallo: --resume-from upload.
Extrae YOUTUBE_URL de stdout (✓ YouTube video: ...) o processed/metadata/${VIDEO_NAME}.json.
Extrae VIDEO_ID de la URL (la parte después de ?v= o el último segmento de la ruta).
Paso 3a: Verificar Subida (OBLIGATORIO)
Después de extraer VIDEO_ID, verifica que el video realmente existe en YouTube antes de continuar. Los videos pueden fallar silenciosamente en el procesamiento o ser eliminados automáticamente por la revisión de contenido de 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)
"
Si la verificación falla: elimina los metadatos del video fallido (rm processed/metadata/${VIDEO_NAME}.json), vuelve a subir con --resume-from upload y vuelve a verificar. NO continúes con los pasos de MDX o miniatura con un VIDEO_ID no verificado.
Inicia el Paso 4 en paralelo — el resumen no depende de la URL de YouTube.
Paso 3b: Miniatura de Estilo Laboratorio (OBLIGATORIO)
Ejecuta este paso siempre — reemplaza la miniatura genérica de process_video.py con la plantilla de laboratorio con marca. La miniatura genérica NO es aceptable para su publicación.
Requisitos previos: VIDEO_ID debe ser conocido (espera a que se complete el Paso 3 si es necesario).
Sigue references/thumbnail-guide.md para el flujo de trabajo completo:
- Genera la imagen de superposición de Nano Banana (mensaje específico del tema a partir de los patrones de mensaje de la guía)
- Lee/inspecciona la imagen sin procesar para confirmar el color de fondo, luego recolorea las líneas a naranja (#e85d04)
- Escribe un archivo HTML temporal (ej.
/tmp/lab-meeting-${MEETING_NUMBER}.html) basado en${YOUTUBE_UPLOADER_DIR}/templates/images/lab-meeting.html— actualiza el número de reunión, el texto principal del tema, las descripciones de los puntos, la fecha. No edites la plantilla original directamente. - Renderiza con Playwright a 1280×720 →
${YOUTUBE_UPLOADER_DIR}/processed/thumbnails/${VIDEO_NAME}.jpg - Lee/inspecciona la miniatura renderizada para verificar el diseño antes de subirla
- Sube a YouTube: usa
VIDEO_IDextraído del Paso 3
NO omitas este paso ni confíes en la miniatura de process_video.py.
Paso 4: Generar Resumen Verificado
Lee ${FATHOM_FILE}. Genera un resumen estructurado en ${TRANSCRIPT_LANG}:
- Encabezados de sección
##, viñetas, ejemplos de código cuando sea relevante - Términos técnicos en inglés (MCP, Skills, Claude Code, etc.)
- Excluye detalles personales de programación
- Sanitiza para MDX: escapa caracteres
<,>y{sin escapar que romperían la compilación de MDX
Verifica las afirmaciones de funciones de Claude Code usando el subagente claude-code-guide (si está disponible; omite la verificación si el agente no es accesible). Guarda el resumen corregido en el bloc de notas como summary.md.
Paso 4b: Actualizar Metadatos de YouTube
Después de que se completen tanto el Paso 3 como el Paso 4. VIDEO_ID, MEETING_NUMBER y LAB_NUMBER deben estar determinados antes de este paso. Lee references/youtube-api.md para conocer el formato de la descripción y fragmentos de la API.
Genera la descripción de YouTube a partir del resumen. Usa la plantilla de idioma apropiada:
- Si
TRANSCRIPT_LANG=en: Etiquetas en inglés ("In this video:", "Course materials and session notes:") - Si
TRANSCRIPT_LANG=ru: Etiquetas en ruso ("В этом видео:", "Материалы и конспект занятия:")
NO mezcles idiomas en una sola descripción.
URL de la página de la reunión: https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER}
Actualiza título, descripción, etiquetas a través de la API de YouTube, luego agrega el video a la lista de reproducción "Claude Code Lab ${LAB_NUMBER}" (se crea automáticamente si no existe).
Paso 5: Generar MDX
python3 ${SKILLS_LOCAL_DIR}/agency-docs-updater/scripts/update_meeting_doc.py \
${FATHOM_FILE} "${YOUTUBE_URL}" ${SCRATCHPAD}/summary.md
Antes de ejecutar: verifica si ya existe un MDX de marcador de posición para la fecha de hoy (grep -l en meetings/). Si es así, usa -n ${MEETING_NUMBER} --update para apuntar a él.
Después de ejecutar:
- Elimina el contenido de Marp agregado (todo después del
---de cierre del resumen antes de<!-- _class: lead -->) — MDX se rompe con comentarios HTML (<!-- -->),<sin escapar y caracteres{sin escapar - Busca el archivo de presentación: busca en
${PRESENTATIONS_DIR}/presentations/lab-${LAB_NUMBER}/y${PRESENTATIONS_DIR}/lesson-generator/archivos que coincidan con${DATE}. Si se encuentra, copia a${DOCS_SITE_DIR}/public/${DATE}-claude-code-lab-${LAB_NUMBER}.htmly agrega enlace en MDX - Reemplaza los marcadores de posición del frontmatter (
[Название встречи],[Краткое описание встречи],[Дата встречи]) - Si
TRANSCRIPT_LANG=en, reescribe el MDX completamente con etiquetas en inglés — el script usa ruso de forma predeterminada y la alternativa de traducción produce resultados de idioma mixto rotos - Verifica:
cd ${DOCS_SITE_DIR} && npm run build 2>&1 | tail -5
Paso 6: Confirmar y Enviar
Solo prepara los archivos del pipeline — nunca 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
# Only stage presentation HTML if it was copied
[ -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
Almacena COMMIT_HASH=$(git rev-parse HEAD) para el Paso 7.
Paso 7: Esperar Despliegue de 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}"
Ejecuta con run_in_background: true. Si el estado es failure o error: revisa los registros de Vercel (vercel logs), corrige localmente, vuelve a enviar, reinicia este paso.
Paso 8: Verificar en el Navegador
Abre https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER} en un navegador (a través de herramientas de automatización de chrome o manualmente). Verifica que el embed de YouTube sea visible. Si no: verifica VIDEO_ID, espera el procesamiento de YouTube o vuelve a subir.
Informe del Pipeline
Después de la finalización, informa: ruta de Fathom, ruta del video, URL de YouTube, ruta de MDX, hash de confirmación, estado del despliegue, verificación del embed.