>_ ash

Mitwirken · Erstellen · Debuggen

Entwicklerhandbuch

Ein praktischer Leitfaden zum Einrichten eines Checkouts, zum Auswählen von Zielen erstellen, zum Verständnis von Release-Buildern, zum Diagnostizieren von Laufzeitprotokollen und zum Testen nativer Paketinstallationen in Tart-VMs.

Richten Sie die Entwickler-Toolchain ein

Das Projekt verwendet Go für die CLI und den Broker sowie native Plugin-Toolchains und Tools in Site-Qualität. Auf macOS,make configverwendet Homebrew; Unter Debian oder Ubuntu wird apt verwendet. Es installiert Go, Node.js/npm, Python,uv, Rust/Cargo und die Flusen- und Sicherheitstools des Projekts. Das Go-Modul des Repositorys gibt die vom Build erwartete Go-Version an.

make config

Beim Verpacken von macOS-Installationsprogrammen werden auch die Xcode-Befehlszeilentools von Apple verwendet. Linux verpacken.debUnd.rpmArtefakte erfordern Ruby,fpmund RPM-Verpackungsdienstprogramme. Das Setup-Skript installiert die allgemeinen Voraussetzungen, für Release-Builds sind jedoch möglicherweise weiterhin plattformspezifische Paketierungstools erforderlich.

Einzelheiten zur erstmaligen Einrichtung und Beitragserwartungen finden Sie unterBEITRAG.md.

Alltäglicher Entwicklungsworkflow

Führen Sie für eine normale Codeänderung die fokussierten Tests während der Iteration aus und führen Sie dann die erforderlichen Lint- und Test-Gates des Repositorys aus, bevor Sie fertig sind:

go test ./internal/app -run 'TestName'
make check-static
make check-security
make test

Die meisten Make-Ziele werden verwendetscripts/dev/run-quiet.sh: Erfolgreiche Schritte drucken einen prägnantenokZeile, während fehlgeschlagene Schritte ihre erfasste Ausgabe drucken. Stellen Sie einem Ziel ein Präfix voranV=1um die komplette Ausgabe während der Ausführung zu streamen:

make V=1 lint
make V=1 test
make V=1 verify

V=1steuert den leisen Wrapper von Make. Es ist getrennt vonASH_VERBOSE, was eine Laufzeitdiagnose im ermöglichtAshProgramm.

Zielreferenz erstellen

make pre-push
Führt statische Prüfungen, Sicherheits- und Abhängigkeits-Scans, Geheimnis-Scans und Tests für die exakt übertragenen Commits aus. make config installiert den Repository-Hook. Lokale Hooks können umgangen werden und sind keine serverseitige Prüfung.
make lint
Überprüft Lokalisierungskataloge, Shell-Syntax für den Site-Installer, Workflow-YAML, Python-Lint/Format, Markdown, Plugin-Lint und Go-Lint.
make test
Erstellt und testet native Plugins und führt sie dann ausgo test ./....
make verify-ci
Führt das Pre-Push-Gate vor der nächtlichen Tag-Erstellung aus. Die tag-ausgelöste Artefakt-CI wiederholt keine Quellcodeprüfungen.
make verify
Führt das gesamte lokale Qualitätstor aus: Flusen, Tests, Renntests, Abdeckung, Tierarzt, statische Analyse, Sicherheit, geheime Scans, Fuzzing und Benchmarks.
make test-race
Führt Go-Tests mit dem Renndetektor durch.
make test-cover
Schreibtcoverage.outund vergleicht die Summe mitCOVERAGE_MIN(standardmäßig 60 %).
make test-fuzz
Führt Anwendungs-Fuzz-Tests für ausFUZZ_TIME(Standardmäßig 10 Sekunden).
make security
Führt gosec, govulncheck, npm-, Cargo- und Python-Abhängigkeitsprüfungen aus.
make build
Führt Lint aus und testet, erstellt und installiert native Plugins und erstelltashPlusash-brokerunter~/.local/bin.
make install
Führt Tests durch, Flusen,gosec, und Plugin erstellen/installieren, erstellt beide Binärdateien und führt sie dann ausash install --shell bash --shell-integration --overwrite. Verwenden Sie es, wenn Sie beabsichtigen, die lokale Bash-Integration zu aktualisieren.
make plugins-build,plugins-test,plugins-lint
Erstellen, testen oder linten Sie jedes Plugin unteninternal/app/ash_bootstrap/plugins_src.make plugins-cleanEntfernt die lokale Plugin-Build-Ausgabe.
make site-locales
Erstellt übersetzte Seiten und aktualisiert die Sitemap. Verwendenmake site-locales SITE_LOCALES="zh-TW lb_LU"um Orte auszuwählen.

