Руководство пользователя SoftAgent

Убедиться, что среда соответствует требованиям, и подготовиться к установке.

1. Убедитесь, что целевой ПК работает под управлением Windows 10/11 x64.
2. Убедитесь, что у вас есть привилегии учётной записи администратора (установщик запросит повышение UAC).
3. Убедитесь, что брандмауэр разрешает входящий UDP-трафик на порт 6500 (порт прослушивания SoftAgent).
4. Пакет установщика самодостаточен — на целевой машине не требуется предварительная установка .NET Runtime.

• Можно запускать программы от имени администратора (повышение UAC принято).
• UDP-порт 6500 не занят другой программой.

• Несколько управляемых ПК могут использовать один и тот же установщик — настраивайте порт и адрес отчётов независимо на каждом.
• Для выставочных проектов рекомендуется настроить все управляемые ПК на автовход с учётной записью администратора, чтобы задача автозапуска надёжно срабатывала.

Завершить установку и убедиться, что SoftAgent нормально работает в системном лотке.

1. Дважды щёлкните SoftAgent-Setup-version.exe и нажмите Да в запросе UAC для предоставления прав администратора.
2. Следуйте мастеру установщика для завершения установки (по умолчанию: C:\Program Files\SoftAgent\).
3. На странице завершения опционально установите флажок «Запустить SoftAgent сейчас» или запустите вручную после.
4. После запуска SoftAgent появляется в системном лотке (главное окно не открывается).
5. Щёлкните правой кнопкой мыши значок лотка и выберите «Открыть конфигурацию» — убедитесь, что открывается главное окно с 4 вкладками (Свойства / Программы / Watchdog / Настройки).

• Значок SoftAgent появляется в системном лотке.
• Диспетчер задач показывает работающие процессы SoftAgent.App и SoftAgent.Watchdog.
• Правый клик по лотку показывает: Открыть конфигурацию / Статус / Приостановить Watchdog / Открыть директорию логов / О программе / Выход.

SoftAgent использует двухпроцессную архитектуру: процесс App обрабатывает функциональность, а Watchdog отслеживает и автоматически перезапускает App при сбое — они взаимно защищают друг друга.

Завершить базовую конфигурацию и подтвердить работу агента через UDP ping.

1. Дважды щёлкните значок лотка для открытия главного окна, переключитесь на вкладку Настройки.
2. Убедитесь, что порт прослушивания 6500 (или измените при необходимости), и установите флажок «Автозапуск» для регистрации запланированной задачи.
3. Для интеграции с SoftControl введите IP:порт машины SoftControl в поле «Адрес отчётов».
4. Нажмите «Сохранить и применить» для сохранения конфигурации.
5. Откройте PowerShell и отправьте ping для проверки:
6. $u = New-Object System.Net.Sockets.UdpClient
7. $b = [Text.Encoding]::UTF8.GetBytes('ping')
8. $u.Send($b, $b.Length, '127.0.0.1', 6500)
9. $r = $u.Receive([ref](New-Object System.Net.IPEndPoint([Net.IPAddress]::Any, 0)))
10. [Text.Encoding]::UTF8.GetString($r)
11. Получение ok:pong подтверждает нормальную работу агента.

• Отправка ping получает ответ ok:pong.
• Флажок автозапуска на вкладке Настройки сохранён.
• Выполнение schtasks /Query /TN SoftAgent показывает зарегистрированную запланированную задачу.

• Изменение порта без нажатия «Сохранить и применить», поэтому изменение не вступает в силу.
• Ввод порта HTTP-консоли управления вместо UDP-порта прослушивания.

Освоить формат команд и уровни риска для безопасного использования SoftAgent.

1. Формат команды: глагол или глагол:аргумент (аргумент следует за первым двоеточием), например volume:80 или ping.
2. Успешный ответ: ok:<код>, например ok:pong или ok:volume.
3. Ответ об ошибке: err:<код>, например err:wol.invalidMac.
4. Три уровня риска: Безопасный (без нарушений, повторяем) / Нарушающий (прерывает сессию/процесс, но без потери данных) / Деструктивный (выключение/перезапуск/выход и т.д.).
5. Деструктивные команды показывают диалог подтверждения в интерфейсе. При удалённом запуске ответственность за подтверждение намерения лежит на вызывающем.

