Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Notifiche audio

Stato: Attuale Ambito: suoni e avvisi vocali della TUI di AX Code Ultima revisione: 2026-09-12 Responsabile: responsabili del runtime di AX Code

La TUI può riprodurre un suono di sistema — oppure pronunciare una breve frase da modello — ogni volta che AX Code ha bisogno della tua attenzione:

Richiesta di autorizzazione — uno strumento attende la tua approvazione.
Domanda dell’agente — l’agente ti ha posto una domanda.
Turno completato — l’esecuzione è terminata (disattivato per impostazione predefinita).
Errore di sessione — il turno non è riuscito.

L’audio usa gli stessi inneschi della notifica del terminale (notifica desktop OSC 9, oppure il campanello del terminale dove OSC 9 non è supportato) ed è governato dallo stesso interruttore notifications.enabled. È disattivato per impostazione predefinita; attivarlo non cambia nient’altro delle notifiche.

Configurazione

Imposta notifications.sound in tui.json:

{
  "notifications": {
    "enabled": true,
    "sound": "chime",
    "events": {
      "permission": true,
      "question": true,
      "complete": false,
      "error": true
    }
  }
}

Campo	Valori	Predefinito	Significato
`enabled`	booleano	`true`	Interruttore principale per le notifiche del terminale e l’audio.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` riproduce un suono di sistema; `speak` sintetizza la voce.
`voice`	stringa	`""`	Nome della voce della piattaforma (`say -v '?'` su macOS); vuoto = predefinita.
`rate`	intero	`0`	Velocità di lettura dove è supportata (parole/min su macOS, 1–500); 0 = predefinita.
`events.permission`	booleano	`true`	Avviso sulle richieste di autorizzazione.
`events.question`	booleano	`true`	Avviso sulle domande dell’agente.
`events.complete`	booleano	`false`	Avviso quando un turno si completa.
`events.error`	booleano	`true`	Avviso sugli errori di sessione.

I valori non validi vengono scartati campo per campo: un valore sound errato torna a "off" senza toccare le altre impostazioni.

Supporto delle piattaforme

Piattaforma	Suono	Voce	Requisito
macOS	`afplay` (suono di sistema)	`say`	Integrato.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Integrato (PowerShell).
Linux	`paplay`, ripiego `canberra-gtk-play`	`spd-say`, ripiego `espeak-ng`	Installa PulseAudio/`libcanberra` e/o `speech-dispatcher`/`espeak-ng`.

La disponibilità viene verificata a runtime. Senza un backend utilizzabile, il passo audio viene saltato in silenzio e la notifica del terminale resta il ripiego. La riproduzione è serializzata (un suono alla volta, le ripetizioni si fondono), ogni evento avvisa al massimo una volta e l’interfaccia non attende mai la riproduzione. Le esecuzioni senza interfaccia (ax-code run) non riproducono mai audio.

Che cosa viene pronunciato

La voce usa solo quattro modelli fissi: Approval required: <tool>, Question: <first question>, Session idle: <session title> e AX Code error. Il testo viene troncato e privato dei caratteri di controllo. Argomenti degli strumenti, percorsi di file dai payload, output del modello e messaggi di errore non vengono mai pronunciati: è sicuro per gli spazi condivisi entro questi limiti.

Suoni personalizzati tramite hook

Per il controllo completo (un tuo file audio, un testo diverso, eventi extra), collega un qualsiasi riproduttore tramite gli hook del ciclo di vita: funziona anche con le notifiche audio disattivate. Dopo l’adesione con AX_CODE_TRUST_PROJECT_CONFIG=1, crea .ax-code/hooks.json:

{
  "hooks": [
    { "event": "Stop", "command": "afplay /System/Library/Sounds/Glass.aiff" },
    { "event": "PreToolUse", "matcher": "bash|edit|write", "command": "say 'AX Code needs approval'" }
  ]
}

Usa il riproduttore della tua piattaforma (afplay su macOS, paplay su Linux, PowerShell [System.Media] su Windows). I comandi degli hook sono frammenti di shell: tienili non bloccanti, così non possono ritardare il percorso del ciclo di vita.

Costruire un notificatore esterno

Strumenti esterni (barre di stato, push su mobile, un’app desktop) possono iscriversi al flusso di eventi del server e reagire a permission.asked, question.asked, session.status e session.error. Vedi Compatibilità HTTP e OpenAPI.