Terminal Access для NVDA

Terminal Access добавляет управляемую с клавиатуры навигацию, поиск, закладки и звуковые сигналы в 30 оконных терминальных приложений, включая Windows Terminal, PowerShell, Command Prompt, WSL и популярные сторонние эмуляторы. Он предоставляет навигацию по строкам, словам и символам в выводе терминала без перемещения курсора, позволяя читать результаты команд так же, как вы читаете документ.

Откройте это руководство в любое время из терминала, нажав NVDA+Shift+F1.

Содержание

1. Начало работы
2. Слой команд
3. Режим таблицы
4. Закладки
5. Обнаружение ошибок и предупреждений
6. Обнаружение конфликтов жестов
7. Профили приложений
8. Поддержка сторонних терминалов
9. Определения окон
10. Текст Unicode и CJK
11. Производительность
12. Поддержка AI CLI
13. Настройки
14. Устранение неполадок
15. Получение помощи

Начало работы

Установка

1. Загрузите последний файл .nvda-addon со страницы релизов.
2. Нажмите Enter на загруженном файле.
3. Подтвердите запрос.
4. Перезапустите NVDA.

Terminal Access требует Windows 10 или 11 и NVDA 2025.1 или новее.

Первые шаги

Откройте любой поддерживаемый терминал. Когда Terminal Access распознает его, вы услышите: "Поддержка Terminal Access активна. Нажмите NVDA+shift+f1 для справки."

Вы можете читать вывод терминала двумя способами:

• Прямые жесты: комбинации с модификатором NVDA, например NVDA+I для чтения текущей строки. Они работают в любое время внутри терминала.
• Слой команд: нажмите NVDA+апостроф для входа в режим, где каждая команда — это одно нажатие клавиши. Вы услышите "Команды терминала" и высокий тон. Нажмите Escape для выхода.

Слой команд быстрее для последовательности команд и позволяет избежать конфликтов с другими дополнениями. Оба способа выполняют одни и те же команды, и вы можете переназначать любые жесты в диалоге "Жесты ввода" NVDA в категории "Terminal Access".

Основные команды чтения

Эти несколько команд покрывают большую часть задач чтения. В первом столбце указана клавиша внутри слоя команд, во втором — эквивалентный прямой жест.

Полный справочник по всем командам приведен в следующем разделе.

Слой команд

Слой команд — это модальный режим ввода, который выполняет команды Terminal Access с помощью однократных нажатий клавиш вместо многоклавишных комбинаций с модификатором NVDA. Это позволяет избежать конфликтов с другими дополнениями NVDA и ускоряет ввод команд.

Вход и выход

Слой остается активным до тех пор, пока вы не выйдете из него. Каждая команда оставляет вас в слое, чтобы вы могли выполнять цепочки команд. Слой автоматически закрывается, когда фокус покидает терминал.

Справочник команд

В слое команд активны следующие клавиши:

Навигация

Информация и чтение

Выделение и копирование

Управление окнами

Конфигурация

Закладки

Вкладки

Поиск и список URL

Диалог поиска содержит текстовое поле и две опции: Учитывать регистр (точное совпадение букв) и Регулярное выражение (интерпретировать текст как регулярное выражение Python). Обе опции запоминают свое состояние для следующего поиска в сессии. Если регулярное выражение недействительно, вы услышите короткое сообщение, и поиск не будет выполнен.

Поиск открывает диалог результатов, в котором перечислены все строки с совпадениями. Активация результата (Enter или кнопка "Активировать") закрывает диалог и помещает курсор обзора в начало строки с совпадением (так же, как переход по закладке), поэтому команда чтения текущей строки прочитает это совпадение. После закрытия диалога F3 и Shift+F3 продолжают перебор оставшихся совпадений, объявляя позицию каждого как "N из M" и произнося "Обертка", когда навигация зацикливается в начало. Если поиск не нашел ничего, предлагаются нечеткие совпадения (с одной ошибкой).

