>_ ash

Contribuer · construire · déboguer

Guide du développeur

Un guide pratique pour configurer une extraction, choisir Créer des cibles, comprendre les générateurs de versions, diagnostiquer les journaux d'exécution et tester les installations de packages natifs dans les VM Tart.

Configurer la chaîne d'outils de développement

Le projet utilise Go pour la CLI et le courtier, ainsi que des chaînes d'outils de plugins natifs et des outils de qualité de site. Sur macOS,make configutilise Homebrew ; sur Debian ou Ubuntu, il utilise apt. Il installe Go, Node.js/npm, Python,uv, Rust/Cargo, ainsi que les outils de charpie et de sécurité du projet. Le module Go du référentiel précise la version Go attendue par le build.

make config

L'empaquetage des installateurs macOS utilise également les outils de ligne de commande Xcode d'Apple. Emballage Linux.debet.rpmles artefacts nécessitent Ruby,fpmet les utilitaires de packaging RPM. Le script d'installation installe les prérequis courants, mais des outils de packaging spécifiques à la plate-forme peuvent toujours être nécessaires pour les versions.

Pour plus de détails sur la première configuration et les attentes en matière de contribution, voirCONTRIBUER.md.

Flux de développement quotidien

Pour un changement de code normal, exécutez les tests ciblés pendant l'itération, puis exécutez le lint requis et les portes de test du référentiel avant de terminer :

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

La plupart Utiliser les ciblesscripts/dev/run-quiet.sh: étapes réussies, imprimez-en une de manière conciseokligne, tandis que les étapes ayant échoué impriment leur sortie capturée. Préfixez une cible avecV=1pour diffuser sa sortie complète pendant son exécution :

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

V=1contrôle le wrapper silencieux de Make. Il est distinct deASH_VERBOSE, qui permet les diagnostics d'exécution dans leAshprogramme.

Faire une référence à la cible

make pre-push
Exécute les vérifications statiques, les analyses de sécurité et des dépendances, la détection de secrets et les tests sur les commits exacts envoyés. make config installe le hook du dépôt. Les hooks locaux peuvent être contournés et ne sont pas imposés par le serveur.
make lint
Vérifie les catalogues de localisation, la syntaxe shell pour le programme d'installation du site, le flux de travail YAML, Python lint/format, Markdown, plugin lint et Go lint.
make test
Construit et teste les plugins natifs, puis s'exécutego test ./....
make verify-ci
Exécute le contrôle pre-push avant la création du tag nocturne. La CI des artefacts déclenchée par un tag ne répète pas les vérifications du code source.
make verify
Exécute le contrôle de qualité local complet : peluches, tests, tests de course, couverture, vétérinaire, analyse statique, sécurité, analyses secrètes, fuzzing et benchmarks.
make test-race
Exécute des tests Go avec le détecteur de course.
make test-cover
Écritcoverage.outet vérifie le total par rapport àCOVERAGE_MIN(60% par défaut).
make test-fuzz
Exécute des tests fuzz d'application pourFUZZ_TIME(10 secondes par défaut).
make security
Exécute gosec, govulncheck et les audits de dépendances npm, Cargo et Python.
make build
Exécute lint et teste, construit et installe des plugins natifs et construitashplusash-brokersous~/.local/bin.
make install
Exécute des tests, des peluches,gosec, et le plugin build/install, construit les deux binaires, puis s'exécuteash install --shell bash --shell-integration --overwrite. Utilisez-le lorsque vous avez l'intention de mettre à jour l'intégration Bash locale.
make plugins-build,plugins-test,plugins-lint
Créez, testez ou lintez chaque plugin sousinternal/app/ash_bootstrap/plugins_src.make plugins-cleansupprime la sortie de construction du plugin local.
make site-locales
Génère des pages traduites et actualise le plan du site. Utilisermake site-locales SITE_LOCALES="zh-TW lb_LU"pour sélectionner les paramètres régionaux.

make allcourtverifyet puisinstall. Les recettes cibles complètes et les variables remplaçables se trouvent dans leMakefile.

Constructeurs de plugins

Les plugins sont des exécutables autonomes avec un contrat indépendant de la langue. Le plugin Makefiles sélectionne la chaîne d’outils de chaque plugin ; les builds locales ciblent l'hôte par défaut. Les versions de version sont réussiesPLUGIN_TARGET_GOOSetPLUGIN_TARGET_GOARCHdonc Rust et d'autres binaires de plugins non-Go correspondent à l'artefact de version.

