Referenz zum Werkzeugsystem

file_read

Fähigkeiten:

• Liest vollständige Dateiinhalte oder bestimmte Zeilenbereiche
• Unverzichtbar, um Code vor Änderungen zu verstehen
• Effiziente Verarbeitung großer Dateien durch Bereichsangabe

Anwendungsfälle:

• Lesen von Konfigurationsdateien vor der Bearbeitung
• Verstehen bestehender Implementierungsmuster
• Überprüfen von Testdateien, um die Testabdeckung zu verstehen

Beispiel:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Fähigkeiten:

• Präzise Textersetzung mittels exakter Zeichenkettenübereinstimmung
• Mehrere Ersetzungsvorgänge mit dem Flag multiple
• Erhält die Dateistruktur und Formatierung

Anwendungsfälle:

• Aktualisieren von Funktionsimplementierungen
• Ändern von Konfigurationswerten
• Umbenennen von Variablen über mehrere Dateien hinweg

Best Practice: Für gezielte Änderungen verwenden. Für vollständige Neuschreibungen file_write stattdessen einsetzen.

file_write

Fähigkeiten:

• Erstellt neue Dateien von Grund auf
• Ersetzt bestehende Dateiinhalte vollständig
• Verarbeitet jedes textbasierte Format

Anwendungsfälle:

• Generieren neuer Komponenten oder Module
• Erstellen von Konfigurationsdateien
• Schreiben von Testdateien

Warnung: Überschreibt bestehende Dateien vollständig. Für teilweise Änderungen file_edit verwenden.

glob

Fähigkeiten:

• Findet Dateien anhand von Mustern: **/*.ts, src/**/*.js
• Filterung nach Verzeichnispfad
• Ausschlussmuster zur Eingrenzung der Ergebnisse
• Steuerung der Ergebnisanzahl

Anwendungsfälle:

• Auffinden aller Komponenten in einem Projekt
• Lokalisieren von Testdateien
• Identifizieren von Konfigurationsdateien über mehrere Verzeichnisse hinweg

Beispielmuster:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Fähigkeiten:

• Durchsucht Dateiinhalte mithilfe von Regex-Mustern
• Zeigt Kontextzeilen vor/nach Treffern (Flags -B, -A)
• Suche ohne Berücksichtigung der Groß-/Kleinschreibung
• Filterung nach Dateityp mittels Glob-Mustern

Anwendungsfälle:

• Auffinden von Funktionsdefinitionen
• Lokalisieren von API-Endpunktimplementierungen
• Suchen nach bestimmten Fehlermeldungen
• Identifizieren von Sicherheitsmustern

Beispiel:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Fähigkeiten:

• Listet Dateien mit Musterübereinstimmungen auf
• Schneller als grep_content, wenn Sie nur Dateipfade benötigen
• Unterstützung für Regex-Muster
• Glob-Filterung nach Dateitypen

Anwendungsfälle:

• Identifizieren, welche Dateien überarbeitet werden müssen
• Auffinden von Dateien, die bestimmte Module importieren
• Lokalisieren von Dateien mit veralteten Mustern

Best Practice: Zunächst grep_file verwenden, um relevante Dateien zu identifizieren, danach file_read für die detaillierte Untersuchung.

list_dir

Fähigkeiten:

• Zeigt die Verzeichnishierarchie an
• Steuerung der Tiefe mit dem Parameter max_depth
• Ausschlussmuster zur Filterung der Ausgabe

Anwendungsfälle:

• Verstehen der Projektstruktur
• Überprüfen der Verzeichnisorganisation
• Auffinden bestimmter Unterverzeichnisse

bash

Fähigkeiten:

• Führt Shell-Befehle aus
• Maximales Timeout: 120 Sekunden (2 Minuten, feste Obergrenze)
• Verkettung von Befehlen mit && bei Abhängigkeiten
• Liefert beschreibende Zusammenfassungen zur Klarheit

Anwendungsfälle:

• Ausführen von Tests
• Erstellen von Projekten (Build)
• Installieren von Abhängigkeiten
• Git-Operationen
• Datenbankmigrationen

Beispiel:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Sicherheit: Befehle werden mit den Berechtigungen des Nutzers ausgeführt. Überprüfen Sie Befehle in Manual Accept Mode.

spawn_subagent

Fähigkeiten:

• Startet spezialisierte Subagenten mit isolierten Kontexten
• Typen: explorer, verifier, code-reviewer
• Delegiert komplexe Aufgaben, ohne den Hauptkontext zu belasten
• Parallele Subagenten-Ausführung für mehr Effizienz

Anwendungsfälle:

• Explorer: Durchsuchen großer Codebasen nach Mustern
• Verifier: Validierung der Implementierungslogik
• Code-reviewer: Sicherheits- und Qualitätsbewertung

Best Practice: Delegieren Sie explorative Recherchen an den Explorer-Subagenten, um den Kontext des Hauptgesprächs zu schonen.

todo_update

Fähigkeiten:

• Erstellt und verwaltet Aufgabenlisten
• Aktualisiert den Aufgabenstatus (ausstehend, in Bearbeitung, abgeschlossen)
• Verfolgt den Fortschritt komplexer Implementierungen

Anwendungsfälle:

• Aufteilen mehrstufiger Funktionen
• Nachverfolgen des Fortschritts bei Refactorings
• Verwalten von Migrationsaufgaben

web_search

Fähigkeiten:

• Abfrage von Internetsuchmaschinen
• Steuerung der Ergebnisanzahl
• Filterung nach Aktualität (letzte Tage)

Anwendungsfälle:

• Auffinden von Dokumentation für unbekannte APIs
• Recherchieren von Fehlermeldungen
• Prüfen aktueller Best Practices

web_fetch

Fähigkeiten:

