>_ ash

Contribuisci · costruisci · esegui debug

Guida per gli sviluppatori

Una guida pratica per impostare un checkout, scegliere Crea target, comprendere i builder di rilascio, diagnosticare i log di runtime e testare le installazioni di pacchetti nativi nelle VM Tart.

Configura la toolchain dello sviluppatore

Il progetto utilizza Go per CLI e broker, oltre a toolchain di plug-in nativi e strumenti di qualità del sito. Su macOS,make configusa l'Homebrew; su Debian o Ubuntu usa apt. Installa Go, Node.js/npm, Python,uv, Rust/Cargo e gli strumenti di sicurezza e lanugine del progetto. Il modulo Go del repository specifica la versione Go prevista dalla build.

make config

Il pacchetto di installazione di macOS utilizza anche gli strumenti da riga di comando Xcode di Apple. Confezione di Linux.debE.rpmgli artefatti richiedono Ruby,fpme utilità di packaging RPM. Lo script di installazione installa i prerequisiti comuni, ma per le build di rilascio potrebbero essere comunque necessari strumenti di confezionamento specifici della piattaforma.

Per i dettagli sulla configurazione iniziale e le aspettative di contributo, vedereCONTRIBUIRE.md.

Flusso di lavoro di sviluppo quotidiano

Per una normale modifica del codice, esegui i test mirati durante l'iterazione, quindi esegui i lint richiesti e i test gate del repository prima di terminare:

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

La maggior parte degli obiettivi Make utilizzascripts/dev/run-quiet.sh: i passaggi riusciti ne stampano uno concisooklinea, mentre i passaggi falliti stampano l'output acquisito. Prefisso una destinazione conV=1per eseguire lo streaming dell'output completo durante l'esecuzione:

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

V=1controlla il wrapper silenzioso di Make. È separato daASH_VERBOSE, che abilita la diagnostica di runtime inAshprogramma.

Fai riferimento al target

make pre-push
Esegue controlli statici, analisi di sicurezza e delle dipendenze, scansione dei segreti e test sui commit esatti in uscita. make config installa l'hook del repository. Gli hook locali possono essere ignorati e non sono controlli imposti dal server.
make lint
Controlla i cataloghi di localizzazione, la sintassi della shell per il programma di installazione del sito, il flusso di lavoro YAML, lint/formato Python, Markdown, plugin lint e Go lint.
make test
Crea e testa i plugin nativi, quindi viene eseguitogo test ./....
make verify-ci
Esegue il controllo pre-push prima della creazione del tag notturno. La CI degli artefatti attivata dal tag non ripete i controlli del codice sorgente.
make verify
Esegue l'intero controllo di qualità locale: lanugine, test, test di gara, copertura, veterinario, analisi statica, sicurezza, scansioni segrete, fuzzing e benchmark.
make test-race
Esegue i test Go con il rilevatore di gare.
make test-cover
Scrivecoverage.oute confronta il totaleCOVERAGE_MIN(60% per impostazione predefinita).
make test-fuzz
Esegue i test fuzz dell'applicazione perFUZZ_TIME(10 secondi per impostazione predefinita).
make security
Esegue gosec, govulncheck e gli audit delle dipendenze npm, Cargo e Python.
make build
Esegue lint e testa, crea e installa plug-in nativi e creaashpiùash-brokerSotto~/.local/bin.
make install
Esegue test, lanugine,gosece plugin build/install, crea entrambi i file binari, quindi viene eseguitoash install --shell bash --shell-integration --overwrite. Usalo quando intendi aggiornare l'integrazione Bash locale.
make plugins-build,plugins-test,plugins-lint
Costruisci, testa o esegui l'linting di ciascun plug-in di seguitointernal/app/ash_bootstrap/plugins_src.make plugins-cleanrimuove l'output di compilazione del plugin locale.
make site-locales
Genera pagine tradotte e aggiorna la mappa del sito. Utilizzomake site-locales SITE_LOCALES="zh-TW lb_LU"per selezionare le impostazioni locali.

make allcorreverifypoiinstall. Le ricette di destinazione complete e le variabili sovrascrivibili si trovano nel fileMakefile.

Costruttori di plugin

