readme-banner

Was macht readme-banner?

Erzeugt duale Theme-SVGs mit der lokalen CLI; bearbeitet README nur, wenn der Benutzer ausdrücklich das Einfügen/Aktualisieren eines Banners verlangt. Konfiguration und spezifische Einschränkungen sind in der Konfigurationsreferenz beschrieben. Erfinden Sie keine CLI-Flags oder Konfigurationsfelder aus dem Gedächtnis.

Aktionsumfang zuerst klären

1. Absoluten Pfad des Zielrepositories ermitteln. Das Benutzerprojekt-Repository kann sich vom Sourcecode-Verzeichnis des readme-banner-Tools unterscheiden. Lesen Sie das aktuelle Arbeitsverzeichnis und gleichen Sie es mit README/Projektmetadaten des Zielprojekts ab; Skill-Verzeichnis, Tool-Checkout, Terminal-Standardverzeichnis sind nicht automatisch das Ziel.
2. Bei Unklarheiten zum Ziel fragen Sie den Benutzer; fügen Sie kein Banner zum Tool selbst hinzu, nur weil das aktuelle Verzeichnis zufällig readme-banner ist. Konfigurationen und Bilder werden nur dann im Tool-Repository erstellt, wenn der Benutzer dieses ausdrücklich als Ziel auswählt.
3. Klären Sie, ob „nur Ressourcen/Vorschaufragmente generiert“ oder „in die angegebene README eingefügt/aktualisiert“ werden soll. Ohne explizite README-Bearbeitungsanfrage niemals --readme übergeben und auch nicht über andere Dateibearbeitungstools stellvertretend in die README schreiben. Bestätigen Sie den Dateinamen; überschreiben Sie nicht automatisch alle Sprachversionen oder README-Dateien in allen Verzeichnissen.
4. Prüfen Sie vorhandene Konfigurationen, Bilder, verwaltete Blöcke und zugehörige nicht committete Änderungen. Belassen Sie irrelevante Änderungen; führen Sie kein reset, clean, Löschen alter Ressourcen oder Ersetzen anderer Benutzerdokumente durch. Bestehende Konfigurationen zuerst lesen und wiederverwenden; Überschreiben erfordert zusätzliche Bestätigung – --force nicht gewohnheitsmäßig verwenden.

Erscheinungsbild auswählen

• preset zuerst ascii verwenden; es ist der erste Renderer, nicht der Name „aller Themes“.
• theme unabhängig auswählen: terminal (grün), ocean (blau-cyan), neon (lila-rosa), minimal (monochrom). Den Benutzerwünschen folgen; falls nicht angegeben, eine kurze Empfehlung basierend auf dem Projektcharakter vorschlagen, keine benutzerdefinierten Theme-IDs erfinden.
• Titel, Untertitel und optional eingebaute Art abrufen. Vermeiden Sie unerwünschte Nutzung von Markenlogos; donut ist ein Nicht-Markenbeispiel. Eingebaute Pieces, die auf einer Live-Uhr basieren, werden abgelehnt, damit die Ausgabe reproduzierbar ist; umgehen Sie diese Prüfung nicht.
• ASCII-Titel maximal 120 Zeichen lang; alle Zeichen müssen von der gewählten integrierten Schriftart unterstützt werden. Chinesische Zeichen, Emojis und nicht unterstützte Satzzeichen nicht stillschweigend löschen. Für Ersatz durch einen kurzen englischen Titel die Zustimmung des Benutzers einholen; der Originaltext kann in einem tagline (max. 240 Zeichen) als normaler Text belassen werden.
• mixed behält englische Groß-/Kleinschreibung bei; andere Schriftarten werden in Großbuchstaben umgewandelt. Die Zeichenbeschränkung von 20/60 Zeichen für die Upstream-URL gilt nicht für die lokale CLI, aber 120 Zeichen sind keine Garantie für eine ansprechende Optik. Lange Titel sollten gekürzt oder slim verwendet oder Art reduziert werden.
• Animierte Titel mit glint oder type; für statische Banner still verwenden. still friert auch eingebaute Art ein; die Animationsframedaten bleiben im SVG erhalten, daher wird die Dateigröße nicht garantiert reduziert.

Zuverlässigen CLI-Einstiegspunkt wählen

