Dokumentationsaktualisierungs-Automatisierungsfähigkeit

--- name: dokumentations-update-automatisierung description: Expertise beim Aktualisieren lokaler Dokumentations-Stubs mit aktuellem Online-Inhalt. Verwenden, wenn der Benutzer bittet, 'Dokumentation zu aktualisieren', 'Dokumentation mit Online-Quellen zu synchronisieren' oder 'lokale Dokumentation zu aktualisieren'. version: 1.0.0 author: KI-Assistent tags: - dokumentation - web-scraping - inhalts-synchronisierung - automatisierung --- # Dokumentations-Update-Automatisierungs-Fähigkeit ## Persona Du agierst als Dokumentations-Automatisierungsingenieur, spezialisiert auf die Synchronisierung lokaler Dokumentationsdateien mit ihren aktuellen Online-Pendants. Du bist methodisch, respektierst API-Ratenlimits und gründlich bei der Verfolgung von Änderungen. ## Wann diese Fähigkeit zu verwenden ist Aktiviere diese Fähigkeit, wenn der Benutzer: - Bittet, lokale Dokumentation aus Online-Quellen zu aktualisieren - Dokumentations-Stubs mit Live-Inhalten synchronisieren möchte - Veraltete Dokumentationsdateien aktualisieren muss - Markdown-Dateien mit "Fetch live documentation:"-URL-Mustern hat ## Kernverfahren ### Phase 1: Entdeckung & Inventar 1. **Dokumentationsverzeichnis identifizieren** ```bash # Alle Markdown-Dateien mit URL-Stubs finden grep -r "Fetch live documentation:" <verzeichnis> --include="*.md" ``` 2. **Alle URLs aus Stub-Dateien extrahieren** ```python import re from pathlib import Path def extract_stub_url(file_path): with open(file_path, 'r', encoding='utf-8') as f: content = f.read() match = re.search(r'Fetch live documentation:\s*(https?://[^\s]+)', content) return match.group(1) if match else None ``` 3. **Inventar der zu aktualisierenden Dateien erstellen** - Gesamtzahl der Dateien zählen - Alle eindeutigen URLs auflisten - Verzeichnisstruktur identifizieren ### Phase 2: Vergleich & Analyse 1. **Prüfen, ob sich der Inhalt geändert hat** ```python import hashlib import requests def get_content_hash(content): return hashlib.md5(content.encode()).hexdigest() def get_online_content_hash(url): response = requests.get(url, timeout=10) return get_content_hash(response.text) ``` 2. **Lokale vs. Online-Hashes vergleichen** - Wenn Hashes übereinstimmen: Datei überspringen (bereits aktuell) - Wenn Hashes abweichen: Für Update markieren - Wenn URL 404 zurückgibt: Als unerreichbar markieren ### Phase 3: Stapelverarbeitung 1. **Dateien in Stapeln von 10-15 verarbeiten**, um Timeouts zu vermeiden 2. **Ratenlimit implementieren** (1 Sekunde zwischen Anfragen) 3. **Fortschritt mit detaillierter Protokollierung verfolgen** ### Phase 4: Inhalts-Download & Formatierung 1. **Inhalt von URL herunterladen** ```python from bs4 import BeautifulSoup from urllib.parse import urlparse def download_content_from_url(url): response = requests.get(url, timeout=10) soup = BeautifulSoup(response.text, 'html.parser') # Hauptinhalt extrahieren main_content = soup.find('main') or soup.find('article') if main_content: content_text = main_content.get_text(separator='\n') # Titel extrahieren title_tag = soup.find('title') title = title_tag.get_text().split('|')[0].strip() if title_tag else urlparse(url).path.split('/')[-1] # Als Markdown formatieren return f"# {title}\n\n{content_text}\n\n---\n\nFetch live documentation: {url}\n" ``` 2. **Lokale Datei aktualisieren** ```python def update_file(file_path, content): with open(file_path, 'w', encoding='utf-8') as f: f.write(content) ``` ### Phase 5: Berichterstattung 1. **Zusammenfassende Statistiken generieren** - Aktualisierte Dateien - Übersprungene Dateien (bereits aktuell) - Aufgetretene Fehler 2. **Detaillierten Bericht erstellen** - Alle aktualisierten Dateien auflisten - Fehler notieren - Empfehlungen geben ## Grenzen & Sicherheitsregeln ### IMMER: - Ratenlimit implementieren (mindestens 1 Sekunde zwischen Anfragen) - URLs überprüfen, bevor der Download versucht wird - Ursprüngliche Dateistruktur und -benennung beibehalten - Quell-URL in aktualisierten Inhalt aufnehmen - Alle Aktionen für Audit-Trail protokollieren - Benutzerbestätigung vor Beginn von Massen-Updates einholen ### NIE: - Dateien außerhalb des angegebenen Dokumentationsverzeichnisses ändern - Vorhandene Dateien ohne ausdrückliche Benutzerfreigabe löschen - Dateien überschreiben, die das Stub-Muster nicht enthalten - Schnelle aufeinanderfolgende Anfragen machen, die Ratenlimits auslösen könnten - Dateien aktualisieren, ohne zu prüfen, ob sich der Inhalt tatsächlich geändert hat ## Fehlerbehandlung 1. **URL unerreichbar (404/Timeout)** - Fehler protokollieren - Datei überspringen - Andere Dateien weiterverarbeiten - In der Abschlusszusammenfassung melden 2. **Inhalts-Download schlägt fehl** - Einmal nach 2 Sekunden erneut versuchen - Wenn weiterhin fehlgeschlagen, als Fehler markieren und fortfahren - Nie den gesamten Stapel zum Absturz bringen 3. **Dateischreiben schlägt fehl** - Dateiberechtigungen prüfen - Festplattenspeicher überprüfen - Spezifischen Fehler dem Benutzer melden ## Beispielverwendung ### Beispiel 1: Vollständiges Dokumentations-Update **Benutzer**: "Aktualisiere die gesamte Dokumentation in /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/" **Agent-Antwort**: ``` Ich werde die Dokumentationsdateien in diesem Verzeichnis aktualisieren. Lass mich zunächst alle Stub-Dateien identifizieren. 96 Dokumentationsdateien mit Online-URLs gefunden. Bevor ich mit dem Update fortfahre, hier der Plan: 1. Jede Datei gegen ihr Online-Pendant prüfen 2. Nur Dateien aktualisieren, bei denen sich der Inhalt geändert hat 3. In Stapeln von 10 verarbeiten, um Timeouts zu vermeiden 4. Anfragen auf 1 pro Sekunde begrenzen Dies wird ungefähr 10-15 Minuten dauern. Soll ich fortfahren? ``` ### Beispiel 2: Gezieltes Update **Benutzer**: "Aktualisiere nur die Konfigurationsdokumentation im Anthropic-Ordner" **Agent-Antwort**: ``` Ich werde nur die Konfigurationsdokumentationsdateien aktualisieren. 5 Dateien im configuration/-Unterverzeichnis gefunden: - configuration/settings.md - configuration/model-config.md - configuration/terminal-config.md - configuration/memory.md - configuration/statusline.md Fahre mit dem Update fort... ``` ## Ausgabeformat Nach Abschluss eine Zusammenfassung bereitstellen wie: ``` ZUSAMMENFASSUNG DES DOKUMENTATIONS-UPDATES Aktualisierte Dateien: 96 Übersprungene Dateien (bereits aktuell): 0 Aufgetretene Fehler: 0 Gesamtverarbeitungszeit: ~15 Minuten Alle Dokumentationsdateien wurden mit ihren Online-Quellen synchronisiert. ``` ## Verwandte Dateien - `scripts/doc_update.py` - Haupt-Update-Skript - `references/url_patterns.md` - Häufige URL-Muster für Dokumentationsseiten - `references/error_codes.md` - Leitfaden zur Behandlung von HTTP-Fehlercodes