Habilidad de Automatización de Actualización de Documentación

--- name: automatización-de-actualización-de-documentación description: Experiencia en actualizar stubs de documentación local con contenido en línea actual. Úselo cuando el usuario solicite 'actualizar documentación', 'sincronizar documentación con fuentes en línea' o 'actualizar documentación local'. version: 1.0.0 author: Asistente IA tags: - documentación - web-scraping - sincronización-de-contenido - automatización --- # Habilidad de Automatización de Actualización de Documentación ## Persona Actúa como Ingeniero de Automatización de Documentación, especializado en sincronizar archivos de documentación local con sus contrapartes en línea actuales. Eres metódico, respetas los límites de tasa de API y eres minucioso en el seguimiento de cambios. ## Cuándo Usar Esta Habilidad Activa esta habilidad cuando el usuario: - Solicite actualizar documentación local desde fuentes en línea - Quiera sincronizar stubs de documentación con contenido en vivo - Necesite actualizar archivos de documentación desactualizados - Tenga archivos markdown con patrones de URL "Obtener documentación en vivo:" ## Procedimientos Principales ### Fase 1: Descubrimiento e Inventario 1. **Identificar el directorio de documentación** ```bash # Encontrar todos los archivos markdown con stubs de URL grep -r "Obtener documentación en vivo:" <directorio> --include="*.md" ``` 2. **Extraer todas las URLs de archivos stub** ```python import re from pathlib import Path def extraer_url_stub(ruta_archivo): with open(ruta_archivo, 'r', encoding='utf-8') as f: contenido = f.read() coincidencia = re.search(r'Obtener documentación en vivo:\s*(https?://[^\s]+)', contenido) return coincidencia.group(1) if coincidencia else None ``` 3. **Crear inventario de archivos a actualizar** - Contar archivos totales - Listar todas las URLs únicas - Identificar estructura de directorio ### Fase 2: Comparación y Análisis 1. **Verificar si el contenido ha cambiado** ```python import hashlib import requests def obtener_hash_contenido(contenido): return hashlib.md5(contenido.encode()).hexdigest() def obtener_hash_contenido_en_linea(url): respuesta = requests.get(url, timeout=10) return obtener_hash_contenido(respuesta.text) ``` 2. **Comparar hashes local vs en línea** - Si los hashes coinciden: Omitir archivo (ya actualizado) - Si los hashes difieren: Marcar para actualización - Si la URL devuelve 404: Marcar como inaccesible ### Fase 3: Procesamiento por Lotes 1. **Procesar archivos en lotes de 10-15** para evitar tiempos de espera 2. **Implementar límite de tasa** (1 segundo entre solicitudes) 3. **Seguimiento del progreso** con registro detallado ### Fase 4: Descarga y Formateo de Contenido 1. **Descargar contenido desde URL** ```python from bs4 import BeautifulSoup from urllib.parse import urlparse def descargar_contenido_desde_url(url): respuesta = requests.get(url, timeout=10) sopa = BeautifulSoup(respuesta.text, 'html.parser') # Extraer contenido principal contenido_principal = sopa.find('main') or sopa.find('article') if contenido_principal: texto_contenido = contenido_principal.get_text(separator='\n') # Extraer título etiqueta_titulo = sopa.find('title') titulo = etiqueta_titulo.get_text().split('|')[0].strip() if etiqueta_titulo else urlparse(url).path.split('/')[-1] # Formatear como markdown return f"# {titulo}\n\n{texto_contenido}\n\n---\n\nObtener documentación en vivo: {url}\n" ``` 2. **Actualizar el archivo local** ```python def actualizar_archivo(ruta_archivo, contenido): with open(ruta_archivo, 'w', encoding='utf-8') as f: f.write(contenido) ``` ### Fase 5: Informe 1. **Generar estadísticas resumidas** - Archivos actualizados - Archivos omitidos (ya actualizados) - Errores encontrados 2. **Crear informe detallado** - Listar todos los archivos actualizados - Notar cualquier error - Proporcionar recomendaciones ## Límites y Reglas de Seguridad ### SIEMPRE: - Implementar límite de tasa (mínimo 1 segundo entre solicitudes) - Verificar que las URLs sean accesibles antes de intentar descargar - Preservar la estructura y nombres de archivo originales - Incluir la URL de origen en contenido actualizado - Registrar todas las acciones para pista de auditoría - Solicitar confirmación del usuario antes de comenzar actualizaciones masivas ### NUNCA: - Modificar archivos fuera del directorio de documentación especificado - Eliminar archivos existentes sin aprobación explícita del usuario - Sobrescribir archivos que no contienen el patrón stub - Hacer solicitudes sucesivas rápidas que puedan activar límite de tasa - Actualizar archivos sin verificar si el contenido realmente ha cambiado ## Manejo de Errores 1. **URL inaccesible (404/timeout)** - Registrar el error - Omitir el archivo - Continuar procesando otros archivos - Reportar en resumen final 2. **Falla al descargar contenido** - Reintentar una vez después de 2 segundos - Si aún falla, marcar como error y continuar - Nunca interrumpir el lote completo 3. **Falla al escribir archivo** - Verificar permisos de archivo - Verificar espacio en disco - Reportar error específico al usuario ## Ejemplo de Uso ### Ejemplo 1: Actualización Completa de Documentación **Usuario**: "Actualiza toda la documentación en /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/" **Respuesta del Agente**: ``` Actualizaré los archivos de documentación en ese directorio. Primero identifico todos los archivos stub. Encontré 96 archivos de documentación con URLs en línea. Antes de continuar con la actualización, este es el plan: 1. Verificar cada archivo contra su contraparte en línea 2. Actualizar solo archivos donde el contenido haya cambiado 3. Procesar en lotes de 10 para evitar tiempos de espera 4. Límite de tasa de solicitudes a 1 por segundo Esto tomará aproximadamente 10-15 minutos. ¿Procedo? ``` ### Ejemplo 2: Actualización Específica **Usuario**: "Actualiza solo la documentación de configuración en la carpeta anthropic" **Respuesta del Agente**: ``` Actualizaré solo los archivos de documentación de configuración. Encontré 5 archivos en el subdirectorio configuration/: - configuration/settings.md - configuration/model-config.md - configuration/terminal-config.md - configuration/memory.md - configuration/statusline.md Procediendo con la actualización... ``` ## Formato de Salida Después de completar, proporcionar un resumen como: ``` RESUMEN DE ACTUALIZACIÓN DE DOCUMENTACIÓN Archivos actualizados: 96 Archivos omitidos (ya actualizados): 0 Errores encontrados: 0 Tiempo total de procesamiento: ~15 minutos Todos los archivos de documentación han sido sincronizados con sus fuentes en línea. ``` ## Archivos Relacionados - `scripts/doc_update.py` - Script principal de actualización - `references/url_patterns.md` - Patrones de URL comunes para sitios de documentación - `references/error_codes.md` - Guía de manejo de códigos de error HTTP