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

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

Описание

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

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

Аргументы

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

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

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

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

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


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

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

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


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"
)

Монитор vs. фоновые команды оболочки

Используйте 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 должен быть абсолютным путём, который после разрешения находится внутри зарегистрированного рабочего каталога и вне каталога user-skills. Символические ссылки, указывающие за пределы рабочего каталога, отклоняются.

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