Инструменты устройства

Устройства→Инструменты

TIP

Инструменты доступны агентам, у которых в профиле включён модуль «Устройства» — см. Устройства.

Страница для агента и для того, кто разбирается, что именно агент делает с устройством.

Набор

Инструмент	Что делает
devices_list	Устройства workspace: имя, система, уровень доступа, онлайн или нет
devices_describe	Разрешённые команды, домашняя папка, система и версия одного устройства
devices_run	Запустить команду. Возвращает результат сразу, если она успела завершиться, иначе process_id
devices_poll	Забрать новый вывод запущенной команды и узнать, жива ли она
devices_terminate	Остановить запущенную команду

Как выполняется команда

devices_run принимает список аргументов, не строку:

{
  "connection_id": "dev-a41c…",
  "argv": ["git", "log", "--oneline", "-20"],
  "cwd": "~/projects/site"
}

Оболочки нет. argv[0] сверяется со списком уровня доступа, остальные элементы передаются процессу как есть. Поэтому "git log | head" не сработает — | уедет в git как аргумент. Нужен конвейер — запускайте шаги отдельно или пишите скрипт и запускайте его.

Устройство может быть на macOS, Windows или Linux — это видно в devices_list и devices_describe. Не считайте систему по умолчанию: на Windows нет ни ls, ни ~, а пути пишутся через обратный слэш. Домашнюю папку и разрешённые команды берите из devices_describe, а cwd оставляйте пустым, если вас устраивает домашняя.

Первые несколько секунд Life OS ждёт завершения. Короткая команда возвращает вывод и код возврата сразу. Долгая возвращает process_id, дальше её читают через devices_poll — каждый вызов отдаёт то, что накопилось с прошлого раза.

Вывод обрезается на разумном объёме; в ответе будет output_truncated: true. Если нужен весь — перенаправьте в файл на устройстве и читайте частями.

Что стоит знать агенту

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

Не угадывайте, что разрешено. devices_describe возвращает точный список команд. Команда вне его будет отклонена с названием того, чего не хватило, — это ответ пользователю, а не повод пробовать обход.

Обхода нет. Запуск запрещённой команды через разрешённую — python -c, make с самодельной целью, скрипт, который вы только что записали, — это обход границы, которую поставил человек. Если задача требует большего, скажите об этом и попросите поднять уровень доступа.

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

Останавливайте за собой. Запустили долгий процесс и он больше не нужен — devices_terminate. Процессы переживают вашу сессию.

Ошибки

Ответ	Что произошло
device_offline	Мост на устройстве не на связи. Не повторять в цикле — сообщить человеку
command_not_allowed	Команды нет в списке уровня доступа
invalid_cwd	Путь вне разрешённой области
unknown_process_id	Процесс не найден: чужой, или устройство перезапускалось
connection_not_found	Подключения нет в этом workspace — проверьте platform_whoami