Результаты поиска фиксируются в момент выполнения поиска. Если программа затем выводит новые данные, следующее нажатие "найти далее" или "найти предыдущее" повторяет поиск по текущему буферу, чтобы результаты оставались точными, сохраняя вашу позицию на той же строке совпадения, где это возможно. Результаты сохраняются для каждого окна терминала в текущей сессии NVDA; они не сохраняются при перезапуске NVDA.

Режим таблицы

Справка и настройки

Режим копирования внутри слоя

Когда вы нажимаете V в слое команд, вы входите в режим копирования. Клавиши L (копировать строку), S (копировать экран) и Escape (отмена) временно заменяют свои привязки в слое. При выходе из режима копирования эти привязки восстанавливаются.

Настройка жестов

Все команды Terminal Access, как в слое, так и прямые, зарегистрированы в категории "Terminal Access" диалога "Жесты ввода" NVDA. Вы можете переназначить любой жест.

Список URL

Нажмите E в слое команд (или NVDA+Alt+U напрямую), чтобы просканировать буфер терминала на наличие URL. Откроется интерактивный диалог:

Поддерживаемые типы URL: HTTP/HTTPS, FTP, с префиксом www и терминальные гиперссылки OSC 8. Дубликаты URL удаляются автоматически.

Примечание по безопасности: URL с file://, javascript: или другими не-веб-схемами обнаруживаются и отображаются в списке, но не могут быть открыты из диалога. Попытка открыть такой URL вызывает голосовое сообщение "Невозможно открыть этот тип URL по соображениям безопасности". Это предотвращает использование вредоносного вывода терминала, который может обманом заставить вас запустить опасные локальные ресурсы.

Режим таблицы

Терминальные программы часто выводят табличные данные, такие как docker ps, kubectl get pods, ls -l, psql и таблицы в формате Markdown. При чтении как обычный текст они превращаются в длинные строки, где трудно сопоставить значение с его заголовком. Режим таблицы читает вывод по столбцам и объявляет заголовок для каждой ячейки, так что вы всегда знаете, в каком столбце находитесь.

Вход и выход

Поместите курсор обзора на любую строку таблицы, затем нажмите G в слое команд (или NVDA+Alt+G напрямую). Если таблица обнаружена в этой позиции, режим таблицы активируется, и клавиши со стрелками перемещают по ячейкам. Если таблица не найдена, вы услышите "Таблица не найдена в этой позиции".

Нажмите Escape или переключите команду снова, чтобы выйти из режима таблицы. Режим таблицы также автоматически закрывается, когда фокус покидает терминал.

Навигация по ячейкам

Пока активен режим таблицы, следующие клавиши управляют навигацией:

Каждая ячейка объявляется с заголовком столбца и значением ячейки, поэтому вы можете перемещаться по столбцу и сравнивать значения, не теряя их смысла.

Поддерживаемые форматы таблиц

Режим таблицы распознает два формата:

Обнаружение столбцов основано на эвристике (экспериментально)

Обнаружение столбцов в режиме таблицы основано на эвристике. Он определяет начало и конец столбцов на основе выравнивания пробелов и символов-разделителей в видимом тексте, поскольку вывод терминала не содержит структурной разметки, описывающей столбцы. Это хорошо работает для распространенных утилит, перечисленных выше, но необычные интервалы, перенос строк, ячейки с несколькими пробелами или широкие символы (CJK) могут привести к неправильному определению границ столбцов.

Это поведение будет улучшено в будущих обновлениях по мере сбора результатов тестирования и сообщений пользователей о таблицах, которые не распознаются или разбиваются некорректно. Если вы столкнулись с таблицей, которая читается неправильно, сообщите об этом с примером вывода, чтобы мы могли улучшить распознавание.

Закладки

Закладки позволяют сохранять и быстро возвращаться к определенным строкам в буфере терминала.

Установка закладок

Нажмите Shift+0 – Shift+9 в слое команд (или NVDA+Alt+0 – NVDA+Alt+9 напрямую), чтобы установить закладку на текущей строке. Текст строки сохраняется как метка для последующей идентификации.

Переход к закладкам

Нажмите 0-9 в слое команд (или Alt+0 – Alt+9 напрямую), чтобы перейти к соответствующей закладке.

Диалог списка закладок