• Ruft Webseiteninhalte ab
• Analysiert Inhalte anhand bestimmter Abfragen
• Extrahiert strukturierte Informationen

Anwendungsfälle:

• Lesen von Dokumentationsseiten
• Analysieren von API-Dokumentation
• Extrahieren von Beispielen aus Tutorials

Datenformate

Build- und Paketdateien

Effizienz von file_read

Best Practices:

• Verwenden Sie Zeilenbereiche für Dateien mit mehr als 500 Zeilen, um eine Überlastung des Kontexts zu vermeiden
• Lesen Sie nur die für die Aufgabe relevanten Abschnitte
• Bei großen Dateien zunächst grep_content verwenden, um relevante Zeilennummern zu identifizieren

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

Präzision von file_edit

Best Practices:

• Stellen Sie exakte Zeichenkettenübereinstimmungen sicher, um fehlgeschlagene Bearbeitungen zu vermeiden
• Für mehrere ähnliche Änderungen das Flag multiple=true verwenden
• Dateipfade vor der Bearbeitung überprüfen

Sicherheit von file_write

Best Practices:

• Pfade doppelt prüfen, um versehentliches Überschreiben zu verhindern
• Nur für neue Dateien oder vollständige Neuschreibungen verwenden
• Für Änderungen aus Sicherheitsgründen file_edit bevorzugen

Spezifität von glob-Mustern

Best Practices:

• Verwenden Sie spezifische Muster, um den Umfang einzugrenzen: src/**/*.ts anstelle von **/*
• Verzeichnisse mit Ausschlussmustern ausschließen: !**/node_modules/**
• Ergebnisse begrenzen, um eine übermäßige Ausgabe zu vermeiden

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep-Strategie

Empfohlener Arbeitsablauf:

1. grep_file verwenden, um relevante Dateien zu identifizieren
2. Bestimmte Dateien mit file_read lesen
3. grep_content verwenden, wenn Sie den umgebenden Kontext benötigen

Leistungstipps:

• Regex-Muster können länger dauern als literale Zeichenketten
• Suchen ohne Berücksichtigung der Groß-/Kleinschreibung sind langsamer
• Kontextzeilen (-A, -B) auf das Notwendige begrenzen

Best Practices für bash

Sichere Befehlsausführung:

• Klare Zusammenfassungen für Befehlsbeschreibungen liefern
• Angemessene Timeouts für lang laufende Operationen festlegen
• Abhängige Befehle mit && verketten
• Destruktive Befehle sorgfältig prüfen (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Sicherheitsüberlegungen

Kritische Sicherheitsregeln:

• Befehle werden mit den Berechtigungen des Nutzers ausgeführt
• Niemals nicht vertrauenswürdige Befehle ausführen
• Manual Accept Mode für die Überprüfung in gemeinsam genutzten Codebasen verwenden
• Befehle vermeiden, die Zugangsdaten oder sensible Daten offenlegen

Effizienz der Subagenten-Delegation

Wann Subagenten verwendet werden sollten:

• Explorer: Codebasis-Suchen, Architekturfragen (schont den Hauptkontext)
• Verifier: Schnelle Validierungsprüfungen (isolierte Verifikation)
• Code-reviewer: Sicherheits- und Qualitätsprüfungen (detaillierte Analyse)
• General: Komplexe mehrstufige Aufgaben (parallele Ausführung)

Best Practice: Delegieren Sie explorative und recherchierende Aufgaben an Subagenten, um den Kontext des Hauptgesprächs für die aktive Entwicklungsarbeit zu schonen.

Kontextverwaltung

Strategische Werkzeugnutzung:

• Dateien strategisch lesen – nur das, was benötigt wird
• Subagenten für Hintergrundrecherchen verwenden
• Kontextverbrauch während langer Sitzungen überwachen
• Komplexe Vorgänge mit todo_update in Schritte aufteilen

Effiziente Arbeitsabläufe:

1. Planung: glob/grep verwenden, um den Umfang zu bestimmen
2. Lesen: Nur relevante Dateien/Abschnitte lesen
3. Ausführung: Bei Bedarf an Subagenten delegieren
4. Verifikation: Schnelle Prüfungen mit dem Verifier-Subagenten

Dateigrößenbeschränkungen

Umgang mit großen Dateien: Sehr große Dateien (>10.000 Zeilen) sollten abschnittsweise gelesen werden, um Folgendes zu vermeiden:

• Erschöpfung des Kontextfensters
• Langsame Antwortzeiten
• Speicherprobleme

Standard-Timeouts der Werkzeuge

Werkzeuggrenzen:

• Bash-Timeout: maximal 120 Sekunden (2 Minuten)
• Dateioperationen: keine Größenbeschränkungen (große Dateien werden automatisch in Batches gelesen)
• Umgang mit großen Dateien: Dateien >256 KB liefern nur die ersten 256 KB des Inhalts zurück
• Suchergebnisse: keine Begrenzungen bei den Ergebnissen von glob oder grep_content
• Gleichzeitige Subagenten: keine Begrenzung bei der parallelen Ausführung

Timeout-Konfiguration:

• Explizite Timeouts für lang laufende Operationen festlegen
• Auf hängende Prozesse achten
• Befehle, die das 2-Minuten-Timeout überschreiten, werden beendet

Gleichzeitige Operationen

Parallele Ausführung: Mehrere Subagenten können parallel ausgeführt werden, um komplexe Vorgänge zu beschleunigen. Der Hauptagent übernimmt die Koordination automatisch.

Leistungsvorteile:

• Verkürzte Gesamtausführungszeit bei mehrstufigen Aufgaben
• Effiziente Ressourcennutzung
• Automatische Aufgabenorchestrierung
• Keine Begrenzung bei der Anzahl gleichzeitiger Subagenten