• Отправка ping получает ok:pong, подтверждая подключение и правильный формат команды.
• Отправка describe получает список возможностей JSON со всеми поддерживаемыми командами и их уровнями риска.

Команда describe возвращает полный список возможностей этого экземпляра SoftAgent, включая имя, описание, уровень риска и необходимость подтверждения каждой команды — полезно для обнаружения возможностей при интеграции с SoftControl или AI-системами.

Освоить безопасные команды для ежедневного управления громкостью и мониторинга статуса.

1. Проверка подключения: ping (отвечает ok:pong, подтверждает онлайн-статус агента).
2. Получить список возможностей: describe (возвращает JSON со всеми командами с описаниями и уровнями риска).
3. Обнаружение устройств: discover (возвращает снимок heartbeat JSON с именем хоста, IP, MAC, громкостью, статусом watchdog).
4. Увеличить громкость на один шаг: volup (по умолчанию +5% за вызов).
5. Уменьшить громкость на один шаг: voldown (по умолчанию -5% за вызов).
6. Переключить отключение звука: mute (переключение между отключённым и включённым звуком).
7. Получить MAC-адрес основного сетевого адаптера: getmac (возвращает формат с заглавными буквами через дефис, например AA-BB-CC-DD-EE-FF).
8. Отправить magic packet Wake-on-LAN: wol:AA-BB-CC-DD-EE-FF (разбудить машину с указанным MAC).
9. Симуляция клавиатуры: key:^s (Ctrl+S), key:{F5} (клавиша F5), key:Hello (ввод символов).

• Команда ping возвращает ok:pong.
• volup/voldown изменяет громкость управляемой машины.
• Команда wol будит целевую машину (требуется включение WoL на целевой машине).

• Используйте discover для быстрого получения текущего состояния управляемой машины (IP, громкость, статус watchdog) — полезно для пакетных проверок работоспособности SoftControl.
• key: использует синтаксис Microsoft SendKeys: ^ — Ctrl, % — Alt, + — Shift, специальные клавиши в фигурных скобках, например {ENTER}.

Освоить команды блокировки экрана, запуска/остановки процессов и отмены выключения.

1. Заблокировать экран: lock (блокирует текущую рабочую станцию — для восстановления требуется повторный вход).
2. Отменить ожидающее задержанное выключение/перезапуск: cancelshutdown (использовать во время обратного отсчёта выключения).
3. Запустить элемент watchdog по ID: run:id (например, run:db-player запускает элемент с именем db-player).
4. Остановить элемент watchdog по ID: stop:id (останавливает и приостанавливает watchdog — процесс не будет автоматически перезапущен).
5. Запустить управляемую программу по индексу: startpro:0 (запускает программу с индексом 0 в списке управляемых программ).
6. Остановить управляемую программу по индексу: killpro:0.
7. Остановить все управляемые программы: killall.

• После lock управляемая машина показывает экран блокировки.
• После run:id соответствующий элемент watchdog запускается — статус меняется с Stopped на Running на вкладке Watchdog.
• cancelshutdown, отправленный во время обратного отсчёта выключения, отменяет выключение.

• Используйте run/stop с ID watchdog (стабильным идентификатором) вместо startpro/killpro с индексом (индекс меняется при удалении или изменении порядка элементов).
• ID watchdog настраиваются на вкладке Watchdog SoftAgent. Обновляйте команды SoftControl при переименовании ID.

Безопасно выполнять деструктивные операции, такие как выключение, перезапуск и выход из системы.

