Инструмент мониторинга (`monitor`)

В этом документе описан инструмент monitor для Qwen Code.

Описание

Используйте monitor для запуска долго выполняющейся команды оболочки, которая построчно передаёт stdout и stderr обратно агенту в виде фоновых уведомлений о задачах. Он предназначен для команд типа watch, где важны новые выходные данные с течением времени, например, для отслеживания логов, наблюдения за выводом сборки, опроса конечной точки состояния или отслеживания изменений файлов.

Монитор работает в фоне, так что агент может продолжать работу, пока поступают события. Каждая непустая строка вывода становится событием уведомления с учётом ограничения частоты.

Аргументы

monitor принимает следующие аргументы:

command (строка, обязательный): Команда оболочки для запуска и наблюдения.
description (строка, опционально): Краткое описание того, за чем следит монитор. Отображаемый текст обрезается до 80 символов.
max_events (число, опционально): Остановиться после этого количества событий уведомления. Должно быть положительным целым числом. По умолчанию 1000; максимум 10000 (значения вне этого диапазона отклоняются, а не молча округляются).
idle_timeout_ms (число, опционально): Остановиться, если команда не выдаёт вывод в течение этого количества миллисекунд. Должно быть положительным целым числом. По умолчанию 300000 (5 минут); максимум 600000 (10 минут), значения вне этого диапазона отклоняются.
directory (строка, опционально): Абсолютный путь для выполнения команды. После разрешения символических ссылок должен находиться внутри одной из зарегистрированных директорий рабочего пространства и не должен находиться внутри директории пользовательских навыков. Если опущен, Qwen Code использует корень проекта.

Как использовать `monitor` с Qwen Code

Модель выбирает инструмент monitor, когда нужно наблюдать за процессом в течение времени, а не получать единичный результат команды. Успешный вызов возвращает ID монитора, команду, лимит событий и тайм-аут простоя.

Использование:


monitor(command="tail -f logs/app.log", description="app log stream")

Вывод монитора отображается в беседе как уведомления о задачах. Вы также можете просмотреть работающие и завершённые мониторы с помощью /tasks или интерактивного диалога «Фоновые задачи».

Чтобы остановить работающий монитор, используйте инструмент task_stop с ID монитора:


task_stop(task_id="mon_abc123def4567890")

Примеры `monitor`

Наблюдение за логом приложения:


monitor(
  command="tail -f logs/app.log",
  description="application log stream",
  max_events=200
)

Мониторинг сервера разработки или сборщика:


monitor(
  command="npm run build -- --watch",
  description="watch build output",
  idle_timeout_ms=600000
)

Опрос локальной конечной точки состояния:


monitor(
  command="while true; do curl -s http://localhost:8080/health; sleep 5; done",
  description="local health check",
  max_events=120
)

Запуск из определённой директории рабочего пространства:


monitor(
  command="npm run dev",
  description="frontend dev server",
  directory="/absolute/path/to/workspace/packages/web"
)

Когда использовать monitor, а когда фоновые команды оболочки

Используйте monitor, если агенту нужно реагировать на потоковый вывод, пока команда продолжает работать. Используйте run_shell_command, когда нужен одноразовый результат или полный вывод команды.

Потребность	Используйте
Наблюдение за логами, выводом сборки или периодическими статусами	`monitor`
Выполнение одноразовой команды и чтение полного вывода	`run_shell_command(is_background=false)`
Запуск демона, который не выводит осмысленных данных	`run_shell_command(is_background=true)`

Не добавляйте & к командам монитора. Завершающий &, например tail -f log &, удаляется, так как монитор сам управляет фоновым выполнением. Нефинальный &, например cmd1 & cmd2, отклоняется полностью; перестраивайте такие команды без фонового выполнения.

Важные замечания

Автоматическая остановка: Мониторы останавливаются автоматически при достижении max_events, по истечении idle_timeout_ms без вывода или при самостоятельном завершении команды. Статус монитора отражает результат команды, а не ошибку инструмента: успешный выход (код 0) становится completed, ненулевой код выхода — failed с сообщением Exit code N, завершение по сигналу — failed с сообщением Killed by signal SIG. Команды не могут быть интерактивными, так как stdin закрыт. Когда монитор останавливается, Qwen Code посылает SIGTERM группе процессов команды и переходит к SIGKILL примерно через 200 мс. В Windows используется taskkill /f /t. Если сам процесс Qwen Code был жёстко завершён, упал или исчерпал память, отделённая группа процессов не очищается автоматически; восстановитесь, остановив монитор с помощью task_stop перед выходом или завершив группу процессов вручную.
Лимит параллельности: Qwen Code допускает до 16 работающих мониторов на сессию CLI как единый общий пул. Мониторы, запущенные подагентами, учитываются в том же лимите, что и мониторы, запущенные основным агентом. При достижении лимита остановите существующий монитор перед запуском нового.
Обработка вывода: Stdout и stderr объединяются в единый поток уведомлений без префикса потока. Пустые строки игнорируются, ANSI-цвета и управляющие символы удаляются, отдельные строки длиннее 2000 символов обрезаются. Высокочастотный вывод ограничивается по скорости: начальный всплеск из 5 событий, затем примерно 1 событие в секунду; строки, превышающие лимит, отбрасываются, а не буферизируются. Вывод монитора попадает в контекст агента как содержимое <task-notification>. Структурные теги уведомлений обезвреживаются, но модель всё равно читает текст каждой строки, поэтому избегайте мониторинга потоков, в которые могут писать внешние стороны, если вы не уверены, что модель проигнорирует встроенные инструкции.
Разрешения: monitor имеет собственные границы и правила разрешений, например Monitor(git status)». Команды только для чтения разрешаются автоматически; команды, изменяющие состояние, требуют одобрения пользователя; команды, содержащие подстановку команд ($(…), обратные кавычки, <(…)или>(…)), отклоняются сразу. Настройки tools.coreиtools.excludeдляrun_shell_commandне применяются кmonitor`.
Ограничения рабочего пространства: Необязательный directory должен быть абсолютным путём, который разрешается внутри зарегистрированной директории рабочего пространства и вне директории пользовательских навыков. Символические ссылки, ведущие за пределы рабочего пространства, отклоняются.

Инструмент мониторинга (monitor)