Shangshui0302/some-NixOS-skills

Nix-Paketentwicklung

EISERNES GESETZ: ÄNDERE EINEN PAKETAUSDRUCK ERST, NACHDEM DIE ZIEL-NIXPKGS-SCHNITTSTELLEN UND UPSTREAM-QUELL-/RELEASE-NACHWEISE ERFASST WURDEN; EIN BUILD OHNE DIESE NACHEISE IST KEIN REPRODUZIERBARES PAKETIERUNGSERGEBNIS.

Rote Flaggen — kehre zum Schritt der Nachweisfindung zurück, wenn eine dieser Bedingungen auftritt:

• Ein Builder wurde basierend auf einer einzelnen Markierungsdatei oder allein aus dem Gedächtnis ausgewählt.
• Ein fließender Channel, ein Registry-Ergebnis oder eine „aktuelle“ URL ist der einzige Quellnachweis.
• Ein Hash, Wrapper, Desktop-Eintrag oder eine Laufzeitabhängigkeit wurde geraten.
• nix develop ist erfolgreich, aber die Ableitung, das Ausgabelayout oder die ausführbare Datei wurde nicht gebaut.
• Ein erfolgreicher Trockenbuild wird als bereitgestellter oder laufender Live-Test gemeldet.

Gültigkeitsbereich

Diese Fähigkeit umfasst den Paketausdruck, seine Build-Eingaben, den Ausgabevertrag und die paketorientierte Flake- oder Overlay-Integration. Behandle NixOS/Home Manager-Module als Konsumenten: Überprüfe deren Paketschnittstelle und führe einen Trockenbuild durch, wenn sie im Gültigkeitsbereich liegen, aber überlasse die Systemkonfiguration und -aktivierung nixos-ecosystem.

Wenn die Anfrage den upstream NixOS/nixpkgs-Wartungsprozess betrifft – wie die Klassifizierung eines Updates oder eines Bruchs, die Übernahme eines Pakets, die Überprüfung betroffener Abhängigkeiten oder die Vorbereitung eines nixpkgs-PRs – verwende nixpkgs-maintainer. Sind beide betroffen, liefert diese Fähigkeit Ableitungsnachweise und die Maintainer-Fähigkeit übernimmt den upstream-Workflow.

Fortschrittsliste

Kopiere diese Checkliste in die Arbeitsnotizen und markiere sie, wenn die Aufgabe voranschreitet:

• Schritt 0: Repository-Richtlinie laden und Gültigkeitsbereich definieren ⚠️ ERFORDERLICH
  • Finde AGENTS.md, Beitragsregeln, schmutzige Dateien, Paketkonsumenten und das angeforderte beobachtbare Verhalten.
  • Klassifiziere die Aufgabe als Hinzufügen, Upgrade, Reparatur oder Überprüfung.
  • Identifiziere, ob der Ausdruck in einem Paket-Repository, einer eigenständigen Datei, einem Flake, einem Overlay oder einem nixpkgs-Baum lebt.
• Schritt 1: Die Frischeprüfung bestehen ⛔ BLOCKIEREND
  • Erfasse die nixpkgs-Revision des Ziels aus flake.lock, einem gepinnten Paket-Repository-Eingang oder dem nixpkgs-Checkout; gib den Fallback an, wenn keiner existiert.
  • Überprüfe den gesperrten Builder/Helper-Schnittstelle und vergleiche sie mit den aktuellen offiziellen Dokumentationen.
  • Melde Abweichungen und Auswirkungen von Migrationen; wende niemals stillschweigend eine neuere API auf einen älteren Lock an.
• Schritt 2: Quell- und Paketnachweise sammeln ⚠️ ERFORDERLICH
  • Durchsuche den Zielbaum, relevante nixpkgs-Eingänge, Overlays und vorhandene Helfer nach einem vorhandenen Paket oder einer Implementierung.
  • Überprüfe Upstream-Tag/Commit, Build-Befehle, CI, Lizenz, Plattform, Artefakt, ausführbaren Dateinamen und Installationslayout.
  • Wähle den schmalsten Pfad: Quelle, vorgebautes ELF, AppImage, Electron/ASAR, Daten, Schriftart/Theme oder Plugin.
