Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Thông báo âm thanh

Trạng thái: Hiện hành Phạm vi: âm thanh và cảnh báo nói của TUI AX Code Xem xét lần cuối: 2026-09-12 Chủ sở hữu: người bảo trì runtime AX Code

TUI có thể phát một âm hệ thống — hoặc đọc một cụm mẫu ngắn — mỗi khi AX Code cần bạn chú ý:

Yêu cầu quyền — một công cụ đang chờ bạn phê duyệt.
Câu hỏi của tác nhân — tác nhân đã hỏi bạn một câu.
Lượt hoàn thành — lần chạy đã xong (tắt theo mặc định).
Lỗi phiên — lượt đã thất bại.

Âm thanh đi cùng các kích hoạt với thông báo terminal (thông báo desktop OSC 9, hoặc chuông terminal nơi OSC 9 không được hỗ trợ) và bị chặn bởi cùng công tắc notifications.enabled. Nó tắt theo mặc định; bật nó không đổi gì khác về thông báo.

Cấu hình

Đặt notifications.sound trong tui.json:

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

Trường	Giá trị	Mặc định	Ý nghĩa
`enabled`	boolean	`true`	Cổng chính cho thông báo terminal và âm thanh.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` phát âm hệ thống; `speak` tổng hợp giọng nói.
`voice`	string	`""`	Tên giọng của nền tảng (`say -v '?'` trên macOS); rỗng = mặc định.
`rate`	integer	`0`	Tốc độ nói nơi được hỗ trợ (từ/phút trên macOS, 1–500); 0 = mặc định.
`events.permission`	boolean	`true`	Cảnh báo khi có yêu cầu quyền.
`events.question`	boolean	`true`	Cảnh báo khi tác nhân hỏi.
`events.complete`	boolean	`false`	Cảnh báo khi một lượt hoàn thành.
`events.error`	boolean	`true`	Cảnh báo khi phiên lỗi.

Giá trị không hợp lệ bị bỏ theo từng trường: một giá trị sound xấu sẽ lùi về "off" mà không ảnh hưởng các thiết lập khác của bạn.

Hỗ trợ nền tảng

Nền tảng	Chuông	Giọng nói	Yêu cầu
macOS	`afplay` (âm hệ thống)	`say`	Tích hợp sẵn.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Tích hợp sẵn (PowerShell).
Linux	`paplay`, dự phòng `canberra-gtk-play`	`spd-say`, dự phòng `espeak-ng`	Cài PulseAudio/`libcanberra` và/hoặc `speech-dispatcher`/`espeak-ng`.

Khả dụng được dò lúc chạy. Khi không có backend dùng được, bước âm thanh bị bỏ im lặng và thông báo terminal vẫn là đường lùi. Phát được tuần tự hóa (một âm tại một thời điểm, các lần lặp được gộp), mỗi sự kiện cảnh báo nhiều nhất một lần, và giao diện không bao giờ chờ việc phát. Các lần chạy không giao diện (ax-code run) không bao giờ phát âm thanh.

Những gì được đọc

Giọng nói chỉ dùng bốn mẫu cố định: Approval required: <tool>, Question: <first question>, Session idle: <session title> và AX Code error. Văn bản bị cắt và được gỡ ký tự điều khiển. Đối số công cụ, đường dẫn tệp từ tải, đầu ra mô hình và thông báo lỗi không bao giờ được đọc — an toàn cho không gian dùng chung trong các giới hạn đó.

Âm tùy chỉnh qua móc

Để kiểm soát đầy đủ (tệp âm của riêng bạn, văn bản khác, sự kiện thêm), hãy nối bất kỳ trình phát nào qua móc vòng đời — cách này vẫn hoạt động khi thông báo âm thanh bị tắt. Sau khi chọn tham gia bằng AX_CODE_TRUST_PROJECT_CONFIG=1, hãy tạo .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'" }
  ]
}

Dùng trình phát của nền tảng bạn (afplay trên macOS, paplay trên Linux, PowerShell [System.Media] trên Windows). Lệnh móc là đoạn shell — hãy giữ chúng chạy rồi quên để chúng không thể làm chậm đường vòng đời.

Dựng một bộ thông báo bên ngoài

Các công cụ bên ngoài (thanh trạng thái, đẩy lên di động, một ứng dụng desktop) có thể đăng ký luồng sự kiện của máy chủ và phản ứng với permission.asked, question.asked, session.status và session.error — xem Tương thích HTTP và OpenAPI.