Нажмите B в слое команд (или NVDA+Shift+B напрямую), чтобы открыть интерактивный список. В диалоге отображаются два столбца: номер закладки и содержимое строки. Нажмите Enter, чтобы перейти к выбранной закладке, или Delete, чтобы удалить её.

Закладки хранятся для каждого окна терминала и сохраняются, пока это окно открыто, включая случаи, когда фокус уходит и возвращается. Разные окна терминала имеют свои собственные закладки. Обратите внимание, что несколько вкладок внутри одного окна Windows Terminal используют одно окно, поэтому они используют общие закладки. Закладки хранятся только для текущей сессии NVDA; они не сохраняются при перезапуске NVDA. На окно сохраняется до 50 закладок; когда лимит достигнут, установка новой закладки сопровождается сообщением "Достигнут лимит закладок" до тех пор, пока вы не удалите одну из них.

Поскольку вывод терминала прокручивается, закладка указывает на строку по её содержимому. Переход к закладке повторно находит эту строку, что надежно, пока строка все еще находится в буфере; если строка вышла за пределы истории терминала, переход может не сработать.

Обнаружение ошибок и предупреждений

Terminal Access воспроизводит звуковые сигналы, когда вы перемещаетесь по строкам, содержащим ошибки или предупреждения. Это помогает на слух просматривать вывод сборки, результаты тестов или файлы журналов.

• Строки с ошибками воспроизводят низкий тон.
• Строки с предупреждениями воспроизводят более высокий тон.

Детектор распознает распространенные шаблоны из вывода компиляторов, линтеров и командной оболочки, такие как error:, ERROR, warning: и WARN.

Настройки звуковых сигналов

Настройте эти параметры в меню NVDA > Параметры > Настройки > Настройки терминала.

Область действия жестов

Жесты Terminal Access активируются только внутри поддерживаемых терминалов. Вне терминала жесты передаются NVDA или другим дополнениям. Обнаружение терминала использует точное совпадение по имени процесса.

Обнаружение конфликтов жестов

Terminal Access обнаруживает, когда его сочетания клавиш конфликтуют с другими установленными дополнениями NVDA. При обнаружении конфликта вы получаете предупреждение, чтобы вы могли решить, какое назначение оставить.

Для разрешения конфликтов:

1. Откройте меню NVDA > Параметры > Настройки > Настройки терминала.
2. В разделе "Конфликты жестов NVDA" снимите флажки с жестов, которые хотите отключить.
3. Отключенные прямые жесты остаются доступными через слой команд (NVDA+апостроф).

Слой команд и жесты справки (NVDA+Shift+F1) не могут быть отключены.

Профили приложений

Профили приложений адаптируют настройки Terminal Access в зависимости от используемого терминального приложения. Каждый профиль может настраивать уровни пунктуации, режимы отслеживания курсора и области окна для специализированного поведения.

Общие сведения о профилях

Terminal Access поставляется с профилями по умолчанию для популярных приложений:

• vim/nvim: Пунктуация MOST (для символов кода), отслеживание курсора WINDOW, бесшумные зоны для строки состояния и командной строки.
• tmux: Отслеживание курсора STANDARD, бесшумная зона для строки состояния.
• htop: Повторяющиеся символы отключены (индикаторы прогресса повторяют символы), области окна для заголовка (строки 1-4) и списка процессов (строки 5+).
• less/more: Тихий режим включен, эхо клавиш отключено.
• git: Пунктуация MOST (символы в различиях), повторяющиеся символы отключены.
• nano: Отслеживание курсора STANDARD, бесшумные зоны для строки состояния и строки быстрых команд.
• irssi: Пунктуация SOME, пауза строки отключена для быстрого чтения чата, бесшумная зона для строки состояния.
• WSL: Пунктуация MOST (удобно для команд Linux и путей), отслеживание курсора STANDARD, повторяющиеся символы выключены.

Управление профилями

Просматривайте, экспортируйте, импортируйте и удаляйте профили в меню NVDA > Параметры > Настройки > Настройки терминала > Профили приложений. В раскрывающемся списке "Установленные профили" сначала отображаются профили по умолчанию, затем пользовательские профили в алфавитном порядке.