• Schritt 3: Den minimalen Plan präsentieren ⚠️ ERFORDERLICH für nicht-triviale Änderungen
  • Gib Dateien, Abhängigkeiten, Risiken, Verifikationsbefehle und an, was unverifiziert bleibt.
  • Frage vor destruktiven Änderungen, Installation, Systemaktivierung, Commit, Push oder PR-Erstellung.
• Schritt 4: Die kleinste Ableitung implementieren
  • Pinne pname, version, Quelle/Revision und SRI-Hashes; verwende pname/version konsistent in URLs und Dateinamen.
  • Verwende den schmalsten nixpkgs-Builder und Standardphasen; benutzerdefinierte Phasen müssen ihre entsprechenden Hooks ausführen.
  • Trenne Build-Tools, Link-/Laufzeitbibliotheken, Test-Tools und vom Wrapper bereitgestellte Befehle.
  • Führe die GUI-Integration als eine Einheit durch: Wrapper, Desktop-Eintrag, Icon, Exec und Laufzeitflags.
  • Erhalte oder lege die vorhandene Paketoberfläche des Ziels offen – Flake-Ausgabe, Overlay oder Paketattribut – nur, wenn sie im Gültigkeitsbereich liegt.
• Schritt 5: In Schichten verifizieren ⚠️ ERFORDERLICH
  • Parse, evaluiere/prüfe, baue, überprüfe die Store-Ausgabe und führe einen sicheren Smoke-Test durch.
  • Führe einen System-Trockenbuild nur durch, wenn das Paket in NixOS/Home Manager integriert ist.
  • Halte Build-, Smoke-, Trockenbuild- und Postaktivierungs-/Live-Status getrennt.
• Schritt 6: Berichten und warten
  • Berichte über Nachweise, geänderte Dateien, Hashes, Prüfungen, Blocker und den genauen manuellen nächsten Schritt.
  • Überprüfe bei Upgrades erneut Changelog, Lockfiles, Lizenz, Artefaktlayout und alle Hashes.
  • Füge ein Update-Skript erst hinzu, nachdem der Update-Pfad als stabil und deterministisch nachgewiesen wurde.

Frischeprüfung

Lade references/freshness-and-evidence.md vor der Auswahl eines Builders oder dem Schreiben eines neuen Hashes. Verwende gh für GitHub-Untersuchungen. Bevorzuge die gesperrte nixpkgs-Quelle für API-Fakten und verwende die aktuellen offiziellen Nixpkgs-/nix.dev-Dokumentationen, um Prozessänderungen zu erkennen. Bei Widersprüchen halte inne und erkläre, ob die Änderung lock-kompatibel ist, ein Lock-Update erfordert oder eine dokumentierte Ausnahme bleiben sollte.

Builder- und Implementierungsrouting

Lade nach dem Schritt der Nachweisfindung nur den relevanten Abschnitt von references/builder-routing.md. Füge keinen breiten Abhängigkeitssatz hinzu, um einen unbekannten Phasenfehler zu verstecken. Bevorzuge einen Quellbuild, wenn er wartbar ist; verwende ein Release-Binary oder AppImage nur, wenn der Upstream-Quellpfad nicht verfügbar oder wesentlich unzuverlässiger ist.

Für benutzerdefinierte buildPhase, checkPhase oder installPhase behalte die entsprechenden runHook preX und runHook postX bei. Für vorgebauten nativen Code dokumentiere die Herkunft und überprüfe Architektur, Interpreter, NEEDED-Bibliotheken und Lizenzen gebündelter Komponenten.

Validierung

Lade references/validation.md für die Pakettyp-Matrix und Ausgabeprüfungen. Passe die folgenden Prüfungen an die Paketoberfläche des Ziels an:

nix-instantiate --parse path/to/package.nix
nix flake check path:. --no-build       # wenn das Ziel einen Flake bereitstellt
nix build path:.#pname -L --no-link --print-out-paths  # verwende den Zielausgabenamen
git diff --check

