Eine lokale CLI bauen, die Dokumente nach Stichwort und Bedeutung durchsucht

## Eine Laufzeitumgebung festlegen und jeder Befehlsgruppe eine klare Aufgabe geben Wählen Sie genau eine unterstützte Laufzeitumgebung und Paketverwaltung als verbindlichen Entwicklungsweg. Mischen Sie keine Ersatzlaufzeiten oder Installationsbefehle, nur weil sie miteinander vereinbar erscheinen. Halten Sie die Zuständigkeiten der Befehle eindeutig: - Sammlungsbefehle verwalten indexierte Stammverzeichnisse und deren Einstellungen; - Kontextbefehle verknüpfen Suchhinweise mit Pfaden; - Abrufbefehle liefern bekannte Dokumente; - Suchbefehle ordnen mögliche Dokumente nach ihrer Eignung; - Wartungsbefehle prüfen oder aktualisieren den Index; - Dienstbefehle stellen dieselben Funktionen anderen Prozessen bereit. Behalten Sie das installierte Befehlsstartskript bei, wenn es kompilierten Anwendungscode aufruft. Erstellen Sie den Quellcode mit dem dokumentierten Kompilierungsablauf; ersetzen Sie das Startskript nicht durch ein einzelnes kompiliertes Programm, wenn systemnahe Erweiterungen von der vorhandenen Anordnung abhängen. ## Die Einstellungen jeder Sammlung festhalten und Ausschließen von Entfernen trennen Beschreiben Sie jede Sammlung durch einen eindeutigen Namen, ein Quellstammverzeichnis, eine Dateimaske, einen Einbeziehungsstatus und einen optionalen Vorlaufbefehl für Aktualisierungen. Unterstützen Sie das Hinzufügen, Auflisten, Prüfen, Umbenennen, Einbeziehen, Ausschließen und Entfernen von Sammlungen. Unterscheiden Sie Entfernen und Ausschließen: Beim Entfernen wird die Registrierung der Sammlung gelöscht, beim Ausschließen wird sie nur in Abfragen ohne Bereichsangabe ausgelassen. Ermöglichen Sie das Auflisten der Dateien einer vollständigen Sammlung oder eines Pfadpräfixes. Akzeptieren Sie sowohl gewöhnliche Sammlungspfade als auch die virtuelle Sammlungs-URI des Werkzeugs, sofern die Schnittstelle dies unterstützt. Behandeln Sie Hinzufügen, Entfernen, Umbenennen, Änderungen an Vorlaufbefehlen, Änderungen am Einbeziehungsstatus und Indexaktualisierungen als Zustandsänderungen. Wenn eine Genehmigung des Benutzers erforderlich ist, zeigen Sie vor der Ausführung den genauen Befehl und die erwartete Wirkung. ## Suchhinweise (Kontext) an Pfade hängen, getrennt vom Dokumenttext Speichern Sie von Menschen verfassten Kontext getrennt vom Dokumentinhalt, damit sich Hinweise für die Rangfolge weiterentwickeln können, ohne Quelldateien umzuschreiben. Erlauben Sie Kontext an folgenden Stellen: - im aktuellen Verzeichnis, das innerhalb einer Sammlung erkannt wurde; - in einem bestimmten Unterpfad; - in einem virtuellen Sammlungspfad; - im globalen Stammverzeichnis für Hinweise, die für alle Sammlungen gelten. Stellen Sie Befehle bereit, um Kontext aufzulisten, Pfade ohne Kontext zu erkennen und veralteten Kontext zu entfernen. Wenden Sie den einschlägigen Kontext mit dem engsten Geltungsbereich an und behalten Sie zugleich die globalen Hinweise bei. Verwechseln Sie Kontextmetadaten nicht mit indexiertem Dokumenttext. Machen Sie den Geltungsbereich sichtbar, damit ein lokaler Hinweis nicht unbemerkt sachfremde Sammlungen beeinflusst. ## Jedem Dokument eine kurze ID geben und die Rückgabemenge begrenzen Weisen Sie jedem Dokument eine kurze Kennung zu, die aus den ersten 6 Zeichen seines Inhaltshashs abgeleitet wird. Zeigen Sie die Kennung in Suchergebnissen an und akzeptieren Sie sie mit oder ohne vorangestelltes Kennzeichen. Unterstützen Sie den Abruf über Pfad oder Kennung, eine wahlweise angegebene Startzeile und Zeilenanzahl sowie den Sammelabruf über ein Glob-Muster oder eine durch Kommas getrennte Liste. Begrenzen Sie den Abruf ausdrücklich: - legen Sie eine Höchstzahl von Zeilen je Datei fest; - legen Sie eine maximale Bytezahl fest und dokumentieren Sie den Vorgabewert, beispielsweise 10 KB; - überspringen Sie zu große Dateien, anstatt unbemerkt nur einen Teil ihres Inhalts zurückzugeben; - fügen Sie Zeilennummern standardmäßig hinzu und ermöglichen Sie deren Abschaltung; - geben Sie vollständige Pfade auf dem Datenträger nur auf Anforderung zurück. ## Die Suchart passend zur Anfrage wählen, standardmäßig die hybride Suche Bieten Sie drei klar getrennte Suchwege an: - Stichwortsuche mit einer Volltextrangfolge wie BM25, ohne Sprachmodell; - Vektorähnlichkeitssuche mit lokalen Einbettungen, ohne Neusortierung; - erweiterte hybride Abfragesuche mit Abfrageerweiterung und Neusortierung als qualitativ beste Vorgabe. Führen Sie unabhängig geordnete Ergebnismengen durch reziproke Rangfusion zusammen. Halten Sie die ursprünglichen Wertungen und die Suchart hinreichend sichtbar, damit sich unerwartete Reihenfolgen untersuchen lassen. Bevorzugen Sie für allgemeine Zwecke den hybriden Abfrageweg. Wählen Sie die Stichwortsuche, wenn genaue Begriffe wichtig sind, die Vektorsuche, wenn semantische Ähnlichkeit das Ziel ist, und eine Variante ohne Neusortierung, wenn Geschwindigkeit wichtiger als die endgültige Güte der Reihenfolge ist. ## Sammlungen und Ausgabeformate wählbar machen, ohne die Ergebnisse zu verändern Ermöglichen Sie die wiederholte Angabe von Sammlungsfiltern, um mehrere benannte Sammlungen zu durchsuchen und alle anderen auszuschließen. Unterstützen Sie eine Ergebnisanzahl, einen Modus für alle Ergebnisse, eine Mindestwertung, einen Modus für vollständige Inhalte und eine Beschreibung der Absicht, welche die Rangfolge schärft. Trennen Sie Darstellung und Datenübertragung. Bieten Sie ein gut lesbares Befehlszeilenformat sowie strukturierte Ausgaben als JSON, CSV, Markdown, XML und Dateiliste an. Behalten Sie ältere Formatschalter nur als gleichbedeutende Verweise auf eine einzige verbindliche Formatoption bei. Stellen Sie beim Sammelabruf Zeilengrenzen, Bytegrenzen und die Steuerung der Zeilennummern unabhängig von der Suchrangfolge bereit. Eine Darstellungsoption darf nicht verändern, welche Dokumente ausgewählt werden. ## Den Suchindex erstellen und Dokumente in vorhersehbare Abschnitte aufteilen Verwenden Sie eine dauerhafte lokale Datenbank für die Volltextindexierung und eine dazu passende Vektorerweiterung für semantische Ähnlichkeit. Führen Sie Einbettungen, Neusortierung und Abfrageerweiterung mit eingerichteten lokalen Modellen aus. Teilen Sie Dokumente intelligent in Abschnitte mit einer Zielgröße von 900 Token pro Abschnitt und 15 % Überlappung. Bevorzugen Sie nach Möglichkeit Markdown-Überschriften als Grenzen. Stellen Sie für unterstützte Quellcodedateien eine syntaxbaumgestützte Vorgehensweise bereit, damit Abschnitte an den Grenzen von Funktionen, Klassen und Importen ausgerichtet werden. Wählen Sie diese Vorgehensweise durch eine ausdrücklich angegebene Automatik. Behalten Sie die Aufteilung anhand regulärer Ausdrücke als Vorgabe bei und verwenden Sie sie einheitlich für Markdown und unbekannte Dateitypen. Halten Sie Indexierung, Erzeugung der Einbettungen und Rangbildung bei der Abfrage als getrennte Stufen, damit sich Fehler untersuchen lassen, ohne alles neu aufzubauen. ## Vor dem Anpassen der Rangfolge den Zustand von Index und Modellen prüfen Geben Sie Zustandsinformationen aus, die den Zustand von Sammlungen und Index ohne Zustandsänderung zeigen. Ergänzen Sie einen Diagnosebefehl für Probleme mit Einstellungen, Index, Modell und Gerät. Messen Sie die Suchgüte mit versionierten Prüfdaten. Erfassen Sie die Abfrage, die erwarteten einschlägigen Dokumente, die Suchart, Kennzahlen der Rangfolge, die Modelleinstellungen und die Indexversion, damit Vergleiche reproduzierbar bleiben. Führen Sie Diagnosen durch, bevor Sie Gewichtungen der Rangfolge, Modelle oder Geräteeinstellungen ändern. Ein fehlendes Modell, ein veralteter Index, eine unverträgliche Vektorerweiterung oder ein nicht verfügbares Gerät beweisen für sich genommen nicht, dass der Rangfolgealgorithmus fehlerhaft ist. ## Das Werkzeug nur auf Anfrage als lokalen oder HTTP-Dienst starten Bieten Sie für die Einbindung lokaler Prozesse einen Dienst für Standardein- und -ausgabe und für entfernte Gegenstellen wahlweise einen HTTP-Dienst an. Verwenden Sie einen dokumentierten Standardport wie 8181 und erlauben Sie eine ausdrückliche Überschreibung. Unterstützen Sie den Vordergrundbetrieb zur Fehlersuche und einen Hintergrunddienstmodus für den dauerhaften Einsatz. Stellen Sie einen passenden Stoppbefehl bereit, der ausschließlich den verwalteten Hintergrunddienst beendet. Trennen Sie die Dienstübertragung von der Bedeutung der Suche. Befehlszeilen- und Dienstschnittstelle sollen dieselben Regeln für Sammlungen, Kontext, Abruf, Rangfolge und Ausgabe verwenden. Starten Sie einen Hintergrunddienst nicht stillschweigend. Geben Sie beim Start eines Dienstes Endpunkt, Prozessmodus, Einstellungsquelle und Abschaltverfahren an. ## Indexänderungen dem Benutzer überlassen und das installierte Startskript nicht beschädigen Fügen Sie niemals automatisch eine Sammlung hinzu, erzeugen Sie niemals automatisch Einbettungen und aktualisieren Sie niemals automatisch Indizes. Ändern Sie die zugrunde liegende Suchdatenbank niemals unmittelbar. Wenn ein angeforderter Arbeitsablauf eine dieser Änderungen erfordert, zeigen Sie den genauen Befehl zur Ausführung durch den Benutzer und erläutern Sie die erwarteten Dateien, die Dauer und den Ressourcenbedarf. Halten Sie Suche und Abruf im Nur-Lese-Betrieb verfügbar, ohne die Berechtigung auszuweiten. Führen Sie keinen Kompilierungsmodus aus, der das installierte Befehlszeilen-Startskript überschreibt oder systemnahe Vektorerweiterungen unbrauchbar macht. Ersetzen Sie kein Startskript, das absichtlich kompiliertes JavaScript aus einem Verteilungsverzeichnis startet. Behandeln Sie Vorlaufbefehle für Aktualisierungen als ausführbare Einstellungen. Zeigen Sie sie bei der Prüfung an und führen Sie sie nur im Rahmen einer ausdrücklich angeforderten Indexaktualisierung aus. ## Regressionstests ergänzen und mit Änderungsprotokoll veröffentlichen Bewahren Sie automatisierte Prüfungen im vorgesehenen Prüfbaum auf und führen Sie die dokumentierten vollständigen Prüfreihen mit der unterstützten Laufzeitumgebung aus. Ergänzen Sie gezielte Prüfungen gegen Rückfälle für Sammlungszustand, Abrufgrenzen, Rangfolgeverfahren, Abschnittsgrenzen und den Lebenszyklus des Dienstes. Verwenden Sie den verbindlichen Veröffentlichungsablauf, statt eine Veröffentlichung von Hand zusammenzustellen: 1. ergänzen Sie während der Änderungen Einträge im Änderungsprotokoll unter dem Abschnitt für unveröffentlichte Änderungen; 2. wandeln Sie diesen Abschnitt bei der Veröffentlichung in eine datierte Version um; 3. nennen Sie externe Beiträge im vom Vorhaben vorgeschriebenen Verweisformat; 4. fassen Sie die Veröffentlichungshinweise über die vorgesehene Versionsreihe hinweg zusammen; 5. führen Sie die Vorlaufbefehle für die Veröffentlichung und die Prüfung vor der Veröffentlichung aus. Berichten Sie über die geänderte Funktionsweise, die Verträglichkeit von Index oder Datenschema, ausgeführte Prüfungen, Auswirkungen auf den Leistungsvergleich, erforderliche Umstellungen und alle zustandsändernden Befehle, deren Ausführung dem Benutzer überlassen bleibt.