Utilisermake plugins-buildpour les intégrerbin/plugins,make plugins-testpour exécuter leurs tests, etmake plugins-installpour les copier dans le répertoire du plugin utilisateur. Voir lecontrat de plugin natifavant d'ajouter ou de modifier un plugin.

Générateurs de versions et artefacts

Après les contrôles de qualité, GitHub exécute make release-artifacts sous Linux. Un travail Ubuntu compile les archives macOS Intel et Apple Silicon pour Homebrew, sans exécuteurs macOS ni installateurs .pkg. Les cibles macOS excluent tous les plugins Rust, dont flip_a_coin, même pour les compilations locales. Linux et FreeBSD conservent les plugins Rust.

CI vérifie le contenu des archives macOS et les architectures Mach-O sans exécuter leurs binaires. Linux et FreeBSD conservent les tests d'exécution des archives extraites ; aucun paquet ni intégration shell n'est installé. Pour compiler macOS sous Linux : make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. make release crée toujours un .pkg local sur macOS sans transmettre les binaires locaux à CI.

Pour les builds d'artefacts locaux, spécifiez explicitement le système d'exploitation cible, l'architecture et la version :

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

release-artifactsconstruit et valide les formats pris en charge pour cette cible. Les valeurs par défaut sont le système d'exploitation hôte (auto) et les deuxamd64 arm64; La publication FreeBSD est limitée àamd64. Les artefacts disparaissentdist/release. Pour une seule version binaire/plugin, utilisezmake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionexécute les vérifications de version et crée des artefacts sans les publier. En revanche,make releaseest un workflow de publication : il nécessite macOS, une arborescence de travail propre et une identité Git configurée, génère des notes de version, crée/pousse des références de version et surveille le workflow GitHub. Son canal par défaut est la version bêta ; sélectionnez stable ou nocturne avecCHANNEL=stableouCHANNEL=nightly. Les notes de version générées nécessitentASH_AI_ENDPOINTetASH_AI_MODEL, à moins que les notes ne soient fournies avecRELEASE_NOTES_INPUT.

Lire leflux de travail de publicationetguide des secrets de publicationavant de publier.

Journalisation d'exécution détaillée

ASH_VERBOSEpermet la journalisation structurée du débogage JSON et imprime un tableau de bord d'exécution avantAshsorties. Les valeurs acceptées sont1,y,yes,true,on, etdebug, sans tenir compte de la casse. Le tableau de bord résume les horaires des étapes, le nombre d'appels d'outils, les totaux de jetons lorsqu'ils sont disponibles et le total en temps réel.

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"

QuandASH_LOG_FILEest défini, les enregistrements détaillés du journal JSON sont écrits dans ce chemin ; le répertoire parent est créé selon les besoins.ASH_LOG_MAX_BYTEScontrôle la rotation et est par défaut1048576octets (1 Mo). Sans fichier journal explicite, la sortie de débogage utilise le rédacteur de diagnostic de processus. Gardez les journaux privés et examinez-les avant de les partager.

Ceci est distinct de celui de MakeV=1: utiliserV=1pour voir le résultat de la commande build/test etASH_VERBOSE=1diagnostiquer unAshappel à l'exécution.

Trouver la source d'un enregistrement de journal

Chaque appel de journalisation Ash possède un champ EID unique. Copiez l'EID de l'enregistrement JSON et recherchez son littéral dans la source Go pour trouver le site d'appel :

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

Par exemple, un appel source enregistre le message et l'EID avec un contexte structuré. Les EID sont des identifiants stables pour les emplacements de journaux : ne les traduisez pas, ne les renommez pas et ne les réutilisez pas. Le journal de débogage et son comportement de rotation sont implémentés dansinterne/app/debuglog.go.

Tester les installations de packages natifs avec vm.sh

scripts/vm.sh détecte le système d'exploitation hôte et sélectionne un backend de VM : Tart sur Apple Silicon macOS ou QEMU/KVM sur Linux x86_64. Les deux backends peuvent tester APT sur Ubuntu/Debian et DNF sur Fedora/Rocky Linux. Tart sur macOS peut également tester le package macOS Homebrew ; Les hôtes Linux ne peuvent pas exécuter d'invités macOS et ne peuvent donc pas tester ce chemin.