• Экспорт: Выберите профиль и нажмите "Экспортировать...", чтобы сохранить его в виде файла JSON со всеми настройками и определениями окон.
• Импорт: Нажмите "Импортировать..." и выберите файл JSON профиля. Профиль с таким же именем будет заменен.
• Удалить: Выберите пользовательский профиль и нажмите "Удалить профиль". Профили по умолчанию (vim, tmux, htop, less, git, nano, irssi) не могут быть удалены.

Переопределение настроек профиля

Когда профиль активен, его настройки переопределяют глобальные настройки Terminal Access. Например, если профиль less отключает эхо клавиш, эхо клавиш отключается во время работы less, независимо от глобальной настройки.

Если вы переключаете настройку, например тихий режим, пока активен профиль, изменение сохраняется в переопределениях этого профиля, а не в глобальных настройках. При переключении на другое приложение глобальные настройки восстанавливаются.

Создание пользовательских профилей

Создайте пользовательский профиль, экспортировав существующий как шаблон, отредактировав JSON и импортировав его обратно:

{
  "appName": "myapp",
  "displayName": "Мое приложение",
  "punctuationLevel": 2,
  "cursorTrackingMode": 1,
  "quietMode": false,
  "keyEcho": true,
  "linePause": true,
  "repeatedSymbols": true,
  "windows": [
    {
      "name": "status",
      "top": 9999,
      "bottom": 9999,
      "left": 1,
      "right": 9999,
      "mode": "silent",
      "enabled": true
    }
  ]
}

Поддержка сторонних терминалов

Terminal Access поддерживает 30 терминалов: 5 встроенных терминалов Windows, WSL и 24 сторонних эмулятора. Он автоматически обнаруживает их при переключении, и для каждого предусмотрен профиль по умолчанию, настроенный для обычного использования.

Встроенные терминалы Windows

Windows Terminal, cmd (Командная строка), powershell (Windows PowerShell), pwsh (PowerShell Core) и conhost (Console Host).

Сторонние эмуляторы терминалов

Cmder, ConEmu, mintty (Git Bash и Cygwin), PuTTY и KiTTY, Terminus, Hyper, Alacritty, WezTerm, Tabby, FluentTerminal, Ghostty, Rio, Wave Terminal, Contour, Cool Retro Term, MobaXterm, SecureCRT, Tera Term, mRemoteNG и Royal TS.

Профили по умолчанию по категориям

Все функции Terminal Access работают со сторонними терминалами: навигация, выделение, отслеживание курсора, уровни пунктуации и определения окон. Чтобы настроить терминал, используйте его, откройте Настройки NVDA > Terminal Access, настройте параметры и экспортируйте профиль для резервного копирования или обмена.

Определения окон

Определения окон отмечают области экрана терминала с различным речевым поведением. Это полезно для приложений со строками состояния, командными областями или разделенными панелями.

Основы

Каждое определение окна имеет имя, координаты (верх, низ, лево, право), режим и флаг включения.

Координаты отсчитываются с 1, поэтому строка 1, столбец 1 — это верхний левый угол. Значение 9999 означает "последняя строка или столбец".

Режимы окон

Пример: Строка состояния Vim

[
  {
    "name": "editor",
    "top": 1,
    "bottom": 9998,
    "left": 1,
    "right": 9999,
    "mode": "announce"
  },
  {
    "name": "status",
    "top": 9999,
    "bottom": 9999,
    "left": 1,
    "right": 9999,
    "mode": "silent"
  }
]

Этот пример читает все строки, кроме последней (область редактора), обычным образом, а последнюю строку (строка состояния) замалчивает. Обычное применение включает замалчивание строк состояния, определение панелей tmux или screen, обработку заголовков htop и мониторинг областей ввода команд.

Текст Unicode и CJK

Terminal Access корректно обрабатывает символы двойной ширины, текст, написанный справа налево, и сложные последовательности эмодзи.

Символы CJK

Китайские, японские и корейские символы считаются как 2 столбца, поэтому операции на основе столбцов работают правильно. Обработка комбинируемых знаков нулевой ширины выполняется корректно.

Hello世界   # "Hello" = 5 столбцов, "世界" = 4 столбца, всего = 9 столбцов