make allläuftverifyund danninstall. Die vollständigen Zielrezepte und überschreibbaren Variablen finden Sie imMakefile.

Plugin-Builder

Plugins sind eigenständige ausführbare Dateien mit einem sprachunabhängigen Vertrag. Die Plugin-Makefiles wählen die Toolchain jedes Plugins aus; Lokale Builds zielen standardmäßig auf den Host ab. Release-Builds bestehenPLUGIN_TARGET_GOOSUndPLUGIN_TARGET_GOARCHDaher stimmen Rust und andere Nicht-Go-Plugin-Binärdateien mit dem Release-Artefakt überein.

Verwendenmake plugins-buildum sie einzubauenbin/plugins,make plugins-testum ihre Tests durchzuführen, undmake plugins-installum sie in das Benutzer-Plugin-Verzeichnis zu kopieren. Siehe dienativer Plugin-Vertragbevor Sie ein Plugin hinzufügen oder ändern.

Release-Builder und Artefakte

Nach den Qualitätsprüfungen führt GitHub make release-artifacts unter Linux aus. Ein Ubuntu-Job erstellt die macOS-Archive für Intel und Apple Silicon für Homebrew, ohne macOS-Runner oder .pkg-Installer. macOS-Ziele schließen alle Rust-Plugins einschließlich flip_a_coin aus, auch bei lokalen Builds. Linux und FreeBSD behalten die Rust-Plugins.

CI prüft macOS-Archivinhalte und Mach-O-Architekturen, führt die Binärdateien aber nicht aus. Linux und FreeBSD behalten Laufzeittests der entpackten Archive; Pakete und Shell-Integrationen werden nicht installiert. macOS-Build unter Linux: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release erstellt weiterhin ein lokales .pkg auf macOS, überträgt aber keine lokalen Binärdateien an CI.

Geben Sie für lokale Artefakt-Builds das Zielbetriebssystem, die Architektur und die Version explizit an:

make release-artifacts \
  RELEASE_TARGET_OSES=linux \
  RELEASE_TARGET_ARCHES="arm64 amd64" \
  RELEASE_VERSION=v1.2.3

release-artifactserstellt und validiert die für dieses Ziel unterstützten Formate. Die Standardeinstellungen sind Host-Betriebssystem (auto) und beidesamd64 arm64; Die Veröffentlichung unter FreeBSD ist beschränkt aufamd64. Artefakte gehen unterdist/release. Für einen einzelnen Binär-/Plugin-Build verwenden Siemake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionführt die Release-Prüfungen durch und erstellt Artefakte, ohne sie zu veröffentlichen. Im Gegensatz,make releaseist ein Veröffentlichungsworkflow: Er erfordert macOS, einen sauberen Arbeitsbaum und eine konfigurierte Git-Identität, generiert Versionshinweise, erstellt/pusht Release-Referenzen und überwacht den GitHub-Workflow. Der Standardkanal ist Beta; Wählen Sie stabil oder nächtlich mitCHANNEL=stableoderCHANNEL=nightly. Generierte Versionshinweise erfordernASH_AI_ENDPOINTUndASH_AI_MODEL, sofern keine Notizen mitgeliefert werdenRELEASE_NOTES_INPUT.

Lesen Sie dieRelease-WorkflowUndLeitfaden zu Release-Geheimnissenvor der Veröffentlichung.

Ausführliche Laufzeitprotokollierung