I plugin sono eseguibili autonomi con un contratto indipendente dalla lingua. I plugin Makefile selezionano la toolchain di ciascun plugin; le build locali prendono di mira l'host per impostazione predefinita. Il rilascio delle build passaPLUGIN_TARGET_GOOSEPLUGIN_TARGET_GOARCHquindi Rust e altri file binari dei plugin non Go corrispondono all'artefatto di rilascio.

Utilizzomake plugins-buildper costruirlibin/plugins,make plugins-testper eseguire i loro test, emake plugins-installper copiarli nella directory dei plugin dell'utente. Vedi ilcontratto di plugin nativoprima di aggiungere o modificare un plugin.

Rilascia builder e artefatti

Dopo i controlli di qualità, GitHub esegue make release-artifacts su Linux. Un job Ubuntu compila gli archivi macOS Intel e Apple Silicon per Homebrew, senza runner macOS né installer .pkg. I target macOS escludono tutti i plugin Rust, incluso flip_a_coin, anche nelle build locali. Linux e FreeBSD mantengono i plugin Rust.

La CI verifica contenuti degli archivi macOS e architetture Mach-O senza eseguirne i binari. Linux e FreeBSD mantengono i test di esecuzione degli archivi estratti; non vengono installati pacchetti o integrazioni della shell. Per compilare macOS su Linux: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release crea ancora un .pkg locale su macOS senza trasferire i binari locali alla CI.

Per le build di artefatti locali, specificare esplicitamente il sistema operativo, l'architettura e la versione di destinazione:

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

release-artifactscrea e convalida i formati supportati per quel target. Le impostazioni predefinite sono il sistema operativo host (auto) ed entrambiamd64 arm64; La pubblicazione di FreeBSD è limitata aamd64. I manufatti affondanodist/release. Per una singola build binaria/plugin, utilizzaremake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionesegue i controlli di rilascio e crea gli artefatti senza pubblicarli. Al contrario,make releaseè un flusso di lavoro di pubblicazione: richiede macOS, un albero di lavoro pulito e un'identità Git configurata, genera note di rilascio, crea/invia riferimenti di rilascio e controlla il flusso di lavoro GitHub. Il suo canale predefinito è beta; seleziona stabile o notturno conCHANNEL=stableOCHANNEL=nightly. Le note di rilascio generate richiedonoASH_AI_ENDPOINTEASH_AI_MODEL, a meno che non siano fornite noteRELEASE_NOTES_INPUT.

Leggi ilflusso di lavoro di rilascioErilasciare la guida ai segretiprima della pubblicazione.

Registrazione dettagliata del runtime

ASH_VERBOSEabilita la registrazione strutturata del debug JSON e stampa prima un dashboard di esecuzioneAshesce. I valori accettati sono1,y,yes,true,on, Edebug, senza distinzione tra maiuscole e minuscole. Il dashboard riepiloga i tempi delle fasi, il conteggio delle chiamate allo strumento, i totali dei token quando disponibili e il tempo reale totale.

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"

QuandoASH_LOG_FILEè impostato, i record di log JSON dettagliati vengono scritti su quel percorso; la directory principale viene creata secondo necessità.ASH_LOG_MAX_BYTEScontrolla la rotazione e il valore predefinito è1048576byte (1 MiB). Senza un file di registro esplicito, l'output di debug utilizza il writer della diagnostica del processo. Mantieni i registri privati ​​e rivedili prima di condividerli.

Questo è diverso da quello di MakeV=1: utilizzoV=1per vedere l'output del comando build/test eASH_VERBOSE=1per diagnosticare unAshinvocazione in fase di esecuzione.

Trova l'origine di un record di registro

Ogni chiamata di registrazione Ash ha un campo EID univoco. Copia l'EID dal record JSON e cerca il suo valore letterale nell'origine Go per trovare il sito della chiamata:

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

Ad esempio, una chiamata all'origine registra il messaggio e l'EID insieme al contesto strutturato. Gli EID sono identificatori stabili per le posizioni dei log: non tradurli, rinominarli o riutilizzarli. Il logger di debug e il relativo comportamento di rotazione sono implementati ininternal/app/debuglog.go.

Testa l'installazione del pacchetto nativo con vm.sh

scripts/vm.sh rileva il sistema operativo host e seleziona un backend VM: Tart su Apple Silicon macOS o QEMU/KVM su x86_64 Linux. Entrambi i backend possono testare APT su Ubuntu/Debian e DNF su Fedora/Rocky Linux. Tart su macOS può anche testare il pacchetto macOS Homebrew; Gli host Linux non possono eseguire guest macOS e pertanto non possono testare quel percorso.