Текст, написанный справа налево

Terminal Access определяет арабский и иврит по диапазону символов и применяет алгоритм двунаправленного письма Unicode (UAX #9), включая контекстное изменение формы арабских символов и смешанный текст RTL/LTR.

Для полной поддержки RTL установите дополнительные библиотеки:

pip install python-bidi arabic-reshaper

Без них Terminal Access использует базовую поддержку Unicode.

Эмодзи

Terminal Access обрабатывает последовательности с соединителем нулевой ширины (эмодзи семьи и профессии), модификаторы цвета кожи, селекторы вариаций и последовательности флагов. Эмодзи обычно имеют ширину 2 столбца.

Для полной поддержки эмодзи установите дополнительную библиотеку:

pip install emoji

Производительность

Terminal Access включает оптимизации для больших буферов терминала.

• Кеширование позиций: Вычисления позиций кешируются для до 100 позиций с таймаутом 1 секунда и аннулируются при изменении содержимого, изменении размера или переключении терминала. Вычисление, которое выполняется за O(n) при первом обращении, становится O(1) при использовании кеша.
• Инкрементальное отслеживание: Небольшие перемещения курсора (в пределах 10 позиций) выполняются в 10–20 раз быстрее, чем полное вычисление, с автоматическим переключением на полное вычисление для больших переходов.
• Фоновая обработка: Выделение более 100 строк выполняется в фоновом потоке с диалогом прогресса и поддержкой отмены.
• Чистый Python: Дополнение не содержит скомпилированных компонентов. Ранние бета-версии 2.0.0 включали собственную библиотеку и вспомогательный процесс для чтения терминала; оба были удалены после полевых испытаний, показавших, что чтение в процессе на Python работает быстрее и надежнее (чтение через вспомогательный процесс зависало на секунды на некоторых терминалах, а встроенная защита NVDA может восстановить медленное чтение в процессе). Будучи чистым Python, дополнение также работает на ARM64-версиях Windows без отдельной сборки.

Поддержка AI CLI

Terminal Access обнаруживает инструменты командной строки на основе ИИ и добавляет навигацию для рабочих процессов с беседами. Поддерживаемые инструменты: Claude, Aider, ChatGPT CLI, GitHub Copilot CLI, Gemini CLI, OpenAI Codex CLI и Ollama.

Экспериментально: обнаружение витков диалога и блоков кода основано на эвристике. Он определяет границы по маркерам приглашений каждого инструмента, поэтому инструмент с нестандартным выводом может разделять витки диалога в неправильном месте или пропускать блок кода. Если беседа читается неправильно, сообщите об этом с примером, чтобы мы могли улучшить обнаружение.

Навигация по виткам диалога

Terminal Access разделяет буфер на витки диалога на основе маркеров ролей, используемых каждым AI CLI (приглашения пользователя и ответы ассистента).

Когда вы попадаете на виток, Terminal Access объявляет роль (пользователь или ассистент) и первую строку. Если в этом направлении больше нет витков, вы услышите "Больше нет витков".

Навигация по блокам кода

Terminal Access сканирует блоки кода в тройных обратных кавычках и отслеживает язык, начальную строку, конечную строку и содержимое каждого блока.

Команда "Объяснить" дает краткое автономное объяснение блока. Она защищена настройкой конфиденциальности "Разрешить объяснение кода", которая по умолчанию выключена.

Потоковая дельта

Нажмите NVDA+Shift+D, чтобы услышать только то, что изменилось с последней проверки, пока ИИ-ассистент транслирует свой ответ. Terminal Access сравнивает текущий буфер с сохраненным снимком, чтобы найти новый контент.

Ограниченный поиск

Нажмите Ctrl+F в слое команд, чтобы выполнить поиск только в текущем витке диалога. Стандартный поиск (F в слое команд) по-прежнему ищет по всему буферу.

Обнаружение ошибок ИИ

Terminal Access распознает специфические для ИИ шаблоны ошибок в дополнение к стандартным ошибкам компиляторов и оболочки.

Ошибки ограничения скорости и лимита токенов воспроизводят пульсирующий низкий тон (два быстрых сигнала по 220 Гц). Другие ошибки API воспроизводят один низкий тон.

Уровень подробности

Уровень подробности контролирует, сколько дополнительного контекста произносит Terminal Access. Нажмите Shift+V в слое команд (или NVDA+Shift+V), чтобы переключать уровни, или установите в меню NVDA > Параметры > Настройки > Настройки терминала.

Настройки конфиденциальности

Две настройки управляют функциями ИИ, которые отправляют содержимое терминала во внешний сервис. Обе по умолчанию выключены.

Когда вы вызываете функцию, защищенную конфиденциальностью, пока она отключена, Terminal Access сообщает, что функция отключена, и объясняет, как её включить. Чтобы включить, откройте Настройки NVDA > Настройки терминала > Конфиденциальность и установите флажок.

Настройки

Откройте настройки из меню NVDA > Параметры > Настройки > Настройки терминала.

Панель настроек также содержит раздел "Конфликты жестов NVDA" для отключения конфликтующих жестов и раздел "Профили приложений" для управления профилями.

Эхо клавиш и эхо набора NVDA

В NVDA есть две собственные настройки эхо-воспроизведения набора в меню NVDA > Параметры > Настройки > Клавиатура: "Произносить набираемые символы" и "Произносить набираемые слова". Эхо клавиш Terminal Access и эти настройки — не одно и то же, и одновременно работает только одно из них:

• Когда обе настройки эхо-воспроизведения NVDA выключены (рекомендуется для работы в терминале), Terminal Access выполняет эхо внутри терминалов. Вы получаете названия символов на выбранном уровне пунктуации, сжатые повторяющиеся символы ("тире 4 раза") и управление на уровне профиля приложения: профили для одноклавишных программ, таких как less, lazygit, btop и Claude, автоматически отключают эхо, чтобы сочетания клавиш не создавали шума.
• Когда любая из настроек эхо-воспроизведения NVDA включена, NVDA сама воспроизводит вводимый текст, а Terminal Access отключается. Это особенно важно для "Произносить набираемые слова": NVDA формирует каждое произносимое слово из отдельных нажатий клавиш, которые она видит, поэтому если бы Terminal Access также воспроизводил каждый символ, он бы перекрывал слова. Когда настройка NVDA включена, эхо клавиш дополнения и любые переопределения эхо на уровне профиля не действуют, и вы теряете сжатие символов и автоматическое поведение на уровне приложений.

Короче говоря: для полноценного использования терминала оставьте обе настройки эхо-воспроизведения NVDA выключенными и используйте эхо клавиш Terminal Access; включайте настройки NVDA, только если хотите одинаковое эхо во всех приложениях, и в этом случае эхо клавиш Terminal Access не работает.

Устранение неполадок

Дополнение не активируется

• Убедитесь, что вы находитесь в поддерживаемом терминале.
• Проверьте, включено ли дополнение в меню NVDA > Сервис > Управление дополнениями.
• Перезапустите NVDA.

Команды не отвечают

• Попробуйте другое терминальное приложение, чтобы проверить, не связано ли это с конкретным терминалом.
• Проверьте конфликты сочетаний клавиш в диалоге "Жесты ввода" NVDA.
• Просмотрите журнал NVDA (меню NVDA > Сервис > Просмотреть журнал).

Получение помощи

• Нажмите NVDA+Shift+F1 в любом терминале, чтобы повторно открыть это руководство.
• Сохранить отчет об ошибке: нажмите Shift+I в слое команд (или NVDA+Alt+I напрямую), когда функция читает что-то неправильно, например, режим таблицы неправильно определяет столбец или виток ИИ обнаружен на неправильной строке. Будет сохранен текстовый файл с версиями вашего дополнения и NVDA, терминалом, активным профилем и образцом буфера. Добавьте предложение о том, что вы ожидали, и прикрепите файл к вопросу на GitHub.
• Сообщайте о проблемах в трекере проблем GitHub. Включите версию NVDA, версию Terminal Access, терминальное приложение и его версию, шаги для воспроизведения, а также ожидаемое и фактическое поведение.
• Часто задаваемые вопросы и история версий доступны на GitHub.