ASH_VERBOSEAktiviert die strukturierte JSON-Debug-Protokollierung und druckt zuvor ein Ausführungs-Dashboard ausAshAusgänge. Akzeptierte Werte sind1,y,yes,true,on, Unddebug, ohne Berücksichtigung der Groß- und Kleinschreibung. Das Dashboard fasst die Phasenzeiten, die Anzahl der Werkzeugaufrufe, die Gesamtzahl der Token, sofern verfügbar, und die Gesamtzeit in Echtzeit zusammen.

ASH_VERBOSE=1 ash "investigate this error"

ASH_VERBOSE=1 \
ASH_LOG_FILE="$HOME/.local/state/ash/debug.jsonl" \
ASH_LOG_MAX_BYTES=10485760 \
ash "investigate this error"

WannASH_LOG_FILEfestgelegt ist, werden ausführliche JSON-Protokolldatensätze in diesen Pfad geschrieben. Das übergeordnete Verzeichnis wird nach Bedarf erstellt.ASH_LOG_MAX_BYTESsteuert die Drehung und ist standardmäßig auf1048576Bytes (1 MiB). Ohne eine explizite Protokolldatei verwendet die Debug-Ausgabe den Prozessdiagnose-Writer. Halten Sie Protokolle privat und überprüfen Sie sie, bevor Sie sie teilen.

Dies unterscheidet sich von Make’sV=1: verwendenV=1um die Ausgabe des Build-/Testbefehls anzuzeigen undASH_VERBOSE=1eine Diagnose stellenAshLaufzeitaufruf.

Suchen Sie die Quelle eines Protokolldatensatzes

Jeder Ash Protokollierungsaufruf hat ein eindeutiges EID-Feld. Kopieren Sie die EID aus dem JSON-Datensatz und suchen Sie in der Go-Quelle nach ihrem Literal, um die Aufrufseite zu finden:

rg '"EID", "EpbG2YtZ"' internal/

Beispielsweise zeichnet ein Quellaufruf die Nachricht und die EID zusammen mit strukturiertem Kontext auf. EIDs sind stabile Kennungen für Protokollspeicherorte: Sie dürfen nicht übersetzt, umbenannt oder wiederverwendet werden. Der Debug-Logger und sein Rotationsverhalten sind in implementiertinternal/app/debuglog.go.

Testen Sie native Paketinstallationen mit vm.sh

scripts/vm.sh erkennt das Host-Betriebssystem und wählt ein VM-Backend aus: Tart auf Apple Silicon macOS oder QEMU/KVM auf x86_64 Linux. Beide Backends können APT unter Ubuntu/Debian und DNF unter Fedora/Rocky Linux testen. Tart auf macOS kann auch das macOS Homebrew-Paket testen; Linux-Hosts können keine macOS-Gäste ausführen und daher diesen Pfad nicht testen.

MacOS-Hostvoraussetzungen

Verwenden Sie einen Apple Silicon Mac mit macOS 13 oder höher, mit installiertem Tart, Netzwerkzugriff auf das VM-Image und das Ash-Repository sowie ausreichend Speicherplatz für die VM. Installieren Sie Tart bei Bedarf mit Homebrew:

brew install openai/tools/tart

Voraussetzungen für Linux-Hosts

Verwenden Sie einen x86_64-Linux-Host mit aktivierter Hardwarevirtualisierung und einem Benutzerkonto, das lesen und schreiben kann/dev/kvm(Üblicherweise durch Beitritt zumkvmGruppe hinzufügen und erneut anmelden). Installieren Sie QEMU/KVM, Cloud-Image-Utils fürcloud-localds, Curl, OpenSSH-Client-Tools und Python 3. Beispielpaketbefehle:

# Debian or Ubuntu
sudo apt-get install qemu-system-x86 qemu-utils cloud-image-utils curl openssh-client python3

# Fedora or Rocky Linux
sudo dnf install qemu-kvm qemu-img cloud-utils curl openssh-clients python3

Das Linux-Backend startet x86_64 Ubuntu-, Debian-, Fedora- oder Rocky-Cloud-Images mit QEMU/KVM und Cloud-Init. Es nutzt QEMU-Benutzermodus-Netzwerke mit SSH-Weiterleitung an localhost; Es ist keine libvirt-Netzwerkeinrichtung erforderlich. Es führt keine macOS-Gäste aus, testet Homebrew nicht auf macOS und erfordert derzeit einen x86_64-Linux-Host. Arch und FreeBSD sind keine unterstützten Ziele.

Führen Sie einen Pakettest durch

Der automatisierte Modus ist die Standardeinstellung und entfernt die VM nach dem Test. Die Standardplattform folgt dem Host: macOS wählt ausmacos, Linux wähltubuntu. Wählen Sie explizit eine andere unterstützte Plattform und einen anderen unterstützten Modus. Der Paketkanal ist standardmäßig aufbeta; verwenden--channel nightly,--channel beta, oder--channel releaseum eines auszuwählen.--channel stableist ein Alias ​​fürrelease.

scripts/vm.sh --platform macos --mode interactive
scripts/vm.sh --platform ubuntu --channel nightly --mode automated
scripts/vm.sh --platform debian --mode interactive
scripts/vm.sh --platform fedora --mode automated
scripts/vm.sh --platform rocky --mode interactive

Der interaktive Modus lässt die installierte VM für manuelle Tests laufen. Führen Sie unter macOS den gedruckten Befehl tart exec -it in einem Terminal aus, um eine Gast-Shell zu öffnen. Beim Beenden dieser Shell bleibt die VM aktiv. Fahren Sie den Gast herunter oder stoppen Sie ihn vom Host aus. Um eine beibehaltene Tart-VM zu stoppen und zu löschen, verwenden Sie:

tart stop VM_NAME && tart delete VM_NAME

Unter Linux gibt das Skript einen SSH-Befehl und einen Stoppbefehl aus; Stoppen Sie die VM und entfernen Sie ihren Status mit:

scripts/vm.sh --stop VM_NAME

Im automatisierten Modus werden Installations- und Shell-Setup-Smoke-Checks durchgeführt, dann wird die VM angehalten und entfernt. Heruntergeladene Basisbilder bleiben im Cache. Tortenbilder können mit geändert werdenASH_TEST_VM_IMAGE; Linux-Cloud-Image-URLs können mit überschrieben werdenASH_TEST_QEMU_IMAGE. Linux-Images werden unter zwischengespeichert${XDG_CACHE_HOME:-~/.cache}/ash/vm-images, und interaktive VM-Festplatten und SSH-Schlüssel werden darunter aufbewahrt${XDG_STATE_HOME:-~/.local/state}/ash/vm. SatzASH_TEST_VM_CACHE_DIRoderASH_TEST_VM_STATE_DIRum diese Standorte zu ändern.

Damit sich der Gast mit demselben AI-Dienst wie der Host verbinden kann, exportieren Sie die erforderlichen DatenASH_AI_*Variablen, bevor Sie beispielsweise das Skript ausführenASH_AI_ENDPOINT,ASH_AI_MODEL, und, wenn nötig,ASH_AI_AUTH_TOKEN. Exportierte Werte werden an den Gast weitergeleitet; nicht exportierte Shell-Variablen nicht. Interaktive VMs behalten diese Anmeldeinformationen im Gastprofil mit Modus0600; Linux-VM-Festplatten sind nicht verschlüsselt. Schützen Sie daher das Statusverzeichnis und stoppen/entfernen Sie die VM, wenn Sie fertig sind.

Sehenscripts/vm.sh --helpInformationen zu den aktuellen Backend-Voraussetzungen, unterstützten Plattformen und Optionen.

Projektquellenhandbücher

  • Mitwirkender Leitfaden– Setup, Tests, Release-Erwartungen und CI-Hinweise.
  • Architektur— Projektlayout und Laufzeitsubsysteme.
  • README– Produkt-, Installations-, Konfigurations- und Umgebungsreferenz.
  • Makefile– maßgebliche Zielrezepte und Build-Variablen.
  • GitHub-Workflows– CI, Plattform-Builder und Veröffentlichungsautomatisierung.