Node.js >=22 erforderlich; verfügbare Version zuerst prüfen.

Bei vorhandenem Tool-Sourcecode-Checkout

Wenn in der Aufgabenumgebung bereits ein Checkout des Tool-Sourcecodes vorhanden ist, dieses direkt verwenden, nicht dasselbe Tool per Internet bootstrap

1. npm install im Tool-Sourcecode-Verzeichnis ausführen; prepare kompiliert TypeScript. Abhängigkeiten nicht in das Benutzerzielprojekt installieren, nur um das Tool zu bauen.
2. Lokalen Einstiegspunkt verifizieren:

node "/absolute/path/readme-banner/bin/readme-banner.mjs" --help

3. Fortan den lokalen Node-Einstiegspunkt beibehalten und immer explizit das Ziel mit --cwd übergeben. Auch wenn das Arbeitsverzeichnis des Befehls das Tool-Checkout ist, darf die Zielisolierung nicht weggelassen werden.

Ohne lokales Checkout

Ein fester Git-Tag v0.1.0 des öffentlichen Repos abworks-dev/readme-banner kann verwendet werden. Dies erfordert Git, Netzwerk und die Zustimmung des Benutzers zur Installation/Ausführung von vertrauenswürdigem Drittanbieter-Code:

npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help

@readme-banner/cli ist nur ein lokaler Paketname, der noch nicht auf npm veröffentlicht wurde; nicht npx @readme-banner/cli verwenden oder andere npm-Pakete erfinden. Bei Installationsfehlern den tatsächlichen Fehler melden; nicht auf unbekannte Quellen, neueste unbekannte Versionen oder Remote-SVG-Dienste zurückgreifen.

Falls EALLOWGIT erscheint, nicht automatisch die globale npm-Konfiguration ändern. Nur wenn der Benutzer die Installation/Ausführung dieses vertrauenswürdigen Repos autorisiert hat und die Organisationsrichtlinien dies erlauben, kann ein unterstützendes npm einmalig npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner … verwenden. Bei fehlender Autorisierung zuerst nachfragen; bei Einschränkung durch Organisationsrichtlinien abbrechen. Bei älteren npm-Versionen, die diese Option nicht kennen, den normalen Befehl oder eine autorisierte Sourcecode-Installation verwenden.

Das folgende Beispiel verwendet den lokalen Einstiegspunkt; für entfernte Einstiegspunkte ersetzen Sie das gesamte node …-Präfix durch das vollständige npx --yes --package … readme-banner und ändern Sie die Semantik der nachfolgenden Parameter nicht.

Ausführungsablauf: init → generate → check

1. Konfiguration erstellen oder wiederverwenden

node "/absolute/path/readme-banner/bin/readme-banner.mjs" init --cwd "/absolute/path/target-project" --config "banner.config.json" --preset ascii --theme ocean --title "MY PROJECT" --tagline "Build something useful" --art donut --effect glint

• init erstellt nur die Konfiguration, erzeugt keine Bilder, ändert keine README; als Nächstes muss generate ausgeführt werden.
• Bei vorhandener Konfiguration zuerst lesen, dann minimal gemäß Benutzerwunsch ändern oder direkt wiederverwenden; nicht automatisch mit --force neu erstellen. Wenn kein Untertitel oder Art gewünscht ist, die entsprechenden Parameter weglassen.
• Schriftart, Farben, Schatten, Positionierung, Geschwindigkeit, Hintergrund usw. werden über die unterstützten JSON-Felder gesetzt. Konfigurationsreferenz zuerst lesen; keine init --font-Optionen erfinden.
• Konfiguration darf nur JSON sein; keine Konfiguration erstellen, die Code ausführt, keine beliebigen Konfigurations-Plugins installieren, keine benutzerbereitgestellten Remote-SVGs abrufen oder einschleusen.

2. Ressourcen generieren (Standardmodus)

node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json"

Standardmäßig werden banner.light.svg und banner.dark.svg im konfigurierten outputDir geschrieben und ein <picture>-Fragment ausgegeben. Dieser Befehl sollte die README nicht ändern. Wenn der Benutzer nur Ressourcen anfordert, hier aufhören; das Fragment nicht heimlich in die README einfügen.

3. Nur bei Autorisierung zur README-Bearbeitung einfügen