Prerequisiti host macOS

Utilizza un Mac Apple Silicon con macOS 13 o versione successiva, con Tart installato, accesso di rete all'immagine VM e al repository Ash e spazio su disco sufficiente per la VM. Installa Tart con Homebrew se necessario:

brew install openai/tools/tart

Prerequisiti dell'host Linux

Utilizza un host Linux x86_64 con la virtualizzazione hardware abilitata e un account utente in grado di leggere e scrivere/dev/kvm(comunemente unendosi alkvmgruppo ed effettuare nuovamente l'accesso). Installa QEMU/KVM, cloud-image-utils percloud-localds, curl, strumenti client OpenSSH e Python 3. Comandi del pacchetto di esempio:

# 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

Il backend Linux avvia immagini cloud x86_64 Ubuntu, Debian, Fedora o Rocky con QEMU/KVM e cloud-init. Utilizza la rete in modalità utente QEMU con SSH inoltrato a localhost; non è necessaria alcuna configurazione di rete libvirt. Non esegue guest macOS, non testa Homebrew su macOS e attualmente richiede un host Linux x86_64. Arch e FreeBSD non sono target supportati.

Esegui un test del pacchetto

La modalità automatizzata è l'impostazione predefinita e rimuove la VM dopo il test. La piattaforma predefinita segue l'host: seleziona macOSmacos, Linux selezionaubuntu. Scegli esplicitamente un'altra piattaforma e modalità supportate. Per impostazione predefinita, il canale del pacchetto èbeta; utilizzo--channel nightly,--channel beta, O--channel releaseper selezionarne uno.--channel stableè un alias perrelease.

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

La modalità interattiva lascia la VM installata in esecuzione per il test manuale. Su macOS, esegui il comando stampato tart exec -it in un terminale per aprire una shell guest. L'uscita da quella shell lascia la VM in esecuzione; spegnere l'ospite o interromperlo dall'host. Per arrestare ed eliminare una VM Tart conservata, utilizzare:

tart stop VM_NAME && tart delete VM_NAME

Su Linux, lo script stampa un comando SSH e un comando di arresto; arresta la VM e rimuovi il suo stato con:

scripts/vm.sh --stop VM_NAME

La modalità automatizzata esegue controlli di fumo di installazione e configurazione della shell, quindi arresta e rimuove la VM. Le immagini di base scaricate rimangono memorizzate nella cache. Le immagini crostate possono essere modificate conASH_TEST_VM_IMAGE; Gli URL delle immagini cloud Linux possono essere sovrascritti conASH_TEST_QEMU_IMAGE. Le immagini Linux sono memorizzate nella cache in${XDG_CACHE_HOME:-~/.cache}/ash/vm-imagese i dischi VM interattivi e le chiavi SSH vengono mantenuti${XDG_STATE_HOME:-~/.local/state}/ash/vm. ImpostatoASH_TEST_VM_CACHE_DIROASH_TEST_VM_STATE_DIRper cambiare quelle posizioni.

Per consentire all'ospite di connettersi allo stesso servizio AI dell'host, esporta il file necessarioASH_AI_*variabili prima di eseguire lo script, ad esempioASH_AI_ENDPOINT,ASH_AI_MODELe, quando necessario,ASH_AI_AUTH_TOKEN. I valori esportati vengono inoltrati al guest; le variabili di shell non esportate non lo sono. Le macchine virtuali interattive conservano queste credenziali nel profilo guest con modalità0600; I dischi delle VM Linux non sono crittografati, quindi proteggi la directory di stato e arresta/rimuovi la VM al termine.

Vederescripts/vm.sh --helpper gli attuali prerequisiti di backend, piattaforme supportate e opzioni.

Guide alle fonti del progetto

  • Guida per contribuire— configurazione, test, aspettative di rilascio e note CI.
  • Architettura— layout del progetto e sottosistemi di runtime.
  • LEGGIMI— riferimento al prodotto, all'installazione, alla configurazione e all'ambiente.
  • Makefile— ricette target autorevoli e variabili di creazione.
  • Flussi di lavoro GitHub— CI, costruttori di piattaforme e automazione della pubblicazione.