本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。英文原文

音訊通知

狀態：現行範圍：AX Code TUI 的音效與語音提示上次審閱：2026-09-12 負責人：AX Code runtime 維護者

TUI 可在 AX Code 需要你注意時播放系統音效，或說出一段簡短的範本文句：

權限請求 — 有工具正在等待你核准。
Agent 提問 — agent 向你提出問題。
回合完成 — 此次執行已結束（預設關閉）。
工作階段錯誤 — 此回合失敗。

音訊與終端機通知使用相同的觸發條件（OSC 9 桌面通知；不支援 OSC 9 時改為終端機鈴響），並受同一個 notifications.enabled 開關控制。它預設關閉；啟用它不會改變通知的其他行為。

設定

設定 notifications.sound，位置在 tui.json：

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

欄位	值	預設	意義
`enabled`	布林	`true`	終端機通知與音訊的總開關。
`sound`	`"off"`、`"chime"`、`"speak"`	`"off"`	`chime` 播放系統音效；`speak` 合成語音。
`voice`	字串	`""`	平台語音名稱（macOS 上為 `say -v '?'`）；空白表示預設。
`rate`	整數	`0`	支援時的語速（macOS 為每分鐘字數，1–500）；0 表示預設。
`events.permission`	布林	`true`	權限請求時提示。
`events.question`	布林	`true`	agent 提問時提示。
`events.complete`	布林	`false`	回合完成時提示。
`events.error`	布林	`true`	工作階段錯誤時提示。

無效值會逐欄捨棄：錯誤的 sound 值會回到 "off"，不影響其他設定。

平台支援

平台	提示音	語音	需求
macOS	`afplay`（系統音效）	`say`	內建。
Windows	`System.Media.SoundPlayer`	`System.Speech`	內建（PowerShell）。
Linux	`paplay`，備援 `canberra-gtk-play`	`spd-say`，備援 `espeak-ng`	安裝 PulseAudio／`libcanberra` 及／或 `speech-dispatcher`／`espeak-ng`。

執行時會探測是否可用。沒有可用後端時，音訊步驟會安靜略過，並以終端機通知作為備援。播放會序列化（一次一個音效，重複會合併），每個事件最多提示一次，介面也不會等待播放完成。無頭執行（ax-code run）絕不播放音訊。

會說出的內容

語音只用四個固定範本：Approval required: <tool>、Question: <first question>、Session idle: <session title> 與 AX Code error。文字會截斷並移除控制字元。工具引數、承載中的檔案路徑、模型輸出與錯誤訊息都不會被說出——在這些限制內，適合共用空間。

透過 hooks 自訂音效

若要完全掌控（自己的音效檔、不同文字、額外事件），可透過生命週期 hooks 接上任何播放器——即使停用音訊通知也能使用。以 AX_CODE_TRUST_PROJECT_CONFIG=1 選擇加入後，建立 .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'" }
  ]
}

使用平台的播放器（macOS 為 afplay，Linux 為 paplay，Windows 為 PowerShell 的 [System.Media]）。Hook 指令是 shell 片段——請讓它們發射後即忘，以免延遲生命週期路徑。

打造外部通知程式

外部工具（狀態列、行動推播、桌面應用程式）可訂閱伺服器的事件串流，並對 permission.asked、question.asked、session.status 與 session.error 做出反應——見 HTTP 與 OpenAPI 相容性。