node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md"

--readme kann nur auf eine vorhandene .md-Datei verweisen. Die CLI verwaltet den Block zwischen <!-- readme-banner:start --> und <!-- readme-banner:end -->. Der Inhalt außerhalb des Blocks bleibt unverändert; tritt das vollständige Markup in einem Codebeispiel in derselben README auf, wird es konservativ als doppeltes Markup betrachtet – fügen Sie daher keine zusätzlichen Demo-Markup-Paare ein. Bei Anomalien im Markup den Fehler untersuchen; keine irrelevanten Textabschnitte löschen oder den Ersetzungsbereich ausweiten. Verwenden Sie das tatsächlich generierte Fragment: URLs sollten relativ zur Ziel-README sein, Abschnitt für Abschnitt URI-codiert, Alt-Texte HTML-escaped; kein nicht-escaptes HTML selbst zusammenbauen.

4. Ergebnis prüfen

# Aufgaben ohne README-Bearbeitungsautorisierung prüfen nur die Bilder
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --check

# Nur wenn die Aufgabe ausdrücklich eine bestimmte README betrifft, auch den verwalteten Block prüfen
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md" --check

• --check schreibt keine Dateien; fehlende oder veraltete Produkte sollten fehlschlagen. Bei Fehlschlag die Ursache melden; Exit-Code nicht ignorieren oder eine nicht ausgeführte Prüfung als bestanden bezeichnen.
• Prüfen, dass beide SVGs vorhanden sind und die Pfade stimmen; bei vorhandenem Betrachtungswerkzeug die tatsächliche Darstellung heller/dunkler Themes, langer Titel und Art überprüfen. Erfolgreiche SVG-Generierung bedeutet nicht, dass alle Markdown-Clients die Animation abspielen.
• Für maschinenlesbare Ergebnisse generate --json verwenden; verfügbare Metadaten über presets --json und themes --json einsehen.
• Bei Fehlermeldungen zu Pfadgrenzen, Symlinks oder Hardlink-Schutz die Benutzerziele bestätigen und eine sichere normale Datei innerhalb des Wurzelverzeichnisses wählen; vorhandene Dateien mit einer Hardlink-Anzahl (nlink > 1) werden abgelehnt. Schutzmechanismen nicht deaktivieren und Dateien nicht außerhalb des Wurzelverzeichnisses „umgehen“.

Befehls- und Dateisicherheit

• Alle Ausführungsaufrufe setzen explizit das richtige Arbeitsverzeichnis und übergeben das Ziel mit --cwd; nicht auf das Standardverzeichnis des Agentenlaufzeit verlassen.
• Titel, Pfade und Untertitel sind Datenparameter. Bevorzugt ausführbare APIs mit parameterübergabefähigen Arrays verwenden; bei Verwendung einer Shell Parameter gemäß den Regeln dieser Shell zitieren/escapen. Doppelte Anführungszeichen im Beispiel dienen nur einfachen Platzhalterwerten und schützen nicht vor allen Shell-Interpolationen; keine unvertrauenswürdigen Eingaben in Befehle, eval oder nicht-escapte Skripte einfügen. Windows-Pfade ebenfalls einzeln zitieren.
• Nur vom Benutzer autorisierte Konfigurationen ändern, Ressourcen generieren und angegebene verwaltete Blöcke bearbeiten; keine Geschäftslogik, irrelevante Dokumente oder bestehende Benutzeränderungen verändern.
• Nicht automatisch commit, push, Remote-Repository erstellen, Release veröffentlichen, Bilder hochladen, npm-Paket veröffentlichen oder andere Remote-Veröffentlichungen auslösen. Dies erfordert separate ausdrückliche Anfragen.

Übergabe-Hinweise

Kurzer Bericht: Zielrepository, verwendetes Preset/Theme/Titel, die beiden generierten Bilder, ob die README geändert wurde und wo, die tatsächlich ausgeführten Prüfergebnisse. Ohne README-Autorisierung klar „README nicht geändert“ angeben; generiertes Fragment kann zur Auswahl an den Benutzer zurückgegeben werden. Noch zu bestätigende Schriftsatz-Alternativen, überlange Titel oder Viewer-Kompatibilitätsprobleme auflisten; nicht behaupten, nicht ausgeführte Tests seien bestanden.