Conditions préalables de l'hôte macOS

Utilisez un Apple Silicon Mac exécutant macOS 13 ou version ultérieure, avec Tart installé, un accès réseau à l'image de la VM et au référentiel Ash, et suffisamment d'espace disque pour la VM. Installez Tart avec Homebrew si nécessaire :

brew install openai/tools/tart

Conditions préalables de l'hôte Linux

Utilisez un hôte Linux x86_64 avec la virtualisation matérielle activée et un compte utilisateur capable de lire et d'écrire/dev/kvm(généralement en rejoignant lekvmgroupe et vous reconnecter). Installez QEMU/KVM, cloud-image-utils pourcloud-localds, curl, les outils client OpenSSH et Python 3. Exemples de commandes de package :

# 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

Le backend Linux lance les images cloud x86_64 Ubuntu, Debian, Fedora ou Rocky avec QEMU/KVM et cloud-init. Il utilise le réseau en mode utilisateur QEMU avec SSH transmis à localhost ; aucune configuration réseau libvirt n'est nécessaire. Il n'exécute pas d'invités macOS, ne teste pas Homebrew sur macOS et nécessite actuellement un hôte Linux x86_64. Arch et FreeBSD ne sont pas des cibles prises en charge.

Exécuter un test de package

Le mode automatisé est le mode par défaut et supprime la VM après le test. La plateforme par défaut suit l'hôte : macOS sélectionnemacos, Linux sélectionneubuntu. Choisissez explicitement une autre plate-forme et un autre mode pris en charge. Le canal du paquet est par défautbeta; utiliser--channel nightly,--channel beta, ou--channel releasepour en sélectionner un.--channel stableest un pseudonyme pourrelease.

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

Le mode interactif laisse la VM installée fonctionner pour des tests manuels. Sur macOS, exécutez la commande imprimée tart exec -it dans un terminal pour ouvrir un shell invité. Quitter ce shell laisse la VM en cours d'exécution ; éteignez l'invité ou arrêtez-le de l'hôte. Pour arrêter et supprimer une VM Tart conservée, utilisez :

tart stop VM_NAME && tart delete VM_NAME

Sous Linux, le script imprime une commande SSH et une commande stop ; arrêtez la VM et supprimez son état avec :

scripts/vm.sh --stop VM_NAME

Le mode automatisé exécute des vérifications d'installation et de configuration du shell, puis arrête et supprime la VM. Les images de base téléchargées restent mises en cache. Les images de tarte peuvent être modifiées avecASH_TEST_VM_IMAGE; Les URL d'images cloud Linux peuvent être remplacées parASH_TEST_QEMU_IMAGE. Les images Linux sont mises en cache sous${XDG_CACHE_HOME:-~/.cache}/ash/vm-images, et les disques interactifs des machines virtuelles et les clés SSH sont conservés sous${XDG_STATE_HOME:-~/.local/state}/ash/vm. EnsembleASH_TEST_VM_CACHE_DIRouASH_TEST_VM_STATE_DIRpour changer ces emplacements.

Pour permettre à l'invité de se connecter au même service d'IA que l'hôte, exportez le fichier nécessaireASH_AI_*variables avant d'exécuter le script, par exempleASH_AI_ENDPOINT,ASH_AI_MODEL, et, si nécessaire,ASH_AI_AUTH_TOKEN. Les valeurs exportées sont transmises à l'invité ; les variables shell non exportées ne le sont pas. Les VM interactives conservent ces informations d'identification dans le profil invité avec le mode0600; Les disques des machines virtuelles Linux ne sont pas chiffrés, protégez donc le répertoire d'état et arrêtez/supprimez la machine virtuelle lorsque vous avez terminé.

Voirscripts/vm.sh --helppour les prérequis backend actuels, les plates-formes prises en charge et les options.

Guides des sources du projet

  • Guide de contribution- configuration, tests, attentes de publication et notes CI.
  • Architecture— la présentation du projet et les sous-systèmes d'exécution.
  • LISEZMOI— référence du produit, de l'installation, de la configuration et de l'environnement.
  • Makefile- des recettes cibles et des variables de construction faisant autorité.
  • Flux de travail GitHub— CI, créateurs de plateformes et automatisation de la publication.