Wenn das Paket in eine NixOS/Home Manager-Konfiguration eingebunden ist, führe auch aus:

nixos-rebuild dry-build --flake path:.

Verwende scripts/validate-skill.py, um dieses Skill-Repository selbst zu überprüfen. Es ist ein deterministischer Lint, kein Ersatz für das Bauen des Zielpakets.

Wenn der Benutzer darum bittet, eine „Validierung durchzuführen“ ohne Angabe eines Konsumenten, standardmäßig auf Paketauswertung, Build, Ausgabeinspektion und einen sicheren Smoke-Test. Füge einen NixOS/Home Manager oder einen anderen Konsumenten-Trockenbuild nur hinzu, wenn dieser Konsument im Gültigkeitsbereich liegt.

Upgrades und Frische-Wartung

Lade references/update-policy.md für wiederholte Updates. Pinne Quell- und Dokumentationseingänge, mache Update-Prüfungen explizit und halte automatische Arbeiten standardmäßig schreibgeschützt. Ein automatisierter Job kann nach bestandenen Prüfungen eine überprüfbare Update-Änderung öffnen; er darf nicht stillschweigend einen Skill umschreiben, ein System umschalten, committen oder pushen.

Vier konkrete Anfrageformen

Lade references/examples.md, wenn die Anfrage mehrdeutig ist. Die unterstützten Formen sind: Hinzufügen eines Pakets zu einem Paket-Repository, eigenständiger Ausdruck, Flake oder Overlay; Upgrade einer vorhandenen Ableitung und Aktualisieren von Quell-/Abhängigkeits-Hashes; Reparatur eines vorgebauten/AppImage-, Electron-, Schriftart-/Theme- oder Plugin-Pakets; und Integration eines Pakets durch einen vorhandenen Flake oder Overlay für einen Konsumenten.

Anti-Patterns

• Verwende den Erfolg von nix develop nicht als Beweis dafür, dass nix build funktioniert.
• Wähle keinen Builder allein aus Cargo.toml, package.json oder einer geratenen Abhängigkeit.
• Lade Abhängigkeiten während eines sandboxed Builds nicht online herunter (cargo fetch, npm install, pip install und ähnliche).
• Verwende keine fließenden Quell-URLs, veränderbaren Branches, alten Hashes oder Versionsliterale, die über einen Ausdruck dupliziert sind.
• Verstecke fehlende Bibliotheken nicht mit autoPatchelfIgnoreMissingDeps, einem Standard-FHS-Wrapper oder einer überdimensionierten buildInputs-Liste.
• Beharre nicht darauf, dass Desktop-, IPC-, Wiedergabe-, Wayland- oder Compositor-Verhalten getestet wurde, wenn nur die Ableitung gebaut wurde.
• Behandle Paketausdrucksprüfungen nicht als nixpkgs-Integration oder PR-Review; verwende für diesen upstream-Workflow nixpkgs-maintainer.
• Führe kein nixos-rebuild switch, Commit, Push, Dateilöschung oder PR-Erstellung ohne explizite Autorisierung durch.

Lieferformat

Gib einen kompakten Nachweisbericht zurück:

1. Gültigkeitsbereich und Pfad — Zielrepository/öffentliche Oberfläche, Aufgabentyp, Pakettyp und warum dieser Builder ausgewählt wurde.
2. Nachweise — gesperrte nixpkgs-Revision/API, Upstream-Revision/Artefakt/Lizenz und relevante Hashes.
3. Änderungen — Paketausdruck, Flake- oder Overlay-Oberfläche, Konsumenten und Dokumentation.
4. Verifikation — Parse, Flake-Check, Build, Ausgabe/Smoke, Trockenbuild und Live-Status getrennt.
5. Nächste Aktion — genauer manueller Befehl oder noch erforderliche Benutzerentscheidung.

Bezeichne ein Paket niemals als „fertig“, solange eine erforderliche Prüfung fehlt; benenne stattdessen den Blocker und das kleinste nächste Experiment.