1. Задержанное выключение (рекомендуется): shutdown:60 (выключение через 60 секунд, cancelshutdown может отменить во время обратного отсчёта).
2. Немедленное выключение (использовать с осторожностью): shutdown (без задержки, нельзя отменить).
3. Задержанный перезапуск (рекомендуется): reboot:60 (перезапуск через 60 секунд).
4. Перезапуск в BIOS/UEFI: reboot:firmware (требуется поддержка прошивки UEFI).
5. Выход текущего пользователя из системы: logoff (убедитесь, что нет несохранённых данных перед выполнением).
6. Включить/отключить UAC: uac:off / uac:on (изменение реестра, требуется перезапуск для вступления в силу, требуются права администратора).
7. Включить/отключить жесты краёв сенсорного экрана Windows: edgeswipe:off / edgeswipe:on.
8. Включить/отключить автоматическое восстановление при запуске Windows: autorepair:off / autorepair:on.

• После shutdown:60 система показывает уведомление с обратным отсчётом «выключение через 60 секунд».
• cancelshutdown, отправленный во время обратного отсчёта, отменяет выключение.

• Отправка shutdown без задержки, что делает отмену невозможной — управляемая машина немедленно выключается.
• После uac:off не перезагружать и считать, что UAC уже отключён (требуется перезапуск для вступления в силу).

Команды выключения требуют прав администратора. При недостаточных разрешениях возвращается чёткий код ошибки, например err:power.denied — без молчаливого отказа.

Завершить базовую конфигурацию, чтобы SoftAgent мог быть правильно обнаружен и управляться SoftControl.

1. Откройте главное окно SoftAgent и переключитесь на вкладку Настройки.
2. Порт прослушивания (по умолчанию 6500): SoftControl и другие контроллеры отправляют UDP-команды на этот порт.
3. Адрес отчётов (формат IP:порт): SoftAgent периодически отправляет heartbeat JSON на этот адрес; введите IP и порт прослушивания SoftControl.
4. Интервал heartbeat (секунды): по умолчанию 10 секунд; heartbeat содержит имя хоста, IP, MAC, громкость, статус watchdog и т.д.
5. Задержка автозапуска (секунды): задержка после входа в систему перед запуском SoftAgent (полезно для ожидания готовности сети).
6. Нажмите «Сохранить и применить» после изменений — изменения порта показывают постоянное уведомление «Требуется перезапуск»; другие изменения вступают в силу немедленно.

• Конфигурация вступает в силу немедленно после сохранения (изменения порта требуют перезапуска).
• Если адрес отчётов настроен, SoftControl должен начать получать периодический heartbeat JSON от этого SoftAgent.

• Для нескольких управляемых ПК рекомендуется использовать одинаковый порт (6500) на всех, чтобы упростить пакетный ввод команд в SoftControl.
• Если адрес отчётов пуст, SoftAgent не будет активно отправлять heartbeat, но по-прежнему будет отвечать на UDP-команды.

Изменить конфигурацию IP управляемой машины через интерфейс SoftAgent без RDP.

1. Откройте главное окно, переключитесь на вкладку Свойства и выберите целевую сетевую карту в выпадающем списке сетевой панели.
2. После выбора сетевого адаптера текущий IP, маска подсети, шлюз, DNS и MAC-адрес заполняются автоматически.
3. Переключите режим «Статический IP / DHCP»: поля редактируемы в статическом режиме; только для чтения в режиме DHCP.
4. Заполните целевой IP, маску подсети, шлюз и DNS (статический режим).
5. Нажмите «Изменить настройки IP» и подтвердите в диалоге подтверждения.
6. Смена IP — деструктивная операция — текущее соединение прерывается после изменения. Переподключайтесь с новым IP.

• После изменения управляемая машина успешно пингуется по новому IP-адресу.
• Heartbeat JSON SoftAgent показывает обновлённый IP-адрес.

Смена IP деструктивна. Перед продолжением убедитесь, что новый IP доступен в локальной сети, чтобы не потерять удалённый доступ к управляемой машине.

Настроить автозапуск, чтобы SoftAgent автоматически возобновлял работу после перезапуска управляемого ПК.

1. На вкладке Настройки главного окна установите флажок «Автозапуск».
2. Нажмите «Сохранить и применить».
3. Проверьте с помощью: schtasks /Query /TN SoftAgent в PowerShell — подтвердите регистрацию запланированной задачи.
4. Триггер задачи: ONLOGON (запускается после входа пользователя) с уровнем привилегий HIGHEST.
5. Для установки задержки запуска (ожидание сети или зависимых служб) укажите секунды в поле «Задержка автозапуска».
6. Для отключения автозапуска снимите флажок «Автозапуск» и сохраните.

• schtasks /Query /TN SoftAgent показывает, что задача существует и включена.
• После перезапуска управляемого ПК SoftAgent автоматически появляется в системном лотке после входа в систему.

Завершить настройку команд SoftAgent в SoftControl для управления управляемыми машинами через кнопки.

1. Войдите в панель администратора SoftControl и откройте Управление командами.
2. Создайте новую команду, выберите протокол UDP.
3. Установите целевой адрес на IP управляемого ПК (например, 192.168.1.101).
4. Установите порт на порт прослушивания SoftAgent (по умолчанию 6500).
5. Установите текст команды на конкретную команду, например: volup (увеличить громкость), mute (переключить звук), lock (заблокировать экран), shutdown:60 (выключить через 60 с).
6. Сохраните и протестируйте команду индивидуально — убедитесь, что управляемая машина отвечает корректно.
7. Привяжите проверенную команду к кнопке на интерфейсе переднего плана SoftControl.

• После отправки UDP-команды SoftControl SoftAgent на управляемой машине выполняет действие.
• Логи SoftControl показывают, что команда отправлена успешно (ответ OK).

• Создавайте набор команд для каждой управляемой машины, используя имя устройства в качестве префикса (например, «Зал-ПК-01_Выключение») для удобного обслуживания.
• Для пакетных операций, таких как закрытие выставки, используйте группы команд SoftControl — добавьте команды выключения для нескольких машин в одну группу и запустите один раз.

Настроить heartbeat-отчёты для мониторинга онлайн-статуса управляемых машин из SoftControl.

1. В настройках SoftAgent настройте адрес отчётов на IP:порт SoftControl (внешний UDP-интерфейс SoftControl, по умолчанию 8818).
2. SoftAgent немедленно отправляет один heartbeat при запуске, затем продолжает с настроенным интервалом (по умолчанию 10 секунд).
3. Heartbeat JSON включает: agentId (уникальный идентификатор устройства), hostname, ip/mac (сетевая информация), volume/muted (состояние звука), guards (состояния watchdog процессов), uptimeSeconds.
4. Для активного запроса текущего состояния управляемой машины отправьте discover из SoftControl — SoftAgent возвращает снимок heartbeat.
5. Поле guards в heartbeat указывает, нормально ли работают watchdog-процессы, выявляя сбои или состояния «дал сбой».

• SoftControl получает периодический heartbeat JSON от SoftAgent.
• Отправка discover получает ответ JSON с именем хоста, IP, громкостью и другой информацией.

Настроить watchdog для автоматического перезапуска при сбоях выставочных приложений.

1. Откройте главное окно SoftAgent и переключитесь на вкладку Watchdog.
2. Нажмите «Обзор...» для выбора .exe под наблюдением, опционально установите имя и ID watchdog (стабильный идентификатор, используемый для команд run/stop).
3. Нажмите «Добавить» для размещения в список watchdog. Отдельный переключатель управляет включением watchdog для этого элемента.
4. Главный переключатель watchdog находится в верхней части вкладки — отключение приостанавливает весь watchdog (синхронизировано с меню «Приостановить Watchdog» лотка).
5. Значки статуса показывают состояние каждого элемента: Running / Stopped / Crashed / GaveUp (watchdog отказался после слишком большого количества сбоев в временном окне).
6. После сбоя SoftAgent перезапускает с экспоненциальной задержкой (начало 5 секунд, удвоение каждый раз; отказ после превышения лимита в временном окне).

• Охраняемая программа показывает статус «Running» в списке watchdog.
• Принудительное завершение охраняемого процесса и SoftAgent автоматически перезапускает его через задержку.
• Поле guards в heartbeat JSON отражает последние состояния watchdog.

Не меняйте ID watchdog произвольно — команды SoftControl run/stop зависят от него. При переименовании ID обновите соответствующие команды SoftControl.

Восстановить канал управления UDP-командами.

1. Убедитесь, что SoftAgent виден в системном лотке (процесс запущен).
2. Убедитесь, что порт отправки соответствует настроенному порту прослушивания SoftAgent (по умолчанию 6500).
3. Проверьте, разрешает ли брандмауэр Windows входящий UDP-трафик на порт 6500.
4. Сначала попробуйте ping с localhost (127.0.0.1) для исключения сетевых проблем, затем попробуйте удалённо.
5. Проверьте файлы логов в %ProgramData%\SoftAgent\logs\ на наличие записей о получении команд.

• Отправка ping на 127.0.0.1 получает ok:pong, подтверждая работу SoftAgent и UDP-порта.
• Отправка ping с удалённой машины также получает ответ, подтверждая открытость сетевого пути.

Обеспечить работу SoftAgent с правами администратора для поддержки всех системных команд.

1. Убедитесь, что SoftAgent работает с правами администратора: автозапуск использует запланированную задачу с привилегиями HIGHEST; для ручного запуска щёлкните правой кнопкой по exe и выберите «Запустить от имени администратора».
2. Если команды запускаются через SoftControl, самому SoftControl не нужны права администратора — привилегии определяются SoftAgent на управляемой стороне.
3. Проверьте столбец «Elevated» для SoftAgent.App.exe на вкладке Подробности диспетчера задач — должно быть «Да».
4. Если не работает от имени администратора, завершите SoftAgent и перезапустите от имени администратора.

• Вкладка Подробности диспетчера задач показывает «Да» в столбце Elevated для SoftAgent.App.exe.
• Команды volup/voldown отвечают нормально (не требуют прав администратора — полезно для базовой проверки).
• Команда lock блокирует экран управляемой машины (уровень Нарушающий — подтверждает правильность привилегий).

Диагностировать и устранить сбои автозапуска.

1. Выполните schtasks /Query /TN SoftAgent в PowerShell, чтобы убедиться, что запланированная задача существует.
2. Если задача не существует, откройте вкладку Настройки SoftAgent, повторно установите флажок «Автозапуск» и сохраните.
3. Убедитесь, что ПК использует автовход (распространено на выставках), а не ожидает ручного входа — триггер задачи ONLOGON требует входа пользователя.
4. При настройке для автовхода убедитесь, что учётная запись автовхода имеет разрешения для запуска задачи (требуется учётная запись администратора).
5. Проверьте последние логи в %ProgramData%\SoftAgent\logs\ на наличие причин сбоя запуска.

• Вывод schtasks /Query /TN SoftAgent содержит триггер ONLOGON и привилегии HIGHEST.
• После перезапуска управляемого ПК и входа в систему SoftAgent автоматически появляется в системном лотке.

Понять, почему watchdog отказался, и восстановить мониторинг целевого приложения.

1. На вкладке Watchdog главного окна SoftAgent проверьте значок статуса — подтверждает состояние 'GaveUp'.
2. Проверьте файлы логов в %ProgramData%\SoftAgent\logs\ на конкретную причину сбоя (ошибки перед каждым сбоем).
3. Устраните первопричину сбоев охраняемого приложения (ошибка конфигурации, отсутствующая зависимость, конфликт портов и т.д.).
4. После исправления переключите индивидуальный переключатель элемента watchdog на вкладке Watchdog выкл, затем вкл (или отправьте run:id из SoftControl) для повторного запуска watchdog.
5. Убедитесь, что статус элемента watchdog меняется на 'Running' и остаётся стабильным со временем.

• После исправления охраняемого приложения статус watchdog меняется с 'GaveUp' на 'Running'.
• Heartbeat JSON показывает обновлённый статус соответствующего элемента watchdog как running.

GaveUp — намеренное поведение для предотвращения бесконечных штормов перезапуска, влияющих на системные ресурсы. Реальное решение — устранить первопричину сбоя, а не вручную повторно запускать